Point docs and comments at the files code moved to

Documentation only, no code change: README's reading order and layout,
docs/design.typ's paragraph on where pane kinds and editor parts live,
docs/helix-keys.md's code map (normalInput and the executors now in
normal.zig and edit.zig, insertTab in edit.zig), docs/open-questions.md
(execute and ttyForDir in exec.zig), and the comments that named pardes.zig
for fold, Cell, takesCommandLine and runBuiltin (tools/gen_themes.zig,
themes/helix.zig, detached/wire.zig, host_io.zig, lsp_zls.zig).
docs/design.pdf is a retained fixture and is not regenerated.

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

9 files changed, 30 insertions, 23 deletions

diff --git a/README.md b/README.md
index 6225bbdb..8899d68a 100644
--- a/README.md
+++ b/README.md
@@ -216,8 +216,10 @@ steps use `-Dhelix-harness=<path>`, `HX_HARNESS`, or `hx-harness` on PATH.
 
 ## Documentation
 
-Start with `src/panes.zig`, `src/layout.zig`, and `src/fs.zig` for ownership and
-operations, and `src/pardes.zig` for input. `docs/design.typ` is the architecture
+Start with `src/panes.zig` (and the pane kinds it names, `src/File.zig`,
+`src/Terminal.zig`, ...), `src/layout.zig`, and `src/fs.zig` for ownership and
+operations, and `src/pardes.zig` for input, with one file per thing beside it
+(`edit.zig`, `normal.zig`, `look.zig`, `exec.zig`, `mouse.zig`, ...). `docs/design.typ` is the architecture
 sketch; `docs/design.pdf` is a retained rendering/search fixture and may lag it.
 
 | file | subject |
