Document the actual OpenTUI send-path ingest

Architecture and implementation still claimed mention resolution and
image paste were unwired. Submit already ingests both; the map was
wrong.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -403,7 +403,7 @@ OpenTUI (`@opentui/core`) is the shipping shell; the Ink/React tree has been del
 - **Runner host** (`runner-host.ts`) — Runner-facing mount: catalog assembly from live config, chrome pushes on session change, subagent observe resolution, and session teardown (quitting is Ctrl+C twice, owned by the shell).
 - **Overlays and pickers** — Resume picker (`src/tui/pick-session.ts`) uses `runListModal` (`src/tui/list-modal.ts`). Slash-command surfaces (`/model`, `/settings`, `/permissions`, `/plugins`, etc.) route through `openCommandSurface` (`src/tui/command-surfaces.ts`).
 - **Auto mode** — Toggled by CLI flags only (`--auto` / `--no-auto`); there is currently no in-session key bound to it.
-- `@file` mention resolution and image paste are not wired on the OpenTUI send path.
+- **Send-path ingest** — Submit, leftover send, and live steer run `ingestOperatorPrompt` (`src/tui/prompt-attachments.ts`): inline image-path mentions become attachments (`findImagePathMentions` / `imageAttachmentFromPath`); `@file` contents are inlined and `@dir` mentions become a directory summary (`resolveAtMentions` in `mention-resolution.ts`). The mention popup splices paths into the prompt (`spliceMentionCompletion`); it does not send. Ctrl+V / Ctrl+P (and `/paste-image`) attach a macOS clipboard PNG (`attachClipboardImage` in `shell.ts` → `readClipboardImage`); Cmd+V stays text (bracketed paste). Linux/Windows bitmap clipboard paste is not supported.
 
 Known keybindings: `Ctrl+C` interrupts the in-flight run, and quits on a second press inside a two-second window.
 

docs/IMPLEMENTATION.md

@@ -195,9 +195,29 @@ Idle-with-fleet is shipped: after a non-blocking `spawn_agent` dispatch the pare
 
 `src/tui/stream-event-map.ts` maps reactor events onto the bridge's inbound events, and `src/tui/turn-state.ts` tracks the turn's status. `src/tui/turns-to-blocks.ts` hydrates a resumed session's stored turns into the same content blocks.
 
-### @file Mention Resolution
-
-`@-mention` resolution and image paste are not wired on the OpenTUI send path.
+### Send-path ingest
+
+Submit, leftover send, and live steer all run `ingestOperatorPrompt`
+(`src/tui/prompt-attachments.ts`) before the inbound user message is sent.
+That ingest:
+
+1. Turns inline image-path mentions (`/path/to/shot.png`, `file://…`) into
+   attachments via `ingestPathMentions` → `findImagePathMentions` /
+   `imageAttachmentFromPath` (`src/tui/image-attachments.ts`).
+2. Expands `@file` mentions to file contents and `@dir` mentions to a
+   directory summary via `resolveAtMentions` (`src/tui/mention-resolution.ts`),
+   gated by sensitive-path and size caps.
+3. Merges any pending clipboard attachments already sitting on the prompt.
+
+The `@` mention popup (`openAtMentionSuggestions` in `shell.ts`) only splices
+a path into the prompt (`spliceMentionCompletion`). Attachments land at send
+time, not at accept time.
+
+Ctrl+V / Ctrl+P and `/paste-image` call `attachClipboardImage` (`shell.ts`) →
+`readClipboardImage` (`image-attachments.ts`), which reads a macOS clipboard
+PNG via osascript `«class PNGf»`. Cmd+V is terminal bracketed paste and stays
+text. Linux and Windows bitmap clipboard paste is a separate product gap; do
+not treat bracketed-paste path text as a paste-time image gesture.
 
 ## Configuration
 

docs/TUI.md

@@ -587,6 +587,13 @@ sent messages. Once a real `paste` event has fired even once, the fallback
 heuristic is permanently skipped for the rest of the session
 (`shell.ts`, the `sawBracketedPaste` guard).
 
+Ctrl+V and Ctrl+P attach a PNG from the macOS clipboard
+(`attachClipboardImage` in `shell.ts` → `readClipboardImage` in
+`image-attachments.ts`).
+Cmd+V stays text (bracketed paste above). Clipboard image attach is
+macOS-only; Linux/Windows bitmap clipboard paste is not supported.
+`/paste-image` is the same attach path.
+
 @-mention path completion opens a popup keyed off the `@token` under the
 cursor (`openAtMentionSuggestions`, `src/tui/shell.ts`); every keystroke re-queries,
 and a generation counter discards a slower, stale query's results if a newer