The docs: which writes fail, mark for one undo step, directory looks, the skill's log line

Round 15's doc findings: one table of which files fail a write and which
only say so; mark to make a loop's data writes one undo step; the
100-byte scratch exemption and the chord write-back in the skill; the
skill's log line with ask, answer, changed, newcol, delcol and the
restored records; a directory looked at opens a terminal that runs ls,
and why; a plain word in a terminal is listed in +Search, its rows
@p<serial>.

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

1 files changed, 23 insertions, 4 deletions

diff --git a/docs/fs.md b/docs/fs.md
index 14b82d48..0a7cee7d 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -313,11 +313,16 @@ same tree without leaving the process.
 `/look` and `/exec` are the editor's two clicks, one per line of a write:
 
 - a line written to `look` is a right click on it: a path opens a file,
-  `file:12` jumps to a line, a directory opens a shell there, a URL opens in
-  the browser, and a plain word, as acme's look3 does, selects its next
+  `file:12` jumps to a line, a directory opens a terminal there that runs
+  `ls` once (pardes has no directory listing pane of acme's kind; a shell
+  in it is where one goes on from a directory), a URL opens in the
+  browser, and a plain word, as acme's look3 does, selects its next
   place in that pane after the dot, wrapping at the end, opening nothing
   (`LookWord list` on the root ctl lists every place in a `+Search` pane
-  instead, as pardes did before; `LookWord search` is the default).
+  instead, as pardes did before; `LookWord search` is the default). In a
+  terminal, which has no dot to go on from, a plain word is always listed
+  in a `+Search` pane, its rows naming the terminal as `@p<serial>:<line>`,
+  and look reads that pane back.
 - a line written to `exec` is a middle click: a command word from
   `src/builtins.zig` (`Save`, `Del`, `New`, `Newcol`, `Mount NAME DIAL`,
   `Unmount NAME`, `Dump`, `Restore`, `Msg TEXT`, `Find`, `Grep`, `Tty`, ...;
@@ -622,7 +627,21 @@ missed its target cannot then write at the last one.
 The three flag files `dirty`, `mark` and `scroll` read `0` or `1` and take
 `0` or `1`: whether the buffer differs from its file, whether a write pushes
 an undo point (writing `1` pushes one now), and whether a write scrolls the
-pane.
+pane. Every `data`, `xdata` or `body` write is an undo step of its own
+while `mark` is 1; to make a loop's writes one step, write `1` (an undo
+point here), then `0`, the writes, then `1` again.
+
+Which writes fail and which only say so:
+
+| file | a write fails (the errno, an `err` record) | said on the message row and logged as `msg`, the write succeeding |
+|---|---|---|
+| `ctl` (root, pane, column) | a malformed line, an unknown word, a builtin's failure, a refusal (Modified...) | what a builtin says when it works |
+| `look`, `exec`, `tagexec`, a column's `exec` | a control character, a line over 1024 bytes, no pane slot or room | a look that finds nothing, a command's own failure, a builtin's failure |
+| `addr`, `dot`, `limit` | an address that does not evaluate | -- |
+| `data`, `xdata` | no address (the last one failed) | -- |
+| `body`, `tag`, `name`, `sel`, the flag files | a bad value, a pane gone | -- |
+| `event` | a malformed record, a range past the text | what the action it runs says |
+| `pty/ctl`, `pty/data`, `pty/run` | a malformed verb, a size out of range, a pane that is no terminal | -- |
 
 `tag` reads the whole tag as the pane shows it: the computed path or PDF
 page (no mark for unsaved text: the grip shows that, and `dirty` says it),