From 85d5467023a9db801d8ea2538e9611b71cd10d9d Mon Sep 17 00:00:00 2001
From: Gabriel Schneider <gbrls@0x4200.cafe>
Date: Tue, 29 Sep 2026 04:22:56 -0300
Subject: The docs: sam gotchas, Restore's log order and paths, stream reads,
 layout's current and active

Round 13's doc findings: a sam gotchas box in the skill ($-1 with and
without a final newline, N+1 at the end, ^/$ at the end, 2,1, y's leading
empty piece, c's literal &, columns from 1); the skill's Restore log order
made the true one (new, restore, restored, restoredcol); a relative
Restore path is looked for in DumpDir then the session's directory, and a
bare one takes the last dump; a follower sees each (xN) as a new line;
reading data or xdata moves addr; a second read of look/exec on one fd is
EOF (re-open or seek 0); /layout's current (the keyboard's column) and
active (acme's activecol) defined; no room, not no rows left; why a
scratch's dirty blocks nothing under 100 bytes; the changed record listed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/fs.md | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

(limited to 'docs/fs.md')

diff --git a/docs/fs.md b/docs/fs.md
index 3baac9c4..ab31e25b 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -111,7 +111,9 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC.
              keep their tag and 2 rows; a terminal's pty follows its pane on every resize
 /commands    every builtin: word, `arg` if it takes one, `root` or `pane` (the ctl that takes it), a setting's values
 /layout      one line per column, left to right: serial index x width current|notcurrent
-             empty|full pane-serials...; then active <serial>: the active column, where
+             (the column with the keyboard now) empty|full pane-serials...; then active
+             <serial>: acme's activecol, which the keyboard leaving for another column's
+             tag does not move, so the two can differ -- the active column, where
              pane/new and a look place a pane next (- when there is none)
 /tag         the workspace tag; > replaces it, >> appends, one line
 /tagexec     write a word: a middle click on it in the workspace tag; read as /exec
@@ -123,7 +125,7 @@ Existing Plan9port/v9fs clients need a userspace bridge for QUIC.
              64 panes (16 on the board); at that, every route that would open one -- this
              open, look, exec, New, Tty -- fails with `no space for a pane: 64 max` (ENOSPC through 9ns, which has
              no word for ENFILE) and an err
-             record, and look reads back empty; a column with no rows left for one
+             record, and look reads back empty; a column with no room for one
              (each pane keeps its tag and 2 rows) refuses it the same way,
              `no space for a pane in that column` (docs/tags.md)
 /pane/<n>/   name body tag ctl addr dot limit data xdata sel dirty mark scroll
@@ -160,7 +162,9 @@ unsaved text, a `+New` scratch of 100 bytes or more too, in one line,
 `<name>, <name>: Modified (Exit again to discard)`, and a second `Exit`
 with nothing edited since quits, throwing that text away; a scratch or a
 command's output under 100 bytes is not asked about, as acme's winclean
-asks about no small unnamed window; `Restore`, which replaces every pane,
+asks about no small unnamed window (so a scratch's `dirty` of 1 in `/index`
+blocks nothing until it holds 100 bytes: it has no file to be out of step
+with, and a few lines typed to try something are not work to lose); `Restore`, which replaces every pane,
 asks the same first -- `Dump` writes `pardes-<date>-<time>.zon` (UTC) in
 `DumpDir` (default `$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`)
 and logs `dump <path>`, and `Restore` with no path takes the last one; a
@@ -402,7 +406,10 @@ pane a look focused or the pane an exec acted on (even one it closed), one
 per line; a look that found text answers the pane the text is selected in,
 not the hits buffer it opened.
 
-The answer belongs to the open, as /net/tcp/clone's does: an open that
+Reads are a stream: once an open has read the answer, a second read on it
+gives EOF (on an open that wrote, until its next write); open it again, or
+seek to 0, to read it again. The answer belongs to the open, as
+/net/tcp/clone's does: an open that
 wrote reads what its own last write touched, from the start after each
 write, whatever offset the read comes at (a shell's `exec 3<>look` shares
 one offset between its write and its read, as with `pty/run`); an open
@@ -540,7 +547,8 @@ whole buffer. Truncating `data` is pardes's own: acme ignores OTRUNC there
 (editors/acme/fsys.c:543) and every write inserts. And as in acme a write
 leaves `addr` just past what it wrote, so a second `echo x > data` deletes
 the empty range there and inserts after the first rather than replacing it
-again; write `addr` before each replacement.
+again; write `addr` before each replacement. A read of `data` or `xdata`
+moves `addr` past what it read, as acme's does.
 `addr` belongs to the pane rather than to a client and keeps what was written
 until someone writes another, so writing an address and reading it back
 evaluates it, which is what acme(4) promises of its own `addr`. Unlike acme,
@@ -645,9 +653,12 @@ the `del` of a terminal whose shell exited by itself, `ask <serial> <what>
 <choices>` when a pane asks a question (answered by `answer` on its ctl),
 `answer <serial> <choice|->` when it is answered, by key or ctl, `-` for
 taken back or for its pane closing with the question standing,
-and `save <serial> <name>`,
+`changed <serial>` when a pane's file changed on disk under its unsaved
+edits (below), and `save <serial> <name>`,
 `dump <path>` when a Dump is written and `restore <path>` in a Restore's
-new log after its panes' `new`s, then `restored <old> <new>` for each pane,
+new log after its panes' `new`s (a relative Restore path is looked for in
+`DumpDir`, then in the directory pardes started in; a bare Restore takes the
+last dump this session wrote), then `restored <old> <new>` for each pane,
 mapping the serial it had to the one it has now, and `restoredcol <old>
 <new>` for each column, and `msg <serial|-> <text>`
 for every line the editor says (with `verbose` on, that includes each
@@ -668,7 +679,8 @@ itself, is counted rather than repeated (`err 3 addr: no match for regexp
 (x4)`: four in all, counting the first), so a client retrying a failing
 write does not push the rest out of the ring. A record a follower has
 already read is never rewritten: the next repeat is a line of its own
-carrying the running total, `(x5)`, and counting goes on from there. Through a kernel mount a client sees only an errno, which 9ns reads from the
+carrying the running total, `(x5)`, and counting goes on from there, so a
+follower sees each count as a new line. Through a kernel mount a client sees only an errno, which 9ns reads from the
 error's words (cloud9's 9ns/src/nine.zig, `enameToErrno`): a malformed write
 -- an unknown or ill-formed control message, `bad address syntax`, `bad
 regular expression` -- is EINVAL; a lock another open holds, EBUSY; a pane
-- 
cgit v1.3