docs: the README and skill answer what dogfooding asked

A first-time user through a mount could not find how to get a terminal,
read path++text as a typo, did not know > on data replaces only the
addressed range, which regexps addr takes, that lock fails fast, what
errors is, where an unknown exec word goes (typed into a terminal, not an
error), that new panes are +New and a column's last pane leaves one, or
which 9ns mount other processes can see. The README (still 45 lines),
docs/fs.md and the skill now say.

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

1 files changed, 19 insertions, 19 deletions

diff --git a/src/fs-help.txt b/src/fs-help.txt
index 3f7357d4..8db1e288 100644
--- a/src/fs-help.txt
+++ b/src/fs-help.txt
@@ -1,45 +1,45 @@
 Pardes control filesystem
 =========================
 README      this guide
-index       one line per pane: serial, kind (text|term|pdf|image), dirty flag, name
+index       one line per pane: serial, kind (text|term|pdf|image), dirty flag, name (+New if unnamed)
 status      pid, version and pane count
 look        write a line: a right click on it at the active pane; read: the serials it touched
 exec        write a line: a middle click, an editor command word or a shell line; read the same
-log         recent events: new/del/rename/save <serial> <name>, msg <serial|-> <text>; write follow to wait
+log         events: new/del/rename/save <serial> <name>, msg <serial|-> <text>, err <serial|-> <why>
 screen      rendered screen as JSON, frozen from open to close
 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 one, or Newcol, Dump; Kill QUITS
 commands    every builtin: its word, arg if it takes one, and root or pane: which ctl takes it
-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, and pty/ for terminals; rmdir closes it
+pane/new    open it to make a pane (named +New); the read answers that pane's serial
+pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll errors (write-only:
+            appended to its directory's +Errors pane) event look exec, pty/ on terminals; rmdir closes
 os/, src/   the host filesystem; the editor's own sources (-Dembed-sources=true builds only)
 
-Below, $m is the mount point (PARDES_MOUNT in a Tty9p shell; 9ns and 9p work too):
+Below, $m is the mount (/mnt/9p/pardes/<pid> via 9ns --mntgen; 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 (>| truncates first)
-  cat $m/pane/$n/name; echo notes.txt > $m/pane/$n/name        read, then rename
-  echo Save > $m/pane/$n/exec                  save it; rmdir $m/pane/$n closes it
+  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
   echo 'Msg hello' > $m/exec                   show text in the editor
-  echo '#0,#5' > $m/pane/$n/addr; printf NEW >> $m/pane/$n/data  replace bytes 0..5
+  echo '/^fn/' > $m/pane/$n/addr; printf NEW > $m/pane/$n/data     replace what addr matched
   cp $m/pane/$n/addr $m/pane/$n/dot; cat $m/pane/$n/sel   select the range, read it
   exec 3<>$m/log; echo follow >&3; cat <&3     what happened lately, then wait for more
   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
+  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, 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
 
 Pitfalls, one each:
-  Each open of pane/new makes another pane (ls, stat, find never do); a reread names the same.
-  rmdir closes a pane even when it is dirty; index and pane/<n>/dirty show the flag.
-  addr, dot and limit read the same pair of offsets they take, so cp between them works.
-  dirty, mark and scroll read "0" or "1" and take "0" or "1"; truncating limit lifts it.
-  body: >> appends, > replaces it all. data: > replaces (and : > deletes) just the addr range.
-  tag reads path++text; writes append to the text (newlines too); truncating clears it, and dot or addr.
+  Each open of pane/new makes another pane (ls, stat, find never do); rmdir closes even a dirty one.
+  addr takes #n,#m or sam-style /regexp/ (^ $ per line); a failed one makes data refuse until reset.
+  data: > replaces just the addr range and : > deletes it; body: > empties the whole buffer.
+  tag reads the path, then the tag's own text; writes append to that text; truncating clears it.
   A terminal's body is a history snapshot frozen per open; pty/data is the live stream.
-  A failing command is reported in the editor and in log, not as a write error; a bad line fails the write.
-  pane/<n>/ctl: acme's status line + current; takes get, lock/unlock (on a held fd) and pane builtins (Del).
+  exec: a word no builtin knows is typed into a terminal in the pane's directory, and not an error.
+  A refused write reads as EINVAL through a mount: the log's err record says why.
+  lock/unlock on a pane's ctl need a held fd (exec 3>ctl); a lock someone holds fails: retry.
+  Closing a column's last pane leaves a +New in its place; Delcol closes the column.