Recipes read look and exec on the open they wrote, the reference says a fresh open reads anyone's last answer, and /pager is documented

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

2 files changed, 14 insertions, 4 deletions

diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 745d7a47..cf5e66d0 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -18,6 +18,7 @@ one-screen summary of this page.
 /index         a line per pane: serial kind dirty name column
 /status        pid, version, panes
 /look /exec    write a line: a right / middle click at the active pane; read: the serials touched
+/pager         write a directory: its one +Pager, made or emptied; read: its serial
 /log           the event log; write `follow` to wait for more
 /screen        the rendered screen as JSON
 /listeners     dial addresses
@@ -90,8 +91,9 @@ refused.
 *Answers.* Reading #file("look"), #file("exec") or #file("tagexec") answers
 the serials the last command made, or else the pane it acted on or
 focused, one a line; nothing when it did none of these (#word("Newcol") at
-#file("/tagexec")). An open that wrote reads its own last answer; an open
-that never wrote reads the session's last. A read is a stream: once read,
+#file("/tagexec")). A read answers the panes touched by this open's last
+write. An open that never wrote reads the session's last answer, from
+whichever client wrote it, so read on the open you wrote. A read is a stream: once read,
 the next read on that fid is EOF until the next write (or seek to 0). With
 other clients about, write and read on one open:
 #cmd("exec 3<>$m/look; echo x >&3; cat <&3; exec 3<&-")
@@ -744,6 +746,10 @@ at 200, ending in `…`. Control characters become spaces.
   closed one at its last (a PDF's is its page); a look at a row reopens it
   there.
 - #file("/status"): `pid`, `version`, `panes`.
+- #file("/pager"): write a directory (empty means the session's); a read on
+  the same open answers the serial of that directory's one `+Pager`, made
+  or emptied for it. It takes one directory a write. This is what
+  `pardes -` uses.
 - #file("/listeners"): the session's dial addresses, a line each
   (#doc("building", section: "listeners")).
 - #file("/os/"): existing regular files take read, write and truncation to
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index 8cb03a8b..555c6b43 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -54,14 +54,14 @@ and name a text pane by its serial (from #file("index"), or one you made):
 
 #pairs(
   [look around], [#cmd("cat $m/index\ncat $m/layout\ncat $m/focus\ncat $m/commands")],
-  [open a file at a place], [#cmd("echo \"$PWD/main.zig:120\" > $m/look; cat $m/look # where it went\necho 'main.zig:0/fn main/' > $m/look # the first match")],
+  [open a file at a place], [#cmd("exec 3<>$m/look; echo \"$PWD/main.zig:120\" >&3; cat <&3; exec 3<&- # where it went\necho 'main.zig:0/fn main/' > $m/look # the first match")],
   [make, fill, name, save], [#cmd("n=$(cat $m/pane/new) # one pane per open\nprintf 'hello\\n' > $m/pane/$n/body # > replaces, >> appends\necho \"$PWD/notes.txt\" > $m/pane/$n/name\necho Save > $m/pane/$n/ctl\nrmdir $m/pane/$n # close it")],
   [say something], [#cmd("echo 'Msg hello' > $m/exec")],
   [replace everywhere], [#cmd("echo 'Edit ,x/foo/c/bar/' > $p/ctl\ngrep -c foo $p/body # 0: none left")],
   [replace one match], [#cmd("echo /old/ > $p/addr && printf new > $p/data")],
   [delete line 3], [#cmd("echo 3 > $p/addr; : > $p/data")],
   [select line 3, read it], [#cmd("echo 3 > $p/addr; cp $p/addr $p/dot; cat $p/sel")],
-  [run a command], [#cmd("echo 'make test' > $m/exec; c=$(cat $m/exec) # its pane\nuntil grep -q ') exit ' $m/pane/$c/tag; do sleep 0.2; done\ngrep -o 'exit [0-9?]*' $m/pane/$c/tag")],
+  [run a command], [#cmd("exec 3<>$m/exec; echo 'make test' >&3; c=$(cat <&3); exec 3<&- # its pane\nuntil grep -q ') exit ' $m/pane/$c/tag; do sleep 0.2; done\ngrep -o 'exit [0-9?]*' $m/pane/$c/tag")],
   [run at a prompt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nexec 3<>$m/pane/$t/pty/run; echo ls >&3; cat <&3; exec 3<&-")],
   [type, interrupt], [#cmd("t=$(awk '$2==\"term\"{print $1; exit}' $m/index)\nprintf 'q' > $m/pane/$t/pty/data # \\r Enter, \\x03 Ctrl-C\necho 'sig INT' > $m/pane/$t/pty/ctl")],
   [ask the language server], [#cmd("echo /myFunc/ > $p/addr; echo dot=addr > $p/ctl\necho Hover > $p/exec # also Rename new, Symbols")],
@@ -164,6 +164,10 @@ pardes the editor of every program run there.
   (`exec 3<>$p/event` ... `exec 3<&-`), never `cat $p/event | while read`:
   the `cat` outlives the loop and holds #file("event") open, so the pane's
   next click goes to it and is lost.
+- Read #file("look"), #file("exec") or #file("pager") on the open you
+  wrote: a read answers the panes touched by this open's last write, and a
+  fresh open reads the session's last answer, from whichever client wrote
+  it (`exec 3<>$m/exec; echo cmd >&3; cat <&3; exec 3<&-`).
 - `tail -f log` never sees anything new: write `follow` on the open you
   read. Through a FUSE mount bash's `read -t` cannot time out: wrap the
   loop in `timeout`.