phase: 123_chat_image_questions

All gates green. Verification complete. **Phase 123 — final verification pass (all 4 tasks already in `complete/`)** - Verified the full implementation is in the working tree: `app/api/chat_images.py` (upload/serve pair), `ChatRequest.image`/`ChatMessage.image` (path-validated, omitted-when-None), toggle-off + stale-file hinted error frames, `build_user_content` multimodal build at both sites (chat.py deflected branch + `run_agent`), config-gated composer attach/preview/upload-then-send, restore + shared rendering, CSP `img-src 'self' data:` carve-out, mock-LLM capture buffer. - `uv run pytest` → **2796 passed**, exit 0 (unit + integration). - `uv run pytest --cov=app --cov-report=term-missing` → **TOTAL 99%** (29/4615 missed; phase-123 modules 99–100%). - `uv run pytest tests/e2e/test_chat_image_questions.py -v --no-cov` → **5 passed** in isolation. - `uv run ruff check . && uv run pyright` → clean (0 errors). **Completion criteria:** (1) attach→send→multimodal text+image to the model, bubble/reload/shared all render it, saved chat stores the PATH with `"base64" not in json.dumps(stored)` — **verified** (E2E tests 1–4 + integration round-trip); (2) `BOR_IMAGES=false` — control hidden, exact hinted error frame, zero model calls / no query_log row — **verified** (E2E test 5 + integration); (3) text-only byte-identical (`content` stays a plain `str`) — **verified** (unit + integration); (4) all gates green — **verified**; (5) commit + phase move — left to the harness per pipeline rules (no `git add`/`commit` run). No defects found; no live-infrastructure changes (repo + local dev DB only). **Next pending phase: none** — 123 is the last phase in `todo/`.
phase: 122_image_documents
2026-09-25 05:19:18 -04:00 · 2026-09-25 01:54:23 -04:00 · 2026-09-24 20:51:39 -04:00 · 2026-09-24 18:50:36 -04:00 · 2026-09-24 16:27:44 -04:00
155 changed files with 15322 additions and 257 deletions
@@ -0,0 +1,51 @@
 # Phase 120 — Failed-turn retry: network errors and refresh survive a failed turn
 **Source:** `TODO.md` L3–4 — "Retry doesn't seem to work on network error" + "Refreshing the page after an error shows only the chat message you sent and no options to retry the message, forcing the user to click 'new chat' or be stuck."
 **Story:** n/a (bug-fix follow-up; extends the phase-49/53 redo-in-place retry, phase-67 LLM retry, and phase-111 banner Retry assets).
 **Context:** `frontend/assets/app.js` — `showErrorBanner(detail, opts)` (L2210) reveals `#banner-retry` only when `opts.retryable && lastBrainWrap` (L2222); `retryLastTurn(wrap)` (L2276) pops the LAST brain record and re-asks the user question immediately before it (the invariant `every brain record follows its user record`); `rememberBrainTurn(rawText, meta, replaceIndex)` (L2108) pushes/replaces the brain record in `conversation` + `saveConversation()` + `persistConversation()` (the phase-55 auto-save rides the same call). `lastBrainWrap` is assigned only on three paths: the `done` settle (L2609), the zero-frame fallback bubble (L2671), and the user-stop finalize (L2699) — **never on a turn error**. The error catch (the `else` branch at ~L2690) calls `setUiState(UI_STATE.error, detail, { hint })` with NO brain record persisted, whether or not a partial `wrap` exists. The stream-drop guard (~L2651, `!sawDone && !aborted && (acc || thinkingAcc)`) also lands in the error state with nothing persisted. Restore: `renderStoredMessage(m)` (L1642) renders `m.stopped` via `appendStoppedNote` (L486); the restore loop sets `lastBrainWrap` on the last restored brain bubble (L1694) and calls `markLastRetryable()` (L1708, L560 — removes all `.retry-btn`, re-adds on the LAST `.brain-wrap`). `app/schemas.py` — `ChatMessage` (L742) is `extra="forbid"` with fields `who`, `text` (≤32 000), `sources?`, `related?`, `deflected?`, `suggestions?`, `thinking?` (≤32 000), `tools?`, `stopped?: bool | None` (L786); `SavedChatCreate/Update` messages are non-empty, ≤200 (phase 83). `tests/e2e/mock_llm.py` + `tests/e2e/test_llm_retry.py` hold the existing LLM-failure mock pattern for the E2E.
 ## Objective
 A failed chat turn — network error (zero frames), SSE `error` frame, or mid-stream drop — leaves a **retryable error state** both live (the banner Retry and an in-bubble Retry both work) and after a page refresh (the failed turn restores as an error bubble with a working Retry button). No failed turn strands the user with a bare question and no recovery.
 ## Dependencies
 - `119_name_signal_read_chips` (complete) — pipeline predecessor (execution order) only.
 - Code dependencies (all complete): phase 49/53 `retryLastTurn` redo-in-place, phase 111 `#banner-retry`, phase 48 `stopped` persistence + `appendStoppedNote` pattern, phase 55 auto-save riding `rememberBrainTurn`.
 ## Design (shared by all tasks — the executor reads this, not the chat)
 - **Failed record (task 01, server side):** two new OPTIONAL fields on `ChatMessage`, the phase-48 `stopped` precedent (L786): `failed: bool | None = None` and `error: str | None = Field(default=None, max_length=500)` (the persisted error detail; 500 caps a hostile detail string in the phase-83 style). `extra="forbid"` stays — the keys are now declared, unknown keys still 422. No change in `app/api/chats.py` logic (the schema flows through `SavedChatCreate/Update`); the shared-chat shape (`SharedChatOut.messages`) carries failed records verbatim (text renders as-is on the shared page — no change needed there).
 - **Failed turn = a brain record (LOCKED A1):** a failed turn persists `{ who: "brain", text: <detail or fallback>, failed: true, error: <detail> }` via `rememberBrainTurn` — so it lands in localStorage AND the server-side saved chat through the existing phase-55 auto-save ride. There is no separate error table and no new API: `retryLastTurn`'s pop-the-last-brain-record-then-re-ask-the-preceding-question logic works on a failed record UNCHANGED (the invariant holds — the question's user record immediately precedes it).
 - **Live error paths (task 01, frontend):** the error catch's `else` branch (non-abort, non-stop) and the stream-drop guard BOTH funnel into one new helper `finalizeFailedTurn(detail, { acc, thinking, tools })`:
  - **Partial exists** (`wrap` with streamed text): close the thinking block + tool calls (the stop-finalize pattern), `appendFailedNote(wrap, detail)` (new, mirrors `appendStoppedNote` L486 — an in-bubble error line with the detail), persist via `rememberBrainTurn(acc, { thinking, tools, failed: true, error: detail }, leavePartialIndex)`, `lastBrainWrap = wrap`.
  - **No wrap** (network error, zero frames): create a brain bubble with a fixed fallback text (a short honest "my answer didn't make it" line — NOT the `EMPTY_ANSWER_FALLBACK` answer text; the `appendFailedNote` carries the real detail), persist the same record shape, `lastBrainWrap = fwrap`.
  - Then `markLastRetryable()` — the in-bubble Retry button appears, and `showErrorBanner`'s existing `opts.retryable && lastBrainWrap` condition (L2222) now holds on a turn error, so the phase-111 banner Retry appears too — **no change to `showErrorBanner`** (it binds `() => retryLastTurn(lastBrainWrap)` at reveal; `lastBrainWrap` is set before `setUiState(UI_STATE.error, …)` runs).
  - The zero-frame-but-stream-completed case keeps its existing fallback bubble (L2663–2673) — now ALSO marked `failed: true` + error note (it is a failed turn; the bubble text stays `EMPTY_ANSWER_FALLBACK` so the record keeps a meaningful `text`).
 - **Restore (task 02):** `renderStoredMessage(m)` gains the failed branch — a `m.failed` record renders as a brain bubble (the persisted `text`), gets `appendFailedNote(wrap, m.error)`, and gets NO Save-as-doc button (a note, not an answer — the `m.stopped` exclusion at L1687 precedent: `if (!m.stopped && !m.failed) appendSaveAsDocButton(…)`). No other restore change is required: the restore loop's `lastBrainWrap = wrap` (L1694) + `markLastRetryable()` (L1708) already target the last `.brain-wrap`, which is now the failed bubble → the in-bubble Retry button renders on refresh. `retryLastTurn` needs no change (the failed record is the last brain record; its preceding user record is the question).
 - **Interaction with `stopped`:** a turn is either stopped (user engaged, partial kept, `stopped: true`) or failed (`failed: true`) — mutually exclusive by construction (the stop path is the catch's `stoppedByUser`/`AbortError` branch, which this phase does not touch).
 - **NOT touched:** `retryLastTurn` itself, the stop path, the done path, the server save/restore API logic (schema fields only), the shared page rendering, and every non-chat `showErrorBanner` caller.
 ## Tasks
 1. `01_persist_failed_turn.md` — `ChatMessage.failed`/`error` fields + the live error paths persist a failed brain record with a rendered error bubble (banner Retry works on network errors).
 2. `02_restore_failed_turn.md` — restore renders a `failed` record as an error bubble with a working Retry button (the refresh case).
 3. `03_failed_turn_tests.md` — unit + integration + isolated E2E `test_failed_turn_retry.py`.
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_message_failed.py` (new, task 03) — `ChatMessage` accepts `failed`/`error`, `error` >500 chars 422s, unknown keys still 422, omitted keys round-trip `None`; `tests/unit/test_frontend_failed_turn.py` (new, task 03) — house-style source assertions: the error catch + stream-drop guard route through the failed-turn finalize (persist `failed: true`, call `markLastRetryable`), `appendFailedNote` exists and mirrors the stopped-note structure, the restore branch renders the note and excludes Save-as-doc, `showErrorBanner` is byte-unchanged (the `lastBrainWrap` condition untouched).
 - Integration: `tests/integration/test_chats_api.py` (extend) — `POST`/`PUT /api/chats` with a `failed: true` + `error` record round-trips byte-identically (the phase-50 contract); a shared chat carrying a failed record still serves (public shape unchanged).
 - E2E: `tests/e2e/test_failed_turn_retry.py` (new, task 03) — run in isolation per AGENTS.md §4. Scenarios (the `mock_llm.py` failure pattern from `test_llm_retry.py`): (A) network-class failure (zero frames) → banner with a visible Retry → click re-asks without re-typing; (B) SSE `error` frame after partial deltas → partial bubble keeps its text + error note + Retry → click re-asks; (C) reload the page after a failed turn → the failed bubble restores with a working Retry button → click re-asks.
 - Coverage: **>90%** on `app/` (validate.sh gate).
 ## Completion Criteria
 - [ ] A network-error turn shows a Retry (banner and/or in-bubble); clicking it re-asks the last question without re-typing.
 - [ ] Reloading the page after a failed turn shows the failed bubble (with the error detail) and a working Retry — no "new chat" required.
 - [ ] Stopped turns (phase 48) and successful turns behave byte-identically to before.
 - [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
 - [ ] One `--no-gpg-sign` commit; phase dir moved to `.agents/phases/complete/` by the pipeline gate.
 ## Locked decisions
 - **A1 — a failed turn persists as a brain record with a `failed` marker (+ capped `error` detail), the phase-48 `stopped` precedent; no separate error table, no new API, `retryLastTurn` reused unchanged (owner-confirmed 2026-09-24, roadmap confirmation).**
 - **Banner Retry stays as-is** — the phase-111 `opts.retryable && lastBrainWrap` condition is kept; this phase makes `lastBrainWrap` exist on the error paths so the existing button finally appears (owner-confirmed: same mechanism, no `showErrorBanner` change).
 ## Commit
 ```bash
 git add app/ frontend/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "fix(chat): persist failed turns so retry works on network errors and survives a refresh"
 ```
@@ -0,0 +1,37 @@
 # Task 01 — Persist the failed turn: schema fields + live error paths
 **Phase:** `120_failed_turn_retry` · **Source:** `TODO.md:3–4` — "Retry doesn't seem to work on network error" + "Refreshing the page after an error shows only the chat message you sent and no options to retry the message, forcing the user to click 'new chat' or be stuck."
 ## Objective
 Every failed chat turn (network error, SSE `error` frame, stream drop) persists a `failed: true` brain record and renders a retryable error bubble live — so the phase-111 banner Retry finally appears on network errors (its `lastBrainWrap` precondition now holds).
 ## Work
 1. `app/schemas.py` — `ChatMessage` (L742, `extra="forbid"`): add, next to `stopped` (L786),
   ```python
   failed: bool | None = None
   error: str | None = Field(default=None, max_length=500)
   ```
   Extend the docstring: the phase-48 `stopped` precedent — a FAILED turn (network/SSE error/stream drop) stores `{who: "brain", text: <detail or fallback>, failed: true, error: <detail>}`; `error` is the persisted banner detail, capped at 500 (phase-83 value-bounds style). No serializer change — `None` values flow as absent/None exactly like `stopped` today (the phase-50 byte-identical round-trip contract covers the new keys automatically).
 2. `frontend/assets/app.js`:
   - New `appendFailedNote(wrap, detail)` — mirror of `appendStoppedNote` (L486): one `.failed-note` per bubble (guard query), a visible error line inside the brain bubble carrying `detail` (the banner keeps its role="alert" summary; the note is the in-bubble, refresh-surviving copy).
   - New `finalizeFailedTurn(detail, { acc, thinking, tools, wrap, leavePartialIndex })` — the single funnel for every non-stop, non-abort turn failure:
     - `wrap` exists (partial streamed): `closeThinkingBlock(wrap)` + `closeToolCalls(wrap)` (the stop-finalize pattern, ~L2685), `appendFailedNote(wrap, detail)`, `rememberBrainTurn(acc, { thinking: thinking || undefined, tools: tools.length ? tools : undefined, failed: true, error: detail }, leavePartialIndex)`, `lastBrainWrap = wrap`.
     - no `wrap` (network error, zero frames): `fwrap = addMessage("brain", FAILED_TURN_TEXT)` where `FAILED_TURN_TEXT` is a new short honest constant ("My answer didn't make it — the connection dropped. Use Retry to ask again.") — NOT `EMPTY_ANSWER_FALLBACK` (that constant stays for the zero-frame-but-completed case); `appendFailedNote(fwrap, detail)`, `rememberBrainTurn(FAILED_TURN_TEXT, { failed: true, error: detail }, leavePartialIndex)`, `lastBrainWrap = fwrap`.
     - end with `markLastRetryable()`.
     - `detail` is the trimmed error string, truncated to 500 chars before persistence (the schema cap is the backstop).
   - The error catch's `else` branch (~L2690, currently `setUiState(UI_STATE.error, detail, { hint })` with no persistence): call `finalizeFailedTurn(detail, {…})` BEFORE `setUiState(UI_STATE.error, detail, err.hint ? { hint: err.hint } : {})` (the banner stays — now with its Retry revealed because `lastBrainWrap` is set).
   - The stream-drop guard (~L2651, `!sawDone && !aborted && (acc || thinkingAcc)` → currently a bare `setUiState(UI_STATE.error, "The stream ended before my answer finished — try again?")`): route through the same `finalizeFailedTurn` with that detail (the partial persists as failed — a half-answer is a failed answer, and Refresh must restore what the user saw + a Retry).
   - The zero-frame-but-completed fallback bubble (L2663–2673): add `failed: true` + `error: "The model answered with nothing."` to its `rememberBrainTurn` call and `appendFailedNote(fwrap, …)` — the bubble text stays `EMPTY_ANSWER_FALLBACK`.
   - Do NOT touch: `showErrorBanner` (L2210), `retryLastTurn` (L2276), the stop branch, the done settle (L2609), `markLastRetryable` (L560).
 3. `frontend/assets/styles.css` — `.failed-note`: the in-bubble error line treatment (the `.stopped-note` family, error-colored per the current theme's error token — contrast ≥4.5:1, PLAN §7).
 4. ASSUMPTION: the zero-frame-but-completed case (stream returns, no events, no throw) is also marked failed — it is a failed turn, and its record previously persisted with no marker (inconsistent with the refresh case this phase fixes).
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_message_failed.py` (shipped with task 03's test task — this task ships the code): `ChatMessage` accepts `failed: true` + `error`; `error` >500 chars → 422; an unknown key still → 422; a record without the new keys is byte-identical to before. `tests/unit/test_frontend_failed_turn.py` (task 03): the catch `else` branch + stream-drop guard + zero-frame fallback all route through the failed finalize (persist `failed: true`, call `markLastRetryable`); `appendFailedNote` exists; `showErrorBanner` and `retryLastTurn` sources are untouched (byte-pinned).
 - Coverage: **>90%** on `app/` for the schema change (the frontend JS is pinned by source-assertion unit tests).
 ## Completion Criteria
 - [ ] `ChatMessage` round-trips `failed`/`error` (unit tests green).
 - [ ] A zero-frame network error (E2E scenario A, task 03) shows the banner WITH a visible Retry button and a failed bubble with the error detail.
 - [ ] No call site outside the three failed paths persists `failed: true` (grep).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,25 @@
 # Task 02 — Restore the failed turn: refresh keeps the Retry
 **Phase:** `120_failed_turn_retry` · **Source:** `TODO.md:4` — "Refreshing the page after an error shows only the chat message you sent and no options to retry the message, forcing the user to click 'new chat' or be stuck."
 ## Objective
 A `failed` record restores as an error bubble (persisted text + error note) that carries a working Retry button — the refreshed page is the same retryable state the live error was, and Retry re-asks the question through the unchanged `retryLastTurn`.
 ## Work
 1. `frontend/assets/app.js` — `renderStoredMessage(m)` (L1642): add the failed branch, mirroring the `m.stopped` handling (L1685–1688):
   - a `m.failed` brain record renders its `text` (the persisted detail or fallback line) as the bubble content, then `appendFailedNote(wrap, m.error)` (the note is absent when `m.error` is null — the record's `text` already carries it), and
   - `if (!m.stopped && !m.failed) appendSaveAsDocButton(wrap, m.text);` — a failed turn is a note, not an answer (the stopped exclusion precedent at L1687).
   - No Tune button for failed records either (a note, not an answer — same scope as the `m.stopped` exclusion around L584–588 if the restore call site applies it there).
   - No other restore change: the restore loop already sets `lastBrainWrap = wrap` on the last restored brain bubble (L1694) and calls `markLastRetryable()` (L1708), which removes every `.retry-btn` and re-adds it on the LAST `.brain-wrap` — the failed bubble. `retryLastTurn` works unchanged: the failed record is the last brain record, the user record immediately before it is the question (the invariant holds by construction — task 01 persists the brain record right after the user record), so the redo-in-place pops the failed record and re-asks.
 2. `frontend/assets/app.js` — the shared-chat restore (`frontend/assets/shared.js` / the shared page): failed records render their `text` as a plain brain bubble (no note, no Retry — the shared view is read-only and text-only by design; no change beyond confirming the `renderStoredMessage`-equivalent there does not choke on the unknown-looking `failed`/`error` keys — it renders `text` only).
 3. ASSUMPTION: a failed bubble restored at the END of the conversation gets the Retry; a failed bubble in the MIDDLE of a longer conversation does not (the phase-49 last-bubble-only rule, unchanged).
 ## Testing & Quality
 - Unit: `tests/unit/test_frontend_failed_turn.py` (task 03): the restore branch renders the failed note, excludes Save-as-doc (and Tune, where applicable), and the restore path is the only place `m.failed` is read for rendering; the shared page renders failed records text-only.
 - E2E: scenario C of `tests/e2e/test_failed_turn_retry.py` (task 03) pins this task end-to-end.
 - Coverage: n/a (frontend) — the validate.sh `app/` gate must stay green.
 ## Completion Criteria
 - [ ] Reload after a failed turn (E2E scenario C): the failed bubble shows with its error detail and a Retry button; clicking Retry re-asks the preceding question without re-typing and the failed record is replaced by the new answer.
 - [ ] A mid-conversation failed record restores with NO Retry button (last-bubble-only rule intact).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,34 @@
 # Task 03 — Failed-turn tests: unit + integration + isolated E2E
 **Phase:** `120_failed_turn_retry` · **Source:** `TODO.md:3–4` — "Retry doesn't seem to work on network error" + "Refreshing the page after an error shows only the chat message you sent and no options to retry the message …"
 ## Objective
 Pin the whole failed-turn contract: the schema boundary, the save/restore round-trip, the three live failure paths, and the two user scenarios (retry on network error; retry after refresh) as an isolated Playwright suite.
 ## Work
 1. `tests/unit/test_chat_message_failed.py` (new):
   - `ChatMessage` accepts `{who: "brain", text: "…", failed: true, error: "detail"}`; `error` of 501 chars → 422; an unknown key (e.g. `"foo": 1`) → 422 (`extra="forbid"` intact); a record WITHOUT the new keys serializes byte-identically to a pre-phase record (the phase-50 contract).
 2. `tests/unit/test_frontend_failed_turn.py` (new) — house-style source assertions (the phase-111 `test_frontend_banner_retry.py` pattern):
   - the error catch `else` branch, the stream-drop guard, and the zero-frame fallback bubble all persist `failed: true` (grep the three sites for the `failed: true` persist) and each funnel path ends with `markLastRetryable`;
   - `appendFailedNote` exists and guards against duplicates (one `.failed-note` per bubble);
   - `FAILED_TURN_TEXT` is a distinct constant (not `EMPTY_ANSWER_FALLBACK`);
   - `showErrorBanner` and `retryLastTurn` are byte-unchanged (pin their source — the phase's explicit "NOT touched" contract);
   - the restore branch renders `m.failed` (note + Save-as-doc exclusion).
 3. `tests/integration/test_chats_api.py` (extend):
   - `POST /api/chats` with a brain record `{text, failed: true, error: "…"}` returns it byte-identically; `PUT` re-Save round-trips it; `error` >500 chars → 422;
   - a shared chat (the phase-51 `share` path) carrying a failed record still serves `GET /api/shared/{token}` (public shape — `title` + `messages` — unchanged).
 4. `tests/e2e/test_failed_turn_retry.py` (new — ONE file, run in isolation per AGENTS.md §4: `uv run pytest tests/e2e/test_failed_turn_retry.py -v --no-cov`), reusing `tests/e2e/mock_llm.py`'s failure pattern from `tests/e2e/test_llm_retry.py`:
   - **A — network error:** mock the chat endpoint to fail with ZERO frames (connection reset / immediate close — the same failure `test_llm_retry.py` exercises past its retry budget, or a hard 500 if the mock supports it) → assert: the banner is visible with a working Retry button AND a failed bubble with the error detail exists → click banner Retry → the question is re-asked (mock now succeeds) → a grounded answer renders and the failed bubble is gone.
   - **B — SSE error frame with partial:** mock streams some `delta` frames then an `error` frame → assert: the partial bubble KEEPS its streamed text + shows the error note + carries the in-bubble Retry → click it → re-asked in place (redo-in-place: the failed record is replaced by the new answer).
   - **C — refresh:** fail a turn (as in A) → `page.reload()` → assert: the question + the failed bubble restore (error detail visible) + the Retry button is present on the failed bubble → click it → re-asked → answer renders.
   - Negative: a STOPPED turn (user Stop) still restores with the "Answer stopped." note and NOT a failed note (phase 48 unchanged).
 5. Run the full gate: `uv run pytest` (unit + integration), `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), the isolated E2E file, `uv run ruff check . && uv run pyright`.
 ## Testing & Quality
 - This task IS the phase's test suite (see Work).
 - Coverage: **>90%** on `app/` — the only `app/` code in this phase is the `ChatMessage` schema (100% by the unit cases).
 ## Completion Criteria
 - [ ] All four test artifacts exist and pass; the isolated E2E file passes standalone.
 - [ ] `uv run pytest --cov=app` TOTAL >90%; lint + types clean.
 - [ ] No test asserts the old (broken) behavior — grep for any assertion that a network error shows NO Retry (must not exist).
@@ -0,0 +1,48 @@
 # Phase 121 — Private git sources: a token that never reaches the UI or the API
 **Source:** `TODO.md` L5 — "Need a way to add private repos without exposing the token in the UI (like when adding an https repo `https://myuser:ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@github.com/myuser/my-private-repo.git`)"
 **Story:** n/a (feature request; extends the phase-28/35/38 git/local sources and phase-89 per-source settings assets).
 **Context:** `app/models.py:245` — `GitSource`: `url: Text UNIQUE NOT NULL`, `kind` ("git"/"local"), `path`, `ignore_paths` (JSONB), `include_hidden`, `added_at` — no token column. `app/schemas.py` — `GitSourceIn` (L561: `kind`, `url` min 1/max 500, `path`, `ignore_paths`, `include_hidden`; `_trim_url` before-validator L594), `GitSourceOut` (L605: `url: str`), `GitSourceRow` (L626: `url`), `GitSourcePatchIn` (L651). `app/api/git_sources.py` — `URL_RE = ^(?:https?://|ssh://|git@)` (L195; a prefix match, so `user:token@` URLs pass); POST validates the prefix (L344–345) and duplicates via `GitSource.url == url` (L349); GET list / GET single return `row.url` RAW (L235, L250, L297, L423) — an embedded token is echoed to any browser (the leak); the local-source upload endpoint (L432). `app/api/sync.py:296` — `clone_or_pull(row.url, sources_root / repo_name(row.url))`; `scripts/git_sync.py` — `clone_or_pull`, `repo_name`; `scripts/import_docs.py::_resolve_sources` — the CLI's second clone caller (both consume `app.rag.git_sources.effective_sources`, L27). `frontend/assets/git-sources.js` — add form `#git-source-url` (L241; submit `body: (url) => ({ url })` L945); every display site renders `s.url` raw (list cell L395–406 incl. the `title` attr, delete row L533, edit modal L697, ignore-list context L763/L830). `alembic/` — migrations.
 ## Objective
 Private repos are added with a bare URL plus an optional MASKED token field. The token lives in a dedicated DB column, is injected only into the clone URL at sync/clone time, and is absent from every API response and UI surface — including legacy rows that already embed the token in `url` (those are sanitized on output but keep working).
 ## Dependencies
 - `120_failed_turn_retry` (todo) — pipeline predecessor (execution order) only; no code dependency.
 - Code dependencies (all complete): phase 35/38 `GitSource` kinds + `effective_sources`, phase 89 per-source settings (the PATCH-field precedent), phase 28 `clone_or_pull`/`repo_name`.
 ## Design (shared by all tasks — the executor reads this, not the chat)
 - **Storage (task 01, LOCKED A2):** `GitSource.token` — `Text NULL` (NULL = public/no credential; **plaintext by necessity** — the repo must remain cloneable, so the raw credential must be recoverable; the Postgres DB is the trusted store and is never served to the UI; there is deliberately no external secrets backend). `GitSourceIn.token: str | None = None` (max 500, trimmed); `GitSourcePatchIn.token: str | None = None` — PATCH semantics: **absent/None = no change, non-empty = replace, empty string = clear** (the UI offers replace; clear exists for API completeness). `GitSourceOut`/`GitSourceRow` gain NO token field — no response shape ever carries it (LOCKED A2).
 - **Normalization (task 02):** on POST (and PATCH when a new url/token arrives), the server normalizes: if the incoming URL contains userinfo (`user:pass@host`, only for `https?://` URLs — ssh/`git@` carry no userinfo), the **userinfo is stripped** for storage and the embedded credential is moved into `token` — UNLESS the caller also sent an explicit `token` field, which WINS (explicit beats embedded). Pasting the old-style `https://user:ghp_…@github.com/x/y.git` URL still works and ends up token-column-clean. The duplicate check (L349) runs on the NORMALIZED bare URL, so the same repo with a different token is still the same source (409, not a second row).
 - **Clone-time credential (task 02):** `clone_url_for(row) -> str` in `app/rag/git_sources.py` (next to `effective_sources`): `row.url` unchanged when `token` is NULL; otherwise inject `https://x-access-token:<token>@<host>/<path>` (https rows only — a token on a non-https row is a no-op with a warning log). `repo_name` keeps operating on the bare `row.url`. Callers switch from `row.url` to `clone_url_for(row)`: `app/api/sync.py:296` and `scripts/import_docs.py::_resolve_sources` (both already import from `app.rag.git_sources`).
 - **Output sanitization (task 02, LOCKED A2):** every API surface that returns a git URL runs it through `sanitize_url(url)` (new, in `app/rag/git_sources.py`): strips the userinfo component (`https://…@host/…` → `https://host/…`), leaves ssh/`git@`/local paths untouched. Applied to `GitSourceOut.url` / `GitSourceRow.url` construction (GET list L235/L297, GET single, the `BOR_GIT_SOURCES` env fallback rows L250 — env rows can embed tokens too) and to any sync-status field echoing a repo URL (grep for `url=` in the sync responses). Belt-and-braces for legacy embedded-token rows whose credential is NOT in the `token` column: their DB value is untouched (the clone still authenticates from the stored URL) but no API/UI output ever shows the credential.
 - **UI (task 03):** the add form gains a second field — a masked `<input type="password" id="git-source-token">`, optional, labelled "Token (private repos)" with a visible "optional" hint; submit sends `{ url, token }` (token omitted when blank). The edit modal mirrors it with placeholder "leave blank to keep the current token" (blank → omit from PATCH = no change). Every display site keeps rendering `s.url` — now bare by server sanitization, so list cells, `title` attributes, the delete row, and the ignore-list context become token-free with no per-site change. No new CSS beyond reusing the existing form-field styles (the theme's input treatment).
 - **NOT touched:** local-kind sources (no URL credential), the `BOR_GIT_SOURCES` env parsing (its rows are sanitized on OUTPUT only), the upload endpoint, sync scheduling, and the Sources page layout.
 ## Tasks
 1. `01_token_storage.md` — migration + `GitSource.token` + input schemas (`GitSourceIn`/`GitSourcePatchIn`); no token in any output shape.
 2. `02_clone_url_and_sanitization.md` — URL/token normalization on write, `clone_url_for` at clone time, `sanitize_url` on every output.
 3. `03_ui_token_field.md` — masked token field in the add form + edit modal; display stays `s.url` (now bare).
 4. `04_token_tests.md` — unit + integration + isolated E2E `test_git_source_tokens.py`.
 ## Testing & Quality
 - Unit: `tests/unit/test_git_source_token.py` (new, task 04) — `sanitize_url` (https userinfo stripped, ssh/git@/local untouched, no-userinfo unchanged), `clone_url_for` (NULL token → bare URL; token → injected; non-https token → bare + no crash), normalization (embedded token moved to the column when no explicit token; explicit token wins; duplicate on bare URL).
 - Integration: `tests/integration/test_git_sources_api.py` (extend) — POST with `token` → GET list/single responses contain the token NOWHERE (assert on the raw JSON text) and show the bare URL; POST with an old-style embedded-token URL → stored bare + token column populated, responses clean; PATCH token replace/clear semantics; the sync flow builds the clone URL with the injected token (mock `clone_or_pull`).
 - E2E: `tests/e2e/test_git_source_tokens.py` (new, task 04) — isolated run per AGENTS.md §4: add a private repo through the Sources UI (bare URL + token) → the list row shows the bare URL, the token is absent from the page text, the `title` attribute, and `GET /api/git-sources` JSON; edit the row (blank token) → no 4xx, token kept.
 - Coverage: **>90%** on `app/` (validate.sh gate).
 ## Completion Criteria
 - [ ] A private repo added via the UI (or a pasted embedded-token URL) syncs/clones fine, and its token appears in NO API response, NO page text, and NO attribute.
 - [ ] Legacy embedded-token rows (pre-phase) still clone, and their API/UI output is token-free.
 - [ ] Public repos and local sources behave byte-identically to before.
 - [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
 - [ ] One `--no-gpg-sign` commit; phase dir moved to `.agents/phases/complete/` by the pipeline gate.
 ## Locked decisions
 - **A2 — the token is stored PLAINTEXT in a dedicated `GitSource.token` column (cloneability requires the raw credential; no external secrets backend), is NEVER returned by any API shape, and legacy embedded-token URLs are sanitized on output while keeping their stored value for clones (owner-confirmed 2026-09-24, roadmap confirmation).**
 - **A6 — pasting an old-style embedded-token URL is accepted and normalized (userinfo → `token` column); an explicit `token` field wins over an embedded one (owner-confirmed: same confirmation — the proposed design).**
 ## Commit
 ```bash
 git add app/ alembic/ frontend/ scripts/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(sources): add private git repos with a masked token that never reaches the UI or API"
 ```
@@ -0,0 +1,38 @@
 # Task 01 — Token storage: model, migration, input schemas
 **Phase:** `121_git_source_tokens` · **Source:** `TODO.md:5` — "Need a way to add private repos without exposing the token in the UI (like when adding an https repo `https://myuser:ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@github.com/myuser/my-private-repo.git`)"
 ## Objective
 The `git_sources` table can hold a per-row token, and the add/patch input shapes can carry one — while NO output shape (`GitSourceOut`, `GitSourceRow`, list, single, env-fallback rows) ever can.
 ## Work
 1. `app/models.py` — `GitSource` (L245): add
   ```python
   #: Private-repo credential (phase 121, LOCKED A2): the PAT the owner
   #: types into the masked Sources-page field. NULL = public repo (or a
   #: legacy row whose credential is still embedded in ``url``). Stored
   #: plaintext BY NECESSITY — the repo must remain cloneable, so the
   #: raw credential must be recoverable at sync time; the DB is the
   #: trusted store and is never served to the UI. Injected into the
   #: clone URL ONLY at clone time
   #: (:func:`app.rag.git_sources.clone_url_for`); NEVER returned by
   #: any API shape (the output models gain no token field).
   token: Mapped[str | None] = mapped_column(Text, default=None)
   ```
   (docstring first, then the column — the phase-89/105 field-docstring house style).
 2. `alembic/versions/` — new revision (head of the current chain): `op.add_column("git_sources", sa.Column("token", sa.Text(), nullable=True))` + downgrade `op.drop_column`. Follow the existing migration file conventions (check the latest revision for the revision/down_revision pattern).
 3. `app/schemas.py`:
   - `GitSourceIn` (L561): add `token: str | None = Field(default=None, max_length=500)` with a `before`-mode trim validator (the `_trim_url` L594 precedent) — plus the docstring note: masked input from the Sources page; absent/None = no credential.
   - `GitSourcePatchIn` (L651): add `token: str | None = Field(default=None, max_length=500)` — docstring the PATCH tri-state: **absent/None = no change, non-empty = replace, empty string = clear**.
   - `GitSourceOut` (L605) / `GitSourceRow` (L626): add NO field; extend their docstrings with the explicit "no token — never a response field (phase 121)" note so the omission is a documented contract, not an accident.
 4. No endpoint changes in this task (acceptance of `token` and normalization are task 02) — the extra field on the input models is inert until then (Pydantic would currently just pass it through unused; task 02 consumes it).
 ## Testing & Quality
 - Unit: `tests/unit/test_git_source_token.py` (task 04 extends): `GitSourceIn`/`GitSourcePatchIn` accept/trim `token`; `GitSourceOut`/`GitSourceRow` reject a `token` key (they are output models built from rows — assert constructing them with a token kwarg raises).
 - Integration: `tests/integration/test_git_sources_api.py` (task 04) — after `alembic upgrade head`, `git_sources.token` exists (a `SELECT` sanity check in the existing test fixtures).
 - Coverage: **>90%** on `app/` for the touched modules.
 ## Completion Criteria
 - [ ] `uv run alembic upgrade head` applies the new revision on a clean DB and the downgrade removes the column.
 - [ ] The ORM round-trips a `token` value; output models have no token field (grep + unit assertion).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,29 @@
 # Task 02 — Clone-time credential + output sanitization
 **Phase:** `121_git_source_tokens` · **Source:** `TODO.md:5` — "Need a way to add private repos without exposing the token in the UI …"
 ## Objective
 The token is injected into the clone URL only at clone time, old-style embedded-token URLs are normalized into the column on write, and every URL that leaves the API is token-free — including legacy rows and env-fallback rows.
 ## Work
 1. `app/rag/git_sources.py` — add two pure helpers (unit-testable, no DB):
   - `sanitize_url(url: str) -> str` — strip the userinfo component of `https?://` URLs (`https://user:pass@host/path` → `https://host/path`); leave `ssh://`, `git@`, and local paths untouched; idempotent. Use a small regex (`^(https?://)([^/@]+)@` → `\1`) — never a URL parser that re-serializes (byte-identical output for clean URLs is a requirement: the phase-50/35 contract is that stored URLs surface verbatim when they carry no credential).
   - `clone_url_for(row) -> str` — `row.url` when `row.token` is falsy; for an `https://` row with a token, inject `https://x-access-token:<token>@<host>/<path>` (replace any existing userinfo with the column credential); for a non-https row with a token, log a warning and return `row.url` unchanged (a token cannot authenticate ssh — the owner must use a deploy key/agent there).
   - Also `normalize_credential(url, token) -> (bare_url, effective_token)` — the write-path normalizer: if `url` (https only) contains userinfo, strip it → bare URL, and the embedded credential becomes `effective_token` UNLESS `token` is non-None (explicit wins, LOCKED A6). Returns the input untouched for clean URLs.
 2. `app/api/git_sources.py`:
   - POST git source (L342–355): run `normalize_credential(payload.url, payload.token)`; store the BARE url + `effective_token`; the duplicate check (L349) runs on the bare URL.
   - PATCH (the url/token branch): when `payload.url` or `payload.token` is present, re-normalize the (current or new) pair with the same rules — PATCH token tri-state from task 01 (None = no change, `""` = clear → store NULL, non-empty = replace).
   - Every output construction runs `sanitize_url` on the URL before it enters the response: the DB-row list path (L235/L297), the GET single path (L423), and the `BOR_GIT_SOURCES` env-fallback rows (L250 — an env URL can embed a token; the ENV VALUE itself is untouched, only the response is masked). Grep the router for any other `url=` response field (including sync-status echoes — `app/api/sync.py` responses that surface a repo URL get the same treatment) and sanitize those too.
 3. `app/api/sync.py` (L296) + `scripts/import_docs.py::_resolve_sources` — swap `row.url` → `clone_url_for(row)` at the clone call site (`clone_or_pull(clone_url_for(row), sources_root / repo_name(row.url))` — `repo_name` stays on the bare URL so the checkout directory name is credential-free).
 4. ASSUMPTION: `x-access-token` as the injected userinfo username (GitHub-agnostic — any git host that accepts `https://user:token@` treats the first component opaquely; `oauth2:` is also common, but `x-access-token` works on GitHub and GitLab and reads as non-identifying).
 ## Testing & Quality
 - Unit: `tests/unit/test_git_source_token.py` (task 04 finalizes) — `sanitize_url` (strip/no-op/idempotent/ssh/git@/local), `clone_url_for` (NULL token; token injected; non-https token no-op), `normalize_credential` (embedded→column, explicit wins, clean URL untouched).
 - Integration: `tests/integration/test_git_sources_api.py` (task 04) — POST embedded-token URL → row.url bare + row.token populated; GET list JSON (raw text) contains the token NOWHERE; sync with a token row (mock `clone_or_pull`) receives the injected URL and a credential-free checkout path.
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] No token string in ANY API response for a token-bearing row (integration assertion on raw JSON text).
 - [ ] A legacy row (token embedded in the stored `url`, `token` NULL) still produces the ORIGINAL stored URL at clone time (the credential keeps working) but its API output is masked.
 - [ ] `repo_name` / checkout paths are credential-free.
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,30 @@
 # Task 03 — UI: masked token field on add + edit
 **Phase:** `121_git_source_tokens` · **Source:** `TODO.md:5` — "Need a way to add private repos without exposing the token in the UI …"
 ## Objective
 The Sources-page git-source form takes a separate masked token field (add and edit); every display surface shows the bare URL (server-sanitized) and the token is nowhere in the DOM.
 ## Work
 1. `frontend/assets/git-sources.js`:
   - Add form (the `#git-source-url` field at L241, submit wiring at L942–945): add a second labelled field
     ```html
     <label for="git-source-token">Token <span class="field-hint">optional — private repos</span></label>
     <input type="password" id="git-source-token" autocomplete="off" placeholder="ghp_… or another PAT">
     ```
     (reuse the existing form-field markup/CSS classes from the url field — the theme's input treatment, no new CSS needed beyond the existing `.field-hint` or an equivalent inline span). Submit body becomes `(url, token) => ({ url, ...(token ? { token } : {}) })` — blank token = key omitted (None = no credential).
   - Edit modal (the url display/edit at L697): the same masked token field, placeholder "leave blank to keep the current token"; PATCH body includes `token` ONLY when non-blank (blank → omitted → no change — the task-01 tri-state).
   - Display sites (L395–406 list cell incl. the `title` attribute, L533 delete row, L763/L830 ignore-list context): keep rendering `s.url` UNCHANGED — the server now returns bare URLs, so nothing to do per site. Add a source-comment note (one line) that URLs arrive sanitized server-side (phase 121) and the UI must never re-embed a credential.
 2. `frontend/assets/styles.css` — only if the "optional" hint span has no existing class to reuse: a minimal `.field-hint` (muted color, contrast ≥4.5:1 per PLAN §7, small).
 3. ASSUMPTION: the password field is `type="password"` with `autocomplete="off"` (a PAT is not a site credential; browsers must not offer to save it).
 ## Testing & Quality
 - Unit: `tests/unit/test_git_source_token.py` (task 04) — house-style source assertions: `#git-source-token` is `type="password"` and `autocomplete="off"`; the submit body omits a blank token; the edit PATCH omits a blank token; no display site concatenates a token.
 - E2E: `tests/e2e/test_git_source_tokens.py` (task 04) — the UI scenarios.
 - Coverage: n/a (frontend) — the validate.sh `app/` gate must stay green.
 ## Completion Criteria
 - [ ] Adding a private repo through the UI with a token succeeds; the list row shows the bare URL.
 - [ ] The token is absent from the rendered page text, the `title` attribute, and the Sources-page DOM (E2E assertion).
 - [ ] Editing with a blank token keeps the existing credential (integration: the PATCH tri-state).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,36 @@
 # Task 04 — Token tests: unit + integration + isolated E2E
 **Phase:** `121_git_source_tokens` · **Source:** `TODO.md:5` — "Need a way to add private repos without exposing the token in the UI …"
 ## Objective
 Pin the whole credential contract: helpers are pure and correct, no token ever crosses the API boundary (raw-JSON assertion), legacy rows stay cloneable and masked, and the UI never renders a credential.
 ## Work
 1. `tests/unit/test_git_source_token.py` (new):
   - `sanitize_url` — https userinfo stripped (`https://myuser:ghp_x@github.com/x/y.git` → `https://github.com/x/y.git`), clean https unchanged byte-identically, `ssh://git@host/x.git` untouched, `git@github.com:x/y.git` untouched, a local path untouched, idempotent on already-clean URLs.
   - `clone_url_for` — `token` NULL → `row.url` verbatim; https + token → `https://x-access-token:<token>@host/path` (existing userinfo REPLACED); non-https + token → `row.url` (no crash, warning logged).
   - `normalize_credential` — embedded userinfo → bare URL + token populated; explicit token wins over embedded; clean URL + None token → unchanged.
   - Output models: `GitSourceOut`/`GitSourceRow` reject a `token` kwarg (no response field can ever carry it).
   - Frontend source assertions (house style): `#git-source-token` is `type="password"` + `autocomplete="off"`; submit/PATCH omit a blank token.
 2. `tests/integration/test_git_sources_api.py` (extend):
   - POST `{url: "https://github.com/acme/private.git", token: "ghp_test123"}` → 201; `GET /api/git-sources` raw response TEXT does not contain `ghp_test123`; the row's `url` is the bare URL; `GET` single likewise.
   - POST an old-style `https://myuser:ghp_legacy@github.com/acme/legacy.git` (no token field) → stored `url` bare, `token` = `ghp_legacy`; responses token-free.
   - POST the same repo a second time (different token) → 409 (duplicate on the bare URL).
   - PATCH token tri-state: absent → kept; non-empty → replaced (clone URL uses the new one); `""` → cleared (clone URL bare again).
   - Legacy-row simulation (insert a row directly with the embedded URL, `token` NULL): `GET` output masked; the sync path (mock `clone_or_pull`) still receives the ORIGINAL stored URL (clone works).
   - Sync flow: a token row → `clone_or_pull` called with the injected URL; the checkout path is credential-free.
 3. `tests/e2e/test_git_source_tokens.py` (new — isolated run per AGENTS.md §4: `uv run pytest tests/e2e/test_git_source_tokens.py -v --no-cov`):
   - Open the Sources page (admin), add a git source with a bare URL + a distinctive fake token (`ghp_e2esecret…`);
   - assert: the list row renders the BARE URL; the token string is absent from `document.body.innerText`, from every `title` attribute, and from the `GET /api/git-sources` JSON (via a `page.request.get` inside the test);
   - open the edit modal: the token field is blank (never pre-filled — a password must not be echoed back, so it is simply empty by design); save with it blank → 200, row intact;
   - remove the source (cleanup) — the list is empty again.
 4. Run the full gate: `uv run pytest`, `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), the isolated E2E file, `uv run ruff check . && uv run pyright`.
 ## Testing & Quality
 - This task IS the phase's test suite (see Work).
 - Coverage: **>90%** on `app/` — the phase's `app/` code (helpers + router + schema + model) is fully exercised by the unit/integration cases.
 ## Completion Criteria
 - [ ] All test artifacts exist and pass; the isolated E2E file passes standalone.
 - [ ] The raw-JSON "token nowhere" assertion covers list AND single AND sync-status surfaces.
 - [ ] `uv run pytest --cov=app` TOTAL >90%; lint + types clean.
@@ -0,0 +1,54 @@
 # Phase 122 — Image documents: standalone images become first-class, retrievable documents
 **Source:** `TODO.md` L6 — "Need to support images. Images uploaded as part of documents or as standalone images should be read, summarized, and retrieved like any other document. Note that the embedding model won't support images, so the only embedded part of an image will be the summary generated by the model. The user should be able to turn on and off image support in their .env depending on whether their model supports it. Images retrieved by the RAG should be shown in the chat nicely and users should be able to submit images as part of their question in brain of reese."
 **Story:** n/a (feature request; extends the phase-28/30/38 import pipeline, phase-90 no-scan uploads, and the RAG/chat assets).
 **Context:** `app/config.py` — `Settings` (`BOR_` prefix; `upload_dir` L361, `sources_dir` L355, `upload_max_mb` L370 — raw-string/`expanduser` house convention). `app/rag/importer.py` — `iter_importable_files` (L235, extension filter via `llm.settings.import_extension_set` + `match_extension` L217), `import_sources` (L279, `prune` L283), `_index_file` (L435 — `read_text` L453, sha256 over text, Document upsert, the unchanged/hash path with the phase-118 summary backfill), `_store_summary` (L582 — lite-model summary + the position −1 `is_summary` chunk), `_prune` (L649 — deletes docs of the imported sources not in `seen`). `app/models.py` — `Document` (L102: `content`, `content_hash`, `summary` L140, `created_at`/`created_at_manual`), `Chunk` (L148: `is_summary` L161). `app/rag/summarizer.py` + `app/rag/llm.py` — the lite summary path + the chat-model client (`Settings` model names, `check_models`). `app/rag/archive_upload.py` — archive unpack into `upload_dir` (image members land on disk today, then get filtered out by the extension walk). `app/api/git_sources.py:432` — the upload endpoint. `app/api/docs.py` — the document content endpoint (document viewer). `app/rag/retriever.py` / `app/rag/agent.py` (read tool, message build L1446–1448) / `app/api/chat.py` — RAG + the SSE sources frames. `app/api/config.py:30` — `GET /api/config` public flags dict (task 01 of phase 123 extends it). Frontend: `frontend/assets/app.js` (chat source chips), `frontend/assets/document.js` + `frontend/document.html` (`#doc-content` L144), `frontend/assets/sources.js` (Sources page). `alembic/` — migrations.
 ## Objective
 With `BOR_IMAGES=true`, a standalone image file — arriving as a direct upload, inside an uploaded archive, or as a file in a git/local source — becomes a first-class document: the vision model (the chat model) describes it, the description is the document's content AND summary, only the description is embedded (the embedding model never sees pixels), the image bytes persist and are served, and the image shows up in the Sources page, the document viewer, and the chat — with retrieved image docs rendered inline in the answer's sources.
 ## Dependencies
 - `121_git_source_tokens` (todo) — pipeline predecessor (execution order) only; no code dependency.
 - Code dependencies (all complete): phase 30 summary pipeline (`_store_summary`, `is_summary` chunk), phase 90 no-scan upload, phase 89/105 per-source walk options, the RAG agent + SSE sources frames.
 ## Design (shared by all tasks — the executor reads this, not the chat)
 - **Toggle (task 01, LOCKED A3):** three new `Settings` fields — `images: bool = False` (`BOR_IMAGES`, `0`/`false` off — the phase-67 `llm_retries` bool style), `image_extensions: str = "png,jpg,jpeg,webp,gif,bmp"` (`BOR_IMAGE_EXTENSIONS`, comma-separated, lowercased into a frozenset by the importer — the `import_extension_set` property precedent), and `image_dir: str = "~/bor-sources/images"` (`BOR_IMAGE_DIR`, raw-string/`expanduser` convention — the persistent home for image bytes, deliberately separate from `sources_dir`/`upload_dir`). `.env.example` gets all three with a comment: **off by default — enable only when your chat model supports vision, because image descriptions are generated by the chat model.** `GET /api/config` (task 01) gains `images: bool` so the UI can gate affordances (consumed by phase 123; the Sources page can show an "images off" hint — optional, not required).
 - **Why the bytes are copied (task 02):** upload dirs are REPLACED on every upload (`archive_upload.swap_in`), git checkouts are re-cloned, and local dirs are user-edited — a served image must outlive its source file. The importer copies each ingested image to `image_dir/<doc-uuid>.<ext>` (created on demand) and stores that path in `Document.image_path`. The copy happens ONLY when the doc is new or its hash changes; a replaced image deletes the stale copy; pruned docs delete their copy.
 - **Storage (task 02):** `Document.is_image: bool` (server default `false` — every pre-phase-122 row is a text doc) + `Document.image_path: str | None` (NULL for text docs). One migration, one downgrade.
 - **Ingest (task 02):** the walk: `iter_importable_files`/`import_sources` accept the image frozenset IN ADDITION to `import_extension_set`, ONLY when `settings.images` is true (images are never user-configurable via `BOR_IMPORT_EXTENSIONS` — the toggle is the single knob, LOCKED A3/A4). `_index_file` branches on image extension: read BYTES (not `read_text`), sha256 over the bytes (the digest rule is unchanged — content identity), copy to `image_dir`, set `is_image` + `image_path`, and `content` = the vision description (task 03). The normal chunk pipeline then embeds the content (= the description) — that is exactly the TODO's "the only embedded part of an image will be the summary generated by the model"; the phase-30 summary chunk (`is_summary`, position −1) mirrors `Document.summary`, which equals the description too. Title = the file stem (the non-markdown rule at L505–509). The unchanged/hash path works unmodified (byte digest → "unchanged" skips re-describing; the phase-118 backfill path re-describes a NULL-summary image doc on its next sync — same fail-soft). **Prune guard:** `_prune` (L649) must NOT delete `is_image` docs while `settings.images` is false (an image doc is invisible to an images-off walk, not a deleted file — otherwise turning the toggle off and syncing would silently destroy the image documents). Toggle ON → normal prune semantics (a deleted image file prunes its doc + copy).
 - **Description (task 03, LOCKED A3):** `describe_image` in `app/rag/summarizer.py` (one function, the summarizer module owns model-text generation): a SINGLE chat-model call (`Settings.llm_chat_model` — the vision model; the lite summary model is NOT assumed vision-capable, LOCKED A3) with a multimodal user message `[{type: "text", text: <fixed describe prompt>}, {type: "image_url", image_url: {url: <data URL from the bytes + mime>}}]`; the prompt asks for a faithful, retrieval-oriented description (what is shown, any text/labels/diagram content, salient details — the description is the ONLY thing retrievable, so it must carry the image's meaning). Output capped at `settings.summary_max_chars` (the description IS the doc's summary; the phase-30 cap keeps it uniform). Stored: `Document.summary = Document.content = description`. **Fail-soft:** a failed/empty description → the doc is SKIPPED (no row, `ImportSummary` counts it in a new `images_failed` counter + a `logger.warning` with source/path) — an undescribed image is unsearchable noise; the sync continues (the importer's existing fail-soft convention).
 - **Serve + display (task 04):** `GET /api/documents/{doc_id}/image` (new route in `app/api/docs.py`) — 404 for missing docs and non-image docs; serves `image_path` bytes with the correct `Content-Type` (ext → mime map: png/jpeg/webp/gif/bmp) — PUBLIC like the document content itself (this app's document content is already anonymous-readable; the image is part of that content). The document content endpoint (the one `frontend/assets/document.js` boots against) gains `is_image: bool` + `image_url` (the new route's path, absent for text docs) so `document.html` renders `<img src>` (max-width 100%, the theme's image treatment) with the summary/description text below it instead of the markdown content; the Sources page row for an image doc shows a small thumbnail (lazy-loaded, `loading="lazy"`, aspect-ratio box) or the existing doc icon when the fetch is not yet possible offline — the thumbnail is a progressive enhancement (a fetch failure falls back to the icon).
 - **RAG display (task 05):** the SSE sources frames (and any sources-list shape the chat bubble renders from) carry an OPTIONAL `image_url` on image docs (the retriever/agent know the `Document` row — add the field where `SourceRef`-shaped frames are built in `app/api/chat.py`/`app/rag/retriever.py`); the chat's sources block renders a compact inline `<img>` (capped height, the summary as caption/alt) for image docs — "shown in the chat nicely" (TODO L6). The agent's `read` tool on an image doc returns its description prefixed with a one-line marker (e.g. `Image document — description generated from the image:`) so the model knows what it is reading. `alt` text = the summary everywhere (WCAG).
 - **NOT touched (this phase):** chat-side image submission (phase 123), the lite summary path for TEXT docs, archive unpacking (image members already land on disk — only the walk filter changes), and git/local sync scheduling.
 - **Locked assumptions:** **A3** — descriptions use the CHAT model (`BOR_LLM_CHAT_MODEL`, must be vision-capable); `BOR_IMAGES` defaults to **false**; generation failure → doc skipped + logged. **A4** — "images uploaded as part of documents" = standalone image files arriving via direct upload / uploaded archives / source walks — NOT embedded-image extraction from PDFs/DOCX.
 ## Tasks
 1. `01_image_toggle.md` — `BOR_IMAGES` / `BOR_IMAGE_EXTENSIONS` / `BOR_IMAGE_DIR` settings + `.env.example` + `GET /api/config` flag; off = byte-identical behavior.
 2. `02_image_ingest.md` — `Document.is_image`/`image_path` + migration; walk accepts image extensions when on; `_index_file` binary branch + persistent copy; prune guard when off.
 3. `03_image_description.md` — `describe_image` (chat-model vision), content = summary = description, fail-soft skip + counter.
 4. `04_serve_and_display.md` — `GET /api/documents/{id}/image`; document viewer + Sources page rendering.
 5. `05_rag_display.md` — `image_url` on chat source frames + inline image in the chat sources block + the agent `read` marker.
 6. `06_image_tests.md` — unit + integration + isolated E2E `test_image_documents.py`.
 ## Testing & Quality
 - Unit: `tests/unit/test_image_documents.py` (new, task 06) — settings parsing (toggle off by default, extensions frozenset, mime map), the `_index_file` image branch (bytes digest, copy to `image_dir`, `is_image`/`image_path` set, text `content` never read for an image), the prune guard (toggle off → image docs survive; toggle on → deleted image prunes), `describe_image` prompt shape (multimodal content list, chat model, cap) with a mock client, and the fail-soft skip path.
 - Integration: `tests/integration/test_docs_api.py` (extend) — the image route (200 + correct Content-Type for a seeded image doc; 404 for text docs and missing ids); the content endpoint exposes `is_image`/`image_url` for image docs and omits them for text docs (byte-identical text-doc responses); `import_sources` end-to-end with `images=True` and a mock vision client (a fixture PNG → doc row with description content + `is_summary` chunk embedding; `images=False` → the file is ignored, pre-existing image doc survives prune).
 - E2E: `tests/e2e/test_image_documents.py` (new, task 06) — isolated run per AGENTS.md §4, `BOR_IMAGES=true` for this suite's app instance: upload a small fixture PNG (via the existing upload endpoint's UI or `page.request`) → sync → the Sources page lists it (thumbnail or icon) → open the document viewer → the image renders with its description → ask a question the mock LLM grounds on the image doc → the chat's sources block shows the inline image.
 - Coverage: **>90%** on `app/` (validate.sh gate).
 ## Completion Criteria
 - [ ] With `BOR_IMAGES=true`: an uploaded standalone image (direct or in an archive) and an image file in a git/local source become documents whose content/summary is the vision description and whose ONLY embedded text is that description.
 - [ ] With `BOR_IMAGES=false` (the default): every request, walk, and response is byte-identical to pre-phase; existing image docs (if any) survive a sync.
 - [ ] The image renders in the document viewer and in the chat's sources block (inline, with alt text); a failed description skips the doc and logs — the sync completes.
 - [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
 - [ ] One `--no-gpg-sign` commit; phase dir moved to `.agents/phases/complete/` by the pipeline gate.
 ## Locked decisions
 - **A3 — image descriptions are generated by the CHAT model (`BOR_LLM_CHAT_MODEL`, vision-capable); `BOR_IMAGES` defaults to false; a failed/empty description skips the doc and logs (owner-confirmed 2026-09-24, roadmap confirmation).**
 - **A4 — "images uploaded as part of documents" = standalone image files via direct upload / uploaded archives / source walks — no embedded-image extraction from PDFs/DOCX (owner-confirmed 2026-09-24).**
 - **Prune guard (derived from A3/A4, same confirmation):** images-off syncs never prune `is_image` docs — turning the toggle off must not destroy image documents.
 ## Commit
 ```bash
 git add app/ alembic/ frontend/ tests/ .env.example .agents/phases/ && git commit --no-gpg-sign -m "feat(rag): index standalone images as documents — described, embedded, and displayed via the vision model"
 ```
@@ -0,0 +1,25 @@
 # Task 01 — Image toggle: BOR_IMAGES + extensions + dir, off by default
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "The user should be able to turn on and off image support in their .env depending on whether their model supports it."
 ## Objective
 The single env knob for image support exists and is surfaced — `BOR_IMAGES` (default **false**), `BOR_IMAGE_EXTENSIONS`, `BOR_IMAGE_DIR` — with `GET /api/config` exposing the flag for UI gating. Toggle off = byte-identical behavior to pre-phase.
 ## Work
 1. `app/config.py` — three new `Settings` fields (house docstring style, the `upload_dir`/`llm_retries` precedents):
   - `images: bool = False` — `BOR_IMAGES`, `0`/`false` off (LOCKED A3 default). Docstring: master switch for image-document indexing (phase 122) — off by default, enable only when the chat model supports vision (descriptions come from it).
   - `image_extensions: str = "png,jpg,jpeg,webp,gif,bmp"` — `BOR_IMAGE_EXTENSIONS`, comma-separated, case-insensitive; a property/parse into a lowercased-dotted frozenset (the `import_extension_set` precedent) — the image set is SEPARATE from `import_extension_set` (images are never user-added via `BOR_IMPORT_EXTENSIONS`).
   - `image_dir: str = "~/bor-sources/images"` — `BOR_IMAGE_DIR`, raw string, `Path.expanduser()` applied by the importer (the `sources_dir`/`upload_dir` convention) — the persistent home for image bytes (uploads are replaced, checkouts re-cloned — the copy must outlive the source file).
 2. `.env.example` — the three entries with the comment block: off by default + the vision-model dependency note (LOCKED A3).
 3. `app/api/config.py:30` — the `app_config` dict gains `"images": settings.images` (the dict is `str | bool`-valued — bools already allowed). Extend the docstring: consumed by the chat composer (phase 123) to show/hide the attach control, optionally by the Sources page.
 4. ASSUMPTION: `GET /api/config` is already anonymous-readable (the UI gates on it pre-login in phase 123 — no auth change here).
 ## Testing & Quality
 - Unit: `tests/unit/test_image_documents.py` (task 06 finalizes) — defaults (`images` False, extensions frozenset `{".png", …}` with the dotted form the matchers expect, dir default), env overrides, the frozenset parse is case-insensitive and trims spaces.
 - Integration: the existing `GET /api/config` test asserts the new `images` key (default false in the test env).
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] `Settings()` with no env: `images is False`, the extension set is the six defaults, `image_dir` is the default path.
 - [ ] `GET /api/config` returns `images: false` in the default test env (byte-check the other keys unchanged).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,30 @@
 # Task 02 — Image ingest: model fields, walk filter, binary index path, prune guard
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "Images uploaded as part of documents or as standalone images should be read, summarized, and retrieved like any other document."
 ## Objective
 When `BOR_IMAGES=true`, standalone image files in ANY ingest path (direct upload, uploaded archive, git/local source walk) become `Document` rows — bytes persisted to `image_dir`, `is_image`/`image_path` set, `content` = the vision description (task 03) — and an images-off sync never prunes existing image docs.
 ## Work
 1. `app/models.py` — `Document` (L102): add, with house docstrings (the `summary` L140 / `created_at_manual` precedent):
   - `is_image: Mapped[bool] = mapped_column(Boolean, default=False, server_default=text("false"), nullable=False)` — True iff the doc's content is a vision description of an image (phase 122); the image bytes live at `image_path`.
   - `image_path: Mapped[str | None] = mapped_column(Text, default=None)` — absolute path of the persistent copy in `settings.image_dir`; NULL for text docs.
 2. `alembic/versions/` — new revision: both columns (`is_image` NOT NULL server_default 'false'; `image_path` nullable) + downgrade.
 3. `app/rag/importer.py`:
   - `iter_importable_files` (L235) / the walk in `import_sources` (L279): when `llm.settings.images`, accept a file iff its extension matches `import_extension_set` OR the image frozenset (task 01) — pass the image set in (the function takes explicit extension sets; the image set is NOT merged into `import_extension_set`).
   - `_index_file` (L435): image branch FIRST (before the `read_text` at L453) — if the path's extension is in the image set: `data = full_path.read_bytes()`, `digest = sha256(data)`, and on new/changed: copy `data` to `image_dir/<doc-id or uuid4>.<ext>` (dir created with `mkdir(parents=True, exist_ok=True)`), set `is_image=True` + `image_path` on the `Document` row, `content` = the description (task 03's `describe_image` — this task wires the call; the function lands in task 03, so for THIS task store `content = ""` placeholder ONLY if task 03 is not yet merged — the phases run task-ordered, so in practice task 03's function exists; wire it directly and let task 03 implement it. If implementing strictly per task: this task stores `content` via a `_describe_or_skip` hook that task 03 fills — keep the seam single and commented).
     - A CHANGED image (hash differs) deletes the stale `image_path` copy before replacing it.
     - The unchanged/hash path (L470+) works unmodified for images (byte digest); the phase-118 summary-backfill branch (L480) re-describes an image doc whose `summary` is NULL on the next sync (same fail-soft).
   - `_prune` (L649): the prune guard (LOCKED derived decision) — when `settings.images` is FALSE, skip every `is_image` doc (invisible to the walk ≠ deleted); toggle TRUE → normal prune + delete the `image_path` copy of each pruned image doc (also on the normal prune path when the file is gone).
   - `ImportSummary` (L100): new `images_failed: int = 0` counter + its slot in `format_counts`/`log` (L135–151) — task 03 increments it; add it now so the log shape is stable.
 4. ASSUMPTION (A4 re-stated): only standalone image FILES are ingested — no archive-of-documents extraction, no PDF/DOCX embedded-image pulls (the archive unpacker already places image members on disk; the walk now just accepts them).
 ## Testing & Quality
 - Unit: `tests/unit/test_image_documents.py` (task 06) — the walk accepts `.png` only when `images=True` (off → ignored, the byte-identical default), the binary branch (digest over bytes, copy made, fields set, `read_text` never called for an image), the changed-image stale-copy delete, the prune guard (off → image doc survives; on + file gone → pruned + copy deleted), `images_failed` in the log line.
 - Integration: `tests/integration/test_docs_api.py` (task 06) — the `import_sources` end-to-end cases.
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] `alembic upgrade head` applies; a seeded image walk with `images=True` creates the doc row + `image_dir` copy; `images=False` ignores the file entirely.
 - [ ] A sync with `images=False` leaves a pre-existing image doc untouched (prune guard).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,28 @@
 # Task 03 — Image description: the vision model writes the only embedded text
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "the only embedded part of an image will be the summary generated by the model."
 ## Objective
 `describe_image` generates the image's description with the CHAT model (vision), the description becomes BOTH `Document.content` and `Document.summary` (so the chunk pipeline embeds exactly that text — and only that text), and a failed description fails soft (skip + count + log, sync continues).
 ## Work
 1. `app/rag/summarizer.py` — new `async def describe_image(llm, data: bytes, mime: str, settings=None) -> str | None` (the summarizer module owns model-text generation; follow the existing summary-call conventions — client, model, timeout, the `summary_max_chars` cap):
   - ONE chat-model call (`settings.llm_chat_model` — LOCKED A3; the lite summary model is not assumed vision-capable) with messages `[{role: "user", content: [{type: "text", text: <DESCRIBE_PROMPT>}, {type: "image_url", image_url: {url: f"data:{mime};base64,{b64}"}}]}]` — the multimodal content-list shape the OpenAI-compatible API expects.
   - `DESCRIBE_PROMPT` (a module constant, pinned by a unit test): a faithful, retrieval-oriented description — what is depicted, any visible text/labels/titles, diagram/table structure, salient details; 2–4 sentences of substance (the description is the ONLY retrievable text of the doc, so it must carry the image's meaning).
   - Return the stripped text capped at `settings.summary_max_chars` (the phase-30 cap — the description IS the summary); return `None` on any client error, empty response, or non-2xx (the caller fails soft). No retries beyond the SDK's own — a description failure must not stall a sync.
 2. `app/rag/importer.py` — wire the task-02 seam: the image branch's `content`/`summary` come from `describe_image` —
   - description `None` → **skip the doc entirely** (no row, no `image_dir` copy kept — delete the copy if it was made, or make the copy AFTER a successful description so a failure never leaves an orphan), `summary.images_failed += 1`, `logger.warning("import: image description failed source=%s path=%s", source, rel)` — the fail-soft skip (LOCKED A3).
   - success → `content = description`, then the existing `_store_summary` path (L582) runs with the description as the summary (the `is_summary` position −1 chunk mirrors it — phase-30 behavior, unchanged), and the normal content chunks embed the description (for a short description that is typically ONE content chunk + the summary chunk — the chunker's existing behavior, no special case).
   - the phase-118 backfill branch (unchanged image doc, `summary is None`) calls the SAME path — a description failure there keeps the doc as-is and logs (no row mutation).
 3. `app/rag/llm.py` — no new client: `describe_image` reuses the existing `llm.chat`-equivalent client the summarizer already uses for text summaries (verify the exact client method name in `app/rag/summarizer.py` and match it — the multimodal payload is a plain `list[dict]` message, so no client change is needed; IF the existing client hard-codes text-only `content: str` typing, extend its signature to accept `content: str | list` — pyright-clean).
 4. ASSUMPTION (A3 re-stated): the CHAT model describes; if the owner's chat model lacks vision, `describe_image` returns `None` (the SDK errors) and every image doc is skipped + logged — honest, visible failure (the `images_failed` counter in the sync log is the signal).
 ## Testing & Quality
 - Unit: `tests/unit/test_image_documents.py` (task 06) — with a MOCK client: the prompt shape (text part + `image_url` data-URL part, correct model), the cap is applied, whitespace stripped; `None` on mock error / empty string / client exception; the importer's skip path (no row, `images_failed == 1`, warning logged, no orphan copy) and the success path (content == summary == description, `is_summary` chunk present, embedding called with the description text — the ONLY text embedded).
 - Integration: the mock-vision `import_sources` end-to-end (task 06).
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] A fixture PNG through the mock vision client yields a doc whose `content` == `summary` == the description, with its embedding(s) derived from that text only.
 - [ ] A failing mock client skips the doc, bumps `images_failed`, logs, and the sync completes with the other docs indexed.
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,31 @@
 # Task 04 — Serve the image + render it in the document viewer and Sources page
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "Images … should be read, summarized, and retrieved like any other document."
 ## Objective
 Image bytes are served through a dedicated document route, the document viewer renders the image with its description, and the Sources page shows an image affordance — image docs read like first-class documents in every existing surface.
 ## Work
 1. `app/api/docs.py` — new route `GET /api/documents/{doc_id}/image`:
   - 404 (the router's existing "unknown document" shape) for a missing doc and for a doc with `is_image` false / `image_path` NULL;
   - 404 if the file is missing on disk (defensive — the row exists but the copy was lost);
   - otherwise `FileResponse` (or a `Response` with the bytes) with `Content-Type` from an ext→mime map (`png`→`image/png`, `jpg`/`jpeg`→`image/jpeg`, `webp`→`image/webp`, `gif`→`image/gif`, `bmp`→`image/bmp` — the map lives in `app/rag/importer.py` or a small shared spot the unit tests can import; default `application/octet-stream` for an unexpected ext) and `Cache-Control: private, max-age=3600` (the image bytes are content-hashed — long enough, bustable by re-upload).
   - PUBLIC, like the document content endpoint (this app serves document content to anonymous visitors — the image is part of that content).
   - The document CONTENT endpoint the viewer boots against (same module): response gains `is_image: bool` (always present) + `image_url` (the `/api/documents/{id}/image` path — ABSENT for text docs, the `_drop_absent_share_url` omission precedent; never `null`). Text-doc responses gain only `is_image: false` — one new key, documented in the response schema's docstring.
 2. `frontend/assets/document.js` + `frontend/document.html`:
   - boot reads `is_image`; when true, `#doc-content` renders `<img src="{image_url}" alt="{summary}">` (block, `max-width: 100%`, the theme's surface treatment) with the description/summary text in the normal content slot below it (the document's readable content IS the description — no markdown render of a non-markdown string is needed; render it as the existing plain-content path).
   - an `<img>` error fallback: on `onerror` the image area shows a small "image unavailable" note (the 404-on-missing-file case) — the page still shows the description.
 3. `frontend/assets/sources.js` — the Sources page row for an image doc: a small thumbnail (48px box, `object-fit: cover`, `loading="lazy"`, `alt = summary`) where the doc icon sits; the thumbnail is a PROGRESSIVE enhancement — a failed fetch (or the row rendered before the fetch resolves) falls back to the existing icon (no layout shift beyond the fixed box). The doc title/path columns are unchanged.
 4. `frontend/assets/styles.css` — the viewer image block + the Sources thumbnail box (theme tokens; WCAG: alt text everywhere, no contrast concerns for decorative images).
 5. ASSUMPTION: the thumbnail uses the SAME full-size route (no separate thumb route) — a KB-scale image set makes a thumb pipeline unjustified; lazy loading keeps the Sources page fast.
 ## Testing & Quality
 - Integration: `tests/integration/test_docs_api.py` (task 06) — the image route (200 + exact `Content-Type` per ext for a seeded doc; 404 for a text doc; 404 for a missing id; 404 for a row whose file is deleted); the content endpoint: `is_image` present in ALL responses, `image_url` absent for text docs and present for image docs.
 - Unit: `tests/unit/test_image_documents.py` (task 06) — the ext→mime map (all six + the octet-stream default); house-style source assertions: the viewer renders the `img` from `image_url` with `alt = summary`, the sources row falls back to the icon on image error, no `null` in the text-doc content response.
 - E2E: `test_image_documents.py` scenarios (task 06) cover viewer + Sources rendering.
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] `GET /api/documents/{id}/image` serves the exact uploaded bytes with the right Content-Type; text docs 404.
 - [ ] The document viewer shows the image + its description; the Sources page shows the thumbnail (or the icon fallback).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,24 @@
 # Task 05 — RAG display: image docs in the chat sources + the agent read marker
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "Images retrieved by the RAG should be shown in the chat nicely."
 ## Objective
 When a retrieved/agent-read document is an image, the chat shows it: the sources block renders a compact inline image with its summary as caption/alt, and the agent's `read` tool tells the model it is reading a generated image description.
 ## Work
 1. `app/rag/retriever.py` / `app/api/chat.py` — the sources frames the chat bubble renders (the SSE `sources`/related-doc frames and the agent-sourced doc list): add an OPTIONAL `image_url` field to the per-doc ref shape — populated (the `/api/documents/{id}/image` path) iff the doc row has `is_image`, absent otherwise (the omission rule — text-doc frames stay byte-identical). The retriever already has the `Document` row; the agent's doc refs (the read-tool results / source list) do too — set it at the frame-build sites (grep for the source-ref construction in both modules; one shared helper `source_ref_with_image(doc, …)` keeps the two sites in lockstep).
 2. `frontend/assets/app.js` — the chat's sources block renderer: when a source ref carries `image_url`, render a compact inline `<img>` (max-height ~96px, `object-fit: contain`, the theme's surface, `alt` + visible caption = the doc summary — the "shown nicely" requirement) in place of / beside the existing doc chip text (keep the title + the existing chip affordance — the image is additive, not a replacement). A failed image load collapses to the plain chip (never a broken-image icon).
 3. `app/rag/agent.py` — the `read` tool's result for an image doc: prefix the description with the marker line `Image document — the text below is a description generated from the image:` (a module constant) so the model reasons about what it is reading; non-image docs' results are byte-identical.
 4. ASSUMPTION: the chat QUESTION side (users submitting images) is phase 123 — this task only covers RETRIEVED images in the answer's sources.
 5. ASSUMPTION: the sources-frame `image_url` is the only new frame field — no doc-id leak beyond what the frame already carries (the path encodes the doc id, same as the content endpoint).
 ## Testing & Quality
 - Integration: `tests/integration/test_chat_api.py` (extend, task 06) — a mocked grounded answer that includes an image doc in its sources → the SSE frame carries `image_url` for that ref only; a text-only grounding has NO `image_url` key anywhere (byte check).
 - Unit: `tests/unit/test_image_documents.py` (task 06) — the frame-helper (present/absent), the agent marker (image vs non-image result), house-style source assertions: the sources renderer reads `image_url`, sets `alt`, and falls back on image error.
 - E2E: `test_image_documents.py` scenario (task 06) — ask a question the mock LLM grounds on the fixture image doc → the chat sources block shows the inline image with its caption.
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] A chat answer grounded on an image doc shows the inline image + caption in its sources block; text-doc answers render byte-identically to before.
 - [ ] The agent `read` result for an image doc carries the marker; the model sees the description, not raw bytes.
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,33 @@
 # Task 06 — Image tests: unit + integration + isolated E2E
 **Phase:** `122_image_documents` · **Source:** `TODO.md:6` — "Need to support images …"
 ## Objective
 Pin the whole image-document contract: the off-by-default byte-identity, the ingest/description/serve pipeline, the RAG display, and the end-to-end user path (upload → Sources → viewer → chat) as an isolated Playwright suite.
 ## Work
 1. `tests/unit/test_image_documents.py` (new) — consolidates the per-task unit cases (the tasks ship code; this task ships the full pin):
   - settings: defaults (`images` False, six-extension frozenset, dir default), env overrides, case-insensitive parse (task 01);
   - the walk: image accepted iff `images=True`; off → the file is ignored (the default byte-identity);
   - `_index_file` image branch: digest over BYTES, copy to `image_dir`, `is_image`/`image_path` set, changed-image stale-copy delete, prune guard (off → survives; on + gone → pruned + copy deleted), `images_failed` in the log line (task 02);
   - `describe_image`: mock-client prompt shape (multimodal parts, chat model), cap, `None` on error/empty, the importer skip path (no row, no orphan, counter, warning) and the success path (content == summary == description; embedding called with the description only) (task 03);
   - the ext→mime map (task 04);
   - the source-frame `image_url` helper (present/absent) + the agent `read` marker + house-style frontend assertions (viewer `img` + alt + fallback; sources thumbnail fallback; chat sources inline image + alt) (task 05).
 2. `tests/integration/test_docs_api.py` (extend, task 04's cases) — the image route (200 + Content-Type per ext; 404 text doc / missing id / missing file), the content endpoint's `is_image`/`image_url` omission rules; `tests/integration/test_chat_api.py` (extend, task 05's case) — the SSE `image_url` frame; `tests/integration/` (new file `test_image_import.py` or the existing import test file — follow whichever exists) — `import_sources` end-to-end: `images=True` + mock vision → the fixture PNG becomes a doc (description content, `is_summary` chunk, one content chunk); `images=False` → ignored + a pre-seeded image doc survives prune; a failing mock → `images_failed == 1`, no row, other docs indexed.
   - Fixtures: a tiny valid PNG (a few bytes, generated in-test or a committed fixture under `tests/` — check the existing fixture conventions), a mock vision client (the existing mock-LLM test patterns in `tests/`).
 3. `tests/e2e/test_image_documents.py` (new — isolated run per AGENTS.md §4: `uv run pytest tests/e2e/test_image_documents.py -v --no-cov`). The suite's app instance runs with `BOR_IMAGES=true` (env override in the E2E fixture — the `conftest.py` pattern for per-suite app env):
   - upload a fixture PNG (the Sources-page upload flow or `page.request` against the upload endpoint, then trigger the sync through the UI as the Sources page does);
   - the Sources page lists the image doc (thumbnail or icon fallback);
   - open the document viewer → the image renders + the description text below it;
   - ask a question the mock LLM grounds on the image doc (the existing mock-LLM grounding pattern) → the chat's sources block shows the inline image with its caption;
   - negative: with the DEFAULT env (`BOR_IMAGES` unset/false), the same upload produces NO image doc (the default-off contract).
 4. Run the full gate: `uv run pytest`, `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), the isolated E2E file, `uv run ruff check . && uv run pyright`.
 ## Testing & Quality
 - This task IS the phase's test suite (see Work).
 - Coverage: **>90%** on `app/` — the phase's `app/` surface (config, importer, summarizer, docs API, chat frames, agent marker) is fully exercised.
 ## Completion Criteria
 - [ ] All test artifacts exist and pass; the isolated E2E file passes standalone.
 - [ ] The default-off byte-identity is asserted (unit + integration + the E2E negative case).
 - [ ] `uv run pytest --cov=app` TOTAL >90%; lint + types clean.
@@ -0,0 +1,50 @@
 # Phase 123 — Chat image questions: attach an image to a question
 **Source:** `TODO.md` L6 — "…users should be able to submit images as part of their question in brain of reese."
 **Story:** n/a (feature request; completes the phase-122 image capability on the question side).
 **Context:** Phase 122 (todo, this pipeline) — `BOR_IMAGES` toggle + `GET /api/config` `images` flag (task 01), the ext→mime map, `image_dir` storage convention. `app/schemas.py:60` — `ChatRequest` (`message` min 1/max 4000, `history` ≤100 — `HistoryTurn` is text-only), `ChatMessage` (L742, `extra="forbid"`, phase-83 value bounds). `app/api/chat.py` — the turn pipeline: the user message is built at L645 (`{"role": "user", "content": request.message}`; a grounded turn runs `run_agent`, a deflected turn a direct `chat_stream` on the same `messages`), and `app/rag/agent.py:1370/1448` — `run_agent(..., user_message: str)` builds its own `[system, user]` (verify the data flow — if `run_agent` receives the already-built `messages`, the single edit site is chat.py). The phase-114 SSE error-frame-with-hint pattern (the "question too long" frame — `ChatErrorEvent.detail` + optional `hint`, consumed by the banner at app.js L2210). `frontend/index.html` — the composer (label L287, `#message-input` L292, `#send-btn` L325). `frontend/assets/app.js` — `handleSend` (L2306), `runTurn` (the turn driver + the user append/save-point-1 at send), `addMessage("user", …)` (user bubble), `rememberBrainTurn` (L2108, the brain save point), `renderStoredMessage` (L1642, user branch). `frontend/assets/shared.js` — the shared page's message render (text-only today). `app/api/config.py:30` — the public flags dict (phase 122 task 01 added `images`).
 ## Objective
 The user attaches one image to a question: a masked-by-server upload stores the bytes, the vision model (the chat model) receives a multimodal message, the user's bubble renders the image, the record persists the image path (not base64) so refresh and shared chats render it, and `BOR_IMAGES=false` rejects the request with a helpful hint.
 ## Dependencies
 - `122_image_documents` (todo) — CODE dependency: the `BOR_IMAGES`/`images` config flag (the toggle gates this feature), the ext→mime map, and the `image_dir` storage convention (this phase's `chat_image_dir` follows it).
 - Code dependencies (all complete): phase 14/50/55 conversation persistence, phase 74 history mapping, phase 114 SSE error-hint frames, phase 51 shared chats.
 ## Design (shared by all tasks — the executor reads this, not the chat)
 - **Storage (task 01, LOCKED A5):** user question-images are server-stored, NOT base64-in-saved-chats: `Settings.chat_image_dir: str = "~/bor-sources/chat-images"` (`BOR_CHAT_IMAGE_DIR`, the `image_dir` convention — a sibling of phase 122's `image_dir`, separate because question-images are per-conversation, not per-source) + `Settings.chat_image_max_mb: int = 10` (`BOR_CHAT_IMAGE_MAX_MB`, the ~10 MB cap of A5; `upload_max_mb`'s fail-loud validator precedent for `<= 0`). `POST /api/chat-images` (multipart, in `app/api/chat.py` or a small new `app/api/chat_images.py` router — the executor's call, following the repo's one-concern-per-module style): accepts an image file, validates the mime/ext against the SAME six-extension set as phase 122 (reuse the frozenset; the Content-Type header is a hint — the EXTENSION is the source of truth, the archive-uploader precedent), rejects oversize with a 413 (the fixed-detail style), stores `chat_image_dir/<uuid4().hex>.<ext>`, returns `{ "path": "/api/chat-images/<uuid-hex>.<ext>" }`. `GET /api/chat-images/{filename}` serves the bytes (404 on missing/unknown — the filename is a uuid, no enumeration value) with the phase-122 mime map; PUBLIC like saved-chat content (a saved chat's id is already its credential — phase 55 A1 — the image is part of that content).
 - **Request (task 01):** `ChatRequest.image: str | None = Field(default=None, max_length=500)` — a STORED PATH, pattern-validated (`^/api/chat-images/[0-9a-fA-F]{32}\.(png|jpe?g|webp|gif|bmp)$` — the stored filename is `uuid4().hex.<ext>`) — never a raw data URL (the upload endpoint already did the size/mime enforcement; re-validating a 10 MB base64 string in the schema would be the anti-pattern). Toggle OFF (`settings.images` false) with `image` set → the turn settles with the phase-114 SSE error frame: `detail` "Image support is turned off on this server." + `hint` "Enable BOR_IMAGES in the server's .env (and restart) to ask with an image." (the question itself is NOT persisted — a rejected turn saves nothing, the existing error-path convention). `image` set but file missing → the same frame shape with a "that image is no longer available" detail (a stale-path edge: the stored file was deleted out-of-band).
 - **Multimodal (task 01):** the user message becomes `{"role": "user", "content": [{"type": "text", "text": request.message}, {"type": "image_url", "image_url": {"url": <data URL from the stored file>}}]}` at BOTH construction sites (chat.py:645 and agent.py:1448 if it builds independently — verify the flow; when `request.image` is None the content stays the plain string, byte-identical to today). The data URL is built server-side from the stored bytes + mime map (the phase-122 `describe_image` data-URL construction — reuse it). `HistoryTurn`/`history_to_messages` are UNCHANGED (LOCKED A7): prior turns' images are never replayed into the model's history — the history budget is text, and a 10 MB image per past turn would blow every budget; the model simply sees the text of a prior turn that had an image.
 - **Persistence (tasks 01+02):** `ChatMessage.image: str | None = Field(default=None, max_length=500)` — the stored path, on the USER record (the image belongs to the question). The user record is saved at save-point-1 (send), BEFORE the turn resolves — so the client uploads FIRST (`POST /api/chat-images`) and stores the returned path in the user record, then POSTs `/api/chat` with `image=<path>`. Saved chats, shared chats, and the localStorage shape all carry the path (≤500 chars — no phase-83 cap pressure). A brain record never carries `image` (the answer may reference the image's sources, but the attachment is the user's).
 - **Composer (task 02):** the attach control appears ONLY when `GET /api/config` says `images: true` (phase 122's flag; fetched once at boot like the other config — the composer reads the existing cached config if present). A paperclip button (SVG, the icon style of the other composer glyphs, `aria-label="Attach an image"`) before the input → hidden `<input type="file" accept="image/png,image/jpeg,image/webp,image/gif,image/bmp">` → on select: a preview strip above the input (thumbnail ≤48px, the filename, a remove ✕) + the file's data URL kept client-side until send; on send with an attachment: `POST /api/chat-images` (the file) → the returned path goes into the user record + the `/api/chat` body → the preview clears. Upload failure (oversize, non-image, server down) → the phase-114-style out-of-turn banner ("Couldn't attach the image — …") and the send is BLOCKED (no question without the image the user attached — ASSUMPTION A8, locked below). The user bubble renders the image (from the data URL live, from the stored path after restore) with `alt = filename`, capped height, above/beside the text (the theme's bubble treatment; the image is part of the question, visible in both the live bubble and the restore).
 - **Restore + shared (task 03):** `renderStoredMessage`'s user branch: `m.image` present → the user bubble includes `<img src="{m.image}" alt="…">` (a load failure collapses to a small "image unavailable" line — never a broken icon). The shared page (`shared.js`) renders the user image the same way (the image route is public — the shared view is faithful; no new shared-shape field beyond `ChatMessage.image`, which the public `messages` shape already carries).
 - **NOT touched:** the history budget/trimming, the honesty gate, the suggestion chips, phase-122's document-image pipeline (a QUESTION image is a separate concern — it is NOT indexed as a document), and the stop/failed-turn paths (they persist whatever records exist, including the new `image` key, unmodified).
 ## Tasks
 1. `01_vision_request.md` — `POST/GET /api/chat-images`, `ChatRequest.image` + `ChatMessage.image`, the toggle-off/stale error frames, the multimodal user message at both construction sites.
 2. `02_composer_attach.md` — the config-gated attach control, preview, upload-then-send, the user bubble's image.
 3. `03_restore_and_shared.md` — `ChatMessage.image` on restore (chat page) and on the shared page.
 4. `04_chat_image_tests.md` — unit + integration + isolated E2E `test_chat_image_questions.py`.
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_image_questions.py` (new, task 04) — the path pattern validator (accepts well-formed, rejects data URLs / wrong ext / traversal), the multimodal message build (both sites; `image=None` → byte-identical plain string), the toggle-off + stale-file error frames (detail + hint shapes), the upload endpoint's mime/size/ext rules (tmp-dir settings), the serve route (200/404), `ChatMessage.image` bounds + omission.
 - Integration: `tests/integration/test_chat_api.py` (extend, task 04) — upload → `POST /api/chat` with `image=<path>` → the mock client RECEIVES the multimodal content list (text part + image_url data URL); `image` with `images=false` → the SSE error frame with the hint and NO model call, no persisted record; `image=None` requests are byte-identical to pre-phase; a saved chat round-trips a user record with `image`; a shared chat serves it.
 - E2E: `tests/e2e/test_chat_image_questions.py` (new, task 04) — isolated run per AGENTS.md §4, `BOR_IMAGES=true`: attach a fixture PNG in the composer → preview + remove works → send → the user bubble shows the image → the (mock) answer streams → reload → the user bubble restores WITH its image → open the shared link → the shared page shows the image. Plus the default-off negative: with `BOR_IMAGES` unset, the attach control is ABSENT from the DOM.
 - Coverage: **>90%** on `app/` (validate.sh gate).
 ## Completion Criteria
 - [ ] With `BOR_IMAGES=true`: attach → send → the vision model gets text+image; the user bubble, the refreshed page, and the shared chat all show the image; the saved chat stores the PATH (assert no base64 in the stored payload).
 - [ ] With `BOR_IMAGES=false`: the attach control is absent, an API request with `image` gets the hinted error frame, and no model call / record happens.
 - [ ] Text-only questions behave byte-identically to pre-phase (the multimodal branch is inert).
 - [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
 - [ ] One `--no-gpg-sign` commit; phase dir moved to `.agents/phases/complete/` by the pipeline gate.
 ## Locked decisions
 - **A5 — one image per question; the ~10 MB cap (`BOR_CHAT_IMAGE_MAX_MB`); server-stored bytes under `chat_image_dir`; the saved/shared record carries the path, never base64 (owner-confirmed 2026-09-24, roadmap confirmation).**
 - **A7 — a question's image applies to the CURRENT turn only; prior turns' images are never replayed into the model's history (the text of a prior turn stands alone) (owner-confirmed: same confirmation — the proposed design).**
 - **A8 — if the image upload fails, the send is blocked with a banner (the question is never sent without the image the user attached) (owner-confirmed: same confirmation).**
 ## Commit
 ```bash
 git add app/ frontend/ tests/ .env.example .agents/phases/ && git commit --no-gpg-sign -m "feat(chat): attach an image to a question — vision input, in-bubble render, persisted and shared"
 ```
@@ -0,0 +1,31 @@
 # Task 01 — Vision request: upload/serve endpoints, request + message schemas, multimodal build
 **Phase:** `123_chat_image_questions` · **Source:** `TODO.md:6` — "…users should be able to submit images as part of their question in brain of reese."
 ## Objective
 The server side of the image question: a uuid-named upload/serve pair for question images, `ChatRequest.image` (stored path) + `ChatMessage.image` (persistence), the toggle-off/stale error frames, and the multimodal user message at both construction sites — with text-only requests byte-identical to pre-phase.
 ## Work
 1. `app/config.py` — `chat_image_dir: str = "~/bor-sources/chat-images"` (`BOR_CHAT_IMAGE_DIR`, the phase-122 `image_dir` convention) + `chat_image_max_mb: int = 10` (`BOR_CHAT_IMAGE_MAX_MB`, the A5 cap; the `upload_max_mb` fail-loud `<= 0` validator precedent). `.env.example` entries.
 2. New router (a small `app/api/chat_images.py`, registered in `app/main.py` next to the chat router — the one-concern-per-module house style):
   - `POST /api/chat-images` — `UploadFile` (the git-sources upload endpoint L432 pattern): extension must be in the phase-122 image frozenset (the EXTENSION is the source of truth — a Content-Type header is a hint); total bytes capped at `chat_image_max_mb` (stream-count the bytes — reject with 413 + a fixed detail that names the cap, never echoing the filename); store `chat_image_dir/<uuid4().hex>.<ext>` (dir created on demand); response `{"path": "/api/chat-images/<uuid>.<ext>"}`.
   - `GET /api/chat-images/{filename}` — filename must be `<uuid-hex>.<ext>` (the regex guard → 404 otherwise, no path traversal by construction); 404 on missing file; serve the bytes with the phase-122 ext→mime map + `Cache-Control: private, max-age=3600` (public, like saved-chat content — phase 55 A1).
 3. `app/schemas.py`:
   - `ChatRequest` (L60): `image: str | None = Field(default=None, max_length=500)` + a `field_validator` — when set, it must match `^/api/chat-images/[0-9a-fA-F]{32}\.(png|jpe?g|webp|gif|bmp)$` (the uuid4().hex shape — 32 hex chars; adjust if the uuid format differs) with a fixed 422 detail ("image must be an uploaded chat image path" — no echo). Docstring: the path from `POST /api/chat-images` (task 01) — never a data URL; the upload endpoint owns size/mime enforcement.
   - `ChatMessage` (L742, `extra="forbid"`): `image: str | None = Field(default=None, max_length=500)` — on the USER record only (the question's attachment); the docstring notes brain records never carry it and the saved/shared shape therefore gains one optional key (omitted when None — the phase-50 byte-identical contract for text-only chats holds).
 4. `app/api/chat.py` — the turn pipeline:
   - pre-stream validation (BEFORE any model call, at the top of the turn handler): `request.image` set → `settings.images` false → yield the phase-114 error frame (`ChatErrorEvent(detail="Image support is turned off on this server.", hint="Enable BOR_IMAGES in the server's .env (and restart) to ask with an image.")`) and return (NO model call, NO record — the existing error-path convention); file missing on disk → the same frame shape, `detail="That image is no longer available."` + a generic reachability-free hint (or no hint — the banner's default is fine).
   - the user message (L645): when `request.image` is set, `{"role": "user", "content": [{"type": "text", "text": request.message}, {"type": "image_url", "image_url": {"url": <data URL>}}]}` — the data URL built from the stored bytes + the phase-122 mime map (REUSE the data-URL construction from `describe_image` — factor it to a shared helper if it is buried in `app/rag/summarizer.py`); `request.image` None → the plain-string content, byte-identical.
   - `app/rag/agent.py` — verify the data flow: if `run_agent` (L1370) receives the already-built `messages` from chat.py, NO change here (the L1448 build is for a different entry); if it builds its own user message from `user_message`, extend `run_agent`'s signature (`user_message: str | list | None` — pyright-clean) and make chat.py pass the multimodal content. Pin the chosen flow in a code comment.
   - a QUESTION image is NEVER indexed as a document (no importer call) — it is turn-local storage.
 5. ASSUMPTION (A7 re-stated): `HistoryTurn`/`history_to_messages` unchanged — prior turns' images are not replayed (text-only history stands).
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_image_questions.py` (task 04 finalizes) — the path validator (well-formed ok; a data URL, a wrong ext, a traversal, and a 31-hex-char uuid all 422); the multimodal builder (both sites; None → plain string); the error frames' exact detail/hint strings; the upload endpoint's ext/size rules (tmp `chat_image_dir`); the serve route 200/404 + Content-Type; `ChatMessage.image` (bounds, omission, the `extra="forbid"` boundary intact).
 - Integration: `tests/integration/test_chat_api.py` (task 04) — the upload → chat flow asserts the MOCK client received the multimodal content list; the toggle-off frame + no model call; text-only byte-identity; saved + shared round-trips with `image`.
 - Coverage: **>90%** on the touched modules.
 ## Completion Criteria
 - [ ] `POST /api/chat-images` stores a uuid-named file and returns its path; `GET` serves it; oversize/non-image → 413/422 with fixed details.
 - [ ] `POST /api/chat` with `image` (toggle on) delivers a multimodal user message to the model; toggle off → the hinted error frame, no model call; `image=None` → byte-identical behavior.
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,38 @@
 # Task 02 — Composer: attach control, preview, upload-then-send, the user bubble's image
 **Phase:** `123_chat_image_questions` · **Source:** `TODO.md:6` — "…users should be able to submit images as part of their question in brain of reese."
 ## Objective
 The composer (when `GET /api/config` says `images: true`) takes one attached image — preview + remove before send, upload on send, the image in the user's bubble — and the user's conversation record carries the stored `image` path.
 ## Work
 1. `frontend/index.html` — the composer (the label L287 / `#message-input` L292 / `#send-btn` L325 region): before the input, the attach control
   ```html
   <button type="button" class="attach-btn" id="attach-btn" hidden aria-label="Attach an image">
     <svg aria-hidden="true" …paperclip glyph, the icon style of the other composer glyphs…></svg>
   </button>
   <input type="file" id="attach-file" accept="image/png,image/jpeg,image/webp,image/gif,image/bmp" hidden>
   ```
   plus the preview strip container (after the input row, `#attach-preview`, `hidden` by default — a thumbnail ≤48px + filename + a remove ✕ button `#attach-remove`). `#attach-btn` is `hidden` by default — JS reveals it only when the config flag is on (task 02 step 3); the hidden-by-default markup keeps the flag-off DOM byte-identical (A5's default-off contract).
 2. `frontend/assets/app.js`:
   - boot: read `images` from the `GET /api/config` fetch (the composer already consumes the cached whoami/config boot — extend that fetch's result use; ONE request, no extra round-trip) → `attachBtn.hidden = !images`.
   - attach flow: `#attach-btn` click → `attachFile.click()`; on change: validate the file's extension against the six (client-side pre-check, the server re-validates — a bad pick → the out-of-turn banner "Only PNG, JPEG, WebP, GIF, and BMP images can be attached." and no state change); keep `{ file, dataUrl (for the live preview) }` in a turn-local `attachedImage` var; show `#attach-preview` (thumbnail from the data URL, the filename, the remove ✕); the remove ✕ (or a new selection) clears the state + hides the strip.
   - send flow (`handleSend` L2306 / `runTurn`): when `attachedImage` is set:
     1. `POST /api/chat-images` (the File) — on failure (413/422/5xx) → the phase-114-style out-of-turn banner with the server's detail ("Couldn't attach the image — try again.") and the send is BLOCKED (LOCKED A8 — the question is never sent without its image; the input text stays).
     2. success → `runTurn(text, { image: <returned path> })`; `runTurn`'s user append (save point 1 — the user record) stores `{ who: "user", text, image: <path> }` (the `image` key joins the `bor.chat.v1` record — the phase-14 shape gains the optional key; `saveConversation()` + the phase-55 auto-save ride the existing path);
     3. the USER bubble renders the image: extend `addMessage("user", text)` with an optional `image` arg (data URL live, path after restore) → `<img src alt={filename}>` in the bubble (capped height ~240px, `max-width: 100%`, the theme's bubble treatment, `loading="lazy"`);
     4. clear `attachedImage` + the preview strip AFTER the user bubble is rendered (the strip must not linger into the turn).
   - text-only sends: `attachedImage` null → the request body omits `image`, the user record omits the key, the bubble is byte-identical to pre-phase.
 3. `frontend/assets/styles.css` — `.attach-btn` (the composer glyph button treatment — match the send-btn family, focus-visible ring per PLAN §7), `#attach-preview` (the strip: flex row, thumbnail box, filename ellipsis, the ✕), the user-bubble image block.
 4. ASSUMPTION (A8 re-stated): an upload failure blocks the send (no partial question-without-image) — the banner tells the user what failed; the typed question is preserved.
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_image_questions.py` (task 04) — house-style source assertions: `#attach-btn` is `hidden` by default + `aria-label`; the reveal is gated on the config `images` flag; the extension pre-check list matches the server's six; the send path uploads BEFORE `runTurn` and blocks on failure (the A8 ordering); the user record gains `image` only when attached; the user bubble renders the `img` with `alt`.
 - E2E: `tests/e2e/test_chat_image_questions.py` (task 04) — the composer scenarios.
 - Coverage: n/a (frontend) — the validate.sh `app/` gate must stay green.
 ## Completion Criteria
 - [ ] Flag on: attach → preview → remove all work; send with an attachment uploads, the user bubble shows the image, and the question reaches the model.
 - [ ] Flag off: the attach button is ABSENT from the DOM; a hand-crafted `image` request still gets the server's error frame (task 01's contract, unchanged).
 - [ ] A text-only send produces the same request body and DOM as pre-phase (byte-check in the E2E where practical).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,26 @@
 # Task 03 — Restore + shared: the question's image survives a refresh and a share link
 **Phase:** `123_chat_image_questions` · **Source:** `TODO.md:6` — "…users should be able to submit images as part of their question in brain of reese."
 ## Objective
 A user record carrying `image` (the stored path) renders its image when the chat is restored from localStorage / the saved-chat API, and on the shared-chat page — a load failure degrades to a small note, never a broken icon.
 ## Work
 1. `frontend/assets/app.js` — `renderStoredMessage(m)` (L1642), the USER branch: when `m.image` is present, the restored user bubble includes `<img src="{m.image}" alt="{m.text || 'attached image'}">` through the SAME bubble-image helper task 02 built for the live bubble (one renderer — the live bubble passes the data URL, restore passes the path; the helper takes any `src`). `onerror` → replace the image with a small "image unavailable" line (the file was deleted out-of-band — the row keeps its path, the render degrades).
   - The restore paths that call `renderStoredMessage` (the localStorage restore ~L1700 and the saved-chat restore ~L1770) need NO other change — the record's `image` key flows through the phase-14/50 restore as any optional key.
   - `retryLastTurn` / regenerate: a RE-ASK of a question that had an image does NOT re-attach the image (the redo re-sends `prev.text` only — LOCKED A7, the image is turn-local to the original send; the restored image stays visible in the replaced record until the redo pops it, which is the existing redo-in-place behavior).
 2. `frontend/assets/shared.js` — the shared page's message render (its text-only loop over `messages`): the user-record branch gains the same image render (the image route is public — a shared chat is faithful; the `alt` + `onerror` degradation are identical to the chat page).
 3. `frontend/assets/styles.css` — no new rules beyond what task 02 added (the shared page reuses the bubble-image block; verify the shared page's bubble class shares it — if the shared page uses a different bubble class, scope the image rule to both).
 4. ASSUMPTION: the `image` key is optional and absent in every pre-phase saved chat — no data migration, no backfill (old chats have no question-images to restore).
 ## Testing & Quality
 - Unit: `tests/unit/test_chat_image_questions.py` (task 04) — house-style source assertions: the user-branch render reads `m.image` and reuses the bubble-image helper; the `onerror` degradation exists on BOTH pages; the shared render includes the image; the redo path sends `prev.text` only (no `image` on the re-ask).
 - Integration: `tests/integration/test_chats_api.py` (extend, task 04) — a user record with `image` round-trips `POST`/`PUT /api/chats` and serves through `GET /api/shared/{token}` (the public shape carries it).
 - E2E: the refresh + shared scenarios of `tests/e2e/test_chat_image_questions.py` (task 04).
 - Coverage: n/a (frontend) — the validate.sh `app/` gate must stay green.
 ## Completion Criteria
 - [ ] Reload after an image question: the user bubble shows the image (from the stored path) + the rest of the conversation is unchanged.
 - [ ] The shared link renders the image on the shared page.
 - [ ] A deleted image file degrades to the "image unavailable" line on both pages (no broken-image icon).
 - [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
@@ -0,0 +1,39 @@
 # Task 04 — Chat-image tests: unit + integration + isolated E2E
 **Phase:** `123_chat_image_questions` · **Source:** `TODO.md:6` — "…users should be able to submit images as part of their question in brain of reese."
 ## Objective
 Pin the whole question-image contract: the upload/serve rules, the multimodal model payload, the toggle-off rejection, the persistence shape (path, never base64), the composer gating, and the refresh/share rendering — as an isolated Playwright suite.
 ## Work
 1. `tests/unit/test_chat_image_questions.py` (new) — consolidates the per-task unit cases (tasks ship code; this task ships the full pin):
   - config: `chat_image_dir`/`chat_image_max_mb` defaults + env overrides;
   - the `ChatRequest.image` validator (well-formed path ok; data URL / wrong ext / traversal / malformed uuid → 422, fixed details, no echo);
   - the multimodal builder (text part + `image_url` data-URL part, correct mime; `image=None` → the plain string, byte-identical); the data-URL helper is shared with `describe_image` (assert the import, not a copy);
   - the error frames: toggle-off (exact detail + hint strings), stale file (exact detail) — both settle the turn WITHOUT a model call (the mock client must see zero calls);
   - the upload endpoint: the six exts accepted, others 422/413-style per the spec, oversize → 413 (fixed detail naming the cap), the stored filename is `<uuid-hex>.<ext>`;
   - the serve route: 200 + Content-Type per ext, 404 for missing/unknown/traversal filenames;
   - `ChatMessage.image` (max 500, omission when None, `extra="forbid"` intact — an unknown key still 422s);
   - frontend source assertions (tasks 02+03): the attach button hidden-by-default + config-gated reveal, the A8 upload-before-send ordering + block-on-failure, the user record's `image` key, the shared bubble render, the `onerror` degradation, the redo sends text-only.
 2. `tests/integration/test_chat_api.py` (extend, task 01's cases):
   - `POST /api/chat-images` → `POST /api/chat` with the returned path → the MOCK client received the multimodal content list (text == the question, data URL decodes to the uploaded bytes);
   - `images=false` + `image` → the SSE error frame with the hint; the mock client got NO call; NO saved record;
   - `image=None` → the model payload is byte-identical to a pre-phase request;
   - a saved chat (and a shared one) round-trips a user record with `image` — and assert the stored payload contains NO base64 (the path only — the A5 contract).
 3. `tests/integration/test_chats_api.py` (extend, task 03's case): the shared-chat serve includes the user record's `image` path.
 4. `tests/e2e/test_chat_image_questions.py` (new — isolated run per AGENTS.md §4: `uv run pytest tests/e2e/test_chat_image_questions.py -v --no-cov`), `BOR_IMAGES=true` for this suite's app instance (the phase-122 E2E env-override pattern):
   - attach a fixture PNG in the composer → the preview strip shows (thumbnail + filename) → remove → the strip clears and the file state is gone;
   - re-attach → send → the user bubble shows the image; the mock LLM's (text-only) answer streams normally (the mock ignores the image part — the assertion is on the REQUEST the server built, verified via the mock's capture);
   - `page.reload()` → the user bubble restores WITH its image (the stored path, not the data URL — the request count for the image route confirms the path fetch);
   - share the chat (the existing share flow) → open the shared link → the shared page shows the user's image;
   - default-off negative (a second app instance or the suite's flag-off fixture): `#attach-btn` is ABSENT from the DOM; a direct `POST /api/chat` with an `image` path returns the hinted error frame (no model call).
 5. Run the full gate: `uv run pytest`, `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), the isolated E2E file, `uv run ruff check . && uv run pyright`.
 ## Testing & Quality
 - This task IS the phase's test suite (see Work).
 - Coverage: **>90%** on `app/` — the phase's `app/` surface (config, the chat-images router, the chat pipeline, the schemas) is fully exercised.
 ## Completion Criteria
 - [ ] All test artifacts exist and pass; the isolated E2E file passes standalone.
 - [ ] The multimodal payload, the no-base64-in-storage, and the toggle-off rejection are each asserted at the unit AND integration level.
 - [ ] `uv run pytest --cov=app` TOTAL >90%; lint + types clean.
@@ -0,0 +1,18 @@
 All verification complete. Final report:
 **Phase 120 — Failed-turn retry: verification pass (all 3 tasks were done; final verification + 1 regression fix)**
 **Verified:** `ChatMessage.failed`/`error` (≤500, `extra="forbid"` intact); `finalizeFailedTurn` funnel on the 3 failure paths (catch-else, stream-drop guard, zero-frame fallback) with `failed: true` + capped detail + `markLastRetryable`; `appendFailedNote` restore branch (Save-as-doc/Tune excluded); `showErrorBanner`/`retryLastTurn` byte-pinned untouched; only the three paths persist `failed: true` (grep + unit pin); no test asserts the old broken behavior.
 **Defect found & fixed (rule 7):** a real navigate-away mid-turn let the browser's teardown fetch rejection (TypeError, not AbortError) leak into the failed funnel, persisting a phantom failed brain record — `test_sources_midstream_bug.py::test_no_orphan_brain_message_when_navigated_before_first_token` failed (2 `.msg` after reload) and violated the phase-20 navigate-away convention. Fixed: turn-scoped `leftThePage` flag (set unconditionally on `pagehide`, reset in `runTurn`) skips the funnel in the catch-else branch; pinned by new unit test `test_navigate_away_is_not_a_failed_turn`. No phase-overview/PLAN/todo/complete files touched; no commits made.
 **Gates (exact):**
 - `uv run pytest` → 2577 passed
 - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 4271 stmts, 99% (>90%)
 - `uv run pytest tests/e2e/test_failed_turn_retry.py -v --no-cov` → 4 passed (isolated)
 - `uv run ruff check . && uv run pyright` → clean (0 errors)
 - Regression E2E, isolated: `test_sources_midstream_bug.py` 6/6 (was 5/6); `test_llm_retry`/`test_tool_scaffolding_guardrails`/`test_stop_generation`/`test_navbar_refresh` 17/17
 **Completion criteria:** (1) network error → banner + in-bubble Retry, re-ask without re-typing ✅ (E2E A); (2) refresh restores failed bubble + working Retry, no "new chat" ✅ (E2E C); (3) stopped/successful turns byte-identical ✅ (negative E2E, stop suite, byte-identity units); (4) pytest/coverage/lint/types ✅; (5) commit + phase move — left to the harness per pass rules.
 **Notable:** deviation = the regression fix above (a navigation is not a failed turn; phase-20 partial-persist convention restored). Next pending phase: `121_git_source_tokens`.
@@ -0,0 +1,104 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 11%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 22%]
 ........................................................................ [ 25%]
 ........................................................................ [ 27%]
 ........................................................................ [ 30%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 39%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 69%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 83%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 94%]
 ........................................................................ [ 97%]
 .........................................................                [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           232      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    128      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            14      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   332      0   100%
 --------------------------------------------------
 TOTAL                           4271     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 **Task 01 complete — persist the failed turn: schema fields + live error paths**
 Implemented:
 - `app/schemas.py`: `ChatMessage.failed: bool|None` + `error: str|None (max_length=500)` beside `stopped`, docstring extended (phase-48 precedent, locked A1); `extra="forbid"` intact.
 - `frontend/assets/app.js`: `FAILED_TURN_TEXT` constant; `appendFailedNote(wrap, detail)` (mirror of `appendStoppedNote`, detail via textContent); `finalizeFailedTurn()` funnel (partial → close block/calls + note + persist `failed:true`; zero-frames → FAILED_TURN_TEXT bubble; both set `lastBrainWrap` + `markLastRetryable()`, detail trimmed/capped 500). Wired into: error-catch `else` (before `setUiState`), stream-drop guard, and the zero-frame fallback (now `failed:true` + "The model answered with nothing." note).
 - `frontend/assets/styles.css`: `.failed-note` — stopped-note family in `--err-ink` (~9:1 on `--surface`, wraps, non-interactive).
 - `showErrorBanner`/`retryLastTurn`/`markLastRetryable`/stop/done paths byte-untouched (verified via diff); `failed: true` persisted at exactly the three failed paths (grep).
 - Ripple fixes for the new response keys (exact-shape pins): `tests/unit/test_schemas.py` fixtures, `tests/integration/test_chats_api.py` (`_expect` + `FULL_BRAIN`), `tests/e2e/test_navbar_refresh.py` allowed key-set.
 Results:
 - `uv run pytest` → 2547 passed; `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%)
 - `uv run ruff check . && uv run pyright` → clean (0 errors)
 - Adjacent E2E sanity (isolated): `test_retry_answer.py` 4/4, `test_stop_generation.py` 3/3 — stopped/success turns unchanged.
 Decisions: no test files authored (task 03 owns them, per the task file); schema verified via ad-hoc checks. No commit made (harness owns the atomic commit).
 Next pending task: `.agents/phases/todo/120_failed_turn_retry/02_restore_failed_turn.md`.
@@ -0,0 +1,104 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 11%]
 ........................................................................ [ 14%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 22%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 31%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 48%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 98%]
 ...........................                                              [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           232      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    128      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            14      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   332      0   100%
 --------------------------------------------------
 TOTAL                           4271     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,21 @@
 All green. My task-02 hunks are cleanly scoped (lines 76, 85–109 of the diff); the rest are task 01's prior work already in the tree.
 **Task 02 — Restore the failed turn: COMPLETE**
 **Implemented** (`frontend/assets/app.js` → `renderStoredMessage`):
 - Failed-branch restore: `m.failed` record renders its `text`, then `appendFailedNote(wrap, m.error)` — note omitted entirely when `m.error` is null (record's `text` already carries the detail)
 - Save-as-doc gate extended: `if (!m.stopped && !m.failed) appendSaveAsDocButton(wrap, m.text);`
 - Tune gate added: `if (!m.failed) appendTuneButton(wrap);` (a note, not an answer; stopped/successful records byte-identical — they keep Tune)
 - No other restore change: existing `lastBrainWrap = wrap` + `markLastRetryable()` already land the Retry on the last restored brain bubble (the failed one when it ends the chat); `retryLastTurn` unchanged; mid-conversation failed bubble gets no Retry (last-bubble-only rule intact)
 - Shared page: confirmed `shared.js` `renderSharedMessage` never reads `failed`/`error` → failed records render text-only, no note/Retry, no code change (per task)
 - Updated `bor.chat.v1` record-shape comment (+ `failed?, error?`) and the phase-59 line-pin in `tests/unit/test_save_as_doc_button.py`
 **Tests / lint / coverage**
 - `uv run pytest` → 2547 passed
 - `uv run ruff check . && uv run pyright` → clean (0 errors, 0 warnings)
 - `uv run pytest --cov=app` → TOTAL 99% (>90% gate; `schemas.py` 100%)
 - `bash .agents/validate.sh` → validation OK
 **Decisions:** the task's "No Tune button for failed records either" implemented as a `!m.failed`-only gate (the restore call site didn't previously gate Tune on `m.stopped`, so stopped behavior is untouched per the byte-identical criterion). Unit/E2E tests for this task are task 03's per the phase plan.
 **Next pending task:** `.agents/phases/todo/120_failed_turn_retry/03_failed_turn_tests.md`
@@ -0,0 +1,104 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 11%]
 ........................................................................ [ 14%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 22%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 31%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 48%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 98%]
 ...........................                                              [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           232      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    128      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            14      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   332      0   100%
 --------------------------------------------------
 TOTAL                           4271     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,16 @@
 All gates green. Final report:
 **Phase 120 task 03 — Failed-turn tests: COMPLETE**
 **Implemented**
 - `tests/unit/test_chat_message_failed.py` (new, 10 tests): `failed`/`error` acceptance, 501-char `error` 422 (500 passes), unknown-key 422 (`extra="forbid"` intact), pre-phase records byte-identical on existing keys
 - `tests/unit/test_frontend_failed_turn.py` (new, 14 tests): all three live failure paths route through `finalizeFailedTurn` (persist `failed: true`, end `markLastRetryable`), `appendFailedNote` dedup + textContent-only, `FAILED_TURN_TEXT` distinct from `EMPTY_ANSWER_FALLBACK`, `showErrorBanner` + `retryLastTurn` **byte-pinned**, restore branch (note + Save-as-doc/Tune exclusion), `.failed-note` CSS
 - `tests/integration/test_chats_api.py` (extended, +4): failed record POST/GET/PUT round-trips byte-identical; `error`>500 → 422 (POST + PUT, nothing stored); shared chat with failed record serves unchanged public shape
 - `tests/e2e/test_failed_turn_retry.py` (new, 4 tests) + two new mock injections (`fail first turn`, `partial then fail`): A zero-frame error → banner Retry + failed bubble → re-ask → grounded answer, bubble gone; B partial+error → text kept + note + in-bubble Retry → redo-in-place; C refresh restores failed bubble with working Retry; negative: stopped turn restores "Stopped" note, never a failed note
 - Defect fixes: `test_llm_retry.py` (exhaustion) + `test_tool_scaffolding_guardrails.py` (terminal) asserted the old broken behavior (no bubble on error) — updated to the phase-120 contract
 **Results**: `uv run pytest` 2576 passed · `uv run pytest --cov=app --cov-report=term-missing` TOTAL 99% (>90%) · `uv run ruff check . && uv run pyright` clean · `tests/e2e/test_failed_turn_retry.py -v --no-cov` 4/4 in isolation (×2) · validate.sh OK
 **Decisions**: mock fails exactly one turn (4 attempts = forced default budget) then answers, so Retry succeeds; B/C use grounded questions so re-asks assert `MOCK_ANSWER_MARKER`; E2E waits for the idle "Send" label before reading localStorage (done-frame settle — the marker is visible a few frames before `done`).
 **Next pending**: none in phase 120 (all 3 tasks done); next phase dir: `todo/121_git_source_tokens`.
@@ -0,0 +1,104 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 11%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 22%]
 ........................................................................ [ 25%]
 ........................................................................ [ 27%]
 ........................................................................ [ 30%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 39%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 69%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 83%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ........................................................                 [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           232      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    128      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            14      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   332      0   100%
 --------------------------------------------------
 TOTAL                           4271     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,15 @@
 **Phase 121 final verification pass — all green** (all 4 tasks already in `complete/`; verified, no defects found, no changes needed)
 - Verified implementation vs phase design: migration `0021` (reversible, round-tripped via `alembic downgrade base` + `upgrade head` → head `0021`), `GitSource.token` column, `normalize_credential`/`clone_url_for`/`sanitize_url`, clone callers switched (`sync.py`, `import_docs.py`), masked token fields in add form + editor, `extra="forbid"` output shapes
 - Tests: `uv run pytest` → 2662 passed, 0 failed (exit 0); `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (≥90% gate)
 - Lint/types: `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings
 - E2E in isolation: `uv run pytest tests/e2e/test_git_source_tokens.py -v --no-cov` → **4 passed**
 Completion criteria:
 1. Private repo (UI add or pasted embedded-token URL) clones with injected token; token absent from every API response, page text, title attr, and full HTML — **PASS** (integration raw-JSON assertions + E2E `_assert_token_nowhere`)
 2. Legacy embedded-token rows still clone from stored URL; output sanitized — **PASS** (`test_sync_legacy_row_clones_with_original_stored_url`, `test_get_masks_legacy_embedded_token_row`, env-fallback masking)
 3. Public/local sources byte-identical — **PASS** (verbatim-URL + no-userinfo-unchanged tests)
 4. pytest / coverage / ruff / pyright — **PASS** (see above)
 5. Commit + phase move — harness responsibility; task files already in `complete/`, changes left in working tree (no commit made, per protocol)
 Notable: no deviations; DB left at head, functional. Next pending phase: **122_image_documents** (then 123_chat_image_questions).
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 38%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ..........................................................               [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4317     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,19 @@
 Task 01 complete. Report:
 **Implemented**
 - `GitSource.token` — `Text NULL` column in `app/models.py` with the phase-121/LOCKED-A2 field docstring (NULL = public/legacy row)
 - `alembic/versions/0021_git_source_token.py` — additive, fully reversible (drop_column downgrade); verified upgrade/downgrade/upgrade on the live dev DB
 - `app/schemas.py`: `GitSourceIn.token` + `GitSourcePatchIn.token` (max 500, before-mode trim validators, tri-state patch docstring); `GitSourceOut`/`GitSourceRow` gain **no** field — docstring contract + `extra="forbid"` so any `token` on construction raises
 - Tests: `tests/unit/test_git_source_token.py` (21 tests) + `tests/integration/test_migration_0021.py` (4 tests, house A13 pattern incl. ORM round-trip)
 **Results**
 - `uv run pytest` — 2602 passed
 - `uv run pytest --cov=app --cov-report=term-missing` — TOTAL **99%** (>90% ✓)
 - `uv run ruff check . && uv run pyright` — clean (0 errors; the two deliberate `token=` rejection lines carry house-style `# type: ignore[reportCallIssue]`)
 - `uv run alembic upgrade head` / `downgrade 0020` — apply/reverse cleanly; dev DB left at head (0021)
 **Decisions**
 - Added the before-mode trim to `GitSourcePatchIn.token` as well (house `_trim_url` precedent; whitespace-only = clear, consistent with the tri-state)
 - `extra="forbid"` on both output shapes makes "no token ever" structural (ChatMessage precedent), satisfying the task's "construction with a token kwarg raises" pin
 **Next pending task:** `02_clone_url_and_sanitization.md` (normalization on write, `clone_url_for`, `sanitize_url`)
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 11%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 22%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 30%]
 ........................................................................ [ 33%]
 ........................................................................ [ 35%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 47%]
 ........................................................................ [ 49%]
 ........................................................................ [ 52%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 60%]
 ........................................................................ [ 63%]
 ........................................................................ [ 66%]
 ........................................................................ [ 69%]
 ........................................................................ [ 71%]
 ........................................................................ [ 74%]
 ........................................................................ [ 77%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 85%]
 ........................................................................ [ 88%]
 ........................................................................ [ 91%]
 ........................................................................ [ 94%]
 ........................................................................ [ 96%]
 ........................................................................ [ 99%]
 ..........                                                               [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           232      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            14      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4284     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 All gates green. Task 02 complete.
 **Implemented**
 - `app/rag/git_sources.py`: three pure helpers — `sanitize_url` (anchored-regex userinfo strip, byte-identical/idempotent for clean URLs), `clone_url_for` (NULL token → stored URL verbatim; https? + token → `https://x-access-token:<token>@…`; non-https + token → unchanged + warning), `normalize_credential` (write-path: embedded userinfo → bare URL + token column; explicit token wins, LOCKED A6)
 - `app/api/git_sources.py`: POST normalizes (embedded `user:pass@` → bare URL + column; duplicate check on bare URL → 409); PATCH token tri-state (absent/None = no change, non-empty = replace, `""` = clear) with legacy-row re-normalization + IntegrityError→generic-409 backstop; `sanitize_url` on all 4 output sites (list DB rows, env rows, POST 201, PATCH 200)
 - `app/api/sync.py` + `scripts/import_docs.py`: clone call sites now use `clone_url_for(row)`; `repo_name` stays on the bare URL (credential-free checkout paths)
 **Tests / gates**
 - 32 new unit tests (`tests/unit/test_git_source_token.py`), 13 new integration tests (`tests/integration/test_git_sources_api.py`) — token absent from raw JSON text of every response, legacy rows clone with original stored URL, sync receives injected URL
 - `uv run pytest --cov=app --cov-report=term-missing` → exit 0, TOTAL **99%** (>90%; touched modules 100%)
 - `uv run ruff check .` clean; `uv run pyright` 0 errors; sanity: `tests/e2e/test_git_sources_admin.py` 6/6 in isolation
 **Notable decisions**
 - The "embedded credential" moved to the column is the *password* part of `user:pass@` (whole run for the no-colon `https://<token>@host` form) — only that authenticates via the injected `x-access-token:<password>@`
 - A token on a `kind=local` row is stored inert (never cloned, never echoed); env-fallback URLs are masked on output only
 **Next pending task:** `03_ui_token_field.md`
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 38%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 49%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 68%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 98%]
 ...................................................                      [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4317     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 All checks pass and the diff is clean. Final verification summary:
 - `uv run pytest --cov=app --cov-report=term-missing` → **2650 passed**, TOTAL coverage **99%** (>90% gate)
 - `uv run ruff check .` → clean; `uv run pyright` → **0 errors, 0 warnings**
 - Affected story E2Es in isolation: `test_source_ignore_paths.py` 6 passed, `test_git_sources_admin.py` 6 passed, `test_hidden_folders_toggle.py` 6 passed
 **Implemented (task 03 — UI masked token field):**
 - **`frontend/index.html`**: add form gains optional masked `#git-source-token` (`type="password"`, `autocomplete="off"`, "optional — private repos" hint span); the per-row editor dialog mirrors it with `#ignore-editor-token` ("leave blank to keep the current token"); dialog title widened "Ignored files and folders" → "Source settings" to match its new scope
 - **`frontend/assets/git-sources.js`**: submit body `(url, token) => ({ url, ...(token ? { token } : {}) })` (blank = key omitted); editor token always opens/resets blank, PATCH body includes `token` only when non-blank (tri-state no-change); display sites keep rendering server-sanitized `s.url` with the required one-line note; phase-121 docstring bullet
 - **`frontend/assets/styles.css`**: `#git-source-token` grouped with the URL input (incl. mobile rule), minimal `.field-hint` (ink-soft, 5.1:1 AA), `.ignore-editor-token` full-width 44px box
 - **Tests**: 7 new house-style source pins in `tests/unit/test_git_source_token.py` (masking, blank-omission on POST+PATCH, display sites, docstring, CSS); updated `test_source_ignore_paths.py` save-body pin + id guard for the intentional dialog extension
 **Notable decisions:**
 - The task's "edit modal (L697)" is not a distinct modal — verified against the phase-authoring commit, L697 is the per-row "Ignore paths" editor dialog (the only per-row edit surface); extended that, matching the phase's "edit row (blank token) → token kept" contract and the "Sources page layout untouched" boundary
 - Task-03 unit pins landed now (task file defers to 04, but they assert this task's changes); the phase E2E file stays task 04's deliverable
 **Next pending task:** `.agents/phases/todo/121_git_source_tokens/04_token_tests.md` (finalize unit/integration + isolated E2E `test_git_source_tokens.py`)
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 38%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ..........................................................               [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4317     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,15 @@
 All work is verified and the tree is as it should be (only my new E2E file added; tasks 01–03 changes already in the working tree, untouched by me, no commits).
 **Phase 121 / Task 04 — Token tests: complete**
 Implemented:
 - `tests/e2e/test_git_source_tokens.py` (new, 4 tests, isolated port 8146, `BOR_GIT_SOURCES=""` + tmp sources/upload dirs pinned): add via UI (bare URL + masked token) → row renders bare URL in cell + `title` attr, token absent from body text / every `title` / page HTML / raw `GET /api/git-sources` JSON, DB = bare URL + token column; old-style `user:token@` paste normalized (A6) and hidden; editor token field `type=password`, opens blank, blank save → single PATCH 200 omitting the `token` key, stored token kept; confirm-modal removal → 204, list empty.
 - Verified task-01–03 deliverables already in place and green: `tests/unit/test_git_source_token.py` (50 tests — sanitize/clone/normalize/output-model/frontend pins) and the `tests/integration/test_git_sources_api.py` token block (POST/409/PATCH tri-state/legacy mask/sync-clone raw-JSON "token nowhere" on list, 201, PATCH, sync-status surfaces).
 Gates (all green):
 - `uv run pytest` → 2650 passed
 - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%); `app/api/git_sources.py`, `app/rag/git_sources.py`, `app/schemas.py`, `app/models.py` all 100%
 - `uv run pytest tests/e2e/test_git_source_tokens.py -v --no-cov` → 4 passed
 - `uv run ruff check . && uv run pyright` → clean, 0 errors
 Decisions: no defects found in prior tasks; only fix was in my new file (Playwright `APIResponse.text` is a method — `r.text()`; body text via `page.evaluate` per house style). Next pending task: none in this phase — all 4 tasks done, phase is complete.
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 19%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 38%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 76%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 84%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ..........................................................               [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    231      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4317     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,19 @@
 **Phase 122 (image documents) — final verification pass: all green. No code changes were needed; defects found: none.**
 **Verified (implementation already complete in working tree, reviewed end-to-end):**
 - Toggle (`BOR_IMAGES`/`BOR_IMAGE_EXTENSIONS`/`BOR_IMAGE_DIR`, off by default) + `GET /api/config` `images` flag
 - Ingest: bytes digest, `image_dir` persistent copy, `content = summary = vision description` (chat-model call; only text embedded), fail-soft skip + `images_failed` counter
 - Serve/display: `/api/documents/{id}/image` route (404 matrix), viewer `<img>` + description, Sources 48px lazy thumbnails, chat inline source figure (alt = summary), agent `read` marker
 - Prune guard: images-off syncs never prune `is_image` docs
 **Test / lint / coverage (exact commands & outcomes):**
 - `uv run pytest` → exit 0 (green; note: pytest 9.1.1 `-q` omits the final count line in output — exit code authoritative)
 - `uv run pytest --cov=app --cov-report=term-missing` → **2715 passed, exit 0, TOTAL 99%** (>90% gate)
 - `uv run ruff check . && uv run pyright` → "All checks passed!" / "0 errors, 0 warnings, 0 informations"
 - `uv run pytest tests/e2e/test_image_documents.py -v --no-cov` → **4 passed, exit 0** (isolation)
 **Completion criteria:** (1) images=true → described/embedded/displayed docs: ✅ (E2E + integration) · (2) images=false byte-identical + image docs survive sync: ✅ (E2E negative app + unit/integration) · (3) viewer + chat rendering with alt text; failed description skips + logs, sync completes: ✅ · (4) test/lint/coverage gates: ✅ · (5) commit + phase move: deferred to harness per this pass's rules (working tree left uncommitted).
 **Notable deviation (pre-existing, documented in code):** image route uses `require_user` (phase-79 posture, same gate as the document content endpoint) rather than the phase text's "public" parenthetical — matches the endpoint it mirrors.
 **Next pending phase:** `123_chat_image_questions`.
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 23%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 31%]
 ........................................................................ [ 34%]
 ........................................................................ [ 37%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 60%]
 ........................................................................ [ 63%]
 ........................................................................ [ 66%]
 ........................................................................ [ 68%]
 ........................................................................ [ 71%]
 ........................................................................ [ 74%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 98%]
 ...................................................                      [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             46      0   100%
 app/schemas.py                   373      0   100%
 --------------------------------------------------
 TOTAL                           4514     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,19 @@
 All green. The untracked `.agents/reports/` dir is a harness runtime artifact — left untouched.
 ## Task 01 complete — image toggle (`BOR_IMAGES` + extensions + dir, off by default)
 **Implemented**
 - `app/config.py`: `images: bool = False`, `image_extensions: str = "png,jpg,jpeg,webp,gif,bmp"`, `image_dir: str = "~/bor-sources/images"` (house docstrings, LOCKED A3 default); `image_extension_set` property (dotted lowercased frozenset, separate from `import_extension_set`); fail-loud validator for empty/malformed `image_extensions` (the `import_extensions` precedent)
 - `.env.example`: three entries + comment block (off by default, vision-model dependency note)
 - `app/api/config.py`: `GET /api/config` gains `"images": settings.images` (six-key contract; docstring notes phase-123 composer consumption)
 - Tests: new `tests/unit/test_image_documents.py` (7 tests: defaults, env overrides, case/trim parse, validators, set separation); `/api/config` pins updated to six keys in `test_api.py` (+ new `images=True` flag-tracking test), `test_save_as_doc_button.py`, `test_ui_settings_api.py`, and 2 E2E suites; conftest leak-pins for the 3 vars (house pattern)
 **Verification**
 - `uv run pytest` → 2658 passed
 - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%); touched modules 100%
 - `uv run ruff check . && uv run pyright` → clean (0 errors)
 - E2E sanity (isolated): `test_configurable_brand.py` 5 passed, `test_ui_customization.py` 4 passed
 **Decisions**: added the `image_extensions` validator (not explicit in the task, but the design cites the `import_extensions` precedent and the house fail-loud rule); `images` placed after `docs_repo_configured` in the response dict. No live-infra touched.
 **Next pending task**: `.agents/phases/todo/122_image_documents/02_image_ingest.md`
@@ -0,0 +1,105 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 27%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 37%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 65%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 73%]
 ........................................................................ [ 75%]
 ........................................................................ [ 78%]
 ........................................................................ [ 81%]
 ........................................................................ [ 83%]
 ........................................................................ [ 86%]
 ........................................................................ [ 89%]
 ........................................................................ [ 92%]
 ........................................................................ [ 94%]
 ........................................................................ [ 97%]
 ..................................................................       [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    129      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              219      3    99%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4333     16    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 Everything is complete and green. The diff is coherent and matches the task spec exactly.
 ## Report — Task 02 (image ingest) complete
 **Implemented**
 - `app/models.py`: `Document.is_image` (bool, server-default false) + `Document.image_path` (Text NULL), house docstrings
 - `alembic/versions/0022_documents_image.py`: both columns + tested downgrade (A13); applied to dev DB
 - `app/rag/importer.py`: walk admits `image_extension_set` only while `settings.images` (separate set, empty default = byte-identical off); `_index_file` image branch BEFORE `read_text` → `_index_image_file` (bytes sha256, persistent copy `image_dir/<doc-id>.<ext>` written only after successful description, stale-copy delete on change, `is_image`/`image_path` set, description = content, normal chunk/`_store_summary` pipeline); single commented seam `_describe_or_skip` for task 03; `_prune` guard (off → `is_image` docs survive; on → pruned + copy deleted); `ImportSummary.images_failed` + slot in the PLAN §9 log line
 - Tests: unit section in `tests/unit/test_image_documents.py` (walk filter, binary branch incl. `read_text`-never-called, fail-soft skip + log line, unchanged/backfill, stale-copy delete, prune guard); `tests/integration/test_migration_0022.py` (upgrade/downgrade/round-trip, backfill, ORM); `tests/integration/test_docs_api.py` `import_sources` e2e (on/off/prune)
 **Results**
 - `uv run pytest --cov=app --cov-report=term-missing` → 2672 passed, TOTAL 99% (>90% gate)
 - `uv run ruff check .` → clean; `uv run pyright` → 0 errors
 **Decisions**: task-02 seam `_describe_or_skip` is a placeholder returning `None` (task 03's `describe_image` fills its body — per the task file's strict reading, since task 03 isn't merged); log-line pin and a walk-stub signature in `tests/unit/test_importer.py` updated for the additive changes. Note: source *removal* (`DELETE /api/git-sources/{id}`) doesn't yet delete image copies — outside this task's list; flag for a later task.
 **Next pending task**: `03_image_description.md`
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 35%]
 ........................................................................ [ 37%]
 ........................................................................ [ 40%]
 ........................................................................ [ 43%]
 ........................................................................ [ 45%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 53%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 78%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 86%]
 ........................................................................ [ 88%]
 ........................................................................ [ 91%]
 ........................................................................ [ 94%]
 ........................................................................ [ 97%]
 ........................................................................ [ 99%]
 ........                                                                 [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              313     17    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             24      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4429     30    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,22 @@
 Everything is green and coherent. Final state of the task verified against all completion criteria.
 ## Report — Task 03 (image description) complete
 **Implemented**
 - `describe_image` in `app/rag/summarizer.py` — ONE CHAT-model (vision) call (LOCKED A3), multimodal user message (`DESCRIBE_PROMPT` text part + `image_url` data-URL part), reply stripped + capped at `summary_max_chars`, `None` on client error/empty/non-2xx (logs the reason; the importer's warning names the doc)
 - New constants: `IMAGE_DESCRIPTION_MODE` marker + `DESCRIBE_PROMPT` (E2E-mock key, task 06 wires the branch), `IMAGE_MIMES` map + fallback (task 04 reuses for `Content-Type`)
 - Importer: `_describe_or_skip` seam filled (real `describe_image`, mime from `IMAGE_MIMES`); `_store_summary` image-aware — for `is_image` docs the description IS the summary (verbatim, no `lite` call/pointer), so `content == summary` and the `is_summary` chunk mirrors it; the phase-118 backfill reuses the same path
 - Widened `Embedder`/`SummaryLLM`/`FakeEmbedder` chat typings to multimodal (no `LLMClient` change needed); E2E mock `_user`/`_context` made list-safe for multimodal messages (byte-identical for string content)
 - Tests: 8 new unit + 1 new integration (mock-vision end-to-end, **no seam patch**); fixed task-02's backfill test for task-03 semantics (an image's remaining summary failure class is now the `is_summary` chunk's embed, not a failing `lite` call)
 **Results**
 - `uv run pytest` → 2681 passed
 - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (summarizer 100%, importer 95%)
 - `uv run ruff check . && uv run pyright` → clean
 - E2E spot-checks (smoke / agent-document-tools / oneshot-retry, in isolation) → all passed
 **Decisions**
 - `describe_image` follows the existing one-shot `chat()` convention (house phase-96 empty-content retry policy) — no extra retry loop added
 - Image `doc.summary` carries the description verbatim (no `Source:` pointer line)
 **Next pending task:** `04_serve_and_display.md`
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  8%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 16%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 24%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 32%]
 ........................................................................ [ 34%]
 ........................................................................ [ 37%]
 ........................................................................ [ 40%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 53%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 69%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 77%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 85%]
 ........................................................................ [ 88%]
 ........................................................................ [ 91%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 99%]
 .................                                                        [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  156      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             46      0   100%
 app/schemas.py                   344      0   100%
 --------------------------------------------------
 TOTAL                           4454     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,18 @@
 All gates green. Final report:
 **Implemented (task 04 — serve + display):**
 - `GET /api/documents/{id}/image` (app/api/docs.py): exact bytes via `FileResponse`, `Content-Type` from the shared `IMAGE_MIMES` map, `Cache-Control: private, max-age=3600`; 404 `document not found` for missing/malformed id, text docs, NULL `image_path`, lost file
 - Content endpoint gains `is_image` (always present) + `image_url` (absent for text docs, never null); tree file nodes gain the same affordance, row-driven (text nodes byte-identical to pre-phase)
 - Viewer (`document.js`, shared page+modal core): `<img>` block from `image_url` (alt = summary), description stays in the plain-content slot, onerror → "Image unavailable" note; duplicate summary panel suppressed when summary === content
 - Sources page: fixed 48px lazy thumbnail (object-fit cover) before the path link, document-glyph fallback on fetch failure; CSS in theme tokens
 **Tests / gates (all green):**
 - `uv run pytest --cov=app` → 2702 passed, TOTAL **99%** (>90%)
 - `uv run ruff check . && uv run pyright` → clean (0 errors)
 - New: route battery (6 ext Content-Types, exact bytes), 404 matrix, auth pin, content/tree wire tests (integration) + schema wire + frontend source pins + builder image-node tests (unit); spot-checked E2E `test_smoke`/`test_summary_in_viewer` → pass
 **Notable decisions:**
 - **Flagged deviation:** task says "PUBLIC" citing anonymous content — stale: phase 79 (owner, 2026-08-22) gated the content endpoint `require_user` (A10: only shared chats anonymous). The image route uses the same `require_user` gate ("like the document content endpoint"); anonymous → 401
 - Thumbnail lives in the Path cell (the phase-97 file table has no icon column); tree affordance is row-driven so surviving image docs keep thumbnails after toggle-off
 **Next pending task:** `.agents/phases/todo/122_image_documents/05_rag_display.md`
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 23%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 31%]
 ........................................................................ [ 34%]
 ........................................................................ [ 37%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 61%]
 ........................................................................ [ 63%]
 ........................................................................ [ 66%]
 ........................................................................ [ 69%]
 ........................................................................ [ 71%]
 ........................................................................ [ 74%]
 ........................................................................ [ 77%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 85%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 95%]
 ........................................................................ [ 98%]
 ......................................                                   [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 347      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             242      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             46      0   100%
 app/schemas.py                   366      0   100%
 --------------------------------------------------
 TOTAL                           4499     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,18 @@
 Everything is complete and green. Final report:
 **Task 05 (RAG display) — implemented**
 - `app/schemas.py` — `SourceRef` gains optional `image_url` (bytes-route path); wrap-serializer drops it when `None` → text-doc frames byte-identical, never `null`
 - `app/rag/retriever.py` — shared helper `source_ref_with_image(doc)` sets `image_url` iff `doc.is_image`; `app/api/chat.py` cited + related tiers both route through it (lockstep)
 - `app/rag/agent.py` — `IMAGE_DOC_MARKER` constant; `read` of an image doc gets the marker line between the byte-identical header/date lines and the description (plain + truncation paths); text results byte-identical
 - `frontend/assets/app.js` — `appendSourceImageFigure` + `fetchContentSummary`, gated on `s.image_url` in both `appendSources` and `appendRelated`: compact inline `<img>` (additive — chip text/affordance kept), alt + visible caption = doc summary (fetched from the existing content endpoint — the frame carries no summary per assumption 5; title until it settles), img error removes the figure (collapses to plain chip, never a broken icon)
 - `frontend/assets/styles.css` — `.source-image*` rules (96px cap, `object-fit: contain`, `--surface`, AA 8.6:1 caption, flat underline hover)
 - Tests: 9 new unit tests in `tests/unit/test_image_documents.py` (helper present/absent + nested done-frame pin + pre-phase saved-ref parse, marker pins incl. truncation, house-style frontend contracts) + 2 integration tests in `test_chat_api.py` (image doc's ref alone carries `image_url`; text-only grounded turn → raw wire frame contains no `image_url` bytes, refs keep exactly the pre-122 key set)
 **Gates (exact):**
 - `uv run pytest --cov=app --cov-report=term` → **2714 passed**, TOTAL **99%** (>90%)
 - `uv run ruff check .` → **All checks passed**
 - `uv run pyright` → **0 errors, 0 warnings**
 **Notable decisions:** summary caption fetched client-side (frame carries no summary — `image_url` is the only new frame field); the figure also renders in the related-docs row (same ref shape, same helper); E2E rendering scenario is task 06's scope per the task file. No live-infrastructure changes.
 **Next pending task:** `06_image_tests.md` (phase-122 test suite: unit consolidation + integration extensions + isolated E2E `test_image_documents.py`).
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 23%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 31%]
 ........................................................................ [ 34%]
 ........................................................................ [ 37%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 61%]
 ........................................................................ [ 63%]
 ........................................................................ [ 66%]
 ........................................................................ [ 68%]
 ........................................................................ [ 71%]
 ........................................................................ [ 74%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 98%]
 ..................................................                       [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             46      0   100%
 app/schemas.py                   373      0   100%
 --------------------------------------------------
 TOTAL                           4514     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,20 @@
 All checks complete. The phase 122 task 06 is done — all gates green.
 ## Report
 **Implemented (task 06 — image tests):**
 - `tests/e2e/test_image_documents.py` (new, isolated): module app with `BOR_IMAGES=true` (leak-guard env) + a second default-env app (`BOR_IMAGES=false`); real admin upload flow (single-PNG zip) → UI "Sync sources" → Sources thumbnail, document-viewer image+description, chat sources inline figure, and the default-off negative case (same upload → no image doc, "0 added · 0 unchanged")
 - `tests/e2e/mock_llm.py`: `IMAGE_DESCRIPTION_MODE` branch + `IMAGE_DESCRIPTION_ANSWER` (deterministic, token-dense so the question grounds at cosine ≈0.31)
 - `tests/integration/test_docs_api.py`: added the task's failing-vision integration pin (`images_failed == 1`, no row, text doc indexed, warning names the doc)
 - **Defect fix (task 04 work):** `frontend/assets/sources.js` `renderLevel` built the `makeRow` row without `is_image`/`image_url`/`summary` — the Sources thumbnail never rendered; now passed through (text nodes stay undefined → byte-identical bare link)
 **Test / lint / coverage:**
 - `uv run pytest` → **2715 passed** (baseline 2714 + 1)
 - `uv run pytest --cov=app --cov-report=term` → **TOTAL 99%** (>90% gate)
 - `uv run pytest tests/e2e/test_image_documents.py -v --no-cov` → **4 passed** (ran 3× incl. consecutive stability; DB up)
 - `uv run ruff check .` → clean; `uv run pyright` → 0 errors
 - Cross-check: `test_chat_rag.py` + `test_document_viewer.py` still pass (11) — mock change is additive; restored an unrelated screenshot regenerated by the cross-check run
 **Decisions:** chat test uses the phase-119 A1 scripted-read convention (zero-read turns chip nothing — the image doc must be read to earn chip+figure); both E2E apps pin `BOR_IMAGES` explicitly so an operator `.env` can't leak the toggle either direction.
 **Next pending task:** none in `122_image_documents` — phase 122 complete (harness moves task 06 + commits). Next phase: `123_chat_image_submission` (todo).
@@ -0,0 +1,106 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 13%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 21%]
 ........................................................................ [ 23%]
 ........................................................................ [ 26%]
 ........................................................................ [ 29%]
 ........................................................................ [ 31%]
 ........................................................................ [ 34%]
 ........................................................................ [ 37%]
 ........................................................................ [ 39%]
 ........................................................................ [ 42%]
 ........................................................................ [ 45%]
 ........................................................................ [ 47%]
 ........................................................................ [ 50%]
 ........................................................................ [ 53%]
 ........................................................................ [ 55%]
 ........................................................................ [ 58%]
 ........................................................................ [ 60%]
 ........................................................................ [ 63%]
 ........................................................................ [ 66%]
 ........................................................................ [ 68%]
 ........................................................................ [ 71%]
 ........................................................................ [ 74%]
 ........................................................................ [ 76%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 98%]
 ...................................................                      [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  226      1    99%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    247      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       66      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             46      0   100%
 app/schemas.py                   373      0   100%
 --------------------------------------------------
 TOTAL                           4514     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,13 @@
 All gates green. Verification complete.
 **Phase 123 — final verification pass (all 4 tasks already in `complete/`)**
 - Verified the full implementation is in the working tree: `app/api/chat_images.py` (upload/serve pair), `ChatRequest.image`/`ChatMessage.image` (path-validated, omitted-when-None), toggle-off + stale-file hinted error frames, `build_user_content` multimodal build at both sites (chat.py deflected branch + `run_agent`), config-gated composer attach/preview/upload-then-send, restore + shared rendering, CSP `img-src 'self' data:` carve-out, mock-LLM capture buffer.
 - `uv run pytest` → **2796 passed**, exit 0 (unit + integration).
 - `uv run pytest --cov=app --cov-report=term-missing` → **TOTAL 99%** (29/4615 missed; phase-123 modules 99–100%).
 - `uv run pytest tests/e2e/test_chat_image_questions.py -v --no-cov` → **5 passed** in isolation.
 - `uv run ruff check . && uv run pyright` → clean (0 errors).
 **Completion criteria:** (1) attach→send→multimodal text+image to the model, bubble/reload/shared all render it, saved chat stores the PATH with `"base64" not in json.dumps(stored)` — **verified** (E2E tests 1–4 + integration round-trip); (2) `BOR_IMAGES=false` — control hidden, exact hinted error frame, zero model calls / no query_log row — **verified** (E2E test 5 + integration); (3) text-only byte-identical (`content` stays a plain `str`) — **verified** (unit + integration); (4) all gates green — **verified**; (5) commit + phase move — left to the harness per pipeline rules (no `git add`/`commit` run).
 No defects found; no live-infrastructure changes (repo + local dev DB only). **Next pending phase: none** — 123 is the last phase in `todo/`.
@@ -0,0 +1,108 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 12%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 20%]
 ........................................................................ [ 23%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 30%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 66%]
 ........................................................................ [ 69%]
 ........................................................................ [ 72%]
 ........................................................................ [ 74%]
 ........................................................................ [ 77%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ............................................................             [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  248      1    99%
 app/api/chat_images.py            50      0   100%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    255      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       68      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             48      0   100%
 app/schemas.py                   390      0   100%
 --------------------------------------------------
 TOTAL                           4615     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,13 @@
 All gates green. Final report:
 **Phase 123 / Task 01 — Vision request: complete**
 - **Implemented (server side):**
  - `app/config.py` + `.env.example`: `chat_image_dir` (`~/bor-sources/chat-images`) + `chat_image_max_mb` (10, fail-loud `<=0` validator)
  - New `app/api/chat_images.py` (registered in `main.py`): `POST /api/chat-images` (user-gated; phase-122 extension frozenset, streamed cap → 413 fixed detail, uuid-named store, returns `{"path": …}`) + public `GET /api/chat-images/{filename}` (regex guard → one fixed 404, phase-122 mime map, `private, max-age=3600`)
  - `schemas.py`: `ChatRequest.image` (stored-path pattern, fixed 422, no echo) + `ChatMessage.image` (≤500, user record only, omitted-when-None serializer → text-only payloads byte-identical)
  - `app/api/chat.py`: pre-stream gates (toggle-off → hinted phase-114 frame; stale file → same shape, no hint — both before any model call, no record) + `build_user_content` multimodal build at **both** sites; `run_agent` signature widened (`str | list`), flow pinned in docstring; data-URL factored to shared `summarizer.image_data_url`; `HistoryTurn`/history unchanged (A7)
 - **Tests:** new `tests/unit/test_chat_image_questions.py` (52 tests) + 7 new integration tests in `test_chat_api.py` (multimodal delivery both branches, toggle-off/stale no-model-call, text-only byte-identity, saved + shared round-trip with no base64 in stored JSONB)
 - **Results:** `uv run pytest` → green; `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (touched modules 99–100%); `uv run ruff check . && uv run pyright` → clean; existing E2E `test_image_documents.py` (4) + `test_chat_rag.py` (3) → pass
 - **Notable decisions:** upload endpoint is `require_user` (matches the chat turn it feeds; anonymous 10 MB disk-fill DoS); GET public per design (uuid = credential); upload extension set = `settings.image_extension_set` (reuses the phase-122 frozenset, matches the schema's six by default); upload is NOT toggle-gated (the gate is at the chat request, per the pinned design)
 - **Next pending task:** `123_chat_image_questions/02_composer_attach.md` (config-gated attach control, preview, upload-then-send, in-bubble image)
@@ -0,0 +1,108 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 12%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 20%]
 ........................................................................ [ 23%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 31%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 46%]
 ........................................................................ [ 49%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 77%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 85%]
 ........................................................................ [ 88%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 98%]
 ......................................                                   [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  248      1    99%
 app/api/chat_images.py            50      0   100%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    255      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       68      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             48      0   100%
 app/schemas.py                   390      0   100%
 --------------------------------------------------
 TOTAL                           4615     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 Task 02 is complete and fully green. Final report:
 **Implemented (phase 123, task 02 — composer attach):**
 - `frontend/index.html`: paperclip `#attach-btn` (hidden by default, `aria-label`, composer icon style) + hidden `#attach-file` input before the textarea; hidden-by-default `#attach-preview` strip (≤48px thumbnail + filename + `#attach-remove` X) above the input row
 - `frontend/assets/app.js`: attach reveal gated on the boot `/api/config` `images` flag (brand boot's single fetch — no extra round-trip); six-extension client pre-check (bad pick → out-of-turn banner, no state change); preview show/remove/replace; send flow (LOCKED A8) uploads first via `POST /api/chat-images` with a double-fire guard — failure → banner + blocked send with the question kept; `runTurn` gains the attachment: user bubble renders via the new shared `attachBubbleImage` helper (data URL live), record gains `image: <path>` (A5: never base64), request body carries top-level `image` only when attached (text-only byte-identical), strip cleared after the bubble renders, redo stays text-only (A7); `startNewChat` resets the attachment
 - `frontend/assets/styles.css`: `.attach-btn` / `.attach-preview` / `.msg-image` (44px targets, AA pairings, focus-visible, ~240px-capped bubble image)
 - Updated 6 existing source-pinning tests to the new shapes (contracts preserved: save-point-before-fetch, scroll intents, sticky-unit children, action-row gap, turn-local reset order)
 **Gates:**
 - `uv run pytest` → exit 0, all pass
 - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%)
 - `uv run ruff check . && uv run pyright` → clean (0 errors, 0 warnings)
 - Throwaway Playwright smoke: flag on (attach → preview → remove → send: bubble image, path in body + localStorage record, bytes served back, no banner), text-only body omits `image`, flag off (button hidden; image request → exact hinted error frame, no model output) — all verified live
 **Decisions:** preview strip sits above the input (phase design's "strip above the input"); upload double-fire guard added (the upload is now handleSend's first `await` — a double-click could otherwise double-upload/double-turn); frontend test pins are task 04's per the phase split ("tasks ship code; this task ships the full pin").
 **Next pending task:** `03_restore_and_shared.md` (restore + shared-page image render, onerror degradation).
@@ -0,0 +1,108 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 12%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 20%]
 ........................................................................ [ 23%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 31%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 46%]
 ........................................................................ [ 49%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 77%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 85%]
 ........................................................................ [ 88%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 98%]
 ......................................                                   [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  248      1    99%
 app/api/chat_images.py            50      0   100%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    255      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       68      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             48      0   100%
 app/schemas.py                   390      0   100%
 --------------------------------------------------
 TOTAL                           4615     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,17 @@
 All green and verified. Final report:
 **Task 03 — Restore + shared: complete**
 - `app.js` `renderStoredMessage` user branch: `m.image` (stored path) renders through the same `attachBubbleImage` one-renderer (live = data URL, restore = path); alt = `m.text || "attached image"`
 - `app.js` `attachBubbleImage`: `onerror` degrades the img in place to a small "image unavailable" line (deleted out-of-band file — never a broken icon)
 - `shared.js`: `renderSharedMessage` user branch + local `addBubbleImage` copy (per-page duplication house style) — identical treatment, alt, and onerror; public image route makes the shared view faithful
 - `styles.css`: shared page reuses task 02's `.msg-image` as-is (same stylesheet + bubble class, verified); one new rule only for the new "image unavailable" note element
 - Re-ask (`retryLastTurn`): byte-unchanged per the phase-120 lock — A7 (re-ask sends `prev.text` only, no attachment) is pinned by that byte-pin itself
 - Restore filters (localStorage / saved-chat / shared) pass records through untouched — optional `image` key needs no migration
 - Server round-trip verified live: user record with `image` survives POST/PUT `/api/chats` and serves through `GET /api/shared/{token}` (public shape)
 **Gates:** `uv run pytest` → exit 0, all pass · `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%) · `uv run ruff check .` → clean · `uv run pyright` → 0 errors, 0 warnings
 **Deviation note:** an A7 pin-comment in `retryLastTurn` initially broke the phase-120 whole-function byte-pin; removed the comment and kept the function byte-identical (the pin itself proves the no-attachment re-ask).
 **Next pending task:** `.agents/phases/todo/123_chat_image_questions/04_chat_image_tests.md`
@@ -0,0 +1,108 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 12%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 20%]
 ........................................................................ [ 23%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 31%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 44%]
 ........................................................................ [ 46%]
 ........................................................................ [ 49%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 57%]
 ........................................................................ [ 59%]
 ........................................................................ [ 62%]
 ........................................................................ [ 64%]
 ........................................................................ [ 67%]
 ........................................................................ [ 70%]
 ........................................................................ [ 72%]
 ........................................................................ [ 75%]
 ........................................................................ [ 77%]
 ........................................................................ [ 80%]
 ........................................................................ [ 83%]
 ........................................................................ [ 85%]
 ........................................................................ [ 88%]
 ........................................................................ [ 90%]
 ........................................................................ [ 93%]
 ........................................................................ [ 96%]
 ........................................................................ [ 98%]
 ......................................                                   [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  248      1    99%
 app/api/chat_images.py            50      0   100%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    255      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       68      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             48      0   100%
 app/schemas.py                   390      0   100%
 --------------------------------------------------
 TOTAL                           4615     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -0,0 +1,15 @@
 All gates green. Final report:
 **Phase 123 task 04 — complete.**
 **Implemented (test suite for question-images):**
 - `tests/unit/test_chat_image_questions.py` (extended): config env overrides, data-URL-helper import-not-copy identity pin, all-six-extension upload acceptance, +12 frontend source pins (hidden-by-default markup, config-gated reveal, A8 upload-before-send ordering/block-on-failure, user record carries path never base64, A7 no-history-replay + text-only redo, one bubble-image renderer + onerror degradation on both pages, single `.msg-image` CSS rule)
 - `tests/integration/test_chats_api.py` (extended): saved + shared round-trips of the user image path, no base64 in raw JSONB, brain/text-only records stay key-free (task 04's `test_chat_api.py` cases were already shipped by task 01 — verified green)
 - `tests/e2e/test_chat_image_questions.py` (new, isolated): preview+remove, send→exactly-one upload + live data-URL bubble + mock capture asserts the exact multimodal request (text + decodable data URL), reload restores from stored path (path-fetch counted), fresh anonymous context sees the image on the shared page, flag-off app: control hidden + exact hinted error frame + zero model calls; `tests/e2e/mock_llm.py` gained an additive observational capture (`/v1/e2e/captured` + reset)
 - **Defect fix (task 02 work):** task-02's data-URL images (preview + live bubble) were blocked by the phase-82 CSP (`default-src 'self'`, no img-src) — the new E2E caught it (bubble degraded to "image unavailable"). Minimal fix: `img-src 'self' data:` appended to the CSP constant (scripts/styles/fetches stay strict; bytes are the user's own local file). Updated the three security-header test pins. **Flagged, not silent: this extends the A20-derived policy string per the owner-confirmed phase-123 data-URL rendering contract.**
 **Gates:** `uv run pytest` → 2796 passed · `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90%) · `uv run pytest tests/e2e/test_chat_image_questions.py --no-cov` → 5 passed in isolation · `uv run ruff check .` clean · `uv run pyright` → 0 errors. CSP-impact checks: e2e security-headers (2) + theme-semantic (8) pass. No live-infra changes.
 **Notable:** E2E runs against an unseeded KB (deterministic deflection); the sync-API request-event pitfall (polls must tick via Playwright calls, not `time.sleep`) is pinned with a comment.
 **Next pending task:** none — task 04 is the last of phase 123; the phase dir is ready for the pipeline gate.
@@ -0,0 +1,108 @@
 ........................................................................ [  2%]
 ........................................................................ [  5%]
 ........................................................................ [  7%]
 ........................................................................ [ 10%]
 ........................................................................ [ 12%]
 ........................................................................ [ 15%]
 ........................................................................ [ 18%]
 ........................................................................ [ 20%]
 ........................................................................ [ 23%]
 ........................................................................ [ 25%]
 ........................................................................ [ 28%]
 ........................................................................ [ 30%]
 ........................................................................ [ 33%]
 ........................................................................ [ 36%]
 ........................................................................ [ 38%]
 ........................................................................ [ 41%]
 ........................................................................ [ 43%]
 ........................................................................ [ 46%]
 ........................................................................ [ 48%]
 ........................................................................ [ 51%]
 ........................................................................ [ 54%]
 ........................................................................ [ 56%]
 ........................................................................ [ 59%]
 ........................................................................ [ 61%]
 ........................................................................ [ 64%]
 ........................................................................ [ 66%]
 ........................................................................ [ 69%]
 ........................................................................ [ 72%]
 ........................................................................ [ 74%]
 ........................................................................ [ 77%]
 ........................................................................ [ 79%]
 ........................................................................ [ 82%]
 ........................................................................ [ 84%]
 ........................................................................ [ 87%]
 ........................................................................ [ 90%]
 ........................................................................ [ 92%]
 ........................................................................ [ 95%]
 ........................................................................ [ 97%]
 ............................................................             [100%]
 =============================== warnings summary ===============================
 .venv/lib/python3.13/site-packages/fastapi/testclient.py:1
  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
    from starlette.testclient import TestClient as TestClient  # noqa
 -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
 ================================ tests coverage ================================
 _______________ coverage: platform linux, python 3.13.13-final-0 _______________
 Name                           Stmts   Miss  Cover
 --------------------------------------------------
 app/__init__.py                    1      0   100%
 app/api/__init__.py                0      0   100%
 app/api/auth.py                   52      0   100%
 app/api/chat.py                  248      1    99%
 app/api/chat_images.py            50      0   100%
 app/api/chats.py                 110      0   100%
 app/api/config.py                 13      0   100%
 app/api/doc_drafts.py             99      0   100%
 app/api/docs.py                  179      1    99%
 app/api/git_sources.py           241      0   100%
 app/api/health.py                 10      0   100%
 app/api/steering.py               42      0   100%
 app/api/suggestions.py            33      0   100%
 app/api/sync.py                  139      0   100%
 app/api/tokens.py                 40      0   100%
 app/api/ui_settings.py            55      0   100%
 app/config.py                    255      0   100%
 app/core/__init__.py               0      0   100%
 app/core/auth.py                  45      0   100%
 app/core/caching.py              124      0   100%
 app/core/debugging.py             29      2    93%
 app/core/docs_push.py             39      0   100%
 app/core/errors.py                 5      0   100%
 app/core/logging.py               13      0   100%
 app/core/rate_limit.py            44      0   100%
 app/core/security_headers.py      20      0   100%
 app/core/theming.py               38      0   100%
 app/core/tokens.py                44      0   100%
 app/db.py                         22      0   100%
 app/main.py                       68      0   100%
 app/models.py                    131      0   100%
 app/rag/__init__.py                0      0   100%
 app/rag/agent.py                 349      1    99%
 app/rag/archive_upload.py        134      0   100%
 app/rag/chunker.py               206      4    98%
 app/rag/doc_dates.py              18      0   100%
 app/rag/folder_summaries.py      123      0   100%
 app/rag/git_sources.py            38      0   100%
 app/rag/importer.py              316     16    95%
 app/rag/llm.py                   244      1    99%
 app/rag/overview.py               71      0   100%
 app/rag/prompts.py               102      0   100%
 app/rag/retriever.py             248      3    99%
 app/rag/scaffolding.py            55      0   100%
 app/rag/source_removal.py         41      0   100%
 app/rag/sources_meta.py           16      0   100%
 app/rag/suggestions.py            27      0   100%
 app/rag/summarizer.py             48      0   100%
 app/schemas.py                   390      0   100%
 --------------------------------------------------
 TOTAL                           4615     29    99%
 coverage gate: app/ 99% (>90%) OK
 All checks passed!
 0 errors, 0 warnings, 0 informations
 WARNING: there is a new pyright version available (v1.1.411 -> v1.1.414).
 Please install the new version or set PYRIGHT_PYTHON_FORCE_VERSION to `latest`
 validation OK
@@ -112,6 +112,29 @@ BOR_IMPORT_EXTENSIONS=md,markdown,txt,yaml,yml,json,py,container,network,volume,
 # BOR_UPLOAD_MAX_MB=512   # caps BOTH the compressed upload and the total
                          # extracted bytes (zip-bomb guard); must be > 0
 # --- Image documents (phase 122) ---
 # Master switch for indexing standalone image files (direct uploads,
 # uploaded archives, git/local source walks) as first-class documents.
 # OFF by default — enable only when BOR_LLM_CHAT_MODEL supports vision:
 # the chat model generates the image's description, and that
 # description is the ONLY part of the image that gets indexed (the
 # embedding model never sees pixels). While off, image files are
 # ignored by the import walks and a sync never prunes existing image
 # documents.
 # BOR_IMAGES=0                        # 1 = index standalone images
 # BOR_IMAGE_EXTENSIONS=png,jpg,jpeg,webp,gif,bmp  # comma-separated, case-insensitive
 # BOR_IMAGE_DIR=~/bor-sources/images  # persistent home for the served image bytes
                                      # (uploads are replaced, checkouts re-cloned)
 # --- Chat image questions (phase 123: attach an image to a question) ---
 # Gated by the SAME BOR_IMAGES toggle above (enable only when the chat
 # model supports vision). The question image is stored on the server —
 # never base64 in saved/shared chats; the record carries the path.
 # One image per question; prior turns' images are not replayed to the
 # model (the question's image applies to the current turn only).
 # BOR_CHAT_IMAGE_DIR=~/bor-sources/chat-images  # where question images are stored
 # BOR_CHAT_IMAGE_MAX_MB=10                      # upload cap, MiB (must be > 0)
 # --- Docs push (phase 59: save a chat answer as documentation) ---
 # The git repo chat answers can be committed to — any remote (URL or
 # local path). While empty, the "Save as doc" action is hidden and the
@@ -0,0 +1,47 @@
 """git_sources.token: private-repo credential column (phase 121)
 Revision ID: 0021
 Revises: 0020
 Create Date: 2026-09-24
 Phase 121 (private git sources: a token that never reaches the UI or
 the API — task 01, storage only):
 * ``git_sources.token`` — TEXT NULLABLE, no server default: the private
  repo credential (LOCKED A2) the owner types into the masked
  Sources-page field. NULL = public repo (or a legacy row whose
  credential is still embedded in ``url`` — those rows keep their
  stored value, which is what authenticates the clone, and are
  sanitized on OUTPUT only, task 02). Stored plaintext BY NECESSITY:
  the repo must remain cloneable, so the raw credential must be
  recoverable at sync time; the Postgres DB is the trusted store and is
  never served to the UI. The column is injected into the clone URL
  ONLY at clone time (task 02's ``clone_url_for``) and is NEVER
  returned by any API shape (the output models gain no token field —
  the omission is a documented contract).
 One additive, fully reversible migration (A13); no other schema
 change. Normalization of embedded-token URLs on write and output
 sanitization are code (tasks 02/03) — this revision only carries the
 column.
 """
 from __future__ import annotations
 import sqlalchemy as sa
 from alembic import op
 revision = "0021"
 down_revision = "0020"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    op.add_column("git_sources", sa.Column("token", sa.Text(), nullable=True))
 def downgrade() -> None:
    # The token column is the only 0021 artefact — dropping it leaves
    # 0020's schema byte-identical (A13, fully reversible).
    op.drop_column("git_sources", "token")
@@ -0,0 +1,54 @@
 """documents image columns: is_image + image_path (phase 122, task 02)
 Revision ID: 0022
 Revises: 0021
 Create Date: 2026-09-24
 Phase 122 (standalone images become first-class documents — task 02,
 storage only):
 * ``documents.is_image`` — BOOLEAN NOT NULL, server default
  ``false``: True iff the doc is a standalone image (LOCKED A3) whose
  ``content``/``summary`` is the CHAT model's vision description — the
  ONLY embedded text (the embedding model never sees pixels). The
  server default makes EVERY pre-phase-122 row a text doc without a
  backfill.
 * ``documents.image_path`` — TEXT NULLABLE: the absolute path of the
  image's persistent copy in ``settings.image_dir`` (``<doc-id>.<ext>``
  — the copy must outlive the source file: uploads are replaced on
  every upload, git checkouts are re-cloned). NULL for text docs.
 One additive, fully reversible migration (A13); no other schema
 change. The walk filter, the binary index path, and the prune guard
 are importer code (task 02) — this revision only carries the columns.
 """
 from __future__ import annotations
 import sqlalchemy as sa
 from alembic import op
 revision = "0022"
 down_revision = "0021"
 branch_labels = None
 depends_on = None
 def upgrade() -> None:
    op.add_column(
        "documents",
        sa.Column(
            "is_image",
            sa.Boolean(),
            server_default=sa.text("false"),
            nullable=False,
        ),
    )
    op.add_column("documents", sa.Column("image_path", sa.Text(), nullable=True))
 def downgrade() -> None:
    # Both columns are the only 0022 artefacts — dropping them leaves
    # 0021's schema byte-identical (A13, fully reversible).
    op.drop_column("documents", "image_path")
    op.drop_column("documents", "is_image")
@@ -179,6 +179,27 @@ as ``reasoning_content`` on the assistant message (the preserve-
 thinking wire convention, A4). The per-turn log line records
 ``history_msgs=N`` after ``kb_chars=N`` (0 when the request carries no
 history — the two-message request stays byte-identical).
 Question images (phase 123, TODO L6; LOCKED A5/A7): the request may
 attach ONE image to the CURRENT question — ``ChatRequest.image`` is the
 STORED path from ``POST /api/chat-images`` (``app.api.chat_images``),
 never a data URL. The turn validates it BEFORE any model call (the
 toggle gate — ``settings.images`` false settles the phase-114 hinted
 error frame; the stale-file gate — the stored bytes deleted out-of-
 band settles the same frame shape) and, when valid, the user message's
 content becomes the multimodal list ``[{type: "text", …}, {type:
 "image_url", image_url: {url: <data URL>}}]`` — built by
 :func:`build_user_content` at BOTH construction sites (this module's
 deflected-branch ``messages`` list and the grounded branch's
 ``run_agent`` call, which builds its own ``[system, *history, user]``
 — the flow is pinned in ``app.rag.agent.run_agent``). The data URL is
 the shared :func:`app.rag.summarizer.image_data_url` (one
 construction, both call sites — the phase-122 describe path).
 ``image=None`` keeps the plain-string content byte-identical to
 pre-phase. A question image is turn-local: it is NEVER indexed as a
 document, and prior turns' images are never replayed into the model's
 history (``history_to_messages`` is unchanged — the text of a prior
 turn that had an image stands alone, LOCKED A7).
 """
 from __future__ import annotations
@@ -188,6 +209,7 @@ import logging
 import time
 from collections.abc import AsyncIterator, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 from fastapi import APIRouter, Depends
@@ -224,10 +246,16 @@ from app.rag.retriever import (
    retrieve,
    select_related,
    select_suggested,
    source_ref_with_image,
    weak_hit_titles,
 )
 from app.rag.scaffolding import ScaffoldingFilter  # phase 71: the streaming filter
 from app.rag.suggestions import derive_suggestions
 from app.rag.summarizer import (
    IMAGE_FALLBACK_MIME,
    IMAGE_MIMES,
    image_data_url,
 )  # phase 123: the phase-122 mime map + the shared data-URL helper
 from app.schemas import (
    ChatDoneEvent,
    ChatErrorEvent,
@@ -280,6 +308,37 @@ def sse_event(payload: dict[str, Any]) -> str:
    return f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"
 def build_user_content(
    message: str,
    image_path: str | None,
    settings: Settings,
 ) -> str | list[dict[str, Any]]:
    """The current turn's user message content (phase 123, task 01).
    *image_path* ``None`` (every text-only question) → the plain
    question string — byte-identical to pre-phase-123 (the multimodal
    branch is inert). Set → the OpenAI-compatible multimodal content
    list: the text part + the image part, a data URL built server-side
    from the stored bytes (``settings.chat_image_dir`` + the path's
    filename) and the phase-122 ``IMAGE_MIMES`` map (one map, one
    truth) through the shared :func:`app.rag.summarizer.image_data_url`
    helper (one construction, both call sites — the phase-122 describe
    path). The caller has already validated the path shape (the
    ``ChatRequest.image`` schema guard) and the file's existence (the
    pre-stream turn gate). The image applies to the CURRENT turn only
    (LOCKED A7) — prior turns' images are never replayed.
    """
    if image_path is None:
        return message
    filename = image_path.rsplit("/", 1)[-1]
    data = (Path(settings.chat_image_dir).expanduser() / filename).read_bytes()
    mime = IMAGE_MIMES.get(Path(filename).suffix.lower(), IMAGE_FALLBACK_MIME)
    return [
        {"type": "text", "text": message},
        {"type": "image_url", "image_url": {"url": image_data_url(data, mime)}},
    ]
@dataclass
 class TurnPlan:
    """What one chat turn sends to the LLM and reports on ``done``."""
@@ -493,6 +552,59 @@ async def chat(
            retries_used = 0  # phase 67: LLM requests restarted this turn (log line)
            try:
                settings = get_settings()
                # Phase 123 (TODO L6, task 01): the question's attached
                # image — validated BEFORE any model call (the embed is
                # a model call): a rejected turn calls nothing and
                # settles with the phase-114 error frame (the existing
                # error-path convention — no ``done``, no ``query_log``
                # row, no persisted record; the question is not saved).
                # Two gates, in order:
                #   1. the ``images`` toggle (``BOR_IMAGES``) — off with
                #      an image set: the HINTED frame (the client's
                #      banner shows the hint in place of its default
                #      reachability copy, phase 114);
                #   2. the stored file — the schema already pinned the
                #      path shape, but the file may have been deleted
                #      out-of-band (the stale-path edge): the same frame
                #      shape, no hint (the banner's default copy is the
                #      honest fallback — there is nothing to point at).
                if request.image is not None:
                    if not settings.images:
                        logger.warning(
                            "chat: image question rejected (images toggle "
                            "off) question=%r image=%r",
                            request.message,
                            request.image,
                        )
                        settled = True  # terminal: the error frame settles the turn
                        yield sse_event(
                            ChatErrorEvent(
                                detail="Image support is turned off on this server.",
                                hint=(
                                    "Enable BOR_IMAGES in the server's .env "
                                    "(and restart) to ask with an image."
                                ),
                            ).model_dump()
                        )
                        return
                    image_file = (
                        Path(settings.chat_image_dir).expanduser()
                        / request.image.rsplit("/", 1)[-1]
                    )
                    if not image_file.is_file():
                        logger.warning(
                            "chat: image question rejected (stored file "
                            "missing) question=%r image=%r",
                            request.message,
                            request.image,
                        )
                        settled = True  # terminal: the error frame settles the turn
                        yield sse_event(
                            ChatErrorEvent(
                                detail="That image is no longer available."
                            ).model_dump()
                        )
                        return
                # Phase 74 (TODO L4): the client's prior turns, mapped ONCE
                # per turn — trimmed newest-first against the settings
                # budgets, assistant turns carrying their prior thinking as
@@ -639,10 +751,21 @@ async def chat(
                        ).model_dump()
                    )
                    return
                # Phase 123 (task 01): the user message's content — the
                # plain question string (``image=None`` — byte-identical
                # to pre-phase) or the multimodal content list (text
                # part + image_url data URL; the image was validated
                # above). BOTH construction sites use the same build:
                # this deflected-branch list and the grounded branch's
                # ``run_agent`` call below (run_agent builds its own
                # ``[system, *history, user]`` — pinned there).
                user_content: str | list[dict[str, Any]] = build_user_content(
                    request.message, request.image, settings
                )
                messages: list[dict[str, Any]] = [
                    {"role": "system", "content": plan.system_prompt},
                    *hist,  # phase 74: the trimmed prior turns (empty by default)
-                    {"role": "user", "content": request.message},
+                    {"role": "user", "content": user_content},
                ]
                # 3. Stream the answer (grounded, or an honest deflection).
@@ -688,7 +811,11 @@ async def chat(
                        llm,
                        db_factory,  # SEC-14-04: session factory, not a long-lived session
                        system_prompt=plan.system_prompt,
-                        user_message=request.message,
+                        # Phase 123 (task 01): the plain question string
                        # (image=None) or the multimodal content list
                        # (validated above) — run_agent builds its own
                        # user message from this value (see its docstring).
                        user_message=user_content,
                        seed_docs=plan.suggested_docs,  # phase 118 (A4): the suggestion tier
                        settings=settings,
                        holder=holder,
@@ -984,14 +1111,16 @@ async def chat(
                # since phase 119). The UI renders the row as the
                # de-emphasized related-docs row, never a citation chip;
                # old clients ignore the field.
                # Phase 122 (task 05): both tiers build their refs
                # through the shared helper — a ref for an image doc
                # carries the optional ``image_url`` (the bytes route),
                # a text doc's stays byte-identical to pre-phase (the
                # key is omitted, never null).
                cited_refs: list[SourceRef] = []
                if not plan.deflected:
-                    cited_refs = [
+                    cited_refs = [source_ref_with_image(d) for d in cited_docs]
                        SourceRef(source=d.source, path=d.path, title=d.title)
                        for d in cited_docs
                    ]
                related_refs = [
-                    SourceRef(source=d.source, path=d.path, title=d.title)
+                    source_ref_with_image(d)
                    for d in plan.related_docs
                    if (d.source, d.path) not in cited_seen
                ]
@@ -0,0 +1,158 @@
 """Question-image upload/serve pair (phase 123, TODO L6 — attach an
 image to a question).
 A user attaches ONE image to a chat question (LOCKED A5): the bytes are
 stored server-side under ``chat_image_dir/<uuid4().hex>.<ext>`` — NOT
 base64 in saved/shared chats. ``POST /api/chat-images`` answers
 ``{"path": "/api/chat-images/<uuid>.<ext>"}`` and that path is what
 ``ChatRequest.image`` / ``ChatMessage.image`` carry (a stored PATH,
 never a data URL — the upload endpoint owns the size/mime
 enforcement). ``GET /api/chat-images/{filename}`` serves the bytes back
 so the user bubble, the refreshed page, and the shared chat can render
 the attachment. A question image is NEVER indexed as a document (no
 importer call) — it is turn-local storage, not a source.
 Auth posture: the upload is user-gated exactly like the chat turn it
 feeds (``require_user`` — the question itself is user-gated, and an
 anonymous 10 MiB disk-fill would be a DoS); the serve route is PUBLIC
 like saved-chat content (phase 55 A1 — a saved chat's id is already its
 credential, and the image is part of that content; the filename is an
 unguessable ``uuid4().hex`` — no enumeration value).
 The extension is the source of truth (the Content-Type header is a
 hint — the archive-uploader precedent): it must be in the phase-122
 image set (``settings.image_extension_set`` — the same frozenset the
 image-document walk uses), lowercased; total bytes are streamed with a
 ``chat_image_max_mb`` cap (413, fixed detail naming the cap — never
 echoing the filename).
 """
 from __future__ import annotations
 import logging
 import re
 import uuid
 from pathlib import Path
 from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
 from fastapi.responses import FileResponse
 from app.config import get_settings
 from app.core.auth import require_user
 from app.rag.summarizer import IMAGE_FALLBACK_MIME, IMAGE_MIMES
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["chat-images"])
 #: Stream receive chunk (the git-sources upload's 1 MiB pattern).
 _STREAM_CHUNK = 1 << 20
 #: Stored question-image filename guard: ``<uuid4().hex>.<ext>`` — 32
 #: hex chars + one of the six image extensions (the ``ChatRequest.image``
 #: path pattern's filename part, kept in lockstep with it). Anything
 #: else 404s — no path traversal by construction (the route parameter
 #: cannot carry a ``/`` and the regex rejects everything but the
 #: upload endpoint's own naming).
 _CHAT_IMAGE_FILENAME_RE = re.compile(r"^[0-9a-fA-F]{32}\.(png|jpe?g|webp|gif|bmp)$")
@router.post("/chat-images")
 async def upload_chat_image(
    file: UploadFile = File(...),  # noqa: B008
    _user: None = Depends(require_user),  # noqa: B008
 ) -> dict[str, str]:
    """Store one question image (phase 123, task 01; LOCKED A5).
    Gates, in order:
    1. **extension** — the file name's extension (lowercased) must be in
       the phase-122 image set (``settings.image_extension_set``); the
       Content-Type header is a hint, never a source of truth (the
       archive-uploader precedent). A missing/unknown extension is a
       422 naming the accepted set — a fixed detail, no filename echo.
    2. **size** — the bytes are streamed (1 MiB chunks) with the
       ``chat_image_max_mb`` cap; over-cap is a 413 naming the cap
       (fixed detail — never echoing the filename), the temp file is
       removed, and nothing is stored.
    The file lands as ``<uuid4().hex>.<ext>`` in ``chat_image_dir``
    (created on demand; a dotfile temp is renamed into place, so a
    failed/partial receive never leaves a servable-looking file). The
    response is the served path — ``{"path":
    "/api/chat-images/<uuid>.<ext>"}`` — the value ``ChatRequest.image``
    accepts (never a data URL, never the on-disk location).
    """
    settings = get_settings()
    filename = file.filename or ""
    ext = Path(filename).suffix.lower()
    if ext not in settings.image_extension_set:
        accepted = ", ".join(sorted(settings.image_extension_set))
        raise HTTPException(
            status_code=422, detail=f"only {accepted} images are accepted"
        )
    root = Path(settings.chat_image_dir).expanduser()
    root.mkdir(parents=True, exist_ok=True)
    name = f"{uuid.uuid4().hex}{ext}"
    temp = root / f".{name}.upload"
    max_bytes = settings.chat_image_max_mb * 1024 * 1024
    total = 0
    try:
        # Stream with the cap — the dotfile temp is hidden from any
        # listing of the store dir (the git-sources upload pattern).
        with open(temp, "wb") as out:
            while chunk := await file.read(_STREAM_CHUNK):
                total += len(chunk)
                if total > max_bytes:
                    raise HTTPException(
                        status_code=413,
                        detail=(
                            f"the image exceeds the "
                            f"{settings.chat_image_max_mb} MB limit"
                        ),
                    )
                out.write(chunk)
        temp.rename(root / name)
    except BaseException:
        # A failed receive (413, broken pipe, cancellation) leaves no
        # file behind — the final name was never created.
        temp.unlink(missing_ok=True)
        raise
    logger.info(
        "chat-image: uploaded name=%s bytes=%d", name, total
    )
    return {"path": f"/api/chat-images/{name}"}
@router.get("/chat-images/{filename}", response_class=FileResponse)
 def serve_chat_image(filename: str) -> FileResponse:
    """Serve one stored question image (phase 123, task 01).
    PUBLIC (no auth dependency) — like saved-chat content: the saved
    chat's id is already its credential (phase 55 A1), the image is part
    of that content, and the filename is an unguessable ``uuid4().hex``
    (no enumeration value).
    Every non-servable case is a 404 with the same fixed detail — a
    filename that does not match ``<uuid-hex>.<ext>`` (the regex guard:
    no path traversal by construction, no 422 that would hint at
    accepted shapes) and a matching name whose file is missing (the
    stale-path edge — the file was deleted out-of-band). Servable files
    stream the exact bytes with the phase-122 ``IMAGE_MIMES``
    ``Content-Type`` (one map, one truth with the describe call's
    data-URL mime; the six-extension guard makes the fallback
    unreachable) and ``Cache-Control: private, max-age=3600`` (the
    phase-122 serve-route convention — the bytes are content-hashed
    uuids, bustable by re-upload).
    """
    if _CHAT_IMAGE_FILENAME_RE.fullmatch(filename) is None:
        raise HTTPException(status_code=404, detail="chat image not found")
    path = Path(get_settings().chat_image_dir).expanduser() / filename
    if not path.is_file():
        raise HTTPException(status_code=404, detail="chat image not found")
    media_type = IMAGE_MIMES.get(path.suffix.lower(), IMAGE_FALLBACK_MIME)
    return FileResponse(
        path,
        media_type=media_type,
        headers={"Cache-Control": "private, max-age=3600"},
    )
@@ -1,6 +1,7 @@
 """Public app metadata (display name + version) for the frontend brand
-layer, the phase-59 docs-push flag (the "Save as doc" gating), and the
+layer, the phase-59 docs-push flag (the "Save as doc" gating), the
-phase-62 UI customization strings (composer placeholder, footer line).
+phase-122 image flag (UI affordance gating), and the phase-62 UI
 customization strings (composer placeholder, footer line).
 Phase 91 (task 01): the three UI strings are now the EFFECTIVE values —
 the ``ui_settings`` row (admin Theme tab) over the env values (B1: DB
@@ -29,17 +30,21 @@ router = APIRouter(tags=["config"])
@router.get("/config")
 def app_config(settings: Settings = Depends(get_settings)) -> dict[str, str | bool]:  # noqa: B008
    """Public app metadata for the frontend brand layer (phase 39) +
-    the phase-59 ``docs_repo_configured`` flag + the phase-62 UI
+    the phase-59 ``docs_repo_configured`` flag + the phase-122
-    customization keys (``input_placeholder``, ``footer_text``) — all
+    ``images`` flag + the phase-62 UI customization keys
-    display strings, the SAME boot fetch (no new network surface) and
+    (``input_placeholder``, ``footer_text``) — all display strings,
-    the same public posture as ``app_name`` (no secrets). Phase 91:
+    the SAME boot fetch (no new network surface) and the same public
    posture as ``app_name`` (no secrets). Phase 91:
    ``app_name`` / ``input_placeholder`` / ``footer_text`` are the
    EFFECTIVE values (the admin Theme tab's ``ui_settings`` row over
    the env values — DB-over-env, B1); the frontend brand layer treats
    an empty string as "keep the template default" (the unset =>
    byte-identical contract). Phase 91 (task 03): the retired
-    CSS-file theming's ``theme`` key is gone — the five keys are the
+    CSS-file theming's ``theme`` key is gone. Phase 122 (task 01):
-    entire response."""
+    ``images`` mirrors ``settings.images`` (the ``BOR_IMAGES`` master
    switch) — consumed by the chat composer (phase 123) to show/hide
    the image-attach control, optionally by the Sources page (an
    "images off" hint). The six keys are the entire response."""
    db = SessionLocal()
    try:
        effective = theming.effective_settings(db, settings)
@@ -49,6 +54,7 @@ def app_config(settings: Settings = Depends(get_settings)) -> dict[str, str | bo
        "app_name": effective["app_name"],
        "version": settings.app_version,
        "docs_repo_configured": settings.docs_configured,
        "images": settings.images,
        "input_placeholder": effective["input_placeholder"],
        "footer_text": effective["footer_text"],
    }
@@ -23,6 +23,18 @@ GET /api/docs/tree — the admin's full recursive KB tree in one fetch
 walks, with the file metadata the RAG view's rows and stat cards need
 (the view drills client-side; ``GET /api/docs`` is untouched).
 GET /api/documents/{doc_id}/image — the phase-122 (task 04) image
 BYTES route: the persistent copy behind an ``is_image`` document's
 ``image_path``, served with the extension's ``Content-Type`` (the
 ``app.rag.summarizer.IMAGE_MIMES`` map — one map, one truth) and a
 ``Cache-Control: private, max-age=3600`` header (the bytes are
 content-hashed — long enough, bustable by re-upload). User-gated like
 the content endpoint (phase 79 — the ONLY anonymous surface is the
 shared chats): a missing doc, a non-image doc, a doc whose
 ``image_path`` is NULL, or a row whose copy was lost all map to 404
 ``document not found`` (the router's unknown-document shape —
 traversal/UUID-guessing has no filesystem surface to hit).
 PATCH /api/folders/summary — the admin folder-description editor
 (phase 97, task 03): update / create / clear a stored
 ``folder_summaries`` row, marking every non-empty save
@@ -34,11 +46,13 @@ contrast with the phase-57 ``is_summary`` re-embed above.
 """
 from __future__ import annotations
 import uuid
 from collections.abc import Mapping, Sequence
 from datetime import UTC, datetime
 from pathlib import Path
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import FileResponse
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
@@ -52,6 +66,7 @@ from app.rag.doc_dates import normalize_doc_date
 from app.rag.folder_summaries import MIN_DOCS_PER_FOLDER, folder_of
 from app.rag.importer import match_extension
 from app.rag.llm import EmbeddingError, LLMClient
 from app.rag.summarizer import IMAGE_FALLBACK_MIME, IMAGE_MIMES
 from app.schemas import (
    DateResult,
    DateUpdate,
@@ -171,6 +186,11 @@ def get_document_content(
    if row is None:
        raise HTTPException(status_code=404, detail="document not found")
    doc, chunks = row
    # Phase 122 (task 04): the image affordance — ``is_image`` is ALWAYS
    # present on the wire (text docs: false — the one new key); for an
    # image doc, ``image_url`` is the bytes route's path (absent for
    # text docs, and for an image row whose copy path is NULL — never
    # null, the ``DocContent`` omission rule).
    return DocContent(
        source=doc.source,
        path=doc.path,
@@ -181,6 +201,62 @@ def get_document_content(
        content=doc.content,
        indexed_at=doc.indexed_at.isoformat(),
        chunks=chunks,
        is_image=doc.is_image,
        image_url=(
            f"/api/documents/{doc.id}/image" if doc.is_image and doc.image_path else None
        ),
    )
@router.get("/documents/{doc_id}/image", response_class=FileResponse)
 def get_document_image(
    doc_id: str,
    db: Session = Depends(get_db),  # noqa: B008
    _user: None = Depends(require_user),  # noqa: B008  # phase 79 posture (see docstring)
 ) -> FileResponse:
    """The phase-122 (task 04) image BYTES route — the persistent copy
    behind an ``is_image`` document's ``image_path``.
    Same auth posture as the document content endpoint (phase 79 —
    ``require_user``: admin OR live token holder; the ONLY anonymous
    surface is the shared chats — the image is part of a document's
    content, so it travels under the same gate): anonymous callers get
    401 ``authentication required`` before any row is read.
    404 ``document not found`` (the router's unknown-document shape) in
    every non-servable case — a missing id (an unparseable string maps
    here too, not to a 422 — a guessed id is an unknown document), a
    text doc, an image doc whose ``image_path`` is NULL, or a row whose
    copy was lost on disk (defensive — the row exists, the bytes
    don't). There is no path parameter to a filesystem value: the path
    comes from the ROW (the importer's ``image_dir`` copy), so there is
    no traversal surface.
    Servable rows stream the exact bytes with the extension's
    ``Content-Type`` (the ``IMAGE_MIMES`` map — one map, one truth with
    the describe call's data-URL mime; an unexpected extension takes
    ``application/octet-stream``) and ``Cache-Control: private,
    max-age=3600`` (the bytes are content-hashed — long enough to be
    useful, bustable by re-upload).
    """
    try:
        uid = uuid.UUID(doc_id)
    except ValueError:
        raise HTTPException(status_code=404, detail="document not found") from None
    doc = db.scalar(select(Document).where(Document.id == uid))
    if doc is None or not doc.is_image or not doc.image_path:
        raise HTTPException(status_code=404, detail="document not found")
    image_file = Path(doc.image_path)
    if not image_file.is_file():
        # Defensive: the row exists but the copy was lost (the owner
        # cleaned the image dir, the disk was wiped) — the viewer's
        # onerror fallback renders the "image unavailable" note.
        raise HTTPException(status_code=404, detail="document not found")
    media_type = IMAGE_MIMES.get(image_file.suffix.lower(), IMAGE_FALLBACK_MIME)
    return FileResponse(
        image_file,
        media_type=media_type,
        headers={"Cache-Control": "private, max-age=3600"},
    )
@@ -446,6 +522,13 @@ def _folder_counts(
    return folders, counts
 #: One image-docs map value (phase 122, task 04):
 #: ``(doc_id, summary)`` — the id the bytes route's URL is built from
 #: and the summary the RAG view's thumbnail uses as ``alt`` (the vision
 #: description; ``None`` = the fail-soft backfill corner).
 ImageDocInfo = tuple[str, str]
 def _level_children(
    source: str,
    folder: str,
@@ -453,6 +536,7 @@ def _level_children(
    counts: dict[str, int],
    rows: Sequence[TreeFileRow],
    summaries: Mapping[tuple[str, str], str],
    images: Mapping[tuple[str, str], ImageDocInfo] | None = None,
 ) -> list[KbTreeFolder | KbTreeFile]:
    """One level's children (pure): subfolders in path order, then the
    direct files in input (catalog) order.
@@ -477,10 +561,19 @@ def _level_children(
    = the subtree's MAX document ``created_at``: the max over this
    folder's direct files' dates and its subfolder children's (already
    recursive) ``updated_at`` values, via :func:`_subtree_max`.
    Since phase 122 (task 04), a file node whose ``(source, path)`` is
    in *images* carries the thumbnail affordance (``is_image`` +
    ``image_url`` built from the mapped doc id + the mapped ``summary``
    — see :class:`app.schemas.KbTreeFile`); every other file node is
    the pre-phase shape (the omission rule keeps its wire shape
    byte-identical).
    """
    children: list[KbTreeFolder | KbTreeFile] = []
    for sub in sorted(g for g in folders if folder_of(g) == folder):
-        sub_children = _level_children(source, sub, folders, counts, rows, summaries)
+        sub_children = _level_children(
            source, sub, folders, counts, rows, summaries, images
        )
        children.append(
            KbTreeFolder(
                path=sub,
@@ -494,15 +587,34 @@ def _level_children(
        )
    for path, title, chunks, indexed_at, created_at in rows:
        if folder_of(path) == folder:
-            children.append(
+            image_info = images.get((source, path)) if images else None
-                KbTreeFile(
+            if image_info is not None:
-                    path=path,
+                # Phase 122 (task 04): the image-docs node — the RAG
-                    title=title,
+                # view's Path cell renders the 48px thumbnail from the
-                    chunks=chunks,
+                # bytes route's URL with ``alt = summary``.
-                    created_at=created_at,
+                doc_id, doc_summary = image_info
-                    indexed_at=indexed_at,
+                children.append(
                    KbTreeFile(
                        path=path,
                        title=title,
                        chunks=chunks,
                        created_at=created_at,
                        indexed_at=indexed_at,
                        is_image=True,
                        image_url=f"/api/documents/{doc_id}/image",
                        summary=doc_summary,
                    )
                )
            else:
                children.append(
                    KbTreeFile(
                        path=path,
                        title=title,
                        chunks=chunks,
                        created_at=created_at,
                        indexed_at=indexed_at,
                    )
                )
            )
    return children
@@ -530,6 +642,7 @@ def build_kb_tree(
    names: Sequence[str],
    doc_rows: Sequence[TreeDocRow],
    summaries: Mapping[tuple[str, str], str],
    images: Mapping[tuple[str, str], ImageDocInfo] | None = None,
 ) -> list[KbTreeSource]:
    """The pure tree builder behind ``GET /api/docs/tree`` (phase 97,
    task 02) — module-level and DB-free so unit tests drive it
@@ -543,7 +656,13 @@ def build_kb_tree(
    ``{(source, folder_path): summary}`` over the stored
    ``folder_summaries`` rows (``folder_path = ""`` = the source root;
    rows for sources the tree does not list are simply never
-    referenced).
+    referenced). *images* (phase 122, task 04) —
    ``{(source, path): (doc_id, summary)}`` over the stored image docs
    (``is_image`` rows with a servable ``image_path`` — the endpoint
    composes the bounded select); the default ``None``/empty map keeps
    EVERY file node the pre-phase shape (byte-identical wire — a
    pre-phase KB has no image rows, so the endpoint's own map is empty
    for it).
    Shape, per the phase-97 ``00_phase.md`` "The tree endpoint":
@@ -614,10 +733,10 @@ def build_kb_tree(
        if name in listed:  # defensive: list_source_names dedupes
            continue
        listed.add(name)
-        tree.append(_source_node(name, by_source.get(name, ()), summaries))
+        tree.append(_source_node(name, by_source.get(name, ()), summaries, images))
    for source in sorted(by_source):
        if source not in listed:
-            tree.append(_source_node(source, by_source[source], summaries))
+            tree.append(_source_node(source, by_source[source], summaries, images))
    return tree
@@ -625,6 +744,7 @@ def _source_node(
    source: str,
    rows: Sequence[TreeFileRow],
    summaries: Mapping[tuple[str, str], str],
    images: Mapping[tuple[str, str], ImageDocInfo] | None = None,
 ) -> KbTreeSource:
    """One source node (pure): whole-source count + the source-root
    summary + the root level's children (direct subfolders + direct
@@ -646,7 +766,7 @@ def _source_node(
    0-document source (no children, no dates).
    """
    folders, counts = _folder_counts(rows)
-    children = _level_children(source, "", folders, counts, rows, summaries)
+    children = _level_children(source, "", folders, counts, rows, summaries, images)
    return KbTreeSource(
        name=source,
        documents=len(rows),
@@ -677,9 +797,12 @@ def list_kb_tree(
    excluded — the tree has no document ids) + ALL stored
    ``folder_summaries`` rows (a bounded select — one row per
    existing folder at the ≥ 1-doc rule; rows for sources the tree
-    does not list are never referenced by the builder) — through the
+    does not list are never referenced by the builder) + the phase-122
-    pure :func:`build_kb_tree`. ``GET /api/docs`` itself is
+    (task 04) image-docs map (a second bounded select over the
-    untouched.
+    ``is_image`` rows with a servable ``image_path`` — empty for every
    pre-phase KB, so the response stays byte-identical to pre-phase)
    — through the pure :func:`build_kb_tree`. ``GET /api/docs`` itself
    is untouched.
    """
    names = list_source_names(db)
    rows = db.execute(
@@ -712,4 +835,22 @@ def list_kb_tree(
            select(FolderSummary.source, FolderSummary.folder_path, FolderSummary.summary)
        ).all()
    }
-    return KbTree(sources=build_kb_tree(names, doc_rows, summaries))
+    # Phase 122 (task 04): the image-docs affordance map — a bounded
    # select over the ``is_image`` rows only (a handful of rows at KB
    # scale, never the whole catalog; the catalogue query above stays
    # byte-identical). EMPTY for every pre-phase KB (no image rows), so
    # the response stays byte-identical to pre-phase — the fields are
    # row-driven, not toggle-driven (a surviving image doc keeps its
    # thumbnail through a toggle-off sync, the prune guard's UX side).
    images: dict[tuple[str, str], tuple[str, str]] = {
        (source, path): (str(doc_id), summary)
        for source, path, doc_id, summary in db.execute(
            select(
                Document.source,
                Document.path,
                Document.id,
                Document.summary,
            ).where(Document.is_image.is_(True), Document.image_path.is_not(None))
        ).all()
    }
    return KbTree(sources=build_kb_tree(names, doc_rows, summaries, images))
@@ -49,11 +49,16 @@ embeddings) committed first, then the app-managed on-disk dir). The
 whole router sits behind :func:`app.core.auth.require_admin` —
 anonymous callers get 403 on every route.
-No credential-echo path: git URLs may embed ``user:pass@`` (phase 32's
+No credential-echo path (phase 32's masking discipline, extended by
-masking discipline), so every git 409/422 detail is a fixed generic
+phase 121 — LOCKED A2): git URLs may embed ``user:pass@``, so (a)
-string that never repeats the submitted URL. Local paths are not
+every git 409/422 detail is a fixed generic string that never repeats
-secrets — the local 422/409 details name the (expanded) path so the
+the submitted URL, and (b) every URL that LEAVES the API is masked
-owner sees exactly which directory failed.
+through :func:`app.rag.git_sources.sanitize_url` before it enters a
 response (DB rows, env-fallback rows, POST 201, PATCH 200) — a legacy
 row whose credential is still embedded in the stored ``url`` clones
 fine (the stored value is untouched) but its API/UI output is
 bare. Local paths are not secrets — the local 422/409 details name
 the (expanded) path so the owner sees exactly which directory failed.
 Scope boundary (phase locked decisions): the CRUD routes do NOT
 clone or import anything — the existing Sync button performs that, and
@@ -110,6 +115,7 @@ from app.rag.archive_upload import (
    swap_in,
    unpack_archive,
 )
 from app.rag.git_sources import normalize_credential, sanitize_url
 from app.rag.importer import normalize_ignore_path
 from app.rag.llm import LLMClient
 from app.rag.overview import regenerate_overview
@@ -220,6 +226,11 @@ def list_git_sources(
    git-only) with null ``id``/``added_at``, ``ignore_paths: []`` and
    ``include_hidden: False`` (no DB row to store a list or a flag on),
    and ``from_env: true``.
    Every URL is masked on the way out (phase 121, LOCKED A2 —
    :func:`sanitize_url`): an env value or a legacy stored URL may
    embed ``user:pass@`` — the env value and the DB value are
    untouched, only the response is bare.
    """
    rows = db.scalars(
        select(GitSource).order_by(GitSource.added_at.asc(), GitSource.id.asc())
@@ -232,7 +243,7 @@ def list_git_sources(
                GitSourceRow(
                    id=row.id,
                    kind=cast(Literal["git", "local"], row.kind),
-                    url=row.url,
+                    url=sanitize_url(row.url),  # phase 121: never echo userinfo
                    path=row.path,
                    added_at=row.added_at,
                    ignore_paths=row.ignore_paths or [],
@@ -247,7 +258,7 @@ def list_git_sources(
            GitSourceRow(
                id=None,
                kind="git",
-                url=url,
+                url=sanitize_url(url),  # phase 121: an env URL can embed a token
                path=None,
                added_at=None,
                ignore_paths=[],
@@ -290,11 +301,20 @@ def create_git_source(
    ``include_hidden`` (phase 105) — optional, both kinds: absent →
    stored ``False`` (A4), present → stored as sent; the stored flag is
    what is reported.
    ``token`` (phase 121, LOCKED A2) — the masked private-repo
    credential: write-only, stored in the dedicated column, never
    echoed (the response has no token field by contract). Git rows
    are normalized on the way in (``normalize_credential``): an
    old-style embedded ``user:pass@`` URL is stored bare with the
    credential in the token column, an explicit ``token`` wins over
    the embedded one (LOCKED A6), and the duplicate check runs on the
    bare URL.
    """
    row = _create_git_row(payload, db) if payload.kind == "git" else _create_local_row(payload, db)
    return GitSourceOut(
        id=row.id,
-        url=row.url,
+        url=sanitize_url(row.url),  # phase 121: the output mask, always
        added_at=row.added_at,
        ignore_paths=row.ignore_paths,
        include_hidden=row.include_hidden,
@@ -346,6 +366,13 @@ def _create_git_row(payload: GitSourceIn, db: Session) -> GitSource:
        raise HTTPException(
            status_code=422, detail="not a valid git URL (expected https://, ssh:// or git@…)"
        )
    # Phase 121 (task 02, LOCKED A6): normalize the credential — an
    # old-style embedded ``user:pass@`` URL is stored BARE and the
    # embedded credential moves to the token column; an explicit
    # ``token`` field wins over the embedded one. The duplicate check
    # below runs on the BARE URL, so the same repo pasted with a
    # different credential is the same source (409, not a second row).
    url, effective_token = normalize_credential(url, payload.token)
    if db.scalar(select(GitSource).where(GitSource.url == url)) is not None:
        raise HTTPException(status_code=409, detail="a git source with this URL already exists")
    return _commit_new(
@@ -354,6 +381,7 @@ def _create_git_row(payload: GitSourceIn, db: Session) -> GitSource:
            kind="git",
            ignore_paths=_validate_ignore_paths(payload.ignore_paths),
            include_hidden=bool(payload.include_hidden),
            token=effective_token or None,
        ),
        "a git source with this URL already exists",
        db,
@@ -380,7 +408,10 @@ def _create_local_row(payload: GitSourceIn, db: Session) -> GitSource:
        )
    # ``url`` is the table's NOT-NULL location column (phase 38: local
    # rows carry the expanded path there too — git URL shapes and absolute
-    # paths cannot collide).
+    # paths cannot collide). A ``token`` on a local row (phase 121) is
    # stored inert — local rows are walked, not cloned, so
    # ``clone_url_for`` never sees it — and, like on git rows, is never
    # echoed by any output shape.
    return _commit_new(
        GitSource(
            url=path,
@@ -388,6 +419,7 @@ def _create_local_row(payload: GitSourceIn, db: Session) -> GitSource:
            path=path,
            ignore_paths=_validate_ignore_paths(payload.ignore_paths),
            include_hidden=bool(payload.include_hidden),
            token=payload.token or None,
        ),
        f"a local source with this path already exists: {path}",
        db,
@@ -400,14 +432,26 @@ def patch_git_source(
    payload: GitSourcePatchIn,
    db: Session = Depends(get_db),  # noqa: B008
 ) -> GitSourceOut:
-    """Edit one source's ignore list and/or hidden-folders flag.
+    """Edit one source's ignore list, hidden-folders flag, and/or
    private-repo token.
-    Phase 89 A5 (ignore list) + phase 105 (the flag): 404 unknown
+    Phase 89 A5 (ignore list) + phase 105 (the flag) + phase 121
-    id; each PRESENT body field applies independently —
+    (the token): 404 unknown id; each PRESENT body field applies
-    ``ignore_paths`` REPLACES the list (normalized + A4-validated,
+    independently — ``ignore_paths`` REPLACES the list (normalized +
-    fixed 422 details); ``include_hidden`` sets the flag. Both
+    A4-validated, fixed 422 details); ``include_hidden`` sets the
-    absent → 200 no-op. Returns the updated row's public shape
+    flag; ``token`` is TRI-STATE (LOCKED A2): absent/None = no change
-    (id, url, added_at, ignore_paths, include_hidden).
+    (the row's stored credential survives an edit that does not touch
    the masked field), non-empty = replace, empty string = clear
    (stored NULL). A PRESENT token also re-normalizes the (current
    url, new token) pair with the POST write-path rules — a legacy
    embedded-token URL gets its userinfo stripped (moved to the
    column) the first time an explicit credential is written; a clean
    URL comes back untouched. The 409 backstop: re-normalizing can
    make the stored URL collide with another row's bare URL (a
    legacy ``user:pass@`` row and a bare row for the same repo) — the
    unique index yields the generic 409, never a 500. Returns the
    updated row's public shape (id, url — masked, added_at,
    ignore_paths, include_hidden); the token is never echoed.
    """
    row = db.get(GitSource, source_id)
    if row is None:
@@ -416,11 +460,28 @@ def patch_git_source(
        row.ignore_paths = _validate_ignore_paths(payload.ignore_paths)
    if payload.include_hidden is not None:
        row.include_hidden = payload.include_hidden
-    db.commit()
+    if payload.token is not None:
        # Phase 121 (task 02): the tri-state applies — "" clears
        # (stored NULL), non-empty replaces. Re-normalize the pair
        # (see the docstring): a legacy embedded-token URL becomes
        # bare + column credential.
        row.url, effective = normalize_credential(row.url, payload.token)
        row.token = effective or None
    try:
        db.commit()
    except IntegrityError:
        # The re-normalized URL collided with another row's stored URL
        # (the legacy-embedded + bare sibling case) — the unique index
        # is the backstop: a generic 409, never a 500 (the phase-35
        # convention).
        db.rollback()
        raise HTTPException(
            status_code=409, detail="a git source with this URL already exists"
        ) from None
    db.refresh(row)
    return GitSourceOut(
        id=row.id,
-        url=row.url,
+        url=sanitize_url(row.url),  # phase 121: the output mask, always
        added_at=row.added_at,
        ignore_paths=row.ignore_paths,
        include_hidden=row.include_hidden,
@@ -27,8 +27,14 @@ decisions):
   URLs) fails loudly (``no sources configured (git or local)``)
   instead of silently importing the legacy local directories;
 3. per resolved row: ``kind=git`` → :func:`scripts.git_sync.clone_or_pull`
-   into ``BOR_SOURCES_DIR/<repo-name>/`` (phase 28 — reused, not
+   with the phase-121 clone URL (:func:`app.rag.git_sources.clone_url_for`
-   re-implemented); ``kind=local`` → the stored directory, re-verified
+   — the row's ``token`` column injected as
   ``https://x-access-token:<token>@…`` only for https? rows; NULL
   token → the bare stored URL verbatim, so public repos and legacy
   embedded-token rows clone exactly as before) into
   ``BOR_SOURCES_DIR/<repo-name>/`` (phase 28 — reused, not
   re-implemented; the checkout name stays on the bare URL —
   credential-free); ``kind=local`` → the stored directory, re-verified
   ``.is_dir()`` **at sync time** (it may have moved/deleted since
   add-time) — a missing directory raises ``local source missing:
   <path>``; a failing clone or a missing local dir aborts before any
@@ -116,7 +122,7 @@ from app.core.auth import require_admin
 from app.core.errors import sanitize_error as _sanitize_error
 from app.db import SessionLocal
 from app.rag.folder_summaries import generate_folder_summaries, missing_folder_summaries
-from app.rag.git_sources import effective_sources
+from app.rag.git_sources import clone_url_for, effective_sources
 from app.rag.importer import ImportSummary, import_sources
 from app.rag.llm import LLMClient, check_models
 from app.rag.overview import regenerate_overview
@@ -293,7 +299,11 @@ async def _run_sync() -> None:
        doc_dates_by_root: dict[str, dict[str, datetime]] = {}
        for row in rows:
            if row.kind == "git":
-                root = clone_or_pull(row.url, sources_root / repo_name(row.url))
+                # Phase 121: the token column is injected into the clone
                # URL ONLY here (clone_url_for — NULL token → the bare
                # stored URL verbatim); repo_name stays on the bare URL
                # so the checkout directory name is credential-free.
                root = clone_or_pull(clone_url_for(row), sources_root / repo_name(row.url))
                # Phase 106 (D2): the checkout's per-file last-commit
                # dates, keyed by the SAME root string the importer
                # sees (full-history checkouts → true per-file
@@ -366,6 +366,52 @@ class Settings(BaseSettings):
    #: pattern).
    upload_max_mb: int = 512
    # --- Image documents (phase 122: standalone images as documents) ---
    #: Master switch for image-document indexing (phase 122,
    #: ``BOR_IMAGES``; ``0``/``false`` = off — the DEFAULT, LOCKED A3).
    #: Enable only when ``llm_chat_model`` supports vision: image
    #: descriptions are generated by the chat model, and the description
    #: is the ONLY part of an image that gets indexed (the embedding
    #: model never sees pixels). While off, the import walks ignore
    #: image files and a sync never prunes existing ``is_image``
    #: documents (the phase-122 prune guard — the image is invisible to
    #: an images-off walk, not a deleted file).
    images: bool = False
    #: Comma-separated, case-insensitive file extensions (no dot) treated
    #: as standalone images when ``images`` is on (phase 122,
    #: ``BOR_IMAGE_EXTENSIONS``). Stored as a raw CSV string (the
    #: ``import_extensions`` house convention) and parsed on demand via
    #: :py:meth:`image_extension_set`. A SEPARATE set from
    #: ``import_extension_set`` — images are never user-added via
    #: ``BOR_IMPORT_EXTENSIONS`` (the ``images`` toggle is the single
    #: knob). The validator rejects an empty list and malformed tokens,
    #: exactly like ``import_extensions`` (a typo would otherwise index
    #: zero images silently).
    image_extensions: str = "png,jpg,jpeg,webp,gif,bmp"
    #: Where ingested image bytes are copied for serving (phase 122,
    #: ``BOR_IMAGE_DIR``). Raw string — ``Path.expanduser()`` is applied
    #: by the importer, not here (the ``sources_dir``/``upload_dir``
    #: convention). Deliberately separate from ``sources_dir`` (git
    #: checkouts, re-cloned) and ``upload_dir`` (replaced on every
    #: upload): the served copy must outlive the source file.
    image_dir: str = "~/bor-sources/images"
    # --- Chat image questions (phase 123: attach an image to a question) ---
    #: Where a user's question image bytes are stored (phase 123,
    #: ``BOR_CHAT_IMAGE_DIR`` — the ``image_dir`` convention: a sibling of
    #: phase 122's document-image dir, separate because question-images
    #: are per-conversation, not per-source). Raw string —
    #: ``Path.expanduser()`` is applied by the upload/serve routes, not
    #: here. Files land as ``<uuid4().hex>.<ext>`` — the uuid is the
    #: credential (no enumeration value; the saved/shared chat record
    #: carries the served path, never base64, LOCKED A5).
    chat_image_dir: str = "~/bor-sources/chat-images"
    #: Cap in MiB for one question-image upload (phase 123, LOCKED A5 —
    #: the ~10 MB cap; ``BOR_CHAT_IMAGE_MAX_MB``). ``<= 0`` would reject
    #: every upload — a typo, so the validator fails loudly at startup
    #: (the ``upload_max_mb`` pattern).
    chat_image_max_mb: int = 10
    # --- Docs push (phase 59: save a chat answer as documentation) ---
    #: The git repo a saved chat answer is committed to (phase 59, D3):
    #: **any** remote — a URL (``https://``, ``ssh://``, ``git@``) or a
@@ -471,6 +517,25 @@ class Settings(BaseSettings):
            )
        return v
    @field_validator("image_extensions")
    @classmethod
    def _image_extensions_known(cls, v: str) -> str:
        """Reject an empty list or malformed tokens loudly (the
        ``import_extensions`` precedent, phase 122): a typo like
        ``png,jpeb`` would otherwise index zero images silently."""
        exts = {part.strip().lstrip(".").lower() for part in v.split(",") if part.strip()}
        if not exts:
            raise ValueError("image_extensions must name at least one format")
        malformed = sorted(
            ext for ext in exts if re.fullmatch(r"[a-z0-9]{1,16}", ext) is None
        )
        if malformed:
            raise ValueError(
                f"image_extensions contains malformed token(s): {', '.join(malformed)} — "
                "each extension must be lowercase letters/digits only, 1-16 chars, no dot"
            )
        return v
    @field_validator("agent_max_rounds")
    @classmethod
    def _agent_max_rounds_non_negative(cls, v: int) -> int:
@@ -525,6 +590,15 @@ class Settings(BaseSettings):
            raise ValueError("upload_max_mb must be > 0 (MiB)")
        return v
    @field_validator("chat_image_max_mb")
    @classmethod
    def _chat_image_max_mb_positive(cls, v: int) -> int:
        """``0``/negative would reject every question-image upload — fail
        loud at startup (the ``upload_max_mb`` precedent, phase 123)."""
        if v <= 0:
            raise ValueError("chat_image_max_mb must be > 0 (MiB)")
        return v
    @field_validator("history_max_turns")
    @classmethod
    def _history_max_turns_non_negative(cls, v: int) -> int:
@@ -647,6 +721,19 @@ class Settings(BaseSettings):
            if part.strip()
        )
    @property
    def image_extension_set(self) -> frozenset[str]:
        """Lowercased, dotted image-extension set (``.png``) for the
        phase-122 walk filter — SEPARATE from
        :py:attr:`import_extension_set` (images are never user-added via
        ``BOR_IMPORT_EXTENSIONS``; the ``images`` toggle is the single
        knob)."""
        return frozenset(
            f".{part.strip().lstrip('.').lower()}"
            for part in self.image_extensions.split(",")
            if part.strip()
        )
    @property
    def git_source_list(self) -> list[str]:
        """Non-empty, stripped git URLs from :py:attr:`git_sources` (phase 28).
@@ -38,7 +38,8 @@ from __future__ import annotations
 from starlette.datastructures import MutableHeaders
 from starlette.types import ASGIApp, Message, Receive, Scope, Send
-#: The exact owner-approved policy (phase 82, decision A1).
+#: The exact owner-approved policy (phase 82, decision A1), extended
 #: by phase 123's ``img-src`` carve-out (see below).
 #: ``default-src 'self'`` is inherited by every sub-policy that has no
 #: explicit entry (``script-src``, ``style-src``, ``connect-src``, …),
 #: ``base-uri 'none'`` blocks base-tag hijacking, and
@@ -46,7 +47,26 @@ from starlette.types import ASGIApp, Message, Receive, Scope, Send
 #: (verified unnecessary — see module docstring), no ``report-uri`` /
 #: ``report-to`` (no collector in the homelab — a report would just
 #: vanish).
-CSP = "default-src 'self'; base-uri 'none'; frame-ancestors 'none'"
+#
 #: Phase 123 (chat image questions, owner-confirmed 2026-09-24) added
 #: the one scoped relaxation the design requires: ``img-src 'self'
 #: data:``. The question-image composer renders the picked file as a
 #: ``data:`` URL — the PREVIEW thumbnail (before the send-time upload
 #: there is no served path yet) and the LIVE user bubble (the data URL
 #: needs no fetch) — and ``default-src 'self'`` alone blocks ``data:``
 #: images in every real browser (the phase-123 E2E caught it: the
 #: bubble degraded to the "image unavailable" line). The carve-out is
 #: ``img-src`` ONLY: ``data:`` never becomes a source for scripts,
 #: styles, or fetches (those keep the strict ``default-src 'self'``
 #: inheritance), and the bytes are the user's OWN locally-picked file
 #: (no exfiltration vector — an ``<img>`` cannot read them back).
 #: Restored / shared bubbles render from the served path (``'self'``),
 #: so the ``data:`` allowance exists for the two pre-upload/first-paint
 #: surfaces only.
 CSP = (
    "default-src 'self'; base-uri 'none'; frame-ancestors 'none'; "
    "img-src 'self' data:"
 )
 class SecurityHeadersMiddleware:
@@ -22,6 +22,7 @@ from starlette.responses import FileResponse
 from app.api.auth import router as auth_router
 from app.api.chat import router as chat_router
 from app.api.chat_images import router as chat_images_router
 from app.api.chats import (
    public_router as chats_public_router,
 )
@@ -116,6 +117,10 @@ def create_app() -> FastAPI:
    app.include_router(docs_router, prefix="/api")
    app.include_router(git_sources_router, prefix="/api")
    app.include_router(chat_router, prefix="/api")
    # Phase 123: the question-image upload/serve pair (POST is
    # user-gated like the chat turn; GET is public like saved-chat
    # content — the uuid filename is the credential).
    app.include_router(chat_images_router, prefix="/api")
    app.include_router(steering_router, prefix="/api")
    app.include_router(sync_router, prefix="/api")
    app.include_router(chats_router, prefix="/api")
@@ -139,6 +139,29 @@ class Document(Base):
    #: failed, and until the phase-118 backfill stores one on the next
    #: sync.
    summary: Mapped[str | None] = mapped_column(Text, default=None)
    #: True iff this document is a standalone image (phase 122,
    #: LOCKED A3): ``content`` (and ``summary``) is the CHAT model's
    #: vision description of the image — the ONLY embedded text (the
    #: embedding model never sees pixels), and the image bytes
    #: themselves live at :py:attr:`image_path` (served by the document
    #: image route, task 04). ``False`` for every text document,
    #: including all pre-phase-122 rows (the server default keeps them
    #: valid without a backfill). An ``is_image`` doc is INVISIBLE to
    #: an images-off walk, not a deleted file — the importer's prune
    #: guard (the phase-122 derived decision) protects it while the
    #: toggle is off.
    is_image: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default=text("false"), nullable=False
    )
    #: Absolute path of the image's PERSISTENT copy in
    #: ``settings.image_dir`` (phase 122) — the importer copies each
    #: ingested image there (``<doc-id>.<ext>``) because the source
    #: file is disposable: uploads are replaced on every upload, git
    #: checkouts are re-cloned, local dirs are user-edited. The copy is
    #: written only when the doc is new or its hash changes, deleted on
    #: a content change (the stale copy) and on prune. NULL for text
    #: documents.
    image_path: Mapped[str | None] = mapped_column(Text, default=None)
    chunks: Mapped[list[Chunk]] = relationship(
        back_populates="document", cascade="all, delete-orphan"
@@ -286,6 +309,16 @@ class GitSource(Base):
    include_hidden: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default=text("false"), nullable=False
    )
    #: Private-repo credential (phase 121, LOCKED A2): the PAT the owner
    #: types into the masked Sources-page field. NULL = public repo (or a
    #: legacy row whose credential is still embedded in ``url``). Stored
    #: plaintext BY NECESSITY — the repo must remain cloneable, so the
    #: raw credential must be recoverable at sync time; the DB is the
    #: trusted store and is never served to the UI. Injected into the
    #: clone URL ONLY at clone time
    #: (:func:`app.rag.git_sources.clone_url_for`); NEVER returned by
    #: any API shape (the output models gain no token field).
    token: Mapped[str | None] = mapped_column(Text, default=None)
    added_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
@@ -427,6 +427,18 @@ READ_TRUNCATION_NOTICE = (
    "document."
 )
 #: The image-document marker (phase 122, task 05): the line prefixed to
 #: the vision DESCRIPTION a ``read`` of a standalone-image document
 #: returns — the model must reason about what it is reading (the text
 #: below is a description GENERATED from the image, not the image's
 #: own words). It sits on the result's THIRD line: the ``Document …``
 #: header and the phase-106 date line stay byte-identical (the E2E
 #: mock's ``_READ_RESULT_PREFIX`` header contract), and a NON-image
 #: doc's result carries no marker at all (byte-identical to pre-122).
 IMAGE_DOC_MARKER = (
    "Image document — the text below is a description generated from the image:"
 )
 #: The no-source ``ls`` refusal with the teaching parenthetical
 #: appended (phase 72): used when a stripped scope has no ``/`` and
 #: matches no registered source (the incident's ``ls(path='.')``). The
@@ -1270,6 +1282,12 @@ def _execute_tool(
            return _no_document_refusal(db, arg)
        holder.read_docs.append(doc)
        holder.tool_calls += 1
        # Phase 122 (task 05): an image document's content IS the vision
        # description — the marker line (a third line between the
        # byte-identical header/date lines and the text) tells the model
        # what it is reading. A text doc's ``marker`` is "" — the result
        # stays byte-identical to pre-122.
        marker = f"{IMAGE_DOC_MARKER}\n" if doc.is_image else ""
        cap = settings.read_max_chars
        if len(doc.content) > cap:
            # Phase 95 (owner permission 2026-09-10, ``TODO.md`` L5): the
@@ -1293,17 +1311,20 @@ def _execute_tool(
            return (
                f"Document {doc.source}/{doc.path}:\n"
                f"date: {doc.created_at:%Y-%m-%d}\n"
                f"{marker}"
                f"{doc.content[:cap]}\n"
                f"{TRUNCATION_MARKER}\n"
                f"{READ_TRUNCATION_NOTICE.format(shown=cap, total=len(doc.content))}"
            )
        # At or under the cap: the pre-phase-95 result plus the
        # phase-106 D5 date line (first line byte-identical — the
-        # mock's header contract; no marker, no notice, no holder
+        # mock's header contract; no truncation marker, no notice, no
-        # entry, no ToolResultPiece).
+        # holder entry, no ToolResultPiece) — and, phase 122, the
        # image-document marker line for image docs only.
        return (
            f"Document {doc.source}/{doc.path}:\n"
            f"date: {doc.created_at:%Y-%m-%d}\n"
            f"{marker}"
            f"{doc.content}"
        )
    if call.name == "grep":
@@ -1372,7 +1393,7 @@ async def run_agent(
    db_factory: Callable[[], Session],
    *,
    system_prompt: str,
-    user_message: str,
+    user_message: str | list[dict[str, Any]],
    seed_docs: Sequence[Document],
    settings: Settings,
    holder: AgentHolder,
@@ -1403,6 +1424,20 @@ async def run_agent(
    unchanged. ``()`` (the default) keeps the pre-phase-74 two-message
    request byte-identical.
    User message (phase 123, TODO L6): *user_message* is the current
    turn's user content — the plain question string (every text-only
    turn, byte-identical to pre-phase) OR the multimodal content list
    ``[{type: "text", …}, {type: "image_url", …}]`` for a question that
    carried an image. FLOW (pinned): the API layer
    (``app.api.chat``) builds the content via its ``build_user_content``
    helper and passes it HERE — ``run_agent`` builds its OWN
    ``[system, *history, user]`` list from this value (it does NOT
    receive the already-built ``messages``; the deflected branch is the
    one that consumes chat.py's list directly), so a single value
    covers both shapes and the tool rounds / recovery / retries operate
    on it untouched. Prior turns' images are never replayed (LOCKED A7
    — *history* is text-only by construction).
    Retries (phase 67, owner-locked A2): every model request goes through
    :func:`chat_stream_retried` — a failed round is retried **before** its
    first piece (same messages, ``settings.llm_retries`` restarts, a flat
@@ -21,9 +21,26 @@ CLI: the legacy ``DEFAULT_SOURCES`` fallback).
 (repo URLs of the effective git rows) so existing importers of the old
 name keep working; new code calls :func:`effective_sources` and
 branches on ``row.kind``.
 Phase 121 (private git sources) adds the token mechanics next to the
 resolver — three pure helpers, no DB of their own:
 * :func:`sanitize_url` — the OUTPUT mask: strips the ``user:pass@``
  userinfo of ``https?://`` URLs so no API/UI surface ever shows an
  embedded credential (legacy rows included; the stored value is
  untouched — LOCKED A2);
 * :func:`clone_url_for` — the CLONE-time credential: a row's
  ``token`` column is injected into the URL handed to git, and only
  there (NULL token → the bare stored URL verbatim);
 * :func:`normalize_credential` — the WRITE-path normalizer: an
  old-style ``https://user:pass@host/repo.git`` URL pasted into the
  API is stored bare and the embedded credential is moved into the
  ``token`` column (an explicit ``token`` field wins — LOCKED A6).
 """
 from __future__ import annotations
 import logging
 import re
 from typing import Literal
 from sqlalchemy import select
@@ -32,6 +49,109 @@ from sqlalchemy.orm import Session
 from app.config import get_settings
 from app.models import GitSource
 logger = logging.getLogger(__name__)
 #: Phase 121 — the userinfo component of an ``https?://`` URL: the
 #: scheme, a run of one-or-more characters that are neither ``@`` nor
 #: ``/`` (the ``user`` or ``user:pass`` part), and the terminating
 #: ``@``. Deliberately a small anchored regex — never a URL parser
 #: re-serialization: for a credential-free URL there is no match and
 #: the input is returned byte-identical (the phase-50/35 contract that
 #: stored URLs surface verbatim when they carry no credential).
 _USERINFO_RE = re.compile(r"^(https?://)([^/@]+)@")
 def sanitize_url(url: str) -> str:
    """Phase 121, LOCKED A2 — the token-free form of a source URL,
    for API/UI output only.
    Strips the userinfo component of ``https?://`` URLs
    (``https://user:pass@host/path`` → ``https://host/path``);
    ``ssh://``, ``git@`` (scp-style), and local paths are left
    untouched. Idempotent — and byte-identical for URLs that carry no
    userinfo (no match → the input unchanged, including a ``@`` inside
    the *path*, which is not userinfo). The stored row value is NOT
    modified: a legacy row whose credential is still embedded in
    ``url`` keeps cloning with its original stored URL; this is the
    output mask that keeps that credential out of every response and
    the UI (the env-fallback rows get the same treatment — the env
    *value* itself is untouched, only the response is masked).
    """
    return _USERINFO_RE.sub(r"\1", url, count=1)
 def clone_url_for(row: GitSource) -> str:
    """Phase 121, LOCKED A2 — the URL git actually clones, with the
    row's credential injected ONLY here.
    * ``token`` NULL/falsy → ``row.url`` verbatim: public repos and
      local rows behave byte-identically to pre-phase-121, and a
      legacy embedded-token row (``token`` NULL, credential in the
      stored URL) keeps cloning with its ORIGINAL stored URL — the
      credential keeps working;
    * an ``https?://`` row with a token →
      ``https://x-access-token:<token>@<host>/<path>`` — any existing
      userinfo in the stored URL is replaced by the column credential
      (``x-access-token`` as the username: GitHub-agnostic, any host
      that accepts ``https://user:token@`` treats the first component
      opaquely — the task-02 assumption, task 02 step 4);
    * a non-https row with a token (``ssh://``/``git@``/local path)
      → ``row.url`` unchanged + a WARNING log (a token cannot
      authenticate ssh — the owner must use a deploy key/agent there;
      the log names the repo via its sanitized URL, never the token).
    ``repo_name`` (and every other checkout-path derivation) keeps
    operating on the bare ``row.url`` — the checkout directory name is
    credential-free.
    """
    token = row.token
    if not token:
        return row.url
    if not row.url.startswith(("https://", "http://")):
        logger.warning(
            "git source %s has a stored token but a non-https? URL — "
            "a token cannot authenticate ssh/git@ clones; the stored "
            "URL is used as-is (configure a deploy key or SSH agent "
            "for private ssh repos)",
            sanitize_url(row.url),
        )
        return row.url
    bare = sanitize_url(row.url)
    return bare.replace("://", f"://x-access-token:{token}@", 1)
 def normalize_credential(url: str, token: str | None) -> tuple[str, str | None]:
    """Phase 121, LOCKED A6 — the write-path credential normalizer.
    If the (``https?://``-only) URL carries userinfo, it is stripped
    for storage and the EMBEDDED CREDENTIAL becomes the effective
    token — UNLESS the caller also sent an explicit ``token``
    (non-None), which WINS (explicit beats embedded — a blank masked
    field, i.e. an explicit "", is a deliberate "no credential").
    Pasting the old-style ``https://user:ghp_…@host/repo.git`` URL
    still works and lands token-column-clean; the caller stores the
    bare URL + ``effective_token or None`` (an empty explicit token
    stores NULL) and runs its duplicate check on the BARE URL, so the
    same repo with a different token is still the same source
    (409, not a second row).
    The embedded credential is the *password* part of a
    ``user:pass`` userinfo (after the first colon — the password may
    contain further colons), or the whole userinfo run for the
    username-as-token form (``https://<token>@host/…``, the documented
    GitHub shape, no colon). Clean URLs and ``ssh://``/``git@``/local
    paths return ``(url, token)`` untouched — byte-identical
    pre-phase behavior.
    """
    match = _USERINFO_RE.match(url)
    if match is None:
        return url, token
    userinfo = match.group(2)
    user, sep, password = userinfo.partition(":")
    embedded = password if sep else userinfo
    effective = token if token is not None else embedded
    return sanitize_url(url), effective
 def effective_sources(db: Session) -> tuple[list[GitSource], Literal["db", "env"]]:
    """``(rows, origin)`` — the effective source rows (both kinds) and
@@ -30,7 +30,12 @@ by their exact lowercased full filename (``Dockerfile`` under the
 no longer exist **or no longer match the format filter** — this is how
 previously-imported junk (e.g. dot-dir READMEs) leaves the index. Per-file
 logging uses the verbs ``added | updated | unchanged | pruned`` plus a
-summary line with per-format counts (PLAN §9).
+summary line with per-format counts (PLAN §9). Phase 122 prune guard
 (LOCKED, derived from A3/A4): while the ``images`` toggle is OFF, an
 ``is_image`` doc is INVISIBLE to the walk, not a deleted file — prune
 skips it (turning the toggle off and syncing must never destroy image
 documents); a toggle-ON run prunes a deleted image file normally and
 deletes its ``image_dir`` copy with the row.
 Document dates (phase 106, D2/D4): every import sources
 ``documents.created_at`` from the file's source — the per-file git
@@ -54,6 +59,32 @@ backfill runs BEFORE the ``created_at_manual`` early-return (the manual
 flag protects the DATE only, D1) and the strict ``is None`` check leaves
 owner-set summaries (even empty strings, phase 57) alone.
 Standalone images (phase 122, LOCKED A3): with the ``images`` toggle
 (``BOR_IMAGES``) ON, the walk also admits the image extension set
 (``BOR_IMAGE_EXTENSIONS`` — a SEPARATE set from ``import_extension_set``;
 images are never user-added via ``BOR_IMPORT_EXTENSIONS``, the toggle is
 the single knob). Such a file takes the binary index path
 (:func:`_index_image_file`): the sha256 digest is over the raw BYTES
 (content identity — the digest rule is unchanged), the bytes are copied
 to the persistent home ``settings.image_dir/<doc-id>.<ext>`` (dir created
 on demand; the copy is written ONLY after a successful description, so a
 failure never leaves an orphan; a changed image deletes the stale copy
 first; a pruned image doc deletes its copy), the row carries
 ``is_image=True`` + ``image_path``, and ``content`` is the vision
 description — the ONLY embedded text of the document (the embedding model
 never sees pixels; ``read_text`` is never called for an image). The
 description comes through the single seam :func:`_describe_or_skip`
 (task 03: :func:`app.rag.summarizer.describe_image` — ONE CHAT-model
 (vision) call with the image bytes as a base64 data URL; the ``lite``
 summary model is NOT assumed vision-capable, LOCKED A3); a failed/empty
 description SKIPS the doc entirely (no row, no copy) — counted in
 ``images_failed`` + a warning, the sync continues (fail-soft). The normal
 chunk pipeline then embeds ``content`` and the phase-30 summary path runs
 on it — image-aware (task 03): for an image doc the description IS the
 summary (stored verbatim, no ``lite`` call, no pointer line), so the
 ``is_summary`` position −1 chunk mirrors ``Document.summary``, which
 equals ``Document.content``.
 ``import_sources`` accepts an optional per-file ``progress`` callback
 (phase 64, task 01) reporting the file being processed right now.
 """
@@ -61,11 +92,12 @@ from __future__ import annotations
 import hashlib
 import logging
 import uuid
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Protocol
+from typing import Any, Protocol
 from sqlalchemy import select
 from sqlalchemy.orm import Session
@@ -76,7 +108,12 @@ from app.models import Chunk, Document
 from app.rag.chunker import chunk_document, extract_title
 from app.rag.doc_dates import file_mtime_datetime, normalize_doc_date
 from app.rag.llm import EmbeddingError, LLMError
-from app.rag.summarizer import generate_summary
+from app.rag.summarizer import (
    IMAGE_FALLBACK_MIME,
    IMAGE_MIMES,
    describe_image,
    generate_summary,
 )
 logger = logging.getLogger("app.importer")
@@ -94,9 +131,12 @@ class Embedder(Protocol):
    async def embed(self, texts: list[str]) -> list[list[float]]: ...
-    async def chat(self, messages: list[dict[str, str]], model: str | None = None) -> str: ...
+    async def chat(self, messages: list[dict[str, Any]], model: str | None = None) -> str: ...
-    # ^ the one-shot completion the summarizer uses for the ``lite`` model
+    # ^ the one-shot completion the summarizer uses — the ``lite`` model
-    #   (phase 30, task 01); :class:`app.rag.llm.LLMClient` satisfies it.
+    #   for text summaries (phase 30, task 01) and the CHAT (vision)
    #   model for the phase-122 image description (multimodal content:
    #   a string or a list of OpenAI-compatible parts); :class:`app.rag.
    #   llm.LLMClient` satisfies it.
@dataclass
@@ -129,6 +169,12 @@ class ImportSummary:
    #: so no ``sources_meta`` bump, no overview/folder-summary
    #: regeneration).
    dates_updated: int = 0
    #: Image docs (phase 122, LOCKED A3) whose vision description failed
    #: or came back empty — the doc is SKIPPED entirely (no row, no
    #: ``image_dir`` copy): an undescribed image is unsearchable noise.
    #: Fail-soft: the sync continues, this counter + the warning line
    #: are the signal.
    images_failed: int = 0
    #: Files walked, keyed by lowercased extension (``md``, ``yaml``, …).
    formats: dict[str, int] = field(default_factory=dict)
@@ -143,7 +189,7 @@ class ImportSummary:
        logger.info(
            "import: summary files=%d added=%d updated=%d unchanged=%d pruned=%d "
            "errors=%d chunks=%d embed_batches=%d summaries=%d summary_errors=%d "
-            "summary_backfilled=%d dates_updated=%d formats=%s",
+            "summary_backfilled=%d dates_updated=%d images_failed=%d formats=%s",
            self.files,
            self.added,
            self.updated,
@@ -156,6 +202,7 @@ class ImportSummary:
            self.summary_errors,
            self.summary_backfilled,
            self.dates_updated,
            self.images_failed,
            self.format_counts(),
        )
@@ -238,6 +285,7 @@ def iter_importable_files(
    excluded: frozenset[str] = EXCLUDED_DIRS,
    ignore: tuple[str, ...] = (),
    include_hidden: bool = False,
    image_extensions: frozenset[str] = frozenset(),
 ) -> list[Path]:
    """All importable files under *root* (sorted), per the A9 scope rules.
@@ -255,6 +303,13 @@ def iter_importable_files(
    source-relative POSIX path starts with any entry; the default ``()``
    keeps every existing caller byte-identical. The *ignore* tuple
    composes additively in both states.
    *image_extensions* (phase 122) is the lowercased dotted
    image-extension set admitted IN ADDITION to *extensions* — passed by
    :func:`import_sources` only while the ``images`` toggle is on (it
    reads ``llm.settings``; the image set is never merged into
    *extensions*). The empty default admits nothing: every existing caller
    (and the toggle-off walk) stays byte-identical to pre-phase.
    """
    if not root.is_dir():
        return []
@@ -270,7 +325,12 @@ def iter_importable_files(
            continue
        if ignore and is_ignored(rel.as_posix(), ignore):
            continue
-        if match_extension(path, extensions) is None:
+        matched = match_extension(path, extensions)
        if matched is None and image_extensions:
            # Phase 122: the image set is admitted IN ADDITION to the
            # import set (toggle on only — the caller passes it in).
            matched = match_extension(path, image_extensions)
        if matched is None:
            continue
        files.append(path)
    return files
@@ -340,10 +400,23 @@ async def import_sources(
    mtime fallback applies to every file — which IS the behavior
    change, D4: an unchanged file now refreshes its stored date from
    its source on every run (the backfill-correction case).
    Images (phase 122): when ``llm.settings.images`` is on, BOTH walks
    (the progress pre-walk and the processing loop — same rules, so
    ``total`` counts images) also admit ``llm.settings.image_extension_set``
    files, each indexed through the binary image path (see the module
    docstring). ``prune=True`` with the toggle ON prunes a deleted image
    file normally (row + ``image_dir`` copy); with the toggle OFF the
    prune skips ``is_image`` docs (the prune guard — the image is
    invisible to the walk, not a deleted file).
    """
    if limit is not None and limit <= 0:
        raise ValueError("limit must be >= 1")
    summary = ImportSummary()
    # Phase 122: the image set is admitted by the walks ONLY while the
    # toggle is on — the empty set admits nothing, so the toggle-off run
    # (walk, counts, prune) stays byte-identical to pre-phase.
    image_exts = llm.settings.image_extension_set if llm.settings.images else frozenset()
    owns_session = session is None
    if session is None:
        session = SessionLocal()
@@ -364,6 +437,7 @@ async def import_sources(
                    include_hidden=_include_hidden_for_root(
                        root, include_hidden_by_root
                    ),
                    image_extensions=image_exts,
                )
            )
    try:
@@ -386,6 +460,7 @@ async def import_sources(
                llm.settings.import_extension_set,
                ignore=ignore,
                include_hidden=include_hidden,
                image_extensions=image_exts,
            ):
                if limit is not None and summary.files >= limit:
                    break
@@ -394,9 +469,11 @@ async def import_sources(
                summary.files += 1
                # Phase 102: the matched bare token (``dockerfile`` for an
                # extensionless ``Dockerfile``), never ``unknown`` — the
-                # file is in scope, so the walk matched it.
+                # file is in scope, so the walk matched it. Phase 122: an
                # image file matches the image set, not the import set.
                ext = (
                    match_extension(path, llm.settings.import_extension_set)
                    or match_extension(path, image_exts)
                    or "unknown"
                )
                summary.formats[ext] = summary.formats.get(ext, 0) + 1
@@ -423,7 +500,9 @@ async def import_sources(
            if limit is not None:
                logger.warning("import: --prune ignored because --limit was given")
            else:
-                summary.pruned = _prune(session, source_names, seen)
+                summary.pruned = _prune(
                    session, source_names, seen, images=llm.settings.images
                )
        summary.embed_batches = llm.embed_batches
        summary.log()
        return summary
@@ -448,8 +527,24 @@ async def _index_file(
    git last-commit datetime from the caller's ``doc_dates_by_root``
    map, or ``None`` (every non-git case): the file's mtime is read
    here, once, and becomes the source date (the D2 fallback).
    Image files (phase 122, toggle on) delegate to
    :func:`_index_image_file` — the binary path (bytes digest,
    persistent copy, ``content`` = the vision description) — BEFORE
    any text read: ``read_text`` is never called for an image.
    """
    settings = llm.settings
    # Phase 122 (task 02): the image branch FIRST. Only reachable while
    # the ``images`` toggle is on — the walk never admits image files
    # while it is off, and with it off this check is a no-op (the text
    # path below stays byte-identical to pre-phase).
    if settings.images:
        image_set = settings.image_extension_set
        if match_extension(full_path, image_set) is not None:
            return await _index_image_file(
                session, source=source, rel=rel, full_path=full_path, llm=llm,
                summary=summary, raw_date=raw_date,
            )
    content = full_path.read_text(encoding="utf-8", errors="replace").replace("\x00", "")
    digest = hashlib.sha256(content.encode("utf-8")).hexdigest()
    doc = session.scalar(select(Document).where(Document.source == source, Document.path == rel))
@@ -609,9 +704,24 @@ async def _store_summary(
    a success counts ``summary_backfilled`` instead of ``summaries``
    (the doc content is untouched, so the import's KB-change signal must
    not move); the rest of the mechanics are identical.
    Image docs (phase 122, task 03, LOCKED A3): for an ``is_image`` doc
    the vision description — ``content`` (which equals ``doc.content``
    on the backfill path) — IS the summary: no ``lite`` call, no
    pointer line (the summary mirrors the description verbatim, so
    ``doc.summary`` == ``doc.content``). The phase-30 chunk mechanics
    (one ``is_summary`` position −1 chunk, replacement, best-effort
    rollback) are unchanged; the only remaining failure class is the
    summary chunk's embed (the ``doc`` row + content chunks survive —
    fail-soft, same as the text path).
    """
    try:
-        text = await generate_summary(llm, source=source, path=rel, content=content)
+        if doc.is_image:
            # Phase 122 (task 03): the description IS the summary —
            # stored verbatim (no ``lite`` call, no pointer line).
            text = content
        else:
            text = await generate_summary(llm, source=source, path=rel, content=content)
        # Replacement: at most one summary chunk per document at a time.
        # Removing from the collection is what the ``delete-orphan``
        # cascade turns into a row delete on flush — and it keeps the
@@ -646,14 +756,265 @@ async def _store_summary(
        logger.error("import: summary failed source=%s path=%s — %s", source, rel, e)
-def _prune(session: Session, source_names: set[str], seen: set[tuple[str, str]]) -> int:
+async def _describe_or_skip(
-    """Delete documents of *source_names* whose file is no longer in *seen*."""
+    llm: Embedder, *, data: bytes, source: str, rel: str, full_path: Path
 ) -> str | None:
    """Phase 122 — the SINGLE seam for the image description (task 03).
    Returns the vision description that becomes the image document's
    ``content`` (and ``summary`` — the ONLY embedded text of the doc),
    or ``None`` when the description failed or came back empty — the
    caller then SKIPS the doc entirely (no row, no copy) and counts
    ``summary.images_failed`` (LOCKED A3, fail-soft: the sync continues,
    the warning + counter are the signal).
    The seam is one line by design (the importer's tests patch exactly
    this function): :func:`app.rag.summarizer.describe_image` — ONE
    CHAT-model (vision) call (LOCKED A3) with the bytes as a data URL
    whose mime comes from :data:`app.rag.summarizer.IMAGE_MIMES`
    (dotted extension; an unlisted ``BOR_IMAGE_EXTENSIONS`` token takes
    the generic fallback — a rejection there fails soft like any other
    description error). ``source``/``rel`` stay on the signature so the
    caller (and the patch) reads like the document being described;
    the failure's doc identity is logged by the caller's warning.
    """
    mime = IMAGE_MIMES.get(full_path.suffix.lower(), IMAGE_FALLBACK_MIME)
    return await describe_image(llm, data=data, mime=mime)
 def _delete_image_copy(image_path: str | None) -> None:
    """Best-effort removal of a stale image copy (phase 122).
    A missing path is a no-op (already gone — e.g. the owner cleaned
    the image dir); an unreadable one is logged, never raised — copy
    cleanup must not break the sync (the doc row's fate is decided by
    the upsert/prune logic, not by filesystem hygiene).
    """
    if not image_path:
        return
    try:
        Path(image_path).unlink(missing_ok=True)
    except OSError as e:
        logger.warning("import: could not delete image copy %s — %s", image_path, e)
 async def _index_image_file(
    session: Session,
    *,
    source: str,
    rel: str,
    full_path: Path,
    llm: Embedder,
    summary: ImportSummary,
    raw_date: datetime | None = None,
 ) -> None:
    """The phase-122 image branch of :func:`_index_file` — a standalone
    image is indexed from its BYTES, never its text:
    * the sha256 digest is over the raw bytes (the digest rule is
      content identity — the same bytes are the same document);
    * the PERSISTENT copy lands in ``settings.image_dir`` as
      ``<doc-id>.<ext>`` (the dir is created on demand; the copy is
      written only AFTER a successful description, so a failure never
      leaves an orphan; a changed image deletes the stale copy before
      replacing it);
    * ``content`` is the vision description — the ONLY embedded text of
      the document (the embedding model never sees pixels) — and the
      normal chunk pipeline then embeds it, with the phase-30 summary
      path running on it (the ``is_summary`` position −1 chunk mirrors
      ``Document.summary``).
    ``raw_date`` follows the text path exactly (the phase-106 D2
    fallback: no source date in the map → the file's mtime, read before
    the unchanged early-return because the unchanged path refreshes the
    stored date from the same source; the D1 manual-date lock and the
    D4 refresh apply unmodified).
    Fail-soft (LOCKED A3): a failed/empty description SKIPS the doc
    entirely (no row, no copy) — ``summary.images_failed`` + a warning,
    the sync continues.
    """
    settings = llm.settings
    data = full_path.read_bytes()
    digest = hashlib.sha256(data).hexdigest()
    doc = session.scalar(select(Document).where(Document.source == source, Document.path == rel))
    if raw_date is None:
        # D2 fallback (same as the text path): no source date in the map
        # → the file's mtime (one stat).
        raw_date = file_mtime_datetime(full_path)
    if doc is not None and doc.content_hash == digest:
        # Unchanged image (byte digest) — the text path's unchanged
        # branch, unmodified in shape.
        summary.unchanged += 1
        logger.info("import: unchanged source=%s path=%s", source, rel)
        # Phase 118 (A2) backfill, image flavour: an unchanged image doc
        # whose summary is still NULL (an earlier fail-soft summary miss
        # — for an image, the one remaining failure class: the summary
        # chunk's embed) gets the same best-effort summary pass. For an
        # image the summary IS the stored description (``doc.content``),
        # so the image-aware ``_store_summary`` (task 03) re-stores it
        # verbatim with one ``is_summary`` chunk; a failure (the
        # embed) keeps the doc as-is (no row mutation) — fail-soft,
        # same as the text path.
        if doc.summary is None:
            await _store_summary(
                session, doc=doc, source=source, rel=rel, content=doc.content,
                llm=llm, summary=summary, backfill=True,
            )
        if doc.created_at_manual:
            # D1/D4: the owner's correction survives the sync — no write
            # at all (the text path's manual-date early-return).
            return
        # D4: the date refreshes on every sync, including unchanged
        # files, and may go OLDER (no monotonic guard).
        target = normalize_doc_date(raw_date)
        if target != doc.created_at:
            doc.created_at = target
            session.commit()
            summary.dates_updated += 1
            logger.info(
                "import: date-refreshed source=%s path=%s date=%s",
                source, rel, doc.created_at.isoformat(),
            )
        return
    verb = "updated" if doc is not None else "added"
    # The description is the doc's content (task 03: and its summary) —
    # it is generated BEFORE anything is written, so a failure skips the
    # doc with no row and no copy (the copy is only made after a
    # successful description — a failure never leaves an orphan).
    content = await _describe_or_skip(
        llm, data=data, source=source, rel=rel, full_path=full_path
    )
    if content is None:
        # LOCKED A3 fail-soft: an undescribed image is unsearchable
        # noise — skip the doc entirely (no row, no copy).
        summary.images_failed += 1
        logger.warning("import: image description failed source=%s path=%s", source, rel)
        return
    # The persistent copy: uploads are replaced on every upload, git
    # checkouts are re-cloned, local dirs are user-edited — the served
    # bytes must outlive the source file. Named by the doc id: a new
    # doc's id is the uuid4 chosen here (row and copy agree); a changed
    # doc keeps its id (the copy path is stable).
    doc_id = doc.id if doc is not None else uuid.uuid4()
    image_dir = Path(settings.image_dir).expanduser()
    image_dir.mkdir(parents=True, exist_ok=True)
    if doc is not None:
        # A CHANGED image (hash differs): the stale copy is deleted
        # before replacement.
        _delete_image_copy(doc.image_path)
    copy_path = image_dir / f"{doc_id}{full_path.suffix.lower()}"
    copy_path.write_bytes(data)
    # The non-markdown title rule (the image's content is prose, but the
    # doc IS the image — the file stem is the title).
    title = full_path.stem
    if doc is None:
        doc = Document(
            id=doc_id,
            source=source,
            path=rel,
            full_path=str(full_path),
            title=title,
            content=content,
            content_hash=digest,
            indexed_at=datetime.now(UTC),
            created_at=normalize_doc_date(raw_date),
            is_image=True,
            image_path=str(copy_path),
        )
        session.add(doc)
    else:
        doc.full_path = str(full_path)
        doc.title = title
        doc.content = content
        doc.content_hash = digest
        doc.indexed_at = datetime.now(UTC)
        # Phase 106 (D4): a content change is a new document version —
        # the date is re-sourced and a previous manual correction is
        # reset (it referred to the old content).
        doc.created_at = normalize_doc_date(raw_date)
        doc.created_at_manual = False
        doc.is_image = True
        doc.image_path = str(copy_path)
    session.flush()  # guarantees doc.id even for brand-new rows
    # Phase 1+2 — the UNCHANGED pipeline on the description: chunk,
    # replace the chunk rows (embeddings NULL), embed, and commit the
    # whole file atomically (one transaction per file). The token-cap
    # retry loop is copied from the text path; a description is short,
    # so it never fires in practice.
    target = max(400, settings.chunk_target_chars)
    while True:
        chunks_text = chunk_document(content, rel, target, settings.chunk_overlap_chars)
        doc.chunks = [
            Chunk(document_id=doc.id, position=i, content=c) for i, c in enumerate(chunks_text)
        ]
        session.flush()  # delete-orphan cascade drops the previous rows
        if not doc.chunks:
            break
        try:
            vectors = await llm.embed([c.content for c in doc.chunks])
            for row, vec in zip(doc.chunks, vectors, strict=True):
                row.embedding = vec
            break
        except EmbeddingError as e:
            if "token cap" not in str(e) or target <= 400:
                raise
            logger.info(
                "import: re-chunking at %d chars after endpoint token cap: %s",
                target // 2,
                rel,
            )
            target //= 2
    session.commit()
    if verb == "added":
        summary.added += 1
    else:
        summary.updated += 1
    summary.chunks += len(chunks_text)
    logger.info("import: %s source=%s path=%s chunks=%d", verb, source, rel, len(chunks_text))
    # Phase 30 shape on the description — image-aware (task 03, LOCKED
    # A3): the description IS the summary (stored verbatim, no
    # ``lite`` call), so ``doc.summary`` == ``doc.content`` and the
    # ``is_summary`` position −1 chunk mirrors it.
    await _store_summary(
        session, doc=doc, source=source, rel=rel, content=content, llm=llm, summary=summary
    )
 def _prune(
    session: Session,
    source_names: set[str],
    seen: set[tuple[str, str]],
    images: bool = False,
 ) -> int:
    """Delete documents of *source_names* whose file is no longer in *seen*.
    *images* (phase 122 prune guard, LOCKED, derived from A3/A4): while
    the image toggle is OFF (``images`` False), every ``is_image`` doc is
    SKIPPED — the image is invisible to an images-off walk, not a deleted
    file, so pruning it would silently destroy image documents on the
    first images-off sync. Toggle ON → normal semantics: a deleted image
    file prunes its doc, and the pruned image's ``image_dir`` copy is
    deleted with it.
    """
    if not source_names:
        return 0
    pruned = 0
    docs = session.scalars(select(Document).where(Document.source.in_(source_names))).all()
    for doc in docs:
        if (doc.source, doc.path) not in seen:
            if doc.is_image and not images:
                # Prune guard: invisible to the walk, not deleted.
                continue
            _delete_image_copy(doc.image_path)
            session.delete(doc)
            pruned += 1
            logger.info("import: pruned source=%s path=%s", doc.source, doc.path)
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
ducoterra	bef24e05e2	phase: 123_chat_image_questions Build and Push Containers / build-and-push-app (push) Successful in 1m54s Details Build and Push Containers / build-and-push-db (push) Failing after 13s Details All gates green. Verification complete. Phase 123 — final verification pass (all 4 tasks already in `complete/`) - Verified the full implementation is in the working tree: `app/api/chat_images.py` (upload/serve pair), `ChatRequest.image`/`ChatMessage.image` (path-validated, omitted-when-None), toggle-off + stale-file hinted error frames, `build_user_content` multimodal build at both sites (chat.py deflected branch + `run_agent`), config-gated composer attach/preview/upload-then-send, restore + shared rendering, CSP `img-src 'self' data:` carve-out, mock-LLM capture buffer. - `uv run pytest` → 2796 passed, exit 0 (unit + integration). - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (29/4615 missed; phase-123 modules 99–100%). - `uv run pytest tests/e2e/test_chat_image_questions.py -v --no-cov` → 5 passed in isolation. - `uv run ruff check . && uv run pyright` → clean (0 errors). Completion criteria: (1) attach→send→multimodal text+image to the model, bubble/reload/shared all render it, saved chat stores the PATH with `"base64" not in json.dumps(stored)` — verified (E2E tests 1–4 + integration round-trip); (2) `BOR_IMAGES=false` — control hidden, exact hinted error frame, zero model calls / no query_log row — verified (E2E test 5 + integration); (3) text-only byte-identical (`content` stays a plain `str`) — verified (unit + integration); (4) all gates green — verified; (5) commit + phase move — left to the harness per pipeline rules (no `git add`/`commit` run). No defects found; no live-infrastructure changes (repo + local dev DB only). Next pending phase: none — 123 is the last phase in `todo/`.	2026-09-25 05:19:18 -04:00
ducoterra	a19d78d284	phase: 122_image_documents Build and Push Containers / build-and-push-app (push) Successful in 1m57s Details Build and Push Containers / build-and-push-db (push) Failing after 13s Details Phase 122 (image documents) — final verification pass: all green. No code changes were needed; defects found: none. Verified (implementation already complete in working tree, reviewed end-to-end): - Toggle (`BOR_IMAGES`/`BOR_IMAGE_EXTENSIONS`/`BOR_IMAGE_DIR`, off by default) + `GET /api/config` `images` flag - Ingest: bytes digest, `image_dir` persistent copy, `content = summary = vision description` (chat-model call; only text embedded), fail-soft skip + `images_failed` counter - Serve/display: `/api/documents/{id}/image` route (404 matrix), viewer `<img>` + description, Sources 48px lazy thumbnails, chat inline source figure (alt = summary), agent `read` marker - Prune guard: images-off syncs never prune `is_image` docs Test / lint / coverage (exact commands & outcomes): - `uv run pytest` → exit 0 (green; note: pytest 9.1.1 `-q` omits the final count line in output — exit code authoritative) - `uv run pytest --cov=app --cov-report=term-missing` → 2715 passed, exit 0, TOTAL 99% (>90% gate) - `uv run ruff check . && uv run pyright` → "All checks passed!" / "0 errors, 0 warnings, 0 informations" - `uv run pytest tests/e2e/test_image_documents.py -v --no-cov` → 4 passed, exit 0 (isolation) Completion criteria: (1) images=true → described/embedded/displayed docs: ✅ (E2E + integration) · (2) images=false byte-identical + image docs survive sync: ✅ (E2E negative app + unit/integration) · (3) viewer + chat rendering with alt text; failed description skips + logs, sync completes: ✅ · (4) test/lint/coverage gates: ✅ · (5) commit + phase move: deferred to harness per this pass's rules (working tree left uncommitted). Notable deviation (pre-existing, documented in code): image route uses `require_user` (phase-79 posture, same gate as the document content endpoint) rather than the phase text's "public" parenthetical — matches the endpoint it mirrors. Next pending phase: `123_chat_image_questions`.	2026-09-25 01:54:23 -04:00
ducoterra	0f77e9a876	phase: 121_git_source_tokens Build and Push Containers / build-and-push-app (push) Successful in 2m3s Details Build and Push Containers / build-and-push-db (push) Failing after 14s Details Phase 121 final verification pass — all green (all 4 tasks already in `complete/`; verified, no defects found, no changes needed) - Verified implementation vs phase design: migration `0021` (reversible, round-tripped via `alembic downgrade base` + `upgrade head` → head `0021`), `GitSource.token` column, `normalize_credential`/`clone_url_for`/`sanitize_url`, clone callers switched (`sync.py`, `import_docs.py`), masked token fields in add form + editor, `extra="forbid"` output shapes - Tests: `uv run pytest` → 2662 passed, 0 failed (exit 0); `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (≥90% gate) - Lint/types: `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings - E2E in isolation: `uv run pytest tests/e2e/test_git_source_tokens.py -v --no-cov` → 4 passed Completion criteria: 1. Private repo (UI add or pasted embedded-token URL) clones with injected token; token absent from every API response, page text, title attr, and full HTML — PASS (integration raw-JSON assertions + E2E `_assert_token_nowhere`) 2. Legacy embedded-token rows still clone from stored URL; output sanitized — PASS (`test_sync_legacy_row_clones_with_original_stored_url`, `test_get_masks_legacy_embedded_token_row`, env-fallback masking) 3. Public/local sources byte-identical — PASS (verbatim-URL + no-userinfo-unchanged tests) 4. pytest / coverage / ruff / pyright — PASS (see above) 5. Commit + phase move — harness responsibility; task files already in `complete/`, changes left in working tree (no commit made, per protocol) Notable: no deviations; DB left at head, functional. Next pending phase: 122_image_documents (then 123_chat_image_questions).	2026-09-24 20:51:39 -04:00
ducoterra	3a0fc3db05	phase: 120_failed_turn_retry Build and Push Containers / build-and-push-app (push) Successful in 3m5s Details Build and Push Containers / build-and-push-db (push) Failing after 2m13s Details All verification complete. Final report: Phase 120 — Failed-turn retry: verification pass (all 3 tasks were done; final verification + 1 regression fix) Verified: `ChatMessage.failed`/`error` (≤500, `extra="forbid"` intact); `finalizeFailedTurn` funnel on the 3 failure paths (catch-else, stream-drop guard, zero-frame fallback) with `failed: true` + capped detail + `markLastRetryable`; `appendFailedNote` restore branch (Save-as-doc/Tune excluded); `showErrorBanner`/`retryLastTurn` byte-pinned untouched; only the three paths persist `failed: true` (grep + unit pin); no test asserts the old broken behavior. Defect found & fixed (rule 7): a real navigate-away mid-turn let the browser's teardown fetch rejection (TypeError, not AbortError) leak into the failed funnel, persisting a phantom failed brain record — `test_sources_midstream_bug.py::test_no_orphan_brain_message_when_navigated_before_first_token` failed (2 `.msg` after reload) and violated the phase-20 navigate-away convention. Fixed: turn-scoped `leftThePage` flag (set unconditionally on `pagehide`, reset in `runTurn`) skips the funnel in the catch-else branch; pinned by new unit test `test_navigate_away_is_not_a_failed_turn`. No phase-overview/PLAN/todo/complete files touched; no commits made. Gates (exact): - `uv run pytest` → 2577 passed - `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 4271 stmts, 99% (>90%) - `uv run pytest tests/e2e/test_failed_turn_retry.py -v --no-cov` → 4 passed (isolated) - `uv run ruff check . && uv run pyright` → clean (0 errors) - Regression E2E, isolated: `test_sources_midstream_bug.py` 6/6 (was 5/6); `test_llm_retry`/`test_tool_scaffolding_guardrails`/`test_stop_generation`/`test_navbar_refresh` 17/17 Completion criteria: (1) network error → banner + in-bubble Retry, re-ask without re-typing ✅ (E2E A); (2) refresh restores failed bubble + working Retry, no "new chat" ✅ (E2E C); (3) stopped/successful turns byte-identical ✅ (negative E2E, stop suite, byte-identity units); (4) pytest/coverage/lint/types ✅; (5) commit + phase move — left to the harness per pass rules. Notable: deviation = the regression fix above (a navigation is not a failed turn; phase-20 partial-persist convention restored). Next pending phase: `121_git_source_tokens`.	2026-09-24 18:50:36 -04:00
ducoterra	0ff1f8c4d6	chore(agent): phase roadmap from TODO.md — 4 phases (120–123) Protocol B append: failed-turn retry (L3–4), git source tokens (L5), image documents (L6 ingest), chat image questions (L6 chat side). TODO.md items now live in .agents/phases/todo/ and the file is cleared. LLM-Generated: true	2026-09-24 16:27:44 -04:00