fs.md answers round 6's doc questions

Event origins and the case of an action (tag x, body X), printf rather than
echo for >> tag, pty/run only at a shell prompt, why error not run gives no
reason, how to rerun a command pane, a shell's exit closing its pane, Kill
stopping a command pane's whole line, and restarting 9ns after a Restore.

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

1 files changed, 25 insertions, 13 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 6419ecc6..c4bdac1b 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -124,7 +124,9 @@ Restore puts a new editor under every client, so the write of it is
 answered and then every connection is hung up, their fids naming the old
 editor's panes (a 9ns older than cloud9 2a7137c could fail the write with
 ECONNRESET all the same, when another request's send met the hang-up
-before the answer was read; the log is the authority): dial again, and the new
+before the answer was read; the log is the authority): dial again -- a 9ns
+mount is one such connection, so after a Restore stop it and start 9ns
+again, or every file under it fails -- and the new
 log names the restored panes and
 `restore <path>`. The answer has 200 ms to leave before the cut, so a slow
 client may see only the cut; the log's `restore <path>` is what says the
@@ -248,7 +250,8 @@ same tree without leaving the process.
   `src/builtins.zig` (`Save`, `Del`, `New`, `Newcol`, `Mount NAME DIAL`,
   `Unmount NAME`, `Dump`, `Restore`, `Msg TEXT`, `Find`, `Grep`, `Tty`, ...),
   or anything else, a command line. Written at a terminal at its prompt it
-  is typed into that shell. From anywhere else -- a file, a scratch, a tag,
+  is typed into that shell (and a terminal whose shell exits, `exit` typed
+  or run, closes its pane). From anywhere else -- a file, a scratch, a tag,
   a terminal whose tty a program holds -- it runs as a command pane: a
   terminal whose child is the root ctl's `Shell` (fish unless set) run
   with `-c` and the line, in the pane's directory, with job control on
@@ -261,17 +264,18 @@ same tree without leaving the process.
   background job outlives the command: job control gives it a process
   group of its own, so the hangup the kernel sends the terminal's
   foreground group when the shell exits misses it. It survives the pane
-  closing or taking the next command too, but its writes to the terminal
-  then fail, so start one that must keep writing with `nohup` or its
-  output redirected. The directory's next command runs in
-  that pane once it is done, below what it showed, after a `% <line>` line;
+  closing too, but its writes to the terminal then fail, so start one that
+  must keep writing with `nohup` or its output redirected. The directory's
+  next command runs in that pane once it is done and nothing holds its pty, below what it showed, after a `% <line>` line;
   one still running gets a second pane. Before the next command the pane
   leaves any alternate screen and turns off the modes a program left on
   (mouse reports, bracketed paste, a hidden cursor); a command that clears
   the screen and its scrollback (`clear`, ED3) erases the history above it. A command pane's own exec starts
   the next command there too. The log says `run <serial> <line>` and `exit
-  <serial> <N|?>`; `exec` reads back the command pane's serial; Kill ends
-  its whole process group; a line is at most 1 KB. A misspelled word is a
+  <serial> <N|?>`; `exec` reads back the command pane's serial; Kill stops
+  its whole line; a line is at most 1 KB. To run a command again, execute
+  its line again from its directory: `echo 'make test' > pane/<n>/exec` on
+  the command pane runs it there, below the last run. A misspelled word is a
   command that says so and ends `exit 127`. `echo Tty > pane/<n>/ctl` makes
   an interactive terminal in that pane's directory.
 
@@ -488,7 +492,8 @@ newlines included, and a tag with more than one line takes a row per line on
 screen; truncating `tag` clears it, as acme's `cleartag` does -- the default
 words (`Del`, `Put` and the rest) with it, since they are that text until
 you edit it, so `echo Make > tag` leaves only `Make`; append with `>>` to
-keep them. The clearing is an edit of the tag like a typed one and its undo
+keep them, with `printf ' Make' >> tag`: `echo` ends its word with a
+newline, which starts a new line of the tag. The clearing is an edit of the tag like a typed one and its undo
 history is kept: `u` in the tag brings back the text it cleared, words
 included.
 
@@ -535,8 +540,11 @@ pane is being made can precede that pane's `new`; panes present at boot are
 recorded before anything else.
 Control characters in a record become spaces, so a record is one line.
 (An `event` record is not: acme's `<origin><action><q0> <q1> <flag> <n>
-<text>\n`, whose text may hold newlines; read `n` bytes of it rather than
-up to a newline -- bytes here, where acme counts runes. Every offset and
+<text>\n`, whose text may hold newlines. The origin is `E` (a 9P write to body or tag), `F` (other
+files, the editor's own lines), `K` (the keyboard) or `M` (the mouse); the
+action's case says where: `x`/`l` a click executed or looked at in the tag,
+`X`/`L` in the body, `I`/`D` text put in or taken out of the body, `i`/`d`
+of the tag. Read `n` bytes of the text, not up to a newline -- bytes here, where acme counts runes. Every offset and
 count pardes serves is in bytes, `#n` and `q0`/`q1` too; the event count
 follows them rather than switch alone, so an acme library reads pardes
 correctly for ASCII text and not beyond it. A `#n` that falls inside a
@@ -583,7 +591,9 @@ are read so that the answer costs the editor a bounded amount. `exit ?` is a
 command whose end mark carried no status, which is not a success; `error out
 of memory` is an answer that could not be made. The header is always the
 whole first line. It reads
-`busy` at once when a command is running or text is typed at the prompt,
+`busy` at once when a command is running or text is typed at the prompt
+-- a run is a line typed at the shell's prompt, so a program holding the
+terminal (a REPL, `less`) takes none: write to `pty/data` for it --
 which is also when the third field of `pty/status` reads 1. `pty/status` is
 one line, three right-aligned fields and a newline: the pty's columns and
 rows, then busy (0 or 1). The size, and `pty/ctl`'s `winsize` read back, is
@@ -597,7 +607,9 @@ could not instrument, or a startup that hangs) leaves such a line waiting
 for ever: cancel the read (interrupt it, or close the open) to give up;
 `error not run` when the shell refused
 the line without running it (a fish syntax error; the line is taken back off
-the prompt); `exit N` and what it printed when the line ended the shell
+the prompt): the shell's marks say only that it did not run, so the answer
+carries no reason or code, and the shell's own complaint is in the pane's
+body (`tail body`); `exit N` and what it printed when the line ended the shell
 itself (`exit 3`, or `echo bye; exit 3`): its terminal closes, and a read
 of the run's open still answers after the pane is gone; `error shell gone`
 when the pane closed or its shell was replaced, or the shell went without