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]>

1 files changed, 8 insertions, 2 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