diff --git a/doc/kde-gui.md b/doc/kde-gui.md
new file mode 100644
index 0000000..ea53784
--- /dev/null
+++ b/doc/kde-gui.md
@@ -0,0 +1,86 @@
+# ollie-gui — Qt6 desktop frontend for ollie
+
+ollie-gui is a free-standing Qt6/QML desktop application that talks to an ollie session directly through `ollie-9p`. No D-Bus, no Plasma dependencies — it runs on any Linux desktop with Qt6 installed.
+
+<p align="center">
+  <a href="img/ollie-kde.png"><img src="img/ollie-kde.png" alt="Ollie KDE GUI window showing a session tree, chat history, and prompt input bar with KDE Plasma Breeze theme" width="75%"></a>
+</p>
+
+## Prerequisites
+
+[olliesrv](../README.md) must be running:
+
+```sh
+olliesrv
+```
+
+## Installation
+
+```sh
+# From the repo root:
+just install-kde
+```
+
+Or build manually:
+
+```sh
+cd kde/gui
+cmake -B build -DCMAKE_INSTALL_PREFIX=~/.local
+cmake --build build
+cmake --install build
+```
+
+## Usage
+
+Launch from the application menu or terminal:
+
+```sh
+ollie-gui
+```
+
+### Interface
+
+- **Session list** — left panel showing all active and inactive sessions with agent state indicators (○ idle, ● thinking, ⚡ tool call). Right-click for session actions.
+- **Chat view** — center panel showing the conversation log. Block markers (`[[[type]]]` / `[[[end]]]`) are rendered as styled headers.
+- **Input bar** — bottom panel for composing prompts. Supports slash commands for common operations.
+- **Theme** — automatically adapts to the active KDE Plasma color scheme. Falls back to Qt Quick Controls Basic style when running outside Plasma.
+
+### Slash commands
+
+Type `/` in the input bar to trigger:
+
+| Command | Action |
+|---------|--------|
+| `/model` | Set the model for the current session |
+| `/backend` | Switch backends |
+| `/agent` | Switch to a different agent |
+| `/stop` | Interrupt the running turn |
+| `/kill` | Terminate the current session |
+| `/new` | Create a new session |
+| `/compact` | Compact the agent context |
+| `/help` | Show available commands |
+
+### Keyboard shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Escape` | Interrupt the running agent |
+| `Enter` | Submit prompt |
+| `Ctrl+Enter` | New line in input |
+
+## Architecture
+
+ollie-gui is a pure 9P client. It spawns `ollie-9p` as a subprocess and communicates through the 9P filesystem — the same interface the `o` CLI and `ellie.el` use. There is no D-Bus, no FUSE mount, and no intermediate daemon.
+
+```
+┌────────────────┐     ollie-9p read/write     ┌──────────────┐
+│   ollie-gui    │ ◄─────────────────────────► │   olliesrv   │
+│  (Qt6 / QML)   │      Unix socket (9P2000)    │  (agent core)│
+└────────────────┘                               └──────────────┘
+```
+
+### Components
+
+- **`Ollie9pClient`** — C++ backend that wraps `ollie-9p` invocations. Manages session discovery, agent listing, prompt submission, and chat streaming.
+- **`ChatBlockModel`** — renders chat log content as styled blocks (plain text, assistant responses, tool output, markdown fences).
+- **`ThemeManager`** — reads the active KDE Plasma color scheme from `~/.config/kdeglobals` and exposes palette properties to QML.
\ No newline at end of file