Flatten the 9P control tree and move it out of fs.zig

The served tree loses the self/ level: /index /ctl /new /log /screen
/listeners /pane/<n>/... /os, with /src only in -Dembed-sources=true builds
(default off, on for esp32p4). ctl speaks the editor's own language with two
lowercase verbs, look TEXT and exec TEXT, plus acme's addr verbs; the new/
factory directory becomes one clone file; cons is gone (exec Msg); name and
sel are files; stats report real lengths, modes and mtimes; /log streams
pane new/del/rename/save events. The tree code lives in src/ninep/
(tree, pane, ctl, addr, pty, events, screen, sources); fs.zig keeps host
access, mounts, resolution and find/grep. Same engine and transports.
README (fs-help.txt) and docs rewritten; tests updated and extended.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

1 files changed, 37 insertions, 60 deletions

diff --git a/src/fs-help.txt b/src/fs-help.txt
index eeb000cc..a0a84b28 100644
--- a/src/fs-help.txt
+++ b/src/fs-help.txt
@@ -1,65 +1,42 @@
 Pardes control filesystem
 =========================
-The mount root contains self/ (this editor) and os/ (host files).
-This guide is available as self/README and self/new/README.
-Examples below run inside a Tty9p shell, where PARDES_MOUNT is set.
+README      this guide
+index       one line per pane: serial, kind (text|term|pdf|image), dirty flag, name
+ctl         write commands; read the serials the last command made or touched
+new         reading it creates one empty pane and answers its serial
+log         one line per editor event (new/del/rename/save <serial> <name>); reads wait
+screen      rendered screen as JSON, frozen from open to close
+listeners   the session's dial addresses
+pane/<n>/   name body tag ctl addr data xdata sel errors event, and pty/ for terminals
+os/         the host filesystem
+src/        the editor's own sources, only in a -Dembed-sources=true build
 
-Explore
--------
-  ls "$PARDES_MOUNT/self"
-  cat "$PARDES_MOUNT/self/index"
-  ls -l "$PARDES_MOUNT/self/new"
-  ls "$PARDES_MOUNT/self/pane"
+Commands, on /ctl (applied at the active pane) or on pane/<n>/ctl (at that pane):
+  look TEXT   a right click: open a file, a file:12 location, a directory, a URL
+  exec TEXT   a middle click: an editor command word (Save Del New Newcol Mount Unmount
+              Dump Restore Msg Find Grep Tty ...), or a shell command for the pane's terminal
+Below, $m is the mount point (PARDES_MOUNT in a Tty9p shell; 9ns and 9p work too):
 
-index lists panes: serial, tag length, body length, reserved zero,
-modified flag, then tag text. Use the serial in self/pane/<serial>/.
-screen is rendered screen JSON; listeners lists the session addresses.
-cons accepts text to display in the editor.
+  cat $m/index                                 which panes exist
+  n=$(cat $m/new)                              make a pane, remember its serial
+  echo 'look /etc/hosts:3' > $m/ctl; cat $m/ctl   open a file, see the pane it went to
+  printf 'text\n' > $m/pane/$n/body             append to a pane (>| truncates first)
+  cat $m/pane/$n/name; echo notes.txt > $m/pane/$n/name        read, then rename
+  echo 'exec Save' > $m/pane/$n/ctl         save it (exec Del closes it)
+  echo 'exec Msg hello' > $m/ctl                show text in the editor
+  echo '#0,#5' > $m/pane/$n/addr; echo NEW > $m/pane/$n/data   replace bytes 0..5
+  echo 'dot=addr' > $m/pane/$n/ctl; cat $m/pane/$n/sel   select the range, read it
+  cat $m/log                                   block until a pane is made, renamed, saved or closed
+  cat $m/pane/$n/event                         hold it open to own that pane's clicks
+  echo 'exec' > $m/pane/$n/pty/ctl             restart a shell; also winsize C R, sig INT
 
-Create a pane
--------------
-new/ lists the same files as a scratch pane, plus this README.
-Listing, walking and statting these paths do not create anything.
-OPENING any file except README creates one scratch pane below the active pane.
-Each open creates a separate pane, even if you open the same path again.
-
-  cat "$PARDES_MOUNT/self/new/ctl"
-
-This creates a pane and prints its control information, beginning with its
-serial. Use self/pane/<serial>/ for all subsequent operations on that pane.
-To create a pane and write its initial text in one operation:
-
-  printf 'Hello from the shell\n' > "$PARDES_MOUNT/self/new/body"
-
-Reading all files recursively would open factories and create panes.
-Use ls or stat to inspect them; read README for this guide.
-
-Work with an existing pane
---------------------------
-Replace <serial> with a number from index or new/ctl:
-
-  cat "$PARDES_MOUNT/self/pane/<serial>/body"
-  printf 'Replacement text\n' > "$PARDES_MOUNT/self/pane/<serial>/body"
-  printf 'More text\n' >> "$PARDES_MOUNT/self/pane/<serial>/body"
-  printf 'name notes.txt\n' > "$PARDES_MOUNT/self/pane/<serial>/ctl"
-
-body       buffer text; for terminals, reads history and writes child input
- tag       editable pane tag
- ctl       control information on read; newline-separated commands on write
- addr      address range; write #0,#5 to select the first five bytes
- data      read from addr onward, or replace the range selected by addr
- xdata     read only the range selected by addr; writes replace that range
- rdsel     read the editor selection
- wrsel     replace the editor selection
- errors    write diagnostics
- event     pane interaction events; opening intercepts Look/Exec events
-
-Common ctl commands: name PATH, put (save), get (reload), dot=addr,
-addr=dot, look PATH, del (close, refusing dirty text), delete (force close).
-Reload and force close can discard unsaved changes.
-
-Terminal panes also expose pty/ctl, pty/status and pty/data.
-Writing pty/data sends terminal input; use carriage return to submit a command.
-Reading pty/data streams new output; read body for a history snapshot.
-
-Embedded source files under self/src/ document the complete interface.
+Pitfalls, one each:
+  Every open of new makes another pane, so `cat $m/new` twice makes two.
+  ls, stat and find create nothing; reading log, event or pty/data blocks until something happens.
+  exec Del closes a pane even when it is dirty; index shows the dirty flag first.
+  look and exec are lowercase verbs; the words after exec are the editor's capitalized commands.
+  ctl also takes acme's addr verbs (addr=dot dot=addr limit=addr clean dirty get show ...), one per line.
+  Writing body appends; open it with truncation to replace; writes are whole UTF-8 sequences.
+  A terminal's body is a history snapshot frozen per open; pty/data is the live stream.
+  screen is frozen per open handle as well; reopen it for a fresh frame.
+  A command that fails is reported in the editor, not as a write error; a malformed line fails the write.