sl0p: document workspace hints for consumers

1 files changed, 16 insertions, 0 deletions

diff --git a/README.md b/README.md
index 7f7a6ddb..8df8605c 100644
--- a/README.md
+++ b/README.md
@@ -332,6 +332,22 @@ printf '\033]5577;1;clear\033\\'                                     # remove bo
 ╰ awaiting review ──────────────────────────[Approve]─[Reject]╯
 ```
 
+### Workspace hints
+
+A pane can carry an opaque `purpose` an agent can discover, so a project's layout
+also says what each pane is *for*:
+
+```kdl
+pane name="server" purpose="dev-server" command="npm" { args "run" "dev"; }
+```
+
+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
+purpose always wins, since in-band data is whatever the pane happens to be
+showing. Zellij never interprets a purpose; the consuming agent owns the
+vocabulary. See `sl0p/workspace-hints-handover.md`.
+
 Buttons render as `[Approve]` by default, or `1:Approve` with
 `ui { pane_frames { status_bar_button_style "indexed" } }` — useful when something
 else binds those numbers to the same actions.