The docs take round 36: empty names, get as an undo step, what a Dump keeps and Restore reads, Find and Grep caps and notes, the ctl read's collapsed and fit/tint, PDF search hits, ./x misses, 1 MiB lines, DumpDir, bad dials, /pager files, rename previews, Lspinfo, and --wait from an agent

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

2 files changed, 52 insertions, 25 deletions

diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 9f45350b..8bab9e56 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -139,8 +139,15 @@ a terminal there. A URL opens in the browser. #word("Find") `name` lists the fil
 below the pane's directory whose names hold it; #word("Grep") `text` lists
 the lines that contain that text, literally (ASCII case aside, no regular
 expression), in files under every pane's directory. Both land in `+Search`,
-a place per row for #btn("B3"); a directory the walk cannot open is
-skipped, and the list ends `N directories skipped: permission denied`.
+a place per row for #btn("B3"). Grep reads at most 256 KiB of a file and
+stops at 512 hits, Find at 512 names; the walk stops at 20000 files or
+100000 entries, 16 deep, and passes over `.git`, `.jj`, `target`,
+`node_modules`, `.venv`, `__pycache__`, `.zig-cache` and `zig-out`. A cap
+hit, or a directory it could not open, is said at the end (`cut at 512
+hits`, `N files read only in part (first 256 KiB)`, `walk cut at N
+entries`, `N directories skipped: permission denied`). A search that finds
+nothing and skipped nothing fails, `Grep: pattern not found`, and leaves
+the `+Search` as it was.
 
 A relative path is looked for where the click was, then where you have
 been: first in the looking pane's own directory, then in the directory of
@@ -246,7 +253,9 @@ search or write, `permission denied`) is printed and the command exits 1.
 `--` ends the options: `pardes -- -name` opens a file named `-name`.
 
 `pardes --wait FILE` (`-w`) returns when the pane showing FILE is closed
