Scripting over 9P has one chapter, and the served README and the 9P skill shrink to a summary, the traps and a pointer to it

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

1 files changed, 25 insertions, 31 deletions

diff --git a/src/fs-help.txt b/src/fs-help.txt
index 62d4ae48..83aa536f 100644
--- a/src/fs-help.txt
+++ b/src/fs-help.txt
@@ -1,45 +1,39 @@
 Pardes control filesystem
 =========================
-README      this guide
-index       one line per pane: serial, kind (text|term|pdf|image), dirty flag, name (<dir>/+New if unnamed), column serial; rsplit(maxsplit=1) first, names hold spaces
+README      this summary; the pardes book's Scripting and Reference chapters have the rest
+index       a line per pane: serial kind(text|term|pdf|image) dirty name column; names hold blanks: rsplit(maxsplit=1)
 status      pid, version and pane count
 look        write a line: a right click on it at the active pane; read: the serials it touched (this open's)
-exec        write a line: a middle click, an editor command word or a shell line; read the same (every exec file)
+exec        write a line: a middle click, a builtin or a shell line; read the same (every exec file)
 log         events: new del rename save newcol delcol run exit send ask answer changed dump restore restored restoredcol msg err
-screen      rendered screen as JSON, frozen from open to close
+screen      the rendered screen as JSON, frozen from open to close
 listeners   the session's dial addresses
-focus       the serial of the pane with the keyboard (empty on a column tag); write a serial to give it the keyboard
-ctl         settings a line; or Newcol, Dump, Restore [f], Exit (asks once), Kill [w], Placement acme|pardes, size C R (--detach)
-commands    every builtin: word, arg if it takes one, root|pane|both (the ctl that takes it), -- what it does
-recent      files opened lately, closed ones too, most recent first: open|closed <path>
-layout      a line per column: serial index x width current|notcurrent empty|full pane-serials; active <serial>
-tag         the workspace tag, tagexec a word as a click in it; col/<serial>/ a column's tag, ctl (Delcol Joincol New Tty), exec; rmdir: empty only
-pane/new    open it to make a pane (<session dir>/+New) in the active column, filling it if empty; the read answers its serial
-pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll errors (write-only, to +Errors) event look exec tagexec, pty/ on terminals; rmdir closes
+focus       the serial of the pane with the keyboard (empty on a column tag); write one to give it the keyboard
+ctl         settings a line; or Newcol, Dump, Restore [f], Exit (refuses once over unsaved panes), Kill [w], size C R
+commands    every builtin: word, arg, root|pane|both (the ctl that takes it), -- what it does
+recent      files opened lately, closed ones too: open|closed <path>
+layout      a line per column: serial index x width current|notcurrent empty|full pane-serials; then active <serial>
+tag         the workspace tag, tagexec a word as a click in it; col/<serial>/ a column's tag, ctl, exec; rmdir: empty only
+pane/new    open it to make a pane (<session dir>/+New) in the active column; the read answers its serial
+pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll errors event look exec tagexec; rmdir closes
+            on terminals pty/data (keys in, output out), pty/status, pty/ctl (winsize, sig, exec), pty/run (a line, its exit and output)
 os/, src/   the host filesystem; the editor's own sources
 
-$m below: $NINE_MOUNT/pardes/<pid|NAME>; $NINE_MOUNT under 9ns --unix; PARDES_MOUNT in a Tty9p shell.
+$m below: $NINE_MOUNT/pardes/<pid|NAME> under 9ns --mntgen; $NINE_MOUNT under 9ns --unix; $PARDES_MOUNT in a Tty9p shell.
 
   cat $m/index                                 which panes exist
-  n=$(cat $m/pane/new)                        make a pane, take its serial
   echo /etc/hosts:3 > $m/look; cat $m/look     open a file, see the pane it went to
-  printf 'text\n' >> $m/pane/$n/body           append to a pane (> replaces it all)
-  echo notes.txt > $m/pane/$n/name; echo Save > $m/pane/$n/ctl     rename, then save it
+  n=$(cat $m/pane/new)                         make a pane (each open makes one), take its serial
+  printf 'text\n' >> $m/pane/$n/body           append to it (> replaces it all)
   echo 'Msg hello' > $m/exec                   show text in the editor
-  echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl   rename every foo, one undo step (sam's commands)
+  echo 'Edit ,x/foo/c/bar/' > $m/pane/$n/ctl   sam's Edit, one undo step; an x that matches nothing succeeds
+  echo /re/ > $m/pane/$n/addr; printf new > $m/pane/$n/data   replace the next match
   exec 3<>$m/log; echo follow >&3; cat <&3     what happened lately, then wait for more
-  echo Tty > $m/pane/$n/ctl; cat $m/index      a terminal in that pane's directory
-  exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3   exit N then its output; or busy: <program> is running, or error
-  printf 'ls\r' > $m/pane/$n/pty/data           type into a terminal; pty/status: cols rows busy
-  echo 'sig INT' > $m/pane/$n/pty/ctl          interrupt it; also winsize C R, and exec to restart
+  exec 3<>$m/pane/$n/pty/run; echo make >&3; cat <&3   exit N, then the output
 
-Pitfalls, one each:
-  Each open of pane/new makes another pane (ls, stat, find never do); rmdir closes even a dirty one.
-  addr: #n,#m, 12:5 or /re/ from the current address (^ $ per line), bytes snapped to runes; 0 resets; a miss refuses data.
-  data: > replaces the addr range, : > deletes it, a 2nd > inserts (addr moved); body: > empties all.
-  tag reads the path, then its own text; > replaces that text (default words too), >> appends.
-  A terminal's body is a history snapshot frozen per open, wrapped rows joined into lines; pty/data is the live stream.
-  exec: a non-builtin line (at most 1024 bytes) runs as a command pane (Shell -c), a shell's typed in; once whole.
-  Through a mount a malformed write is EINVAL, a failed one EIO or an errno that fits (ENOENT): log's err says why.
-  lock/unlock need a held ctl fd (exec 3>ctl); a held lock fails: retry. fs.md has the rest.
-  Repl python on a terminal's ctl: a .py body's clicks go to it (Repl - unbinds, Repl says it); tags stay commands.
+Traps:
+  A refused write says only EINVAL or EIO: the log's last err record says why.
+  addr is the pane's and moves on: each /re/ searches from the last, a data write leaves it past the text.
+  Through a mount, printf 'a\nb\n' arrives a line a write: send a block with one write, ending in a newline.
+  Pane words (Save Undo Del) go to pane/<n>/ctl, settings and session words to /ctl.
+  Exit, Restore, Del and get refuse once over unsaved text; the same word again discards.