Split control messages by scope: the root ctl takes the session's builtins and reads the settings, a pane's ctl its own

Every builtin could only be clicked, or written to exec, and the settings
could be read only as the Config window's prose. acme keeps window verbs on
a window's ctl, and webfs and upas/fs keep session settings on a root ctl.
Each builtin now declares its scope (scope = .session; settings are all
session, the rest pane), read by the registry. The root /ctl takes session
builtins and reads every setting in the words a write takes, so its read
written back changes nothing (panel and scene effects now take on/off like
the toggles, to make that true); a pane's ctl takes the pane's builtins
beside get, lock and unlock. Writes are checked whole and refused in Plan
9's ctl words (unknown control message "X", wrong #args ...), which 9ns
now maps to EINVAL (cloud9 re-pinned at a8c7a715). A builtin that would
prompt for its argument fails the write instead, and a refusal is answered
at once, not after the frame.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 30 insertions, 1 deletions

diff --git a/docs/fs.md b/docs/fs.md
index c2819adb..b3f3cb45 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -81,6 +81,7 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC.
 /screen      rendered screen JSON; frozen per open handle
 /listeners   the session's dial addresses
 /focus       the serial of the pane with the keyboard; write a serial to give it the keyboard
+/ctl         the settings, one a line as a write takes them; write a setting or a session builtin
 /pane/new    open it to make a pane; the read answers that pane's serial
 /pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll
              errors event look exec, plus pty/{ctl,status,data} on terminals
@@ -88,6 +89,33 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC.
 /src/        the editor's embedded sources, only when built with -Dembed-sources=true
 ```
 
+Control messages are split by what they act on, as acme keeps window verbs
+on a window's ctl and webfs and upas/fs keep session settings on a root ctl.
+Each builtin declares its scope in src/builtins.zig (`scope = .session`;
+every setting is one, the rest act on a pane). `/ctl` takes the session's
+builtins, one a line, at whichever pane has the keyboard as each runs --
+`Newcol`, `Dump`, `Kill`, `Mount name dial`, `Theme ink`, `Verbose off` --
+and reads every setting there is, one a line, in the words a write of it
+takes (`Verbose on`, `WindowOpacity 70`, `PanelSlide off`, `DumpDir` bare
+for the default directory, `LocationsConfig ...`), so writing what it reads
+back changes nothing; platform and startup facts are `/status`'s and the
+Config window's, not settings. A pane's `ctl` takes the builtins that act on
+a pane (`Del`, `Save f`, `Collapse`, `Find pat`) beside acme's `get`, `lock`
+and `unlock`. The words are case-sensitive and do not alias: acme's verbs
+are lowercase and the builtins keep their tag spelling, so `Get` is no word
+and `del` none either. A write is checked whole before any line runs, and a
+line is refused in Plan 9's words for a ctl (kernel/misc/parse.c:82-97):
+`unknown control message "X"`, `wrong #args in control message "X"` for an
+argument to a builtin that takes none, `bad value in control message "X"`
+for a setting's value it does not take, and `not a session control message
+"X"` or `not a window control message "X"` for a word of the other ctl; 9ns
+maps them all to EINVAL. A builtin that would ask at a prompt for its
+argument (`Save` on a scratch, `Find` bare) fails the write with `control
+message needs its argument` rather than open one nobody is there to answer,
+though a click on the same word written to `exec` still opens it. Like any
+write, a ctl write answers once the editor has performed what it asked for
+(a save written, a shell started).
+
 `/focus` reads the serial of the pane with the keyboard, and a serial written
 to it gives that pane the keyboard, off any column or workspace tag that had
 it -- rio's `current` written to a window's `wctl`, named once for the whole
@@ -161,7 +189,8 @@ pane's Look and Exec clicks to that client; writing a record back performs the
 action. `ctl` reads acme's window status line — serial, tag length, body
 length, a reserved zero, the dirty flag, the width in cells, the font and the
 tab width — followed by rio's `current` or `notcurrent` (rio(4), `wctl`):
-whether the pane has the keyboard. It takes `get`, which reloads the buffer from the name it
+whether the pane has the keyboard. It takes the pane's builtins (below),
+`get`, which reloads the buffer from the name it
 carries, and acme's `lock` and `unlock` (editors/acme/xfid.c:603-611), for an
 edit of several writes to `addr` and `data` that another client must not
 land in the middle of. As in acme the lock binds only the clients that take