docs: dired arc framing (revision 5) + post-merge doc refresh

Lands the approved dired framing on main as its own docs PR, and brings
the two required docs current after find-file merged as #162.

The framing was approved after two review rounds (seven findings, then
six) and revised twice more since: revision 4 recorded what implementing
Stage 0 falsified in the approved text, and revision 5 adds the coherence
impact statement that #163 made mandatory for every framing.

The coherence statement is new work, not a restatement. COHERENCE.md
section 20 Priority 1 already names this arc -- a find-file surface and
directory-argument handling -- so the framing now states which journey
steps it touches (7, and partially 3), that it adds no interaction island
because its keys are a mode-scoped keymap through the ordinary registry
and wdired is a mode swap rather than a modal layer, that it adopts the
config registry for dired.kill-when-opening, and that it inherits the
worker-attribution gap for its read_dir jobs without worsening it. It
also draws the boundary against the adjacent Journey Stage 1 arc: CLI
directory handling belongs there, the two meet at resolve_target_buffer,
and dired supplies the buffer a directory should resolve to rather than
growing a second directory surface.

One convergence worth recording: section 2 grades the golden journey
broken at step 3 because pmacs on a directory exits 1, and the mechanism
it cites -- File::open succeeding on a directory, then read_to_end
returning EISDIR -- is the same one Stage 0 pinned in its
accepting-a-directory test, where the pcall turns it into a status
message instead.

The handoff snapshot was stale through eight merges. It now anchors on
main at 2af1ab3, records COHERENCE.md as required reading and a required
framing input, and carries the two minibuffer facts find-file
established: a custom completion source cannot descend directories, and
a selected candidate shadows typed text -- both of which apply to M-x and
switch-buffer, not just find-file.

The ledger gains the dired lane with Stage 1's scope, the reason its one
Rust change cannot be done in Lua, and the rebase note for the dired
branch, whose framing commits become redundant when this lands.

docs/active-work.md

@@ -1,6 +1,6 @@
 # Active work — cross-machine resume ledger
 
-**Snapshot: 2026-07-24.** This file records volatile work that has not
+**Snapshot: 2026-07-25.** This file records volatile work that has not
 landed on `main`. Read it after `docs/agent-handoff.md`. Remove completed
 entries when their PR merges; do not let this become a second permanent
 backlog.
@@ -124,6 +124,45 @@ If it does not, stop and repair the remote/fetch configuration.
   or markerless scratch files fragment into one server per directory for
   every language.
 
