The reference gains Coming from acme, one table of what differs for acme users and scripts; the intros say modelled on acme's; Look says it has no plumber; the guide compares Esc with acme's and answers the acme question fairly; the OTRUNC sentence reads

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

4 files changed, 41 insertions, 13 deletions

diff --git a/docs/typ/cheatsheet-a4.pdf b/docs/typ/cheatsheet-a4.pdf
index 61c3f078..0aed63ce 100644
--- a/docs/typ/cheatsheet-a4.pdf
+++ b/docs/typ/cheatsheet-a4.pdf
@@ -1606,12 +1606,12 @@ x�}��Kq�?�U�X
94%MQKS��N�#Ԧ��Q�v��B�ˡ�h�Fk	������!
 endstream
 endobj
 438 0 obj
-<</Creator(Typst 0.15.1)/ModDate(D:20261001154233-03'00)/CreationDate(D:20261001154233-03'00)>>
+<</Creator(Typst 0.15.1)/ModDate(D:20261001155455-03'00)/CreationDate(D:20261001155455-03'00)>>
 endobj
 439 0 obj
 <</Length 996/Type/Metadata/Subtype/XML>>
 stream
-<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?><x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="xmp-writer"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/"  xmlns:xmp="http://ns.adobe.com/xap/1.0/"  xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"  xmlns:xmpTPg="http://ns.adobe.com/xap/1.0/t/pg/"  xmlns:pdf="http://ns.adobe.com/pdf/1.3/" ><xmp:CreatorTool>Typst 0.15.1</xmp:CreatorTool><dc:language><rdf:Bag><rdf:li>en</rdf:li></rdf:Bag></dc:language><xmp:ModifyDate>2026-10-01T15:42:33-03:00</xmp:ModifyDate><xmp:CreateDate>2026-10-01T15:42:33-03:00</xmp:CreateDate><xmpTPg:NPages>1</xmpTPg:NPages><dc:format>application/pdf</dc:format><xmpMM:InstanceID>t0REzPxUfQD8BEDzU7OUiQ==</xmpMM:InstanceID><xmpMM:DocumentID>t0REzPxUfQD8BEDzU7OUiQ==</xmpMM:DocumentID><xmpMM:RenditionClass>proof</xmpMM:RenditionClass><pdf:PDFVersion>1.7</pdf:PDFVersion></rdf:Description></rdf:RDF></x:xmpmeta><?xpacket end="r"?>
+<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?><x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="xmp-writer"><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"><rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/"  xmlns:xmp="http://ns.adobe.com/xap/1.0/"  xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"  xmlns:xmpTPg="http://ns.adobe.com/xap/1.0/t/pg/"  xmlns:pdf="http://ns.adobe.com/pdf/1.3/" ><xmp:CreatorTool>Typst 0.15.1</xmp:CreatorTool><dc:language><rdf:Bag><rdf:li>en</rdf:li></rdf:Bag></dc:language><xmp:ModifyDate>2026-10-01T15:54:55-03:00</xmp:ModifyDate><xmp:CreateDate>2026-10-01T15:54:55-03:00</xmp:CreateDate><xmpTPg:NPages>1</xmpTPg:NPages><dc:format>application/pdf</dc:format><xmpMM:InstanceID>4QIAwa/Wq0Z0q+sNfmgIHw==</xmpMM:InstanceID><xmpMM:DocumentID>4QIAwa/Wq0Z0q+sNfmgIHw==</xmpMM:DocumentID><xmpMM:RenditionClass>proof</xmpMM:RenditionClass><pdf:PDFVersion>1.7</pdf:PDFVersion></rdf:Description></rdf:RDF></x:xmpmeta><?xpacket end="r"?>
 endstream
 endobj
 440 0 obj
@@ -2061,7 +2061,7 @@ xref
 0000110957 00000 n

 0000112030 00000 n

 trailer
-<</Size 441/Root 440 0 R/Info 438 0 R/ID[(t0REzPxUfQD8BEDzU7OUiQ==)(t0REzPxUfQD8BEDzU7OUiQ==)]>>
+<</Size 441/Root 440 0 R/Info 438 0 R/ID[(4QIAwa/Wq0Z0q+sNfmgIHw==)(4QIAwa/Wq0Z0q+sNfmgIHw==)]>>
 startxref
 112217
 %%EOF
\ No newline at end of file
diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ
index 5957692a..077c62f1 100644
--- a/docs/typ/guide.typ
+++ b/docs/typ/guide.typ
@@ -46,6 +46,9 @@ steps raw, normal, insert.
   [a PDF], [#key("Esc"): clears the selection and the search highlights. #key("Shift-Esc"): back to the previous pane.],
 )
 
+In acme, Esc selects the text typed since the last click; here it leaves
+insert mode, or goes back a pane.
+
 #key("Shift-Esc") needs the kitty keyboard protocol or the GUI. Elsewhere
 it is a plain Esc. The previous pane is the last one you jumped from, else
 the next pane down the column.
@@ -155,7 +158,7 @@ pardes.
   addr("notes.txt:12"), [line 12],
   addr("notes.txt:/TODO/"), [the next match of `TODO`],
   addr("src/"), [`ls` typed into a terminal idle there, else a new terminal there],
-  addr("https://ziglang.org"), [the browser],
+  addr("https://ziglang.org"), [the browser, through `xdg-open` (`open` on macOS); there is no plumber],
 )
 
 #key("Enter") does the same from the keyboard; the other address forms are
@@ -271,9 +274,11 @@ Shell zsh
 = Questions <questions>
 
 / Why not helix and tmux, or acme?: helix and tmux edit and run shells
