sl0p: document --purpose and tab purposesHEADmain

2 files changed, 34 insertions, 13 deletions

diff --git a/README.md b/README.md
index 8df8605c..36f63082 100644
--- a/README.md
+++ b/README.md
@@ -341,6 +341,10 @@ also says what each pane is *for*:
 pane name="server" purpose="dev-server" command="npm" { args "run" "dev"; }
 ```
 
+Tabs can carry one too (`tab name="work" purpose="agent-work"`, reported by
+`list-tabs --json`), and an agent can tag panes it spawns with
+`zellij run --purpose agent:build -- …`.
+
 It shows up in `zellij action list-panes --json`, survives resurrection, and can
 also be declared in-band by the program in the pane
 (`printf '\033]5577;1;purpose;agent:build\033\\'`) — though a layout-declared
diff --git a/sl0p/workspace-hints-handover.md b/sl0p/workspace-hints-handover.md
index 9ce49288..bcbd9d18 100644
--- a/sl0p/workspace-hints-handover.md
+++ b/sl0p/workspace-hints-handover.md
@@ -65,27 +65,45 @@ zellij --layout .pi/workspace.kdl attach --create myproject
 existing session NAME" and fails if the session does not exist. This bites
 everyone once.
 
-### 2. In-band, from inside the pane (fills blanks only)
+### 2. `--purpose` at spawn time (authoritative)
+
+```bash
+id=$(zellij run --no-focus --purpose agent:build --name job -- cargo build)
+zellij action new-pane --no-focus --floating --purpose agent:scratch
+```
+
+Rejected with `--in-place` (that replaces another pane rather than being one), so
+you get an error rather than a flag that silently does nothing.
+
+### 3. In-band, from inside the pane (fills blanks only)
 
 ```bash
 printf '\033]5577;1;purpose;agent:build\033\\'
 ```
 
-This is how you tag a pane **you** spawned, since there is no `--purpose` flag
-(spawn-time tagging would have meant threading a field through 28 call sites, and
-a new action variant is impossible while protobuf enums cannot be regenerated):
+For a program that decides its own role as it runs. Prefer `--purpose` when you
+are the one spawning the pane.
 
 ```bash
-id=$(zellij run --no-focus --name buildjob -- \
-     bash -lc 'printf "\033]5577;1;purpose;agent:build\033\\"; exec cargo build')
+zellij run --no-focus --name buildjob -- \
+     bash -lc 'printf "\033]5577;1;purpose;agent:build\033\\"; exec cargo build'
+```
+
+### Tab purpose
+
+```kdl
+tab name="work" purpose="agent-work" { ... }
 ```
 
-Wrap that in a pi helper once and forget it.
+Reported by `zellij action list-tabs --json` as `purpose`. Panes carry `tab_id`,
+so join the two listings when you need "the pane in the agent's tab". Tabs have no
+in-band path -- a tab is not a thing a program runs inside.
 
 ### The asymmetry you must not design against
 
-**A layout-declared purpose outranks an in-band one and cannot be overridden or
-cleared by it.**
+**A layout-declared or `--purpose` purpose outranks an in-band one and cannot be
+overridden or cleared by it.** (`--purpose` counts as out-of-band: whoever can run
+the CLI can already do anything.)
 
 Because OSC arrives in-band from whatever the pane is showing: without this rule,
 `cat hostile.txt` in the human's editor pane could relabel it `agent-scratch` and
@@ -168,10 +186,9 @@ terminal habits this builds on, all verified against the binary:
 
 Ask if you need any of these; each was left out for a stated reason, not forgotten.
 
-- **`--purpose` flag on `new-pane`/`run`** — the 28-call-site thread plus blocked
-  protobuf enums. The OSC wrapper is the sanctioned idiom.
-- **tab-level purpose** — plausible ("this tab is agent scratch"), but pane-level
-  answered the question first.
+- **`--purpose` with `--in-place`** — an in-place pane replaces another rather
+  than being one. Rejected by clap, not silently ignored.
+- **purposes on plugin panes** — plugin panes are zellij's own UI.
 - **a structured `meta` bag** — one string until it demonstrably is not enough.
   `command`/`args`/`cwd` already carry "what runs here".
 - **plugin visibility** — `purpose` is on `PaneListEntry` (CLI JSON), not