+## Dired lane — framing APPROVED; Stage 0 MERGED, Stage 1 next
+
+- Approved framing: `docs/dired-framing.md` (revision 5), landing as its
+  own docs PR off `githubsucks/main` @ `2af1ab3`, branch
+  `githubsucks/dired-framing`, worktree `../pmacs-dired-framing`. The
+  repo's `-framing`-branch convention (`vterm-framing`,
+  `gpu-initial-target-framing`, `tab-width-parity-framing`).
+- **Stage 0 (`C-x C-f` find-file) MERGED as #162** (`main` @ `2af1ab3`,
+  2026-07-25, one review round, 12/12 CI green). Durable facts moved to
+  `docs/agent-handoff.md` §1 per rule 3 below.
+- **Stage 1 (the dired view) is next and unstarted.** Branch `dired`
+  (worktree `../pmacs-dired-arc`) carries the framing commits only and is
+  based on the now-superseded `0827dd1`; **rebase it onto the `main`
+  resulting from the framing PR before implementing**, or cut a fresh
+  branch — its framing commits become redundant once the docs PR lands.
+- Stage 1's scope, from the framing §10: `builtin/runtime/dired.lua`; the
+  `dired` major mode + mode keymap; buffer-per-directory with lexical
+  canonicalization and the ownership check; read-only intercept +
+  `set_round_trip_input`; visit routing through `window.display_file`;
+  parent/sort/revert/quit; `C-x d` (with the `display` opt) / `C-x C-j`;
+  cursor preservation by basename; the `dired.kill-when-opening` config
+  key; **and the tolerant `read_dir` opt** — the only Rust in the stage.
+- The one Rust change is load-bearing and is why Stage 1 is not
+  pure-Lua: `read_dir_blocking` (`src/fs.rs:201`) fails the **entire
+  listing** on any of five per-entry conditions, and the tolerant wrapper
+  its own module doc delegates to package authors **cannot be written in
+  Lua** — the primitive returns one error and no partial vec.
+- Coherence (framing §0.5, required since #163): serves `COHERENCE.md`
+  §20 Priority 1, which names this work explicitly; journey steps 7 and
+  (partially) 3; **adds no interaction island** — keys are a mode-scoped
+  keymap, and wdired is a mode swap; adopts `pmacs.config` for
+  `dired.kill-when-opening`; inherits §9's worker-attribution gap for its
+  `read_dir` jobs without worsening it.
+- **Boundary with the Journey Stage 1 arc** (`COHERENCE.md` §20 arc-cut
+  1): CLI directory-argument handling (`pmacs .` exits 1) belongs there,
+  not here. The two meet at `resolve_target_buffer`; dired supplies the
+  buffer a directory should resolve *to*, and `pmacs .` should route into
+  it rather than growing a second directory surface.
+
 ## Bottom-panel lane (window placement + side windows) — Stage 1 IN REVIEW
 
 - Portable branch: `githubsucks/bottom-panel`, worktree

docs/agent-handoff.md

@@ -1,7 +1,12 @@
 # Agent handoff — cross-machine continuity
 
-**Last updated: 2026-07-24, after GPU initial-target (#148, protocol v20)
-landed, following folding Stage 2 (#149) and its landed-doc refresh (#150),
+**Last updated: 2026-07-25, after find-file (#162) landed — the dired
+arc's Stage 0 — following COHERENCE.md (#163), Lean 4 Stage 1 (#160), the
+minimap blank-slab fix (#159), bottom-panel Stage 1 (#155), the
+inline-math re-scout (#154), the vterm PTY-flake fix (#153), and the
+GPU initial-target doc refresh (#152); and before that GPU
+initial-target (#148, protocol v20),
+following folding Stage 2 (#149) and its landed-doc refresh (#150),
 web grammars HTML+CSS (#146), the LaTeX Stage 1 / inline-math framing pair
 (#144/#145), folding Stage 1 (#142), one-command GPU invocation (#141), the
 documentation refresh (#140), Vterm Stage 3 (#135), tab-width rendering
@@ -19,9 +24,55 @@ reads it the way you just did.
 For volatile branches, checkpoints, verification, and recovery
 commands, read `docs/active-work.md` immediately after this file.
 
-## 1. Where the project stands (2026-07-24)
+## 1. Where the project stands (2026-07-25)
 
-- `main` @ `0dd16a5` (GPU initial-target #148 atop folding Stage 2 landed-doc
+- `main` @ `2af1ab3` (find-file #162 atop COHERENCE.md #163, Lean 4 Stage 1
+  #160, minimap blank-slab #159, bottom-panel Stage 1 #155, inline-math
+  re-scout #154, vterm PTY-flake #153, and doc refresh #152). Protocol
+  unchanged at **v20**. The bullets below describe the arcs in their own
+  terms; this line is the head-of-`main` anchor.
+- **`COHERENCE.md` is now required reading and a required framing input
+  — #163.** It carries the product-coherence thesis, an audited
+  scorecard, per-concern gaps, and §20's priority order, and it is the
+  standard new work is evaluated against. Per `CLAUDE.md`, **every new
+  framing doc must state its coherence impact** — journey steps touched,
+  interaction islands added, config-registry adoption, background-work
+  attribution. Its §2 grades the golden journey **broken at step 3**
+  (`pmacs .` exits 1).
+- **find-file LANDED — #162** (`docs/dired-framing.md` §10, Q#DR11; merge
+  `2af1ab3`; one review round). `C-x C-f` is the dired arc's **Stage 0**:
+  pmacs previously had no discoverable way to open a file by path — no
+  such command existed and `pmacs.buffer.find_or_open` had no interactive
+  caller. Pure Lua in `builtin/commands/default.lua`, one keymap line, an
+  8-test dispatch-driven acceptance suite; no Rust, no protocol change.
+  Two substrate facts it documents, both worth knowing before touching
+  any minibuffer prompt:
+  - **Completion over files is flat and cannot be made hierarchical from
+    Lua.** A custom `source` function is called with **zero arguments**
+    (`minibuffer.rs:591`) and runs synchronously outside any coroutine,
+    where `Handle:await()` raises — so it can neither see the input to
+    re-root on nor list a directory. Only the Rust
+    `CompletionSource::Files { root }` can list, and it is
+    single-directory and 1024-capped.
+  - **A selected candidate SHADOWS typed text.** `recompute_candidates`
+    sets `selected = Some(0)` whenever the list is non-empty
+    (`minibuffer.rs:372-377`) and `resolve_accepted_value` returns the
+    candidate over the typed contents (`:564-574`). So free-text accept
+    fires only when the input filters every candidate away — for
+    basename candidates under a subsequence filter, when it contains a
+    `/`. This applies to `M-x` and `switch-buffer` too. Consequences are
+    pinned as decisions, including the hole where a new bare name that is
+    a subsequence of an existing entry opens the existing file, and the
+    empty-input case (`fuzzy_score` gives `Some(0)` for an empty needle
+    and ties break lexicographically, so dotfiles lead).
+  - Also: `get_or_load_buffer` computes a normalized path but **loads
+    from the raw one** (`editor_core.rs:842-856`), so a `~/…` path dedups
+    against an open buffer yet fails to load one that is not open —
+    find-file expands the tilde Lua-side. Loading through the normalized
+    path is a named deferral.
+- **GPU initial target LANDED — #148**
+  (`docs/gpu-initial-target-framing.md` rev 3; merge `0dd16a5`; two review
+  rounds). `pmacs --gpu [--socket NAME|PATH] FILE` transports exact Unix path
   refresh #150, folding Stage 2 #149, ledger refresh #147, web grammars #146,
   LaTeX Stage 1 #144 / inline-math framing #145, and folding Stage 1 #142),
   protocol **v20** (`SUPPORTED=[6..=20]`; v16 = `ThemeFacts`, v17 =