-  well, but their text is inert. acme makes text the interface, without
-  modal keys, a terminal emulator or PDFs. pardes puts text as the interface, helix's
-  keys, terminals, PDFs and a scriptable session in one program.
+  well, but their text is inert. acme makes text the interface and is
+  modeless by design, with win for shells and page and the plumber for
+  documents. pardes keeps acme's text as the interface and trades the rest
+  for helix's modal keys, a VT terminal and PDFs in a pane. What changes
+  for acme users and scripts is in #doc("reference", section: "from-acme").
 / Does it run inside tmux?: Yes, as in any terminal. Where tmux does not
   pass kitty's protocols, #key("Shift-Esc") is a plain Esc and images draw
   as glyph art.
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 9b107fe5..29f535ee 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -5,8 +5,8 @@
 #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs, fstree
 
 Every native session is a virtual filesystem, served as 9P2000 (not .u,
-not .L), in acme's manner: panes, columns, tags and the session are
-files. Paths here are the served ones (#file("/pane/2/body")); through a
+not .L) and modelled on acme's (#doc("reference", section: "from-acme")):
+panes, columns, tags and the session are files. Paths here are the served ones (#file("/pane/2/body")); through a
 mount they sit under the session's directory (`$m`; #doc("scripting", section: "find-the-session")
 says how to find it). The served #file("/README") is a
 one-screen summary of this page. Two builtins: #word("Look") (right-click): open what the
@@ -983,8 +983,8 @@ Under `9ns --mntgen` (which sets `NINE_MNTGEN=1`) a session is at
 `$NINE_MOUNT/<service>/<name>`, pardes's `$NINE_MOUNT/pardes/<name>`, and
 every pane pardes spawns gets it as `$PARDES_MOUNT`. Under `9ns --unix SOCK
 -- cmd` the session is `$NINE_MOUNT` itself, and `$PARDES_MOUNT` is unset.
-plan9port's `9p write` opens with OTRUNC, so it replaces a whole
-#file("body"); append with `>>` through a mount. Through a FUSE mount
+plan9port's `9p write` opens with OTRUNC, so on #file("body") it replaces
+the whole text. To append, use `>>` through a mount. Through a FUSE mount
 bash's `read -t` cannot time out: wrap a follow loop in `timeout`. The
 scripting chapter's rule (a mount, else `9p`) covers most uses. Two more:
 
@@ -1015,6 +1015,28 @@ with Client(sys.argv[1]) as c:    # a socket path, or (ip, port)
 
 `client.screen()` returns the parsed #file("/screen").
 
+= Coming from acme <from-acme>
+
+#pairs(
+  [`$NAMESPACE/acme`], [not posted there: a session is `$XDG_RUNTIME_DIR/9p/pardes/<name>`; reach it with `9p -a "unix!$PARDES_9P"` or a `9ns --mntgen` mount (#doc("fs", section: "other-clients"))],
+  [`N/`], [#file("pane/N/"), N the pane's serial],
+  [`new/ctl`], [read #file("pane/new"): it makes a pane and answers its serial; `rmdir pane/N` closes it],
+  [`index`], [#file("index") lines are serial, kind, dirty, name, column (acme: id, tag and body lengths, isdir, dirty, tag)],
+  [rune offsets], [bytes everywhere, event offsets and counts included; addresses snap to rune boundaries],
+  [`addr` reset on first open], [#file("addr") is the pane's; no open resets it (write `0`)],
+  [OTRUNC on `data` ignored], [`: > data` deletes the addressed text; OTRUNC on #file("body") (`9p write`) replaces it all],
+  [event flags 1, 2, 4, 8], [1, 4 and 8; never 2, so no expansion record follows],
+  [`Get`], [`get` on the pane's #file("ctl")],
+  [`Put`, `Delete`], [#word("Save"); a #word("Del") that does not ask],
+  [`Snarf`, `Cut`, `Paste`], [refused: the chords, #key("y"), #key("p")],
+  [acme's other builtins], [refused: `Putall`, `Zerox`, `Sort`, `Load`, `ID`, `Send`, `Tab`, `Indent`, `Local`, `Incl`, `Abort`],
+  [Edit], [no `< | >`, `X`, `Y`, `b B D e r w f`, no `\1`-`\9`; an alternation takes the first branch that matches, not the longest (#doc("fs", section: "edit"))],
+  [`win`], [#word("Tty") is a VT terminal pane; #file("pty/run") runs a line at its prompt and answers `exit N` and the output; with #word("Repl") bound, #word("Exec") on a source pane types the text into it],
+  [a directory window], [#word("Look") on a directory types `ls` into a terminal idle there, else opens one],
+  [the plumber], [none: #word("Look") on an `http://` or `https://` URL runs `xdg-open` (`open` on macOS); files, addresses and directories follow built-in rules],
+  [#key("Esc") selects what was typed], [#key("Esc") leaves insert mode, or goes back a pane (#doc("tags", section: "modes"))],
+)
+
 = Limits <limits>
 
 #pairs(
diff --git a/docs/typ/scripting.typ b/docs/typ/scripting.typ
index 47eb8a24..590d71ac 100644
--- a/docs/typ/scripting.typ
+++ b/docs/typ/scripting.typ
@@ -3,8 +3,9 @@
 // reference.
 #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
 
-Every session is a virtual filesystem, served over 9P, as acme's is, so
-a program that opens files is an extension:
+Every session is a virtual filesystem, served over 9P and modelled on
+acme's (#doc("reference", section: "from-acme")), so a program that opens
+files is an extension:
 
 ```
 $ ls $m