From 627d4fba9cc958b1c07c6f050825658e567ea4de Mon Sep 17 00:00:00 2001
From: Gabriel Schneider <gbrls@0x4200.cafe>
Date: Mon, 28 Sep 2026 13:39:58 -0300
Subject: docs: what dogfooding asked of the second round

The served README, the skill and docs/fs.md now say where an address search
starts, that an event record's text may hold newlines and is read by its
count, that truncating tag clears its default words too (append to keep them,
u in the tag to get them back), how Dump and Restore behave and where dumps
go, that Kill stops only the foreground job (the rest of 'sleep 30; echo done'
still runs) and that Joincol needs a column to the right. The skill and
fs.md had Collapse as a column word; it folds the pane it is given.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .agents/skills/pardes-9p/SKILL.md | 17 +++++++++++++----
 docs/fs.md                        | 30 ++++++++++++++++++++----------
 src/fs-help.txt                   |  6 +++---
 3 files changed, 36 insertions(+), 17 deletions(-)

diff --git a/.agents/skills/pardes-9p/SKILL.md b/.agents/skills/pardes-9p/SKILL.md
index 9b751a26..6b955eb4 100644
--- a/.agents/skills/pardes-9p/SKILL.md
+++ b/.agents/skills/pardes-9p/SKILL.md
@@ -62,9 +62,11 @@ $m/ctl        the settings, one a line as a write takes them; write a setting or
               (Newcol, Dump, Theme x; Exit QUITS the editor, Kill [word...] stops the
               commands pardes typed into terminals; Exit and Restore refuse once per
               unsaved pane, `<name>: Modified (Exit again to discard)`, and the same
-              word again DISCARDS that text -- not a retry, unlike lock's `file in use`); a pane's builtins (Del, Save f,
-              and the column words Delcol, Collapse, which act on that pane's column) go to
-              $m/pane/<n>/ctl
+              word again DISCARDS that text -- not a retry, unlike lock's `file in use`;
+              Kill signals only the foreground job, so of `sleep 30; echo done` the
+              echo still runs; Joincol needs a column to the right of the keyboard's);
+              a pane's builtins (Del, Save f, Collapse, which folds that pane, and the
+              column word Delcol, which closes that pane's column) go to $m/pane/<n>/ctl
 $m/commands   every builtin: `Word`, `Word arg`, then `root` or `pane` (which ctl takes it)
 $m/pane/new   open it to make a pane (a scratch named <dir>/+New), read names it;
               rmdir $m/pane/<n> closes it; closing a column's last pane leaves a +New there
@@ -220,7 +222,14 @@ terminal's body, also at `0 0` -- so it is not a
 passive logger. To have a record done, write it back: the short form
 `<origin><action><q0> <q1>\n` acts on that range's text, and the whole record
 as read acts on its text when the range is empty (the only way for a record
-at `0 0`). Chord reports need explicit handling.
+at `0 0`). Chord reports need explicit handling. A record is
+`<origin><action><q0> <q1> <flag> <n> <text>\n` and its text may hold
+newlines: read `n` bytes of text, never up to the next newline.
+A Restore puts a new editor under every client: the Restore write is
+answered, then every connection is hung up (their fids name the old
+editor's panes); dial again, and the new log names the restored panes then
+`restore <path>`. `Dump` writes `pardes-<date>-<time>.zon` under `DumpDir`
+(`~/.local/share/pardes` by default) and logs `dump <path>`.
 Read the event implementation before building an interceptor. Close handles in
 `finally`, and disconnect after a socket timeout. The service shares four
 connection slots and 32 screen/terminal-history snapshot handles.
diff --git a/docs/fs.md b/docs/fs.md
index 41b960f2..ae5e27ad 100644
--- a/docs/fs.md
+++ b/docs/fs.md
@@ -127,17 +127,21 @@ to its end mark (D); Kill sends its foreground job SIGTERM -- acme posts the
 "kill" note, which ends a process -- and never signals the shell itself;
 in a shell running without job control (`set +m`) the job shares the
 shell's group, so there is none to signal: Kill says `Kill: no job to
-signal`, and a write of it to `ctl` fails with that --
+signal`, and a write of it to `ctl` fails with that; and only the
+foreground job, so of `sleep 30; echo done` the `echo` still runs once the
+`sleep` is stopped --
 and reads every setting there is, one a line, in the words a write of it
 takes (`Verbose on`, `WindowOpacity 70`, `PanelSlide off`, `DumpDir` bare
 for the default directory, `LocationsConfig ...`), so writing what it reads
 back changes nothing; platform and startup facts are `/status`'s and the
 Config window's, not settings. A pane's `ctl` takes the builtins that act on
-a pane (`Del`, `Save f`, `Collapse`, `Find pat`) beside acme's `get`, `lock`
-and `unlock`. The column words are pane words too, acting on the column that
-pane is in: `Delcol`, `Collapse`, `DelAbove`, `DelBelow` and the focus moves
-`Left`/`Right`/`Up`/`Down` from it. `Joincol` and `Newcol` are the root's:
-they act on the column of the pane with the keyboard. The words are case-sensitive and do not alias: acme's verbs
+a pane (`Del`, `Save f`, `Collapse`, which folds that pane, `Find pat`)
+beside acme's `get`, `lock` and `unlock`. The column words are pane words
+too, acting on the column that pane is in: `Delcol`, `DelAbove`, `DelBelow`
+and the focus moves `Left`/`Right`/`Up`/`Down` from it. `Joincol` and
+`Newcol` are the root's: they act on the column of the pane with the
+keyboard, and `Joincol` needs a column to its right (`Joincol: no column to
+the right`). The words are case-sensitive and do not alias: acme's verbs
 are lowercase and the builtins keep their tag spelling, so `Get` is no word
 and `del` none either.
 
@@ -344,9 +348,12 @@ pane.
 `tag` reads the whole tag as the pane shows it: the computed path, dirty
 marker or PDF page, then the text you may edit. A write appends to that text,
 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 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.
+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
+history is kept: `u` in the tag brings back the text it cleared, words
+included.
 
 Stats report real lengths for `index`, `status`, `look`, `exec`, `listeners`,
 `name`, `body`, `tag`, `sel`, `ctl`, the range files and the flag files, and
@@ -385,7 +392,10 @@ acme's `errors` only takes text, and one record stream is simpler to watch
 than a file per pane. A `msg` said while a
 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
+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.) An
 open freezes the ring's text the way `/screen` freezes a frame: reads walk it
 and end. Writing `follow` to that same open makes reads past it wait for the
 next record, one per read; a follower the ring outran reads `lost N` first.
diff --git a/src/fs-help.txt b/src/fs-help.txt
index 4633d91c..7e869f9e 100644
--- a/src/fs-help.txt
+++ b/src/fs-help.txt
@@ -9,7 +9,7 @@ log         events: new/del/rename/save <serial> <name>, msg <serial|-> <text>,
 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         settings, one a line as a write takes them; or Newcol, Dump, Exit (quits), Kill (stops cmds)
+ctl         settings, one a line; or Newcol, Dump, Exit (quits; asks once), Kill (stops the fg job)
 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 (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:
@@ -35,9 +35,9 @@ Below, $m is the mount (/mnt/9p/pardes/<pid> via 9ns --mntgen; PARDES_MOUNT in a
 
 Pitfalls, one each:
   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.
+  addr takes #n,#m or /regexp/ from the current address (^ $ per line); a failed one refuses data.
   data: > replaces the addr range, : > deletes it, a 2nd > inserts (addr moved); body: > empties all.
-  tag reads the path, then the tag's own text; writes append to that text; truncating clears it.
+  tag reads the path, then its own text; writes append; truncating clears it, default words too.
   A terminal's body is a history snapshot frozen per open; pty/data is the live stream.
   exec: a word no builtin knows is typed into a terminal in the pane's directory, and not an error.
   Through a mount a malformed write is EINVAL, a well-formed one that fails EIO: log's err says why.
-- 
cgit v1.3