[TheGreatAxios]

Summary

• Apply verified doc fixes to docs/TUI.md (11 items: W1-W3, M1a, M1b, M2-M5, U1), each spot-checked against code before editing.
• Fix four stale TUI path lines in docs/ARCHITECTURE.md on the same branch.
• Docs text only; no behavior files touched.

Verification

• bun run lint: pass (exit 0)
• bun run typecheck: pass (exit 0)
• git diff --name-only: docs/TUI.md, docs/ARCHITECTURE.md

Fixes CL-7895

[linear-code]

CL-7895

[TheGreatAxios]

Corrected the observe findings (pushed as d6d6488):

• docs/TUI.md Subagent observe: the empty-state sentence now reads 'With no subagent session at all, the chord paints a system row saying so instead of opening anything.' The old 'no live subagent session' wording was wrong — observeSessionFromSubAgents (src/tui/runner/host.ts:250) falls back to the newest running session else the most recent session of any status, returning null only on an empty store, so with only completed sessions Alt+O opens history (covered by the fallback test in src/tui/runner-host.test.ts:145-156).
• docs/ARCHITECTURE.md Observe paragraph: fixed both stale paths — src/tui/runner-host.ts to src/tui/runner/host.ts, and shell.ts:observeActiveSubagent to src/tui/shell/observe.ts:observeActiveSubagent (defined at observe.ts:105).

No merge — fix only.

[TheGreatAxios]

Critic review — docs/TUI.md verification (PR #1016)

Independent read of the full diff (docs/TUI.md, docs/ARCHITECTURE.md; docs text only, no behavior files). Spot-checked each behavioral claim against code. No fixes made, per lane.

Blocking

None.

Verified (evidence)

• Runner/shell path updates: mountRunnerHost lives in src/tui/runner/host.ts; shell is now the src/tui/shell/ directory. New paths match the tree.
• OVERLAY_TRANSCRIPT_FLOOR drop of "proposed": src/tui/geometry/zones.ts:177 defines it as a real 8. The old "proposed" wording was stale; removal is correct.
• Subagent observe section: enterSubagentObserve in src/tui/shell/observe.ts:21; Alt+O chord calls observeActiveSubagent in src/tui/shell/keys.ts:819-829; no-session path paints a system row (observe.ts:112-116, "no subagent session to observe"). Matches the new doc paragraph.
• Escape-leaves-observe: src/tui/shell/keys.ts:301-304 leaves observe via leaveSubagentObserve when shell.observe is set, after overlay dismissal. The amended Escape sentence is accurate.
• Command origin markers: src/plugins/origin-marker.ts:11-17 ([bundled] for repo, [<origin>] otherwise) and src/tui/command-catalog.ts:42 applies withOriginMarker to registry items. The /name [bundled] / /name [<origin>] doc wording matches.
• Empty-state row: OVERLAY_EMPTY_STATE = "(no choices)" in src/tui/overlay-view.ts:58. New sentence is accurate.
• /plugins chords: src/tui/command-surfaces.ts:1032-1035 documents Enter toggles (blocked pre-trust), Alt+C/V/T/A/X/W — matches the amended doc line.
• MCP row states: mcpRowLabel in src/tui/command-surfaces.ts:1231-1246 returns exactly the five name — <state> strings the doc lists.
• Newline chords: PROMPT_KEY_BINDINGS in src/tui/prompt-input.ts:40-48 (shift/ctrl+return, linefeed) plus the linefeed-fallback comment at :30-36. The "portable pair vs kitty-only Shift+Enter" doc wording is a fair paraphrase.

Nits (non-blocking, author may take or leave)

• docs/ARCHITECTURE.md TUI bullet still reads **Shell** (\shell.ts`)while this same PR correctly migrates every other shell reference tosrc/tui/shell/`. One stale flat path survives the path-fix pass.
• Amended Escape sentence ("dismisses the open overlay, or leaves subagent observe when observe holds the transcript, and, for a permission…") is accurate but clunky with the doubled comma; consider "dismisses the open overlay — or leaves subagent observe when observe holds the transcript — and, for a permission…".
• New "Subagent observe" paragraph says "a running child's stream" while ARCHITECTURE (same PR) notes observe also covers the most recent historical session. Slight narrowing; adding "(live or, when done, historical)" would close it.

Verdict

Merge-ready. Docs-only, all behavioral claims verified against code, no blocking defects. Nits above are optional polish.