The docs and the 9P skill say each fact once, in the file that owns it, and say only what a live session does

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

1 files changed, 28 insertions, 48 deletions

diff --git a/docs/detached.md b/docs/detached.md
index 46e93fd5..e010677c 100644
--- a/docs/detached.md
+++ b/docs/detached.md
@@ -1,7 +1,7 @@
 # Detached sessions
 
-A detached session owns the editor core, pane shells, files, undo history and
-layout. TTY and SDL frontends can join and leave without ending the session.
+A detached session owns the editor core, pane shells, files, undo history
+and layout. TTY and SDL frontends join and leave without ending it.
 
 ```sh
 pardes --detach=work &
@@ -9,61 +9,41 @@ pardes --attach=work
 pardes-gui --attach=work
 ```
 
-Bare `--detach` names the session after its process ID. Bare `--attach`
-requires exactly one listening session. The detached process runs in the
-foreground unless the shell backgrounds it.
+Bare `--detach` names the session after its pid; bare `--attach` needs
+exactly one listening session. The detached process runs in the foreground
+unless the shell backgrounds it. Inside an editor, `Attach work` (`SPC s a`)
+switches this window to that session and `Detach` (`SPC s D`) closes only
+this frontend.
 
-Inside an editor, `Attach work` (`SPC s a`) switches the current window to
-that session. `Detach` (`SPC s D`) closes only that frontend. It does not
-turn a local editor into a detached session.
-
-A message stays until the next key or click dismisses it. With no frontend
-attached there is none to come, so a detached session drops each pane's
-messages once the newest has been up `MessageLinger` on the clock, checked
-by the session's own loop between the editor's steps; /screen then shows
-what is current.
+With no frontend attached, `/ctl`'s `size C R` sets the screen (160x50 until
+then; [fs.md](fs.md#the-root-ctl)), and messages clear after `MessageLinger`
+on the clock, since no key will come to dismiss them.
 
 ## Files and transport
 
 The frontend socket is `pardes-detached-<name>.sock` under
-`$XDG_RUNTIME_DIR`, or `~/.local/state/pardes` when no runtime directory is
-set. A second session cannot replace a live listener with the same name.
-Shared Unix socket handling lives in `src/9p_io.zig`.
-
-The session also opens its default 9P socket. Optional TCP and QUIC listeners,
-runtime mounts and the control filesystem belong to the session, not its
-frontends. See [fs.md](fs.md).
+`$XDG_RUNTIME_DIR`, else `~/.local/state/pardes`, beside the session's 9P
+socket `pardes-9p-<name>.sock`. A second session cannot take a live name.
+TCP and QUIC listeners, mounts and the control filesystem belong to the
+session, not its frontends.
 
 ## Ownership
 
-One poll loop owns all core mutation, frontend connections, PTY I/O and file
-watch notifications. LSP and selection-pipe workers own request snapshots and
-post completions through a bounded mailbox. Each subprocess is reaped by its
-owner; PTY reaping cannot consume a language server or filter's exit status.
-
-Restore constructs a replacement core before changing the current one. It then
-joins old work, clears obsolete completions, replaces panes and watches, and
-sends a fresh frame to the existing frontends.
-
-Frontends provide input and presentation. Clipboard writes are broadcast;
-clipboard reads, browser opens and Detach go to the originating frontend,
-falling back to the primary attachment. Frontends never spawn pane shells,
-write session files or install file watches.
+One poll loop owns core mutation, frontend connections, PTY I/O and file
+watches; LSP and selection-pipe workers post completions through a bounded
+mailbox. Restore builds the replacement core before changing the current
+one, then sends existing frontends a fresh frame. Frontends provide input
+and presentation only: clipboard writes are broadcast; clipboard reads,
+browser opens and Detach go to the frontend that asked (else the first
+attached). Frontends never spawn shells, write session files or watch files.
 
 ## Wire and tests
 
-`src/detached/wire.zig` owns the versioned frontend protocol. Frames are full
-grids or changes relative to each frontend's last queued frame. A new
-attachment receives a full grid. Output queues and per-poll work are bounded;
-a lagging frontend cannot hold the session's event loop. Protocol version 6
-also carries the pointer shape, compact source-context body layers, source-gap
-separators and independently sized tag text. Pointer
-updates work even when no grid cells change, and graphical clients use the
-same compact row and tag geometry for drawing and mouse input. Tag text positions
-are separate from physical pane and drag-handle coordinates. Terminal clients retain
-the ordinary fixed grid.
+`src/detached/wire.zig` owns the versioned frontend protocol (version 8).
+Frames are full grids or changes against each frontend's last frame; a new
+attachment gets a full grid. Queues are bounded, so a lagging frontend
+cannot hold up the session.
 
-`zig build unit-test` covers encoding, session ownership, real frontend
-connections, worker completion and Restore. `zig build fs-test` drives
-detached sessions through an independent 9P client. The snapshot suites also
-exercise attach, detach and shared screen behavior.
+`zig build unit-test` covers the wire, ownership, real frontend connections
+and Restore; `zig build fs-test` drives detached sessions over 9P; the
+snapshot suites exercise attach, detach and shared screens.