From e5759e43d231a8a37779749f90598f97d9143d21 Mon Sep 17 00:00:00 2001
From: Levi Neely <lneely@pascom.net>
Date: Fri, 9 Oct 2026 14:07:40 +0200
Subject: [PATCH] doc: add Plan 9 plumber integration documentation

---
 doc/architecture-kde.md | 60 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/doc/architecture-kde.md b/doc/architecture-kde.md
index 2d2509b..3d2c6dd 100644
--- a/doc/architecture-kde.md
+++ b/doc/architecture-kde.md
@@ -86,3 +86,63 @@ The GUI uses native client code for streaming and session operations. Other inte
 | Plasma environment | `kde/99-ollie.sh` |
 
 For the public protocol and namespace, see [`architecture-9p.md`](architecture-9p.md). For the core agent runtime, see [`architecture-core.md`](architecture-core.md).
+
+## Plan 9 Plumber Integration
+
+`ollie-gui` integrates with the Plan 9 plumber for context-aware navigation. The GUI listens on the `ollie` plumb port for `ollie://` URLs.
+
+### URL Scheme
+
+```
+ollie://session/agent#block
+ollie://session/agent
+ollie://session
+```
+
+| Part | Description |
+|---|---|
+| `session` | Session name (required) |
+| `agent` | Agent name (optional) |
+| `#block` | Block index to scroll to (optional) |
+
+Examples:
+- `ollie://default/main#42` — switch to session "default", agent "main", scroll to block 42
+- `ollie://myproject/src:kate-custom` — switch to agent "src:kate-custom" in session "myproject"
+- `ollie://default` — switch to session "default"
+
+### Setup
+
+1. Add the ollie plumb rule to `$HOME/lib/plumbing`:
+
+```
+# ollie:// URLs go to the ollie port
+type is text
+data matches 'ollie://[a-zA-Z0-9_\-.:]+(/[a-zA-Z0-9_\-.:]+)?(#[0-9]+)?'
+plumb to ollie
+```
+
+Or include the bundled rules file:
+
+```
+include /path/to/ollie/data/plumbing
+```
+
+2. Reload plumber rules:
+
+```sh
+cat $HOME/lib/plumbing | 9p write plumb/rules
+```
+
+3. Ensure `ollie-gui` is running — it opens the `ollie` port for reading.
+
+### Usage
+
+From any Plan 9 application (acme, sam, rc, etc.):
+
+```sh
+plumb 'ollie://default/main#100'
+```
+
+Or right-click an `ollie://` URL in acme/sam and plumb it.
+
+The GUI also provides a 📋 button on bookmarks to copy the `ollie://` link to the clipboard, making bookmarks plumbable from anywhere.