1 files changed, 55 insertions, 1 deletions
diff --git a/docs/acme-fs.md b/docs/acme-fs.md
index 15f45c4f..25cbcc2d 100644
--- a/docs/acme-fs.md
+++ b/docs/acme-fs.md
@@ -3,7 +3,8 @@
 `pardes --fs` serves plan9 [acme(4)](https://man.cat-v.org/plan_9/4/acme)'s control
 filesystem over Linux FUSE: a directory per pane, named by the pane's serial and
 holding `addr`, `body`, `ctl`, `data`, `errors`, `event`, `rdsel`, `tag`, `wrsel`
-and `xdata`, plus `index`, `cons` and `new/` at the root (`PaneFile` and
+and `xdata`, plus a `pty/` directory on a terminal pane, plus `index`, `cons`
+and `new/` at the root (`PaneFile` and
 `TopFile` in `src/acmefs.zig`). A program that opens those files IS an editor
 extension — no plugin API, no embedded interpreter, no rebuild.
 `examples/acmefs/` has four of them: `clock.py`, `eventlog`, `life.py` and
@@ -368,6 +369,59 @@ has no `log` either; it is a plan9port addition. No example needed it, and a
 script that wants to notice panes it did not open reads `index`, which is what
 acme gives it.
 
+## What is served that acme does not have: `pty/`
+
+One directory, three files, and **no prior art anywhere**: acme has no terminals
+and `ad` — the other editor that serves a control filesystem over 9P — has no
+terminal surface at all (its tree is `{ctl, minibuffer, scratch, log,
+buffers/…}`). So there is nobody's mistakes to learn from and nobody's scripts
+to keep compatible, which is the argument for keeping it to three files and
+stopping.
+
+A pty is a file interface wearing the wrong clothes: everything one wants to do
+to it is an `ioctl`, and neither 9P nor FUSE has one. They become writes.
+
+| ioctl | here |
+|---|---|
+| `TIOCSWINSZ` | `winsize 80 24` → `pty/ctl` |
+| `kill` | `sig INT` → `pty/ctl` |
+| spawn | `exec` → `pty/ctl` |
+| `TIOCGWINSZ` | read `pty/status` |
+| `read`/`write` | `pty/data` |
+
+Two of the three verbs are effects the core already had — `push_spawn` and
+`push_pty_resize` — so `exec` and `winsize` are existing capabilities acquiring
+a name. `sig` is the one new host capability in the whole directory
+(`push_pty_signal`, and there was no `kill` anywhere in `host_io.zig` before
+it); it targets the tty's foreground process group rather than the shell's pid,
+because an interactive shell ignores SIGINT while it waits for a job.
+
+The directory is **absent** on a pane that is not a terminal, rather than
+present and refusing, so `test -d <id>/pty` is how a script asks what kind of
+pane it has. `pty/data`'s read is the only new state: the core keeps no raw pty
+bytes anywhere (they go into the emulator grid, which is a rendering and cannot
+be turned back into a stream), so they are queued as they arrive — gated on a
+reader count exactly as `event` is, so a pane nobody is reading costs one
+branch and no memory, and capped drop-oldest by the same `queue_cap`. Unlike
+`event`, a read smaller than one arrival is SERVED and the remainder kept: raw
+bytes have no record framing to split down the middle.
+
+Three things it deliberately does not have. There is no **exit status**,
+because the core does not track one: a shell's death arrives as `Event.eof`,
+whose whole handler is `removePane`, so by the time anyone could read a status
+the directory is gone. There is no **`raw`/`cooked`**, because the termios
+belongs to the program on the far side of the pty and it never reports one. And
+`exec` takes **no argv**, because `Effect.spawn` carries a pane and a cwd and
+has nowhere to put one — so `exec /bin/sh` is EINVAL rather than an argument
+accepted and silently ignored.
+
+`Node.file` is a `u4`. These four variants (`pty`, `pty_ctl`, `pty_status`,
+`pty_data`) take it to fifteen of sixteen used: **one value is left**, and the
+next file added to a pane's directory needs a wider field and therefore a new
+node-id layout. That is also why `pty/` is a directory rather than three more
+names beside `body` — a subdirectory costs one value and buys a namespace, so
+`ctl` and `data` did not have to be spelled twice.
+
 ## Reading order
 
 `src/acmefs.zig` (semantics; start at its header), `src/fuse.zig` (the wire),