@@ -242,7 +244,7 @@ says which waiver proves it is still open.
 ## Layout
 
 ```
-src/            core events (pardes.zig), panes, layout, fs, syntax
+src/            core events (pardes.zig), panes, edit, look, exec, layout, fs, syntax
 src/detached/   the wire, the detached core, the frontend client
 src/lsp/        ZLS and external language-server backends
 test/           harnesses, snapshot goldens, helix cases
diff --git a/docs/design.typ b/docs/design.typ
index 01b850b9..82bafb49 100644
--- a/docs/design.typ
+++ b/docs/design.typ
@@ -521,13 +521,18 @@ const platform_has_fs = !pardes.isolated and
 the option is comptime, so every libc path below is dead code the compiler
 removes rather than a branch that could be taken by accident.
 
-The core's one `pointerOperand` primitive owns click-word expansion and is shared
+The core's one `pointerOperand` primitive (in `exec.zig`) owns click-word expansion and is shared
 verbatim by right-click and the delayed hover preview; that policy stays beside
 input because it also observes live pane selections and wrapped grid coordinates.
 
-`panes.zig` keeps each pane kind's storage and operations together.
+Each pane kind keeps its storage and operations together in its own file
+(`File.zig`, `Terminal.zig`, `Output.zig`, `Mini.zig`, `pdf_view.zig`, and the
+image pane in `image.zig`), reached through `panes.zig` beside `Pane`.
 `layout.zig` owns placement and presentation state. `pardes.zig` handles input
-and cross-pane state directly, without a pane vtable. Integration fixtures live
+and cross-pane state directly, without a pane vtable; the rest of the editor
+is split by thing as acme is: `edit.zig`, `normal.zig`, `look.zig`, `exec.zig`,
+`mouse.zig`, `Messages.zig`, `Pipe.zig`, `colors.zig`, `surface.zig`,
+`body_layer.zig` and `dump.zig`. Integration fixtures live
 in `test/panes.zig`, `test/output.zig`, and `test/pdf.zig`.
 
 = State
diff --git a/docs/helix-keys.md b/docs/helix-keys.md
index 6907473a..4de3901a 100644
--- a/docs/helix-keys.md
+++ b/docs/helix-keys.md
@@ -15,14 +15,14 @@ and is described in the Files list at the bottom instead.
 Code map, by SYMBOL — line numbers rot, names do not. Body-normal key
 RECOGNITION is `modal.Normal` in `src/modal.zig`: a state machine over `Role` (one
 per bound command, matched against `src/config.zig`'s chord lists by
-`Pardes.normalInput`), a `Prefix`, a `MatchSub` and a count, emitting a
+`normalInput` in `src/normal.zig`), a `Prefix`, a `MatchSub` and a count, emitting a
 semantic `Action` that both the text and PDF adapters consume. It knows
-nothing about panes or text. `src/pardes.zig` then EXECUTES: `Key`,
-`handleKey` (intercept order is load-bearing, see the comment there),
-`handleNormal` (parses directly into `Pane.normal`),
-`executeNormalAction`, `setPaneRange` (helix range → pane state),
-`enterInsert`, `handleInsert` / `insertKey`, `insertTab`, `normalDelete`,
-`normalYank`, `pasteText`, `normalChange`, `replaySels`, `multiOnce`. Undo
+nothing about panes or text. Then it is EXECUTED: `Key` and `handleKey` in
+`src/pardes.zig` (intercept order is load-bearing, see the comment there);
+`handleNormal` (parses directly into `Pane.normal`), `executeNormalAction`,
+`replaySels` and `multiOnce` in `src/normal.zig`; `setPaneRange` (helix range
+→ pane state); and `enterInsert`, `handleInsert` / `insertKey`, `insertTab`,
+`normalDelete`, `normalYank`, `pasteText`, `normalChange` in `src/edit.zig`. Undo
 and redo live in `panes.File` and `panes.Terminal`. Pure text math:
 `src/modal.zig` (the `hx*` family is the helix-semantics layer: gap offsets +
 ranges over the flat text). Differential harness: `test/hxdiff.zig` +
@@ -313,7 +313,7 @@ text.
 | `Ctrl-j` | insert newline (Enter alias) | | helix-verified (phase 5) |
 | `Home` / `End` | line start / line end past-the-last-char (`goto_line_end_newline`) | file panes (terminal insert cursor rides its run, as before) | helix-verified (phase 5) |
 | `PageUp` / `PageDown` | cursor page up / down, col kept (clamped to line) | file panes | helix-verified (phase 5) |
-| `Tab` | indent to the next 4-column stop with SPACES (`insertTab`, `pardes.zig`: `pad = INDENT_W - col % INDENT_W`) — no `\t` byte ever reaches the file | helix's Spaces indent style; helix smart-tab skipped. After a `.` in a file the backend speaks, Tab instead asks for completion and only indents if the answer is empty (section A) | helix-verified (phase 5) |
+| `Tab` | indent to the next 4-column stop with SPACES (`insertTab`, `edit.zig`: `pad = INDENT_W - col % INDENT_W`) — no `\t` byte ever reaches the file | helix's Spaces indent style; helix smart-tab skipped. After a `.` in a file the backend speaks, Tab instead asks for completion and only indents if the answer is empty (section A) | helix-verified (phase 5) |
 
 ## C. Skipped
 
diff --git a/docs/open-questions.md b/docs/open-questions.md
index e48d715e..9f4f44f5 100644
--- a/docs/open-questions.md
+++ b/docs/open-questions.md
@@ -10,8 +10,8 @@ Raised 2026-09-27 in the review of pardes against acme (Plan 9 source at
 
 **Today.** A middle-click, an `exec` write or a tag word that is not a builtin
 is typed into a terminal pane: the pane itself when it takes a command line,
-else a shell for the pane's directory (`Pardes.execute`, `ttyForDir` in
-`src/pardes.zig`). The command shares that shell's cwd, environment, history
+else a shell for the pane's directory (`execute`, `ttyForDir` in
+`src/exec.zig`). The command shares that shell's cwd, environment, history
 and aliases, and its output lands in the terminal.
 
 **acme.** An external command runs as its own process: stdin from
diff --git a/src/detached/wire.zig b/src/detached/wire.zig
index 20b5c093..94bd7f0b 100644
--- a/src/detached/wire.zig
+++ b/src/detached/wire.zig
@@ -550,7 +550,7 @@ fn colorSize(c: pardes.Color) usize {
 }
 
 /// An unpainted cell is ONE byte: `default` means "the shell renders the
-/// terminal's default cell" (pardes.zig `Cell`), so its text and style are not
+/// terminal's default cell" (surface.zig `Cell`), so its text and style are not
 /// merely equal to the defaults, they are not part of the frame at all.
 fn putCell(w: *Writer, c: *const pardes.Cell) Error!void {
     try w.putBool(c.default);
diff --git a/src/host_io.zig b/src/host_io.zig
index 34c2f57a..d0b9de71 100644
--- a/src/host_io.zig
+++ b/src/host_io.zig
@@ -1260,7 +1260,7 @@ pub fn ttyTaken(shell_pid: libc.pid_t, master_fd: c_int) bool {
 /// and what still catches `bash -c 'sleep 30'`: the group holds `sleep` too.
 ///
 /// Until this existed, `ttyTaken` answered `false` on darwin for every pane,
-/// so `Pardes.takesCommandLine` was permanently true and every bare Escape in
+/// so `exec.takesCommandLine` was permanently true and every bare Escape in
 /// a raw terminal ran the `Last` builtin instead of reaching the child.
 const darwin = struct {
     const proc_pgrp_only: u32 = 2;
diff --git a/src/lsp/lsp_zls.zig b/src/lsp/lsp_zls.zig
index 68538125..09493c26 100644
--- a/src/lsp/lsp_zls.zig
+++ b/src/lsp/lsp_zls.zig
@@ -1015,7 +1015,7 @@ fn documentSymbols(
 }
 
 /// Depth-first so the rows read in source order, with the parent's name as a
-/// qualifier — `Pardes.runBuiltin` rather than a bare `runBuiltin`,
+/// qualifier — `Pardes.update` rather than a bare `update`,
 /// because a flat list of method names is not navigable.
 fn emitSymbols(
     gpa: std.mem.Allocator,
diff --git a/src/themes/helix.zig b/src/themes/helix.zig
index 76eaeab2..db51de3a 100644
--- a/src/themes/helix.zig
+++ b/src/themes/helix.zig
@@ -33,7 +33,7 @@
 //! itself.
 //!
 //! No imports, and neither has any other theme file: a theme is DATA. The
-//! `.{...}` becomes a pardes.Theme in pardes.zig's `fold`, which is also what
+//! `.{...}` becomes a pardes.Theme in colors.zig's `fold`, which is also what
 //! turns a missing field here into a compile error naming it.
 pub const theme = .{
     .name = "helix",
diff --git a/tools/gen_themes.zig b/tools/gen_themes.zig
index 3add2040..65e85d1c 100644
--- a/tools/gen_themes.zig
+++ b/tools/gen_themes.zig
@@ -22,7 +22,7 @@
 //! moving when the other source gains or loses a file. helix's own `acme.toml`
 //! is vendored as `acme_helix.toml` for the same reason, since pardes ships an
 //! acme of its own; the file is otherwise untouched. Two themes answering to
-//! one name is a bug (`Theme <name>` would silently pick one), so src/pardes.zig
+//! one name is a bug (`Theme <name>` would silently pick one), so src/colors.zig
 //! asserts the ring's names are distinct at comptime.
 //!
 //! Provenance: vendor/themes/*.toml are helix's own runtime themes (from
@@ -50,7 +50,7 @@ const Rgb = [3]u8;
 
 /// pardes's Theme, minus the type: the generated file spells an anonymous
 /// `.{...}` because a theme file deliberately imports NOTHING (it is data, not
-/// code) — src/pardes.zig's `fold` is what turns it into a real Theme.
+/// code) — src/colors.zig's `fold` is what turns it into a real Theme.
 const Theme = struct {
     name: []const u8,
     bg: ?Rgb,
@@ -132,7 +132,7 @@ pub fn main(init: std.process.Init) !void {
     }
     // the INDEX, and the only reason it is generated rather than written: a zig
     // file cannot list a directory at comptime, so the imports have to come
-    // from whoever can. pardes.zig folds its declarations into the ring.
+    // from whoever can. colors.zig folds its declarations into the ring.
     buf.clearRetainingCapacity();
     try buf.writer.writeAll("// Generated by tools/gen_themes.zig. Do not edit.\n");
     for (themes) |t| try buf.writer.print("pub const {s} = @import(\"{s}.zig\");\n", .{ t.name, t.name });