3 files changed, 33 insertions, 14 deletions
diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json
index 95eeaa07..b42f9c72 100644
--- a/docs/typ/builtins-gui.json
+++ b/docs/typ/builtins-gui.json
@@ -32,7 +32,7 @@
   {"name": "DumpConfig", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the settings in effect, each a word to click, and the startup file's path."},
   {"name": "DumpDir", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "The directory Dump writes to and a relative Restore reads from; bare, the default."},
   {"name": "DumpThemes", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Write the bundled themes into the config directory's themes, to edit."},
-  {"name": "Edit", "leader": null, "also": [], "arg": true, "scope": "both", "setting": false, "choices": null, "doc": "acme's Edit: sam's command language over the pane's body, from a tag, a pane ctl or exec."},
+  {"name": "Edit", "leader": null, "also": [], "arg": true, "scope": "both", "setting": false, "choices": null, "doc": "acme's Edit: sam's command language over the open text panes, from a tag, a pane ctl or exec, starting in the pane's body."},
   {"name": "EffectCode", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Open the source of a panel transition or post shader, by name."},
   {"name": "Exec", "leader": null, "also": ["tab", "middle-click"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Execute its argument as a middle click on it would, a builtin or a shell command."},
   {"name": "Exit", "leader": "SPC q", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Quit the editor, refusing once while a pane holds unsaved text: an Exit with nothing edited since discards it."},
diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json
index 887393ac..53bcf033 100644
--- a/docs/typ/builtins-tty.json
+++ b/docs/typ/builtins-tty.json
@@ -29,7 +29,7 @@
   {"name": "DumpConfig", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Open the settings in effect, each a word to click, and the startup file's path."},
   {"name": "DumpDir", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "The directory Dump writes to and a relative Restore reads from; bare, the default."},
   {"name": "DumpThemes", "leader": null, "also": [], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Write the bundled themes into the config directory's themes, to edit."},
-  {"name": "Edit", "leader": null, "also": [], "arg": true, "scope": "both", "setting": false, "choices": null, "doc": "acme's Edit: sam's command language over the pane's body, from a tag, a pane ctl or exec."},
+  {"name": "Edit", "leader": null, "also": [], "arg": true, "scope": "both", "setting": false, "choices": null, "doc": "acme's Edit: sam's command language over the open text panes, from a tag, a pane ctl or exec, starting in the pane's body."},
   {"name": "EffectCode", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Open the source of a panel transition or post shader, by name."},
   {"name": "Exec", "leader": null, "also": ["tab", "middle-click"], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Execute its argument as a middle click on it would, a builtin or a shell command."},
   {"name": "Exit", "leader": "SPC q", "also": ["topbar"], "arg": false, "scope": "root", "setting": false, "choices": null, "doc": "Quit the editor, refusing once while a pane holds unsaved text: an Exit with nothing edited since discards it."},
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 5bcd8f6f..321860d6 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -98,8 +98,8 @@ own), never a C library string; a bad setting value is quoted, the value
 itself (`bad value in control message; takes on, off "maybe"`); a ctl
 refusal quotes the offending word alone (`wrong #args in control message "Newcol"`). Through 9ns the kernel sees an errno 9ns reads
 from those words (cloud9's `fs.enameErrno`): the first of these that the
-words hold, case aside, wins, and anything else is EIO (`Modified`, an
-#word("Edit") command pardes leaves out):
+words hold, case aside, wins, and anything else is EIO (`Modified`, a
+sam command pardes's #word("Edit") leaves out, `B <cmd`):
 
 #pairs(
   [`control message`], [EINVAL],
@@ -683,15 +683,34 @@ ceiling:
 == Edit <edit>
 
 #word("Edit") `<sam commands>` on a pane's #file("ctl") or #file("exec") (or the
-root's, at the pane with the keyboard) runs acme's #word("Edit") on the body: addresses as
-above, commands `x y g v c a i d s p = m t u` and `{ }`. All changes are
-one undo step, applied only if every command succeeds; a failure changes
-nothing and fails the write with acme's words (`Edit: no substitution`).
-An `x` that finds nothing succeeds silently. `p` and `=` print to the
-directory's `+Errors`. Not there: `b B D e r w f X Y`, `< | >`,
-`\1`-`\9`. In `s`, `&` is the match (`\&` a literal); in `c`, `a`, `i` it
-is a literal. `y` yields the stretch before the first match too. Braces
-take a command a line, so a block goes on one open, in one write or
+root's, at the pane with the keyboard) runs acme's #word("Edit") over the open text
+panes, from that pane's body. Addresses are as above, and `"re"` is the one
+open file whose line matches. Commands:
+
+- `x y g v c a i d s p = m t u` and `{ }`.
+- `X`/`Y` run a command in each open file whose line (` +. /path`, `'` when
+  edited) matches, or does not: `X/'/w` writes every edited file.
+- `b` makes a file current, `B` opens files, `D` closes panes (an edited one
+  on the second asking, as #word("Del")).
+- `e` reads a file over the whole text and names the pane after it, `r`
+  over dot. `w` writes all of it, or the address, to its file or a name;
+  all of it to its own name leaves it clean. `f` names the pane and prints
+  its line.
+- `<cmd` replaces dot with what `cmd` writes, `|cmd` pipes dot through it,
+  `>cmd` sends dot to it and prints what it writes.
+
+Each command runs in its file's directory through #word("Shell"), off the
+loop, so the editor goes on; the write that ran the Edit is answered when
+they are done, and a line after it in the same write is refused. A command
+that fails (an exit status, 10 seconds, 1 MiB of output) fails the Edit, its
+stderr in `+Errors`. Each file's changes are one undo step, applied only if
+every command succeeds; a failure changes nothing and fails the write with
+acme's words (`Edit: no substitution`), as does a file edited while the
+commands ran. An `x` that finds nothing succeeds silently. `p`, `=` and `>`
+print to the directory's `+Errors`. Not there: `B <cmd`, `D <cmd`, the `'`
+address, `\1`-`\9`. In `s`, `&` is the match (`\&` a literal); in `c`, `a`,
+`i` it is a literal. `y` yields the stretch before the first match too.
+Braces take a command a line, so a block goes on one open, in one write or
 several:
 #cmd("printf 'Edit ,x/foo/{\\ni/</\\na/>/\\n}\\n' > $p/ctl")
 
@@ -1040,7 +1059,7 @@ with Client(sys.argv[1]) as c:    # a socket path, or (ip, port)
   [`Snarf`, `Cut`, `Paste`], [refused: the chords, #key("y"), #key("p")],
   [`Font`, `Send`, `ID`], [#word("Font"); #word("Repl") and #word("Exec"); `$winid`],
   [acme's other builtins], [refused: `Sort`, `Local`, `Abort` (plan9port's debugging word)],
-  [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"))],
+  [Edit], [every acme command but `B <cmd`, `D <cmd` and the `'` address; no `\1`-`\9`, and an alternation takes the first branch that matches, not the longest; a failing `< | >` command changes nothing, where acme puts in what it wrote (#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], [as acme's: a text pane named `dir/` (#file("index") kind `text`, #file("ctl") isdir 1), its entries in columns sorted bytewise, dotfiles shown, a directory's marked `/`; blanks pad the columns where acme's tabs do; a #word("Look") at an entry is from that directory, `Get` or a look at it again reads it again, and an edit is kept until then rather than lost to a resize; never dirty, #word("Save") refuses it; #word("DirLook") `terminal` types `ls` into a terminal there instead],
   [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],