-(exit 0) or the session goes away (exit 1), as acme's `E` does. Set
+(exit 0) or the session goes away (exit 1), as acme's `E` does. With
+`$PARDES_9P` set but no pane of its own (an agent's `EDITOR`) it opens FILE
+in that session and waits there. Set
 `EDITOR='pardes --wait'` (`GIT_EDITOR` follows it), and `git commit`,
 `crontab -e` and fish's Alt-E open in a pane and read the file once you
 close it. Bare `pardes` inside a pane refuses and names `--nested`, which
@@ -285,8 +294,10 @@ One answer jumps; several open a list where #key("Enter") on a row goes
 there. In insert mode #key("Tab") after a `.` lists the candidate
 declarations and inserts nothing. A format or a rename within the file is
 one undo step. A rename that reaches other files applies nothing: it opens
-a `+Search` preview of the edits, telling the server first of every open
-file of its language so those are included. A server is `not started yet`
+a `+Search` preview of the edits. So does one the server answers in this
+file alone while another open file of its language still holds the old
+name, with a row per such file (zls does this renaming at a declaration;
+from a use it reaches every file). A server is `not started yet`
 until its first query.
 
 = Sessions <sessions>
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index feabd4e2..a7f2c869 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -108,8 +108,9 @@ lines are skipped. A line runs once it is whole: a write's last line runs
 without its newline, except where a mount cut the write
 (#doc("building", section: "writes-through-a-mount")); end a write with a newline when its result
 matters. An `Edit` whose `{` or `a`/`c`/`i` text is still
-open waits for the next write on that open. A line held past 1 MiB is
-refused.
+open waits for the next write on that open. A line or Edit block over
+1 MiB is refused once (EINVAL), and the rest of it, through its newline,
+is dropped.
 
 *Answers.* Reading #file("look"), #file("exec") or #file("tagexec") answers
 the serials the last command made, or else the pane it acted on or
@@ -187,8 +188,10 @@ files.
 - A whole line of a diff pane written to #file("look") is the look a
   #btn("B3") click on its first column makes. The line is matched in the
   pane from its cursor row on, wrapping, and the first match wins.
-- On a PDF pane `:N:H` is page N, search hit H, as `file.pdf:N:H` is.
-  Only a `+PdfSections` row's second number is a section,
+- On a PDF pane `:P:H` is hit H of the pane's search on page P, as
+  `file.pdf:P:H` is; a hit not there, or any H with no search active, is a
+  miss, `has no search hit H on page P`. Only a `+PdfSections` row's
+  second number is a section,
   `file.pdf:PAGE:SECTION`, and only such rows are checked against the
   outline: a section not there, or not on that page, is a miss.
 - A plain word selects its next place after dot, wrapping. `LookWord list`
@@ -201,7 +204,8 @@ was written when nothing by that name exists; `<path>:99 has no line 99`
 for a line past a file's end, `<path> has no page 99` for a PDF's page;
 `<path>: no match for regexp` or `<path>: address out of range` when an
 address fails), opens nothing, and leaves #file("look") reading empty; the
-write succeeds. A look whose address fails says so and leaves open no file
+write succeeds. A `./x` or `../x` that is not there is such a miss too
+(`look: ./x: no such file`). A look whose address fails says so and leaves open no file
 it opened. A look of `file:12:` reads as `file:12`: a trailing colon is
 dropped, as a click leaves it off. A path too long to repeat whole gives up
 its middle to `…`.
@@ -222,8 +226,10 @@ A line written to #file("exec") is a #btn("B2") click:
   files applies nothing: it opens a `+Search` preview of the edits, which
   is the pane the write answers, and says how many it lists;
   #word("Diagnostics") and #word("Symbols") list the file's in `+Search`;
-  #word("Lspinfo") says which server serves the file and its state (`not
-  started yet` until its first query starts it);
+  #word("Lspinfo") fills `+Lsp`, the pane its write answers, with which
+  server serves the file and its state (`not started yet` until its first
+  query starts it, `<server> failed recently; retry in Ns` while it backs
+  off);
   #word("Lspwhy") narrates the last query step by step (in `+Lsp`). The
   write returns once the answer is in; a pane with no file is refused.
 - acme's words run as pardes's where it has one (`Put` is #word("Save"),
@@ -275,11 +281,11 @@ Explicit paths skip that search:
 )
 
 `--mount=peer=work` or `Mount peer <dial>` mounts a session name, an
-absolute socket path, `unix!/path`, `tcp!IP!port` or `quic!IP!port`;
+absolute socket path, `unix!/path`, `tcp!host!port` or `quic!host!port`;
 `Unmount peer` removes it. #word("Mount") dials at once and fails if
 nothing answers (`dial failed: no answer`, `timed out`, `hung up`); with no
-dial it is `wrong #args`, and a dial that is no address `bad dial address`,
-both EINVAL. There are eight named mounts; `os` and `self` are reserved.
+dial it is `wrong #args`, and any other `x!y` `bad dial address`, both
+EINVAL. There are eight named mounts; `os` and `self` are reserved.
 #word("Unmount") refuses a mount a pane, a working directory or a pending
 Save still uses. Mounts are dumped.
 
@@ -318,7 +324,12 @@ Writes take settings and session builtins (`scope = .session` in
   wrote). The Restore write is answered, then *every connection is hung
   up*: dial again, and restart a 9ns mount. The new log has a `new` per
   pane, `restore <path>`, then `restored <old> <new>` per pane and
-  `restoredcol <old> <new>` per column. A Restore that fails says why in
+  `restoredcol <old> <new>` per column. A dump keeps an unsaved pane's
+  text and the hash of the file it was read against; a clean file pane's
+  text is read from disk at Restore, so a file changed since comes back as
+  it is now. An unsaved one whose file changed comes back with its own
+  text, marked changed on disk, and its first Save asks before
+  overwriting. A PDF's fit and tint are kept too. A Restore that fails says why in
   the parser's words, a ZON error with its line (`line 3: expected ','`),
   so the errno a mount gives depends on them (usually EIO): read the `err`
   record for why. A ThemeFile the dump names that fails to load changes
@@ -360,7 +371,7 @@ word clicked in a tag does. The same lines go in the startup file
   [`LookWord search|list`], [`search`: a looked-at word selects its next place, or lists all in `+Search`],
   [`TermImages real|petscii`], [`real`: a new terminal draws its program's kitty graphics (yazi's previews) as pixels where the shell can; #word("Petscii") flips one terminal; a tty under a terminal without kitty graphics draws them as glyph art either way],
   [`Shell <name or path>`], [`$SHELL` when it is executable, else `/bin/sh`: the shell the next terminal and command pane run; a bare name is looked for in the usual bin directories, not `$PATH`; bare #word("Shell"): `$SHELL` if it is executable, else `/bin/sh`],
-  [`DumpDir <dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes; bare returns to the default],
+  [`DumpDir <dir>`], [`$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes`: where #word("Dump") writes, an absolute or `~` path to a directory that may be written (made if missing); a relative one, or one under a directory that may not be written, is refused; bare returns to the default],
   [`TreeContext`], [off: sticky declaration headers in a source pane (per pane, dumped)],
   [`TreeContextTagStyle`], [on: draw those headers in the tagline style],
   [`LocationsConfig ...`], [the layout of #word("Grep"), search and language-server results (below)],
@@ -473,7 +484,8 @@ renames the buffer (relative to the pane's directory) and marks nothing
 dirty; #word("Save") then writes under the new name. A name takes any byte
 a file name can hold, blanks, control bytes and bytes not UTF-8 included,
 so what #file("name") reads writes back as it was; refused (EINVAL) are
-only a second line and a NUL (`bad character in file name: a NUL`). Up to
+an empty name, a second line and a NUL (`bad character in file name: an
+empty name`, `...: a NUL`). Up to
 255 bytes a component. The ctl word `name x` takes all after its one
 blank; a second blank there is refused rather than read as the name's
 first byte. A directory (`/`, `~`, `foo/`) is no file name: refused,
@@ -497,10 +509,11 @@ colours the glyph art uses, the C64's (`commodore`) or the terminal
 theme's own 16 (#word("Palette") toggles it); `ascii` is whether the
 printable ASCII bitmaps join the glyph set the matcher picks from
 (#word("Ascii") toggles it). Palette and ascii only change the glyph art.
-#word("Petscii") and #word("Ascii") (`on|off`), #word("Palette")
-(`commodore|terminal`), and a PDF's #word("PdfFit") (`width|height`) and
-#word("PdfTint") (`disabled|filtered|full`) take the value their tag word
-shows and set it; bare, they step to the next.
+#word("Petscii") and #word("Ascii") (`on|off`) and #word("Palette")
+(`commodore|terminal`) take the value their tag word shows and set it, as
+a PDF's #word("PdfFit") (`width|height`) and #word("PdfTint")
+(`disabled|filtered|full`) take the value its ctl read shows; bare, they
+step to the next.
 A terminal pane showing kitty graphics shows `petscii:on` or `petscii:off`
 after its directory in its tag; #word("Petscii") toggles it there too: on
 draws the program's images as glyph art instead of host pixels, off goes
@@ -518,7 +531,9 @@ while a column or workspace tag has the keyboard.
 
 *Pane ctl.* Reading it gives acme's status line: serial, tag length, body
 length, isdir (0), dirty, width in cells, font, tab width, undo available,
-redo available, then `current`/`notcurrent` and a REPL's id if bound. It
+redo available, then `current`/`notcurrent`, a REPL's id if bound,
+`collapsed` when it is, and for a PDF `fit:width|height
+tint:disabled|filtered|full`. It
 takes:
 
 - the pane builtins: #word("Del") (`Del k`/`Del j`, or
@@ -530,7 +545,7 @@ takes:
   #word("Left")/#word("Right")/#word("Up")/#word("Down"), which give the
   keyboard to the pane beside it that way (#key("Ctrl-w") with
   #keys("h", "l", "k", "j")), up from a column's top pane to its tag.
-- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`).
+- `get`: reload from the file (refused once over unsaved edits, `<name>: Modified (get again to discard)`). It is an undo step, so Undo brings back what was there: the sure way back to the file on disk.
 - `lock`/`unlock` (acme's). The lock binds only clients that take it and
   belongs to the open that wrote it: `exec 3>$pane/ctl; echo lock >&3; ...; exec 3>&-`. A `lock` another open holds fails at once, `file in use`
   (EBUSY): retry.
@@ -794,7 +809,8 @@ at 200, ending in `…`. Control characters become spaces.
 - #file("/status"): `pid`, `version`, `panes`.
 - #file("/pager"): write a directory, `~` expanded and resolved (an empty
   line is the session's; one not there is refused ENOENT, a relative one
-  EINVAL, one you may not write `permission denied`); a read on
+  EINVAL, one you may not write `permission denied`, a regular file `not
+  a directory`, ENOTDIR); 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; from a directory you may not write, it pages into the