The docs take the 9P agent's round 30: log stats 0, names escape every control byte, $winid and the pager defaults, the one client rule, and Shift-Esc said one way in the guide and the cheatsheet

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

1 files changed, 13 insertions, 5 deletions

diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index b247ab6b..39e99aa6 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -29,10 +29,13 @@ Shift-Esc depend on the mode:
 #pairs(
   [normal], [#key("Esc"): back to the previous pane (#word("Last")). #key("Shift-Esc"): the same, except in a terminal, where it switches to raw.],
   [insert], [#key("Esc"): back to normal. #key("Shift-Esc"): the same, except in a terminal, where it switches to raw.],
-  [raw `$`], [#key("Esc"): to the program, except at an idle, empty shell prompt, where it goes back to the previous pane. #key("Shift-Esc"): always back to the previous pane. Either way the terminal stays `$`.],
+  [raw `$`], [#key("Esc"): to the program, except at a shell prompt with nothing typed on it, where it goes back to the previous pane. #key("Shift-Esc"): always back to the previous pane. Either way the terminal stays `$`.],
   [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.],
 )
 
+In short, #key("Shift-Esc") is as Esc, but always back to the previous pane from raw `$` or a PDF, and into raw from a terminal's normal or insert mode. "A shell prompt with nothing
+typed on it" is one pardes knows from the prompt marks it injects into bash
+and fish (and, for other shells, from no program holding the terminal).
 "The previous pane" is the last other pane on the jump list; with none, the
 next pane down its column (wrapping), else any other pane. In raw mode
 every key but #key("Ctrl-b"), Esc and the paste chords goes to the
@@ -115,7 +118,10 @@ tag opens a `+New` scratch named in that pane's directory, in that pane's
 column; from a column tag, in that column and the session's directory.
 Every new pane but a command pane takes the keyboard. No pane is made
 shorter than its tag and two rows; where there is no room the pane is
-refused.
+refused. `Placement pardes` instead fills an empty column whose tag asked
+or has the keyboard, puts a scratch or a shell under the pane that asked,
+a document beside the last one read (or in a column of its own on a wide
+screen), and a command pane at the foot of the last column.
 
 A column can be empty, as in acme: closing its last pane leaves it, its
 tag over blank space. #word("Delcol") and #word("Joincol") take columns
@@ -138,7 +144,7 @@ pane's own directory.
 
 #btn("B2") on a line that is no builtin (`make`, `git log`) runs it with
 the #word("Shell") setting's `-c`, in the directory of the tag or pane it
-came from. In a terminal idle at an empty prompt, a line from that
+came from. In a terminal at a shell prompt with nothing typed on it, a line from that
 terminal's own text is typed into its shell. Anywhere else it runs in a
 command pane, a terminal of its own:
 
@@ -213,7 +219,8 @@ git's `a/` and `b/` prefixes are dropped (and `c/ i/ w/ o/` with
 In a pane's shell, `pardes FILE` opens FILE in this session and returns at
 once, as acme's `B` does. A FILE not there yet opens an empty pane named
 for it; #word("Save") creates it, making its directories first. Something
-the session refuses (a bad name) is printed and the command exits 1.
+the session refuses (a bad name, or a new name in a directory that is there
+but may not be read or written) is printed and the command exits 1.
 
 `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
@@ -269,7 +276,8 @@ The session owns the panes, shells and files; frontends come and go.
 #word("Attach") `work` (#key("SPC s a")) switches this window to that
 session, and #word("Detach") (#key("SPC s D")) leaves it running, shells
 and all. Bare `--detach` names the session after its pid; bare `--attach`
-needs exactly one session. Every attached frontend sees the same screen,
+needs exactly one session; a second `--detach=NAME` while NAME runs says so
+and exits 1. Every attached frontend sees the same screen,
 at the smallest common size. With none attached, `size C R` on the root
 ctl sets the screen and messages clear by the clock. A detached session
 ends when its last pane closes, as any session does.