phase: 194_sync_pending_count

**Phase 194 — final verification pass: all green.**

**Verified (all 5 tasks already complete; nothing re-implemented needed)**
- `app/rag/importer.py`: `_prescan_pending` + `_pending_hash_stmt` (scalar `documents.file_hash`, own session, ONE `asyncio.to_thread` span, REPLACES the stats pre-walk), `on_scan_progress`, `progress` pair = pending position, `0` branch = byte-identical phase-193 walk.
- `app/config.py`/`settings_catalog.py`/`.env.example`: `sync_pending_count=1` + validator; `app/api/sync.py`: `"scan"` phase, `scan_done`/`scan_total` (additive after `files_total`, kept at every terminal), forced/throttled RSS split; `frontend/assets/sources.js`: `fmtSyncPhaseLabel` scan branch first-arm, `fmtSyncLabel` untouched.

**Tests / lint / coverage (exact commands)**
- `uv run pytest --cov=app --cov-report=term-missing` → **4835 passed**, `app/` 99% (7240 stmts / 16 miss), exit 0
- `uv run pytest tests/e2e/test_sync_pending_count.py -v --no-cov` → **8 passed in 150.81s** (phase suite, isolated)
- 14 sync-lineage E2E suites, one pytest process each (`test_sync_remaining_count`, `…_chunk_progress`, `…_progress_box`, `…_peak_memory_visible`, `…_label_mobile`, `…_upload_progress`, `test_archive_upload_sources`, `…_image_progress`, `…_summary_visibility`, `…_status_freshness`, `test_smoke`, `test_fast_path_deferred_content`, `test_sync_session_reset`, `test_sync_git_freeze`) → **all exit 0**
- `uv run ruff check .` → All checks passed; `uv run pyright` → **0 errors**

**Completion criteria** — all met: `N remaining` = predicted change set (E2E arms 1/2/5, first import counts the walk, no-change → no count part); `scan` phase visible + flips to `import`, scan pair reset/kept at terminals (`test_sync_scan_phase.py`); `BOR_SYNC_PENDING_COUNT=0` walk semantics ("7 remaining" arm) + **negative refuses startup naming the field (verified live by importing `app.main`)**; pre-scan off-loop + cancel lands `cancelled` (integration pins); CLI/upload byte-identical (unedited pins green); payload additive (`_PRE_187_STATUS_KEYS | _MEMORY_KEYS | _SCAN_KEYS`); suite green, coverage >90%, lint/types clean.

**Documentation** — 3 fixes: README sync "States" bullet had an **unclosed parenthesis** (pre-existing, 193/194) and the scan-label "total is 0" clause was ambiguous about a `=0` run (it still counts the walk once the import starts); **AGENTS.md rule 17 had a stray `)`** (pre-existing from phase 191). Also verified consistency both directions for all 87 settings ↔ README ↔ `.env.example` ↔ settings catalog, the pages table ↔ `app/main.py` routes, no stale `BOR_` names, and README/AGENTS claims through phase 194.

**Notes/deviations** — no live-infra changes (prod sync knob ships default-on, no deployment touched); no git index/history commands run (all changes left in the working tree for the harness); commit criterion left to the harness as instructed.

**Next pending phase:** none — `.agents/phases/todo/` holds only `194_sync_pending_count`, which is now ready to move to `complete/`.

.agents/PLAN.md

@@ -59,6 +59,7 @@ accounts (one admin + hand-out tokens is the model).
 | A18 | Docs push | Save-a-answer-as-doc: server-side draft (`doc_drafts`, long body never in a URL — unguessable `uuid4` token is the URL credential) pushed to a **generic git remote** (`BOR_DOCS_REPO`, URL or local path; no `gh`) on a dedicated branch, `--ff-only`, re-cut per push; **no PR tooling**; inert (hidden + 409) while the repo is unset |
 | A19 | Deploys & caching | HTML pages `Cache-Control: no-cache` (no etag/last-modified); `/assets/*` versioned (`?v=<token>`) + `immutable, max-age=1y`; **the token is the deploy** (git `HEAD` short SHA; content-hash fallback) — a deploy is a commit the browser sees without a hard refresh |
 | A20 | Security headers | Every response: `Content-Security-Policy: default-src 'self'` (+ the theme's inline-`<style>` hash on themed pages), `frame-ancestors 'none'`, `X-Content-Type-Options: nosniff`; login rate-limited 10 attempts / 15 min (in-memory, A12) |
+| A21 | LLM call economics | **ALL LLM calls are free** (chat, vision, embed, `lite` — self-hosted aipi): the sync/import path may burn as many LLM/vision calls as quality requires — e.g. render + describe **every** sparse page of a pictorial PDF, no page caps, no call budgets (owner 2026-09-30). Latency targets bind the **interactive** path only (retrieval, inference, tool calling — the inference engine's job, not ours to micro-optimize): never cap, throttle, or skip work to save calls; a slower sync is acceptable, a lower-quality KB is not |
 
 **UI/theming anchors (B):**
 
@@ -70,14 +71,38 @@ accounts (one admin + hand-out tokens is the model).
 | B5 | Admin-only nav views (Sources, Git sources, Tuning, History, Tokens, Theme) are hidden from non-admins; a monochrome theme must keep every state **text** label ("text + color, never color alone") |
 
 **Key recent revisions (full log in the previous plan revision / phase
-records):** A10 — single-admin cookie auth, saved chats + shares +
-staleness, client history budgets, access tokens.
+records):** A21 — ALL LLM calls (chat, vision, embed, lite) are free for
+this project (owner 2026-09-30): import/sync may burn unlimited
+LLM/vision calls for quality (e.g. every page of a 500+ page pictorial
+PDF, rendered + described); sync duration is not an optimization target,
+interactive-path speed is the inference engine's job. A10 — single-admin
+cookie auth, saved chats + shares + staleness, client history budgets,
+access tokens.
 A15 — `thinking`, `tool`, unlimited tool rounds under
 `BOR_AGENT_MAX_ROUNDS`, `retry`, harness-aligned
 `ls`/`read`/`grep` surface. A7 — the **retrieval** path's
 never-truncated contract is unchanged; the `read`-tool cap is
 the only exception, owner-permitted 2026-09-10.
 
+Phase 182 (verbatim text display, owner chat 2026-10-14) adds
+**`show_text(path, offset?, limit?)` as the fifth agent tool** — offered
+only when `BOR_ANSWER_TEXT=1` (the default), gated exactly like
+`show_image`, with its own `<tools>` clause and its own kill switch — and
+the **additive `done.answer_text`** field above. The new settings are
+`BOR_ANSWER_TEXT` (master switch, ON), `BOR_SHOW_TEXT_MAX_CHARS` (per-block
+budget, 12 000) and `BOR_SHOW_TEXT_MAX_BLOCKS` (per-answer budget, 5), all
+following the `agent_max_rounds` pattern (`0` inert, negative refuses
+startup). The principle in one sentence: **the model points, the server
+supplies the bytes** — a ` ```bor source/path 12-40 ` fence or a
+`show_text` call names a location (canonical locator `source/path` or
+`source/path#start-end`, 1-based and inclusive), and the displayed text is
+sliced from `documents.content` server-side, so what the user copies is the
+knowledge base, never a re-typed approximation. **A1–A6 and A15 are
+otherwise
+UNCHANGED:** no new SSE event type, no new table or column, no new model,
+endpoint or transport, no change to retrieval, the honesty gate, the
+persona text or the embedding dimension.
+
 ---
 
 ## 3. High-Level Architecture
@@ -123,7 +148,9 @@ POST /api/chat {message, history?}   (auth: require_user)
   → cosine top-100 ∪ FTS top-30 → RRF fuse (k=60)     [A7]
   ├─ HIGH (cosine ≥ 0.62 OR fts_hits > 0):
   │    persona + <knowledge_base> + <tuning> + full top-2 <documents>
-  │    + <tools> → agent loop (ls/read/grep; round-capped
+  │    + <tools> → agent loop (ls/read/grep, plus show_image when
+  │    BOR_ANSWER_IMAGES=1 and show_text when BOR_ANSWER_TEXT=1 — the two
+  │    "show the user an artifact" tools, gated independently; round-capped
   │    BOR_AGENT_MAX_ROUNDS=10, 0 = tools off) → turbo streamed
   └─ LOW (A8): DEFLECT_MODE prompt (weak titles only, no tools,
        byte-identical direct-stream path) → turbo streamed
@@ -133,8 +160,20 @@ POST /api/chat {message, history?}   (auth: require_user)
 SSE frames (`data: <json>\n\n`): `thinking` (before first delta) →
 `tool` (grounded turns, one per model call) → `retry` (pre-first-frame
 restarts) → `delta` (answer tokens) → `done` `{deflected, sources[],
-suggestions[]}` (terminal). Failure: `error` (terminal — no `done`, no
-`query_log` row; a pre-stream DB outage is a plain 503 JSON).
+suggestions[], budget_exhausted?, answer_text[]?}` (terminal). **Phase 182
+extends the `done` frame ADDITIVELY** — `answer_text` is the list of
+server-resolved verbatim blocks (`locator`, `source`, `path`, `start`,
+`end`, `total_lines`, `text`, `format`, `truncated`) the answer displayed;
+there is **no eighth event type**, the key is OMITTED when no block was
+displayed, and with `BOR_ANSWER_TEXT=0` it is absent on every turn (the
+frame is then byte-identical to pre-phase). The same array persists on the
+saved chat record, so restore and the anonymous shared page re-render the
+panels from the server's bytes. Failure: `error` (terminal — no `done`, no
+`query_log` row; a pre-stream DB outage is a plain 503 JSON). A
+`tools=None` request never emits a `tool` frame; a round-capped turn
+whose final reply carries no visible content answers with the budget
+fallback instead of erroring (phase 160, recorded revision of the
+phase-71 cap-path terminal, owner-confirmed 2026-10-05).
 `BOR_STREAM_THINKING=0` suppresses `thinking` frames server-side (chars
 still counted). LLM retries (A15 extension): retry count and delay are
 configurable (defaults: 3 retries, 5 s flat delay), **only before a
@@ -262,8 +301,12 @@ scripts.…`, and tests all honor it.
   ```
   question=… embed_ms=… top_score=… fts_hits=… summary_hits=… tuning=N
   kb_chars=N history_msgs=N threshold=… deflected=… sources=…
-  thinking_chars=… tool_calls=N total_ms=… retries=N scaffold_stripped=N
+  thinking_chars=… tool_calls=N rounds=N cap_hit=0|1 total_ms=…
+  retries=N scaffold_stripped=N verbatim_blocks=N
   ```
+  (`verbatim_blocks=` — phase 182 — is the count of verbatim display blocks
+  actually SENT on the `done` frame, `0` on every turn without them,
+  deflected included.)
   (`sources=` = retrieval + agent-read docs, deduped; `tool_calls=`
   executed only; a cancelled turn writes neither line nor `query_log`
   row.)

.agents/phases/complete/124_image_chips_and_answers/00_phase.md

@@ -0,0 +1,56 @@
+# Phase 124 — Image chips and answers: retrieved images earn their source chips, and the LLM can show a supporting image in the answer
+
+**Source:** `TODO.md` L3 — "Image support is working but images don't show up as sources in the sources chips. I also want the chat to be able to show images as answers, so if there's a supporting image with the answer rather than summarizing it alone the supporting image should be shown in the chat if the model thinks it would be effective. Note this will require some relevancy tuning since we don't want to just show every image that seems relevant. The LLM will need to decide when to show an image based on whether it contains the answer. Summaries should still be provided, and showing images as answers in chat should be a feature toggle in .env."
+**Story:** n/a (feature request + bug report; completes the phase-122 image capability on the chat side).
+**Context:** Phase 122 (`122_image_documents`, complete) — the image-doc pipeline: `BOR_IMAGES` toggle (`app/config.py` L379), `Document.is_image`/`image_path` (L153), the vision description as content+summary, `GET /api/documents/{id}/image` bytes route (`app/api/docs.py` L247), the ext→mime map, and `source_ref_with_image` (`app/rag/retriever.py` L945 — the shared ref builder that already puts `image_url` on image docs' cited + related refs). Phase 119 (complete) — the cited tier is the agent's READ DOCS only (`app/api/chat.py` L1040-1046, the deduped `holder.read_docs`). Phase 118 — the `<documents>` seed blocks carry the top-N suggested docs' SUMMARIES (`app/rag/prompts.py` `build_high_prompt`, `SUGGEST_INTRO`); for an image doc the summary IS the content (the vision description) — a seeded image doc is already 100% in the prompt. The agent surface: `AGENT_TOOLS` (the harness-aligned `ls`/`read`/`grep`, `app/rag/agent.py` L264), `_execute_tool` (L1193 — the read branch L1257-1328: `_resolve_path` L1037, the phase-72 `_no_document_refusal` L1098, the `IMAGE_DOC_MARKER` L438, the `Document …`/`date:` result header contract), `AgentHolder` (L1144 — `read_docs`/`tool_calls`/`read_truncations`), `run_agent` (L~1393 — the tools wiring L1490: `tools = AGENT_TOOLS if max_rounds > 0 else None`). The frames: `ChatDoneEvent` (`app/schemas.py` L236 — `deflected`/`sources`/`related`/`suggestions`; `SourceRef` L124 with the None-`image_url`-omitting serializer L159-164), the done-frame build in `app/api/chat.py` L1119-1133. Persistence: `ChatMessage` (L892, `extra="forbid"` — the brain-record meta keys, `sources`/`related` capped lists, the phase-113 lesson that a done-time auto-save key missing from the model 422s silently). Frontend: `frontend/assets/app.js` — the `done` handler (L2981+: `appendSources(wrap, ev.sources)` L2999, the `rememberBrainTurn` save point L3015+), `renderStoredMessage` (L1856 — the brain branch's `appendSources(wrap, m.sources)` L1904), `appendSourceImageFigure` (L1677 — the phase-122 chip figure, the collapse-on-error + `fetchContentSummary` alt pattern to reuse, L1716), `addMessage` (L948). `frontend/assets/shared.js` — the shared page's fragment builders (the brain branch L354+, `addSources` L274 — the phase-123 user-image renderer L329+ is the closest precedent). `frontend/assets/styles.css` — `.source-image` family (L784-815) the answer-figure styling extends. E2E tooling: `tests/e2e/mock_llm.py` (the marker-driven mock — `IMAGE_DESCRIPTION_MODE` L~33, the `use your tools` scripted-`read` trigger L~100, the `<documents>` block tail-echo parser), `tests/e2e/test_image_documents.py` (the module-apps pattern with `BOR_IMAGES` on/off L88-186, the fixture archive L201+, the upload/sync helpers L237+, and — the diagnosis pin — the comment at L62-64: a zero-read grounded turn chips NOTHING, so the suite had to script a mock `read` to earn the image doc's chip).
+
+## Objective
+Two gaps in the phase-122/123 image capability, closed in one phase: (1) the **bug** — a retrieved image document effectively never shows up as a source chip, because the cited tier is read-docs-only and a real model never `read`s an image doc (its seed block already carries its entire content); fix it deterministically by auto-citing suggested-tier image docs. (2) the **feature** — the LLM can show a standalone image document as part of its answer: a new `show_image` tool it calls only when the image itself contains the answer (the relevance gate is the model's decision, taught in the tool description + prompt clause — never every merely-relevant image), the text answer/summary is still provided in full, one image per answer, all behind a new `BOR_ANSWER_IMAGES` `.env` toggle that defaults to false.
+
+## Dependencies
+- `123_chat_image_questions` (complete) — pipeline predecessor (execution order) and code dependency: the `BOR_IMAGES`/image-extension/mime conventions (this phase's toggle and tool follow them), `Document.is_image`, the image bytes route, and `source_ref_with_image` (the answer-image ref is built by it).
+- Code dependencies (all complete): phase 118 summary seeding, phase 119 read-docs citation tier, phase 37/70 the agent tool loop, phase 113 the brain-record meta persistence, phase 51 shared chats, phase 122 the image-doc pipeline.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Root cause (task 05, the bug):** since phase 119 (LOCKED A1) `done.sources` = the agent's `holder.read_docs` deduped by `(source, path)` — a zero-read grounded turn chips nothing. For an image document the seed block (`SUGGEST_INTRO` + `<document>` block) carries its summary — which IS its entire content (the vision description; content == summary by construction, phase 122 task 03). Reading it would add only the marker line. A real model therefore never reads it → the chip never appears (the phase-122 E2E had to script a mock `read` — `test_image_documents.py` L62-64 — the live-app confirmation the owner saw). The fix is deterministic and server-side: **an image doc in the suggested (seed) tier is auto-cited** — in `app/api/chat.py`'s `cited_docs` build (L1040-1046), after the read-docs loop, merge the `is_image` members of `plan.suggested_docs` into `cited_docs` (deduped against the read docs via `cited_seen`, suggestion order; grounded turns only — a deflected turn cites nothing, unchanged). Rationale: for an image doc "suggested" ≡ "read" — the model already has 100% of its content, so the phase-119 cite discipline ("cite the document you answered from") is honored, not weakened. Consequences: auto-cited image docs leave the related tier (`related_refs` already excludes `cited_seen` members, L1123-1127 — no duplicate figure); the `query_log`/log-line `sources=` field is untouched (it logs `record_docs`, which already includes suggested docs). An image doc ranking beyond the suggested set is unchanged — it stays in the "Nearby docs" row, where its figure already renders (phase 122 task 05).
+- **Toggle (task 01, LOCKED A2):** one new `Settings` field — `answer_images: bool = False` (`BOR_ANSWER_IMAGES`, the phase-67 `llm_retries`/phase-122 `images` bool style; `1`/`true` on). A SEPARATE knob from `images` (`BOR_IMAGES`): indexing image docs and showing them in answers are independent owner decisions — `BOR_ANSWER_IMAGES=true` with `BOR_IMAGES=false` is a coherent (if image-less) state: the tool is offered, finds no image docs, and always refuses. `.env.example` documents it beside the existing image block (L124-136). Off = byte-identical everywhere: no 4th tool offered, no prompt clause, no `answer_image` key in any frame or record.
+- **The tool (task 02, LOCKED A3/A5):** a 4th agent tool `show_image(path)` — same harness shape as the other three (one string argument, the combined `source/path` identity). It is OFFERED only when `settings.answer_images` is true: `run_agent`'s tools wiring (L1490) becomes `tools = agent_tools(settings) if max_rounds > 0 else None`, where `agent_tools` returns the three base tools + `show_image` when the toggle is on (the base three stay a byte-identical list — the E2E mock does not inspect the tools array, but the offer gating is the feature's server-side gate). The description carries the RELEVANCE GATE (A5 — "we don't want to just show every image that seems relevant"): call it ONLY when the image itself contains the answer — a diagram, screenshot, or photo of the thing the user asked about — never for mere topical relevance; at most ONE image per answer; the text answer is still given in full (the image supplements, never replaces — "summaries should still be provided"). Handler (a `call.name == "show_image"` branch in `_execute_tool`, before the unknown-tool fallback): missing/empty `path` → the `MISSING_SHOW_ARGS` refusal (the `MISSING_READ_ARGS` shape); unresolvable arg → the phase-72 `_no_document_refusal` teaching (same as read); a resolvable NON-image doc → the `NOT_AN_IMAGE_DOC` refusal ("not an image document — only standalone image documents can be shown" — a text doc's `show_image` is refused, not silently converted to a read); a second call in the same turn → the `ALREADY_SHOWING` refusal (A3 — one image per answer, enforced server-side, not just taught). Refusals count in nothing and consume a round, exactly like every other refusal. Success: `holder.tool_calls += 1`, the doc appended to the NEW `AgentHolder.shown_images: list[Document]` field (the API layer's read-after-stream signal, the `read_docs` precedent), and a result that CONFIRMS the show and carries the doc block so the model verifies before finalizing — a first line `Image shown to the user — it is now part of your answer.`, then the read-result document block for the image doc (`Document {source}/{path}:` header + `date:` line + `IMAGE_DOC_MARKER` + the description — an image doc's content is the summary-capped description, always short, so no truncation machinery; the mock's `_READ_RESULT_PREFIX` header contract is unaffected because that contract is pinned on `read` results).
+- **Prompt (task 03, LOCKED A5):** the `TOOLS_SECTION` constant stays BYTE-IDENTICAL; `build_high_prompt` gains the clause only when its caller passes the toggle on — a new `show_image: bool = False` parameter (default keeps every existing call byte-identical; `app/api/chat.py` passes `settings.answer_images`). The clause is appended INSIDE the `<tools>` section (after the existing three-tool copy, before `</tools>`), so the E2E mock's `<tools>`-presence keying is untouched and the clause rides the grounded HIGH prompt only — the deflection prompt (no tools, ever) is unchanged. The clause teaches the same gate as the tool description, plus the image-doc nature: the text of an image doc in a `<documents>` block or a `read` result is a description GENERATED from the image; show the image when THAT is what the user actually wants to see (the thing they asked about, in picture form); one image per answer; answer fully in text either way.
+- **Frame + persistence (task 04):** `ChatDoneEvent` gains `answer_image: SourceRef | None = None` — the shown doc's ref, built by the SAME `source_ref_with_image` (source/path/title + `image_url`). A `model_serializer(mode="wrap")` on `ChatDoneEvent` DROPS `answer_image` from the dumped dict when it is `None` (the `SourceRef._serialize` None-omission precedent) — without it, `model_dump()` would add `"answer_image": null` to every turn's frame and break the byte-identical-off contract. `ChatMessage` gains `answer_image: SourceRef | None = None` (brain records only — the user record's phase-123 `image` key, the stored PATH string, is untouched and distinct). This is the phase-113 lesson applied up front: the done-time auto-save carries the key, and a `extra="forbid"` model missing it would 422 every grounded brain record silently (the A2 quiet-failure path) — the integration suite pins the round-trip. `app/api/chat.py`'s done-frame build (L1119-1133) passes `answer_image=source_ref_with_image(holder.shown_images[0]) if holder.shown_images else None`.
+- **UI (task 06):** the `done` handler (app.js L2981+) renders `ev.answer_image` as a prominent ANSWER FIGURE in the brain bubble's `.msg-body` — appended right BEFORE `appendSources` so it sits below the answer text, above the source-chip row (a new `appendAnswerImage(wrap, ref)` helper, distinct from the compact chip figure `appendSourceImageFigure` — the answer image is a first-class part of the answer, styled larger). The figure: `<figure class="answer-image">` with a lazy `<img>` (`loading="lazy"`, `src = ref.image_url`, the public bytes route), `alt` = `ref.title` immediately and swapped to the doc's summary via the SAME `fetchContentSummary` pattern (L1716 — the phase-122 WCAG alt contract); an `img` error REMOVES the figure (the collapse-to-nothing rule — an answer with a lost image renders as a normal answer, never a broken icon; the chip row below still cites the doc). The figure reuses the chip navigation affordance (the `documentUrl` href as the no-JS escape hatch; left-click → the same-page document modal, phase 26) — it is a link to the image document. Persistence: the `rememberBrainTurn` meta gains `answer_image: ev.answer_image || undefined` (the house undefined-drops-the-key pattern — pre-phase and image-less turns store byte-identical records). Restore: `renderStoredMessage`'s brain branch renders `m.answer_image` through the SAME helper before `appendSources(wrap, m.sources)` (L1904) — the refresh lands pixel-identical. Shared page: `shared.js`'s brain fragment builder renders it the same way (the bytes route is public — a shared chat is faithful, the phase-123 user-image precedent). CSS: `.answer-image` / `.answer-image-img` in the `.source-image` family's language (`.source-image-img` L793: the bordered-image treatment) but larger — the answer figure is not a chip accessory: max-width 100% of the bubble, a capped max-height (≈320px), `object-fit: contain`, theme-aware border/background, a caption line (the summary, the `.source-image-caption` styling) — the theme's image treatment, WCAG contrast per PLAN §7.
+- **NOT touched:** the image-INGEST pipeline (phase 122), question-image attachment (phase 123), the suggestion/related TIERING math (only the cited-tier composition changes), the honesty gate, the deflection path (no tools, no `answer_image` — a deflected answer never shows an image), history trimming (an `answer_image` rides the stored record, never the model's history — the model's image input remains the phase-123 turn-local contract), and the agent round cap.
+- **Locked assumptions:** **A1** — auto-cite scope = suggested-tier image docs (deeper-ranked ones keep the related-row figure). **A2** — `BOR_ANSWER_IMAGES`, default false, independent of `BOR_IMAGES`. **A3** — one image per answer (server-enforced refusal). **A4** — the answer figure renders in the brain bubble below the text, above the chips; visible on restore and the shared page. **A5** — the relevance gate is the LLM's decision (tool description + prompt clause), no server-side image scoring.
+
+## Tasks
+1. `01_answer_images_toggle.md` — `Settings.answer_images` (`BOR_ANSWER_IMAGES`, default false) + `.env.example` doc; off = byte-identical.
+2. `02_show_image_tool.md` — `agent_tools` gating + the `show_image` handler (refusals, `holder.shown_images`, the confirming result).
+3. `03_prompt_clause.md` — the toggle-gated `show_image` clause in the HIGH prompt's `<tools>` section (base byte-identical).
+4. `04_frame_and_persistence.md` — `ChatDoneEvent.answer_image` (None-omitting serializer) + `ChatMessage.answer_image` + the chat.py done-frame wiring.
+5. `05_auto_cite_image_docs.md` — the bug fix: suggested-tier image docs merge into `cited_docs`.
+6. `06_chat_ui_answer_image.md` — the answer figure: live `done` render, persistence, restore, shared page, CSS.
+7. `07_answer_image_tests.md` — the mock-LLM `show_image` trigger + isolated E2E `test_answer_images.py` + the final coverage gate.
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_chips_and_answers.py` (new, across tasks 01-05) — settings parsing (default false, truthy parsing, independent of `images`); `agent_tools` (off → the three base tools byte-identical; on → + `show_image`); the `show_image` handler (success → `shown_images` appended + `tool_calls` bumped + the confirming result containing the doc block; each refusal: missing args, no-doc teaching, non-image doc, already-showing — none counted); the prompt clause (off → `build_high_prompt` byte-identical to pre-phase; on → the clause inside `<tools>`, base copy byte-identical; the deflection prompt unchanged either way); the `ChatDoneEvent` serializer (`answer_image=None` → key ABSENT from the dump, not null; present → the full ref incl. `image_url`); the auto-cite merge (a suggested image doc + read text docs → cited = reads first then the image doc, deduped; a suggested image doc the agent also read → once; deflected → `[]`; a non-image suggested doc → never auto-cited).
+- Integration: `tests/integration/test_chat_api.py` (extend, task 04) + `tests/integration/test_chats_api.py` (extend, task 04) — a grounded turn whose mock client emits a scripted `show_image` tool call on an image doc → the done frame carries `answer_image` (source/path/title/`image_url`) and the cited tier includes the doc; a toggle-off turn (mock emits the same call — the tool is not offered, so in the mock-driven integration test the frame simply has no `answer_image` and no such call occurs) → the frame dump has NO `answer_image` key and the offer list is the three base tools; the auto-cite integration: a zero-read grounded turn (no tool calls at all) whose suggested tier contains an image doc → the done frame's `sources` include the image ref WITH `image_url` (the bug-fix pin end-to-end) and the related tier excludes it; a saved-chat round-trip: a brain record with `answer_image` persists and serves back (the phase-113 422-silence regression pinned).
+- E2E: `tests/e2e/test_answer_images.py` (new, task 07) — isolated run per AGENTS.md §4; module apps on the `test_image_documents.py` pattern: `BOR_IMAGES=true` + `BOR_ANSWER_IMAGES=true` (the feature) and a second app with `BOR_IMAGES=true` + toggle unset (the default-off contract). Feature flow: upload the fixture image archive → sync → ask the mock's trigger question → the mock scripts ONLY a `show_image` call (NO `read` — the zero-read turn) → the brain bubble shows the ANSWER FIGURE (an `<img>` whose src is the doc's bytes route, visible, not collapsed) AND the source-chip row carries the image doc's chip + figure (the bug fix — a zero-read turn chips it) → reload → the restored bubble shows the figure again → the shared link shows it. Default-off flow: the same question → no answer figure in the DOM, the done frame (via the saved record) carries no `answer_image`, and the mock never sees the tool (assert the recorded request's `tools` has 3 entries).
+- Coverage: **>90%** on `app/` (validate.sh gate); `uv run ruff check . && uv run pyright` clean.
+
+## Completion Criteria
+- [ ] With `BOR_IMAGES=true` (any `BOR_ANSWER_IMAGES`): a retrieved image doc in the suggested tier appears in the sources chips WITH its figure on a zero-read grounded turn — no scripted `read` needed (the phase-122 E2E's scripted `read` remains valid but is no longer load-bearing for the chip).
+- [ ] With `BOR_IMAGES=true` + `BOR_ANSWER_IMAGES=true`: the LLM can call `show_image` on an image doc; the answer figure renders in the bubble (below the text, above the chips) with the summary as alt/caption; the answer text is still streamed in full; a second `show_image` call is refused; the record persists the figure and restore + the shared page render it.
+- [ ] With `BOR_ANSWER_IMAGES` unset (the default): no `show_image` tool offered, no prompt clause, no `answer_image` key in any done frame or saved record — every byte-identical contract of completed phases holds.
+- [ ] `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 — auto-cite scope: suggested-tier (seeded) image docs become citation chips; image docs ranked beyond the suggested set stay in the "Nearby docs" row (their figure already renders there) (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A2 — `BOR_ANSWER_IMAGES`, default false, a SEPARATE toggle from `BOR_IMAGES` (indexing) — showing answer images requires image docs to exist but the knobs stay independent (owner-confirmed 2026-09-26).**
+- **A3 — one image per answer: a second `show_image` call in a turn is refused server-side (owner-confirmed 2026-09-26).**
+- **A4 — the answer figure renders in the brain bubble below the answer text, above the source chips; lazy-loaded; collapses on load failure (never a broken icon); alt = the doc's summary; visible on refresh restore and the shared page (owner-confirmed 2026-09-26).**
+- **A5 — the relevance gate is the LLM's decision, taught in the tool description + the prompt clause (show only when the image itself contains the answer — a diagram/screenshot/photo of the thing asked about — never mere topical relevance; the text answer is always provided in full); no server-side image scoring (owner-confirmed 2026-09-26).**
+
+## Commit
+```bash
+git add app/ frontend/ tests/ .env.example .agents/phases/ && git commit --no-gpg-sign -m "feat(chat): image source chips + LLM-chosen answer images behind BOR_ANSWER_IMAGES"
+```

.agents/phases/complete/124_image_chips_and_answers/01_answer_images_toggle.md

@@ -0,0 +1,21 @@
+# Task 01 — The `BOR_ANSWER_IMAGES` feature toggle
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "…and showing images as answers in chat should be a feature toggle in .env."
+**Story:** n/a
+
+## Objective
+A new `Settings.answer_images` field (`BOR_ANSWER_IMAGES`, default **false**) — the single knob that turns the whole answer-image feature on or off (task 02's tool offer, task 03's prompt clause, task 04's frame field all key on it). Off (the default) = byte-identical behavior everywhere.
+
+## Work
+1. `app/config.py` — add `answer_images: bool = False` to `Settings` inside the existing image block (after `chat_image_max_mb`, L413 — the phase-122 `images` field L379 is the style precedent: a docstring stating it gates the ANSWER side only, that it is INDEPENDENT of `images`/`BOR_IMAGES` (indexing image docs vs showing them — A2), and that off = no `show_image` tool, no prompt clause, no `answer_image` frame key). `BOR_`-prefixed, so `BOR_ANSWER_IMAGES=1`/`true` enables it.
+2. `.env.example` — document it beside the existing image block (L124-136): a commented `# BOR_ANSWER_IMAGES=0` line + a two-line comment (off by default; enable alongside `BOR_IMAGES` to let the model show a supporting image in its answer).
+3. ASSUMPTION: none beyond the phase's locked A2 (name, default, independence — owner-confirmed 2026-09-26). Do NOT add an `answer_images` key to `GET /api/config` — the UI is purely reactive (it renders what the done frame carries); there is no client-side affordance to gate, so the phase-122 config-flag precedent does not apply here.
+
+## Testing & Quality
+- Unit: `tests/unit/test_config.py` (extend) or the new `tests/unit/test_image_chips_and_answers.py` (create it here if absent) — `answer_images` defaults to `False`; `BOR_ANSWER_IMAGES=1` / `=true` (the settings loader's accepted truthy forms — mirror the existing `images`/`llm_retries` bool test) parse to `True`; `=0`/`=false`/unset → `False`; setting it does not affect `images` and vice versa.
+- Coverage: **>90%** on this task's new/modified code (a config field — the parsing tests carry it).
+
+## Completion Criteria
+- [ ] `Settings().answer_images is False` with no env; `BOR_ANSWER_IMAGES=1` yields `True`.
+- [ ] `.env.example` documents the new var with the "off by default" comment.
+- [ ] Full test suite green; no behavior change in completed work (no other file reads the field yet).

.agents/phases/complete/124_image_chips_and_answers/02_show_image_tool.md

@@ -0,0 +1,30 @@
+# Task 02 — The `show_image` agent tool (toggle-gated)
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "The LLM will need to decide when to show an image based on whether it contains the answer." + "…we don't want to just show every image that seems relevant." + "Summaries should still be provided"
+**Story:** n/a
+
+## Objective
+The 4th agent tool `show_image(path)` — offered ONLY when `settings.answer_images` is true — by which the LLM decides to show a standalone image document as part of its answer. The tool's description IS the relevance gate (A5); the handler enforces the contract server-side (image docs only, one per answer) and records the shown doc in `holder.shown_images` for task 04's frame.
+
+## Work
+1. `app/rag/agent.py` — the tool definition: keep `AGENT_TOOLS` (L264) as the three base tools, UNCHANGED (byte-identical — existing tests pin its shape); add a new module constant `SHOW_IMAGE_TOOL: dict[str, Any]` (the same OpenAI function shape: `name: "show_image"`, one required string arg `path`) and a function `agent_tools(settings: Settings) -> list[dict[str, Any]]` returning `[...AGENT_TOOLS]` + `SHOW_IMAGE_TOOL` when `settings.answer_images` else `[...AGENT_TOOLS]` (a fresh list each call — never mutate the constant).
+   - The description carries the full gate (A5) in the other tools' voice: "Show a standalone image document to the user as part of your answer. Call it only when the image itself contains the answer — a diagram, screenshot, or photo of the thing the user asked about — never for a merely related image. Show at most one image per answer. The image supplements your text answer — answer fully in text either way. Its `path` is the combined `source/path` string, exactly as shown in the `ls` output or the `<documents>` blocks — a bare document path will not resolve. Call one tool at a time — wait for this result before your next call."
+   - The `path` parameter description mirrors `read`'s (the combined `source/path` contract, the bare-path-will-not-resolve teaching).
+2. `app/rag/agent.py` — the offer gating: `run_agent`'s wiring (L1490) changes from `tools: list[dict[str, Any]] | None = AGENT_TOOLS if max_rounds > 0 else None` to `tools = agent_tools(settings) if max_rounds > 0 else None` (the `max_rounds == 0` kill switch still yields `tools=None`, unchanged; `settings` is already a `run_agent` parameter).
+3. `app/rag/agent.py` — the handler: a `if call.name == "show_image":` branch in `_execute_tool` (L1193), placed after the `read` branch and before the unknown-tool fallback (L1388):
+   - `raw_path = call.arguments.get("path")`; stripped-arg empty → return `MISSING_SHOW_ARGS` (new constant, the `MISSING_READ_ARGS` L388 shape: "show_image requires a string argument 'path'.").
+   - `doc, _source, _path = _resolve_path(db, arg)` (L1037); `doc is None` → `return _no_document_refusal(db, arg)` (the phase-72 "did you mean …?" teaching — same as read).
+   - `not doc.is_image` → `return NOT_AN_IMAGE_DOC` (new constant: "`{arg}` is not an image document — only standalone image documents can be shown as answers." with the arg echo — a text doc is refused, never converted to a read).
+   - `holder.shown_images` non-empty → `return ALREADY_SHOWING` (new constant, the `ALREADY_IN_CONTEXT` L384 shape: "Already showing an image this answer — do not show another one. Answer from what you have." — A3, server-enforced).
+   - Success: `holder.shown_images.append(doc)`; `holder.tool_calls += 1`; return the confirming result — a FIRST LINE `Image shown to the user — it is now part of your answer.` followed by the same document block `read` returns for an image doc at-or-under-cap (L1323-1328): `Document {doc.source}/{doc.path}:\n` + `date: {doc.created_at:%Y-%m-%d}\n` + `IMAGE_DOC_MARKER` + `\n`-handling as there + `{doc.content}` (an image doc's content is the summary-capped vision description — always under `read_max_chars`, so NO truncation machinery; if the content ever exceeded the cap, the plain uncapped block is still correct for this purpose — the description is short by construction, phase 122 task 03). The confirming line is NEW (not in `read`'s result — the model must know the show registered); the `Document …` header contract (the E2E mock's `_READ_RESULT_PREFIX`) is pinned on `read` results and this block deliberately reuses its exact shape.
+4. `app/rag/agent.py` — `AgentHolder` (L1144): add `shown_images: list[Document] = field(default_factory=list)` with a docstring entry (the shown docs, in call order — at most one in practice due to the `ALREADY_SHOWING` refusal; read by `app.api.chat` after the stream for the `answer_image` frame, the `read_docs` precedent).
+5. ASSUMPTION: none beyond the phase's locked A3/A5 (owner-confirmed 2026-09-26). The per-turn log line (PLAN §9) needs no new field: a successful `show_image` is a tool call (`tool_calls=N` already counts it); the `answer_image` frame is task 04's job.
+
+## Testing & Quality
+- Unit (new `tests/unit/test_image_chips_and_answers.py` if task 01 didn't create it, else extend): `agent_tools` — toggle off → exactly the three base tools, equal to `AGENT_TOOLS` element-for-element (and NOT the same list object mutated); toggle on → the fourth tool present with name `show_image`, required `["path"]`, description containing the gate copy ("at most one image", "never for a merely related"); the handler matrix via `_execute_tool` with a temp-DB fixture and a mock `ToolCallPiece` (the existing agent unit-test fixtures): (a) empty/missing `path` → `MISSING_SHOW_ARGS`, `tool_calls` unchanged, `shown_images` empty; (b) unresolvable arg → the `_no_document_refusal` text, nothing counted; (c) a resolved TEXT doc → `NOT_AN_IMAGE_DOC`, nothing counted; (d) a resolved image doc → `shown_images == [doc]`, `tool_calls == 1`, result starts with the confirming line then the `Document {source}/{path}:` header + `date:` line + `IMAGE_DOC_MARKER` + the description; (e) a second call after a success → `ALREADY_SHOWING`, `shown_images` still length 1.
+- Coverage: **>90%** on this task's new/modified code (the handler matrix + `agent_tools` tests carry it).
+
+## Completion Criteria
+- [ ] With `answer_images=False`: `agent_tools(settings)` returns exactly the three base tools and a grounded turn offers no `show_image` (the `run_agent` wiring passes the gated list).
+- [ ] With `answer_images=True`: a scripted `show_image` call on an image doc appends to `holder.shown_images`, bumps `tool_calls`, and returns the confirming result with the doc block; every refusal path counts in nothing and leaves `shown_images` empty/unchanged.
+- [ ] Full test suite green; `AGENT_TOOLS` itself byte-identical (no existing test diffs); no behavior change in completed work.

.agents/phases/complete/124_image_chips_and_answers/03_prompt_clause.md

@@ -0,0 +1,25 @@
+# Task 03 — The `show_image` prompt clause (HIGH prompt, toggle-gated)
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "Note this will require some relevancy tuning since we don't want to just show every image that seems relevant. The LLM will need to decide when to show an image based on whether it contains the answer."
+**Story:** n/a
+
+## Objective
+When the toggle is on, the grounded HIGH prompt teaches the model the `show_image` contract — the relevance gate, the image-doc nature (its text is a GENERATED description), the one-image cap, and "summaries still provided" — as a clause appended inside the locked `<tools>` section. The `TOOLS_SECTION` constant and the whole prompt stay BYTE-IDENTICAL when the toggle is off (every existing `tests/unit/test_prompts.py` pin holds untouched).
+
+## Work
+1. `app/rag/prompts.py` — add a new module constant `SHOW_IMAGE_CLAUSE: str` (the appended copy — written in the `TOOLS_SECTION` voice, referencing the tools by backtick names):
+   "`show_image` displays a standalone image document as part of your answer. The text of an image document — in a <documents> block or a `read` result — is a description GENERATED from the image, not the image's own words. Call `show_image` only when that image is what the user actually wants to see: a diagram, screenshot, or photo of the very thing you are answering about — never for a merely related image, and never to pad an answer. Show at most one image per answer. The image supplements your text — answer fully in text either way."
+2. `app/rag/prompts.py` — `build_high_prompt` (L~437) gains a keyword parameter `show_image: bool = False` (the default keeps EVERY existing call byte-identical — update the docstring: section order unchanged, the clause rides inside `<tools>`). Implementation: the final return currently concatenates `… + "</documents>\n" + TOOLS_SECTION` — with `show_image=False` keep EXACTLY that; with `show_image=True` build the tools section as `TOOLS_SECTION`'s body + the clause: i.e. replace the trailing `TOOLS_SECTION` with the same text minus its final `</tools>`, then the clause, then `</tools>` (the clause lands AFTER the existing three-tool copy and BEFORE the closing tag — do NOT edit `TOOLS_SECTION` itself).
+3. `app/api/chat.py` — the `build_high_prompt` call site (find it where `plan.system_prompt` is assembled for the grounded plan — the retrieval-plan construction; it is the single HIGH-prompt build site) passes `show_image=settings.answer_images`. No other call site changes (tests' direct calls keep the default).
+4. The deflection prompt (`build_deflect_prompt`) is UNTOUCHED — a deflected turn has no tools and never shows an image (the phase's locked design).
+5. ASSUMPTION: none beyond the phase's locked A5 (owner-confirmed 2026-09-26). The clause copy above is the starting text — it must state all four gate elements (image-doc nature / "contains the answer" bar / one per answer / text answer in full); exact wording is the executor's within that constraint (the E2E mock keys on `<tools>` PRESENCE, not wording — `tests/e2e/mock_llm.py`'s documented contract — so a re-wording is safe, but the four elements are not).
+
+## Testing & Quality
+- Unit: `tests/unit/test_prompts.py` (extend) — (a) `build_high_prompt(docs)` (no new arg) → byte-identical to the pre-task output (the existing pins already assert the `TOOLS_SECTION` tail — they must pass UNMODIFIED); (b) `build_high_prompt(docs, show_image=True)` → the output ends with the clause then `</tools>`, the clause contains the four gate elements (assert on stable phrases: "description GENERATED from the image", "at most one image per answer", "answer fully in text"), and the prefix up to the clause is byte-identical to the toggle-off output (the three-tool copy untouched); (c) the clause appears ONLY in the HIGH prompt — `build_deflect_prompt` output is byte-identical with and without the flag's existence (it takes no such flag); (d) with empty `documents` (the "(no documents matched…)" body) + `show_image=True` → the clause still lands inside `<tools>` (the grounded turn may still `ls`/`grep` its way to an image doc and show it).
+- Coverage: **>90%** on this task's new/modified code (the prompt tests carry it — pure string logic).
+
+## Completion Criteria
+- [ ] `build_high_prompt(..., show_image=False)` (and all pre-existing calls) → byte-identical output (existing `test_prompts.py` pins pass unmodified).
+- [ ] `show_image=True` → the clause is inside `<tools>`, after the existing copy, with all four gate elements; the deflection prompt is unchanged.
+- [ ] The grounded plan carries the clause exactly when `settings.answer_images` is true.
+- [ ] Full test suite green; no behavior change in completed work.

.agents/phases/complete/124_image_chips_and_answers/04_frame_and_persistence.md

@@ -0,0 +1,23 @@
+# Task 04 — The `answer_image` done frame + saved-chat persistence
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "…the supporting image should be shown in the chat if the model thinks it would be effective."
+**Story:** n/a
+
+## Objective
+The shown image reaches the client and survives a refresh: `ChatDoneEvent.answer_image` (the shown doc's `SourceRef`, OMITTED from the frame when absent — every toggle-off / image-less turn stays byte-identical) and `ChatMessage.answer_image` (the brain-record key the done-time auto-save persists, restored by task 06).
+
+## Work
+1. `app/schemas.py` — `ChatDoneEvent` (L236): add `answer_image: SourceRef | None = None` with a docstring entry (the shown image document — the LLM's `show_image` pick, phase 124; the brain answer's first-class image, distinct from the user record's question attachment `ChatMessage.image`). Add a `model_serializer(mode="wrap")` to `ChatDoneEvent` (the `SourceRef._serialize` L159-164 precedent): `data = handler(self)`; `if self.answer_image is None: data.pop("answer_image", None)`; return `data` — WITHOUT this, `model_dump()` emits `"answer_image": null` on every frame and the byte-identical-off contract (task 01) is broken.
+2. `app/schemas.py` — `ChatMessage` (L892, `extra="forbid"`): add `answer_image: SourceRef | None = None` (on BRAIN records only — the user record's phase-123 `image: str | None` stored-path field is untouched and semantically distinct; the docstring must say so). This is the phase-113 lesson applied up front: the done-time auto-save (task 06's `rememberBrainTurn`) will carry the key, and a missing field would 422 every grounded brain record on the public `POST/PUT /api/chats` boundary (the A2 quiet-failure path swallows it → grounded turns silently unsaved). No length cap needed — it is a single ref (`SourceRef`'s own field caps bind).
+3. `app/api/chat.py` — the done-frame build (L1119-1133): pass `answer_image=source_ref_with_image(holder.shown_images[0]) if holder.shown_images else None` into `ChatDoneEvent` (the shared ref builder — source/path/title + `image_url` for the image doc; `holder.shown_images` is always empty on deflected turns — they run no agent — so deflected frames omit the key automatically).
+4. ASSUMPTION: none beyond the phase's locked design (owner-confirmed 2026-09-26). The `query_log` row and the per-turn log line are UNCHANGED (the shown doc is a suggested/read doc already inside `record_docs`; `tool_calls` already counts the call — task 02).
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_chips_and_answers.py` (extend) — the `ChatDoneEvent` serializer: `answer_image=None` → `model_dump()` has NO `answer_image` key (assert `"answer_image" not in dump`, and the JSON has no `null` field) and the dump is byte-identical to the pre-phase shape; `answer_image=SourceRef(source=…, path=…, title=…, image_url=…)` → the key present with all four fields; the existing `sources`/`related`/`suggestions` serialization is untouched in both cases. `ChatMessage` boundary: a brain record dict with `answer_image` (full ref shape) parses; with `answer_image=None`/absent parses (pre-phase records); the user record's `image` (str path) still parses independently; an `answer_image` missing `image_url` parses (the field is optional on `SourceRef`) — and the phase-83 value bounds still bind the ref's fields.
+- Integration: `tests/integration/test_chat_api.py` (extend) — (a) a grounded turn whose mock chat client scripts a `show_image` tool call on a seeded image doc (the mock's scripted-tool mechanism, the `use your tools` precedent) → the final SSE `done` frame JSON carries `answer_image` with `image_url == /api/documents/<id>/image` and the cited `sources` include the same doc; (b) the SAME scripted flow with `answer_images=False` settings → no `show_image` in the offered tools (assert on the mock's recorded request `tools` list: 3 entries) and the `done` frame has NO `answer_image` key; (c) a zero-tool grounded turn (no scripted calls) → `done` frame has NO `answer_image` key (byte-identical to pre-phase). `tests/integration/test_chats_api.py` (extend) — the phase-113 regression pin: `POST /api/chats` with a brain record carrying `answer_image` → 201 (NOT a silent 422) and the served chat round-trips the ref byte-for-byte; a record without the key round-trips unchanged.
+- Coverage: **>90%** on this task's new/modified code (serializer + boundary + turn tests carry it).
+
+## Completion Criteria
+- [ ] A turn whose agent called `show_image` → the `done` frame's JSON contains `answer_image` (source/path/title/image_url); every other turn's `done` frame is byte-identical to pre-phase (no key, no null).
+- [ ] A saved chat persists and serves back a brain record with `answer_image`; pre-phase records (no key) round-trip byte-identically.
+- [ ] Full test suite green; no behavior change in completed work.

.agents/phases/complete/124_image_chips_and_answers/05_auto_cite_image_docs.md

@@ -0,0 +1,39 @@
+# Task 05 — Bug fix: suggested-tier image docs earn their source chips
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "Image support is working but images don't show up as sources in the sources chips."
+**Story:** n/a
+
+## Objective
+Close the observed bug deterministically: a retrieved image document in the suggested (seed) tier becomes a citation chip — WITHOUT the agent having to `read` it — because for an image doc the seed block already carries its ENTIRE content (summary == content == the vision description, phase 122 task 03), so "suggested" ≡ "read" and the phase-119 cite discipline is honored, not weakened.
+
+## Work
+1. `app/api/chat.py` — the `cited_docs` build (L1040-1046, currently the deduped `holder.read_docs` loop, the phase-119 read-docs-only contract per the L1027-1038 comment): AFTER that loop, add the auto-cite merge —
+   ```python
+   # Phase 124 (TODO L3): a suggested-tier IMAGE doc's seed block IS its
+   # entire content (content == summary == the vision description) —
+   # "suggested" is equivalent to "read" for it, so it is auto-cited
+   # (the model never needs a read that would add only the marker line).
+   # Grounded turns only — a deflected answer cites nothing (unchanged).
+   if not plan.deflected:
+       for doc in plan.suggested_docs:
+           if not doc.is_image:
+               continue
+           key = (doc.source, doc.path)
+           if key not in cited_seen:
+               cited_seen.add(key)
+               cited_docs.append(doc)
+   ```
+   Order: read docs first (read order, as today), then the auto-cited image docs in SUGGESTION order. Dedup: an image doc the agent also explicitly read is already in `cited_seen` from the first loop — it appears ONCE (at its read position). Update the L1027-1038 comment block to state the phase-124 addition (the read-docs-only rule gains its single documented exception: suggested-tier image docs).
+2. Consequences to VERIFY (assert in tests, not code): (a) the related tier already excludes `cited_seen` members (`related_refs` filter, L1123-1127) — an auto-cited image doc leaves the "Nearby docs" row (no duplicate figure); (b) `record_docs` (L1049-1053, the `query_log.sources` + log-line `sources=` field) already includes `plan.suggested_docs` — the observability fields are UNCHANGED by this task; (c) a non-image suggested doc is never auto-cited (the `is_image` guard — the phase-119 read-docs rule stays intact for text docs: a zero-read text turn still chips nothing).
+3. ASSUMPTION: none beyond the phase's locked A1 (scope = suggested tier only; deeper-ranked image docs keep the related-row figure — owner-confirmed 2026-09-26). No retriever change: `select_suggested`/`select_related` are untouched (the tiering math is out of scope — the fix is in the cited-tier COMPOSITION only).
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_chips_and_answers.py` (extend) — factor the cited-docs merge into a small pure helper if the inline version is untestable in place (the executor's call — prefer a module-level `def merge_cited_docs(read_docs, suggested_docs, deflected: bool) -> list[Document]` in `app/api/chat.py` taking exactly those args, called from the turn pipeline; test the helper directly): (a) suggested image doc + zero reads → it is cited (with its position after reads); (b) suggested image doc + agent also read it → exactly once; (c) suggested TEXT doc + zero reads → NOT cited (phase-119 contract intact); (d) `deflected=True` → `[]` (weak hits cite nothing); (e) two suggested image docs → both, in suggestion order; (f) read order preserved for mixed read text docs.
+- Integration: `tests/integration/test_chat_api.py` (extend) — the end-to-end pin of the bug fix: a grounded turn with NO scripted tool calls (the mock answers straight from the seed) whose suggested tier contains an image doc (seed the KB with the fixture image doc — the image-ON app settings + a mock vision description, the `test_image_documents.py` fixture pattern) → the `done` frame's `sources` include the image ref WITH `image_url` set (the chip + figure data), and `related` does NOT contain the same (source, path). A text-only KB turn → byte-identical `sources` to pre-phase (no auto-cite without image docs).
+- Coverage: **>90%** on this task's new/modified code (the helper matrix + the integration pin carry it).
+
+## Completion Criteria
+- [ ] A zero-read grounded turn whose suggested tier holds an image doc → the sources chips (the `done` frame's `sources`) include the image doc with `image_url` — the phase-122 E2E's scripted `read` is no longer load-bearing for the chip.
+- [ ] Text docs are unaffected: a zero-read text turn chips nothing (phase-119 contract); a deflected turn cites nothing.
+- [ ] No duplicate: an auto-cited image doc does not also appear in the related row.
+- [ ] Full test suite green; `query_log`/log-line `sources=` unchanged; no behavior change in completed work.

.agents/phases/complete/124_image_chips_and_answers/06_chat_ui_answer_image.md

@@ -0,0 +1,27 @@
+# Task 06 — The answer figure: live render, persistence, restore, shared page
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — "…the supporting image should be shown in the chat if the model thinks it would be effective." + "Summaries should still be provided"
+**Story:** n/a
+
+## Objective
+The client renders `answer_image` as a first-class figure in the brain bubble — below the answer text, above the source-chip row (A4) — persists it in the brain record, and restores it on refresh and on the shared page. The answer text is untouched and always rendered (the figure is ADDITIVE — "summaries should still be provided").
+
+## Work
+1. `frontend/assets/app.js` — a new `appendAnswerImage(wrap, ref)` helper (place it near `appendSourceImageFigure`, L1677 — it is its visual sibling but a different surface): build `<figure class="answer-image">` containing a lazy `<img>` (`loading="lazy"`, `src = ref.image_url`, the public bytes route) + a visible caption `<span class="answer-image-caption">`. `alt` = `ref.title` immediately, swapped to the doc's summary via the SAME `fetchContentSummary` pattern (L1716 — the phase-122 WCAG alt contract: a caption is ALWAYS visible, the summary arrives by fetch, any fetch failure keeps the title). An `img` `error` listener REMOVES the whole figure (the collapse rule — an answer whose image bytes are gone renders as a normal answer, never a broken icon; the chip row below still cites the doc). Navigation reuses the chip affordance: the `<figure>` is wrapped/behaves as the `documentUrl(ref.source, ref.path, "/")` href (the no-JS / context-menu escape hatch) with the left-click → same-page document modal (phase 26, the `openDocumentModal` pattern from `appendSources`/`appendSourceImageFigure`).
+2. `frontend/assets/app.js` — the `done` handler (L2981+): right BEFORE `appendSources(wrap, ev.sources)` (L2999), `if (ev.answer_image) appendAnswerImage(wrap, ev.answer_image);` (the figure lands in `.msg-body` above the `.msg-meta` chip row — position per A4). The text bubble is untouched (the `delta`-accumulated markdown stays — the figure is appended, never replaces).
+3. `frontend/assets/app.js` — the `rememberBrainTurn` call in the `done` handler (L3015+): the meta gains `answer_image: ev.answer_image || undefined` (the house undefined-drops-the-key pattern — the `related: ev.related?.length ? ev.related : undefined` line two above is the precedent; image-less / pre-phase turns store byte-identical records).
+4. `frontend/assets/app.js` — `renderStoredMessage` (L1856), the BRAIN branch: right BEFORE `appendSources(wrap, m.sources)` (L1904), `if (m.answer_image) appendAnswerImage(wrap, m.answer_image);` (a record without the key renders byte-identically — pre-phase chats restore unchanged).
+5. `frontend/assets/shared.js` — the shared page's brain message fragment builder (L354+, the phase-123 user-image renderer at L329-352 is the closest precedent): the same `if (m.answer_image)` figure render (the shared page uses the chat page's fragment builders per its L188 comment — wire it where the brain branch appends sources, mirroring app.js's ordering: figure before `addSources`). The bytes route is PUBLIC — the shared view is faithful (the phase-123 user-image contract).
+6. `frontend/assets/styles.css` — the `.answer-image` family in the `.source-image` language (L784-815) but at answer scale: `figure.answer-image` — margin within the bubble's flow, max-width 100% of the bubble; `.answer-image img` — max-width 100%, max-height ≈320px (the bubble is the 46rem chat column — a full-width image would blow the turn's height; cap it), `object-fit: contain`, the theme's bordered-image treatment (`.source-image-img`'s border/background, L793), `display: block`; `.answer-image figcaption`/caption span — the `.source-image-caption` styling (L804) at answer size (the visible caption = the summary). Dark/light theme parity (the semantic color tokens the theme system uses — no hardcoded colors outside the token system, PLAN §7); contrast ≥4.5:1 for the caption (WCAG AA per AGENTS.md rule 5).
+7. ASSUMPTION: none beyond the phase's locked A4 (owner-confirmed 2026-09-26). The max-height cap value (≈320px) is the one free number — the executor matches the theme's existing image scaling; the COLLAPSE-on-error rule and the alt=summary contract are locked, not free.
+
+## Testing & Quality
+- The UI is covered end-to-end by task 07's E2E suite (the house pattern — no separate JS unit suite; the E2E asserts the DOM): the live figure's presence/position (in `.msg-body`, before the `.msg-meta` chip row), its `src` (the bytes route) and lazy attribute, the caption/alt behavior, the collapse on a failed image load (assert the figure is ABSENT from the DOM, the answer text intact), persistence (the saved record carries `answer_image` — via the served saved chat), the restore render, and the shared-page render.
+- Coverage: **>90%** on `app/` overall (this task is frontend — it must not regress the `app/` gate; the E2E in task 07 exercises it).
+
+## Completion Criteria
+- [ ] Live: a `done` frame with `answer_image` → the brain bubble shows the figure below the text, above the chips; the text is fully rendered; a frame without it renders byte-identically (no figure DOM).
+- [ ] Restore: a saved chat with a brain record carrying `answer_image` renders the figure after reload; pre-phase records render unchanged.
+- [ ] Shared: the shared page renders the figure for such a record.
+- [ ] A lost image (bytes route 404) → the figure collapses (removed), never a broken-image icon; the answer + chips are intact.
+- [ ] Full test suite green; no behavior change in completed work (the chip figure `appendSourceImageFigure` is untouched).

.agents/phases/complete/124_image_chips_and_answers/07_answer_image_tests.md

@@ -0,0 +1,32 @@
+# Task 07 — The mock-LLM `show_image` trigger + isolated E2E suite
+
+**Phase:** `124_image_chips_and_answers` · **Source:** `TODO.md:3` — the whole item (the E2E proves both halves: the chips fix and the answer-image feature, plus the toggle-off contract)
+**Story:** n/a
+
+## Objective
+A deterministic E2E proof of the phase, run in isolation per AGENTS.md §4: the mock LLM learns to script a `show_image` call (and to NOT `read` — the zero-read turn is what makes the bug-fix assertion meaningful), and `tests/e2e/test_answer_images.py` drives the real user path on a toggle-ON app and a default-OFF app.
+
+## Work
+1. `tests/e2e/mock_llm.py` — a new scripted trigger (the documented marker-driven contract — extend the module docstring's trigger list):
+   - **Trigger:** the user message contains `show me the picture of` AND the system prompt contains `show_image` (the tool clause's presence — the toggle-ON gate: on a default-OFF app the clause is absent, so the trigger NEVER fires there and the mock behaves exactly as pre-phase for every other suite).
+   - **Flow:** on the FIRST matching request, stream ONLY `tool_calls` deltas — `show_image` with `path` = the combined `source/path` of the image document seeded in the `<documents>` blocks (the mock picks the seeded block whose `path` attribute ends in an image extension — `.png/.jpg/.jpeg/.webp/.gif/.bmp` — the fixture guarantees exactly one; the block-parsing machinery of the `use your tools` / tail-echo triggers is the precedent). Synthetic id `call_show`, `finish_reason: "tool_calls"`, no content. On the follow-up request (the tool result in context — recognize the `Image shown to the user` confirming line), stream the final answer: a short deterministic sentence ending with the mock's tail-echo of the `<documents>` block (the existing echo convention — it proves the seed was there) — NO further tool calls, NO `read` (the zero-read turn).
+   - **The bug-fix-only trigger:** the user message contains `which diagram is in your notes` (a second trigger, same image-doc pick, but NO `show_image` — the mock answers straight from the seed with ZERO tool calls; its answer quotes the tail of the seeded image doc's block — proving the description was in the prompt and that the chip appears with NO tool calls at all).
+2. `tests/e2e/test_answer_images.py` (new) — module apps on the `test_image_documents.py` pattern (L88-186: dedicated ports, scratch dirs, `BOR_IMAGES=true`):
+   - **App A (feature ON):** `BOR_IMAGES=true` + `BOR_ANSWER_IMAGES=true`.
+   - **App B (default off):** `BOR_IMAGES=true`, `BOR_ANSWER_IMAGES` unset (the production default — the toggle-off contract).
+   - **KB fixture (both apps):** upload the single-PNG fixture archive (the `test_image_documents.py` archive builder, L201+) via the real admin upload flow → "Sync sources" → the image doc exists (assert on the Sources page, as that suite does). The mock's `IMAGE_DESCRIPTION_MODE` serves the description (the fixture doc's content/summary — already byte-stable).
+   - **Feature flow (App A):** open the chat → ask `<trigger question with "show me the picture of …">` → assert: (1) the brain bubble's `.msg-body` contains `.answer-image` with an `<img>` whose `src` is `/api/documents/<id>/image` (fetch the served bytes — 200, image Content-Type) and `loading="lazy"`; (2) the figure sits BEFORE the `.msg-meta` source-chip row (the A4 position); (3) the answer TEXT is non-empty (the "summaries still provided" contract); (4) the source-chip row carries the image doc's chip (the AUTO-CITE proof — the mock made ZERO `read` calls; only `show_image`) with its phase-122 figure; (5) the "Nearby docs" row does NOT repeat the image doc. Reload the page → the restored brain bubble shows the figure again (the `answer_image` persistence). Open the shared link (the existing share flow) → the shared page shows the figure.
+   - **Bug-fix-only flow (App A):** a fresh chat → ask the `which diagram is in your notes` trigger → ZERO tool calls → the source-chip row STILL carries the image doc's chip + figure (the bug fix on the pure zero-read path — the assertion the owner's report describes), the answer text quotes the seeded description tail.
+   - **Toggle-off flow (App B):** the same feature trigger question → the mock never sees `show_image` in the offered tools (assert via the mock's request log, the suite's existing mechanism where present — else assert the DOM: NO `.answer-image` in the brain bubble) and the `done` frame carries no `answer_image` (the saved chat's brain record has no `answer_image` key — fetch the saved chat via the API); the bug-fix trigger still chips the image doc (the chips fix is NOT gated by `BOR_ANSWER_IMAGES` — it belongs to `BOR_IMAGES`-indexed docs, per the phase design).
+3. Run the suite IN ISOLATION: `uv run pytest tests/e2e/test_answer_images.py -v --no-cov` (AGENTS.md §4/§9 — one file, its own app instances on dedicated ports; no cross-suite state).
+4. ASSUMPTION: none beyond the phase's locked decisions (owner-confirmed 2026-09-26). The two trigger phrases are new and carry no collision with existing triggers (the mock's docstring lists every trigger — verify against it when writing; pick differently on collision).
+
+## Testing & Quality
+- This task IS the E2E suite; it also runs the final phase gate: `uv run pytest` (unit + integration) green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL **>90%** on `app/` (the validate.sh gate — if the new `app/` code (agent branch, prompts clause, schemas serializer, chat.py merge) dips the total, add unit pins, do NOT lower the bar); `uv run ruff check . && uv run pyright` clean.
+- The mock change must not perturb any existing suite: run at least `tests/e2e/test_image_documents.py` and `tests/e2e/test_agent_document_tools.py` after the mock edit (the trigger is clause-gated, so pre-phase prompts never fire it — verify, don't assume).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_answer_images.py -v --no-cov` passes in isolation (feature flow, bug-fix-only flow, toggle-off flow — all assertions above).
+- [ ] The mock's new trigger is inert for every existing suite (the two spot-checked suites pass unmodified).
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `ruff` + `pyright` clean.
+- [ ] One atomic `--no-gpg-sign` commit for the phase code (per AGENTS.md §8 — the commit block in `00_phase.md`); the pipeline gate then moves the phase dir to `.agents/phases/complete/` (the house `phase: NN_name` bookkeeping commit, as for every completed phase).

.agents/phases/complete/125_image_anchor_context/00_phase.md

@@ -0,0 +1,54 @@
+# Phase 125 — Image-anchor context: markdown image references enrich image documents with surrounding text
+
+**Source:** `TODO.md` — "improve image handling: use context of surrounding text to describe images, use alt text from markdown image syntax `![alt](image.png)` to give context to the summary."
+**Story:** n/a (improvement on phase-122/124 image capability).
+**Context:** `app/config.py` — `Settings` (`images` L379, `image_extensions` L390, `image_dir` L413). `app/rag/importer.py` — `iter_importable_files` (L235, extension walk), `import_sources` (L279), `_index_file` (L435 — text branch for markdown, binary branch delegates to `_index_image_file`), `_index_image_file` (L801 — bytes digest, persistent copy, `describe_image` seam, chunk + embed pipeline), `_store_summary` (L582), `_describe_or_skip` (L762 — calls `describe_image`). `app/rag/summarizer.py` — `describe_image` (L208 — multimodal chat call, DESCRIBE_PROMPT constant), `DESCRIBE_INSTRUCTION` (L89 — the locked prompt text), `generate_summary` (L182), `build_summary_prompt` (L162). `app/rag/chunker.py` — markdown section splitter on `##` headings, paragraph packing. `app/models.py` — `Document` (L102: `content`, `summary`, `is_image`, `image_path`), `Chunk` (L171). `app/rag/retriever.py` — `_selection_order` (L666, shared selection walk), `select_suggested` (L864, seeds prompt summaries), `source_ref_with_image` (L945). `app/rag/prompts.py` — `<document>` block body (L438, uses `doc.summary`), `build_high_prompt` (L461 — the LOCKED `<tools>` section, phase-124 `show_image` clause). `app/api/chat.py` — done-frame build (L1119-1133, `cited_docs` merge from task 05 of phase 124). `alembic/versions/0022_documents_image.py` — the phase-122 migration (the pattern for additive, reversible migrations).
+
+## Objective
+When a markdown file references an image (e.g. `![alt text](diagram.png)`), the image document's description is enriched with the alt text and surrounding paragraphs — so the image becomes retrievable not just by what it shows, but by why it exists in the documentation. This closes the gap between standalone image descriptions (phase 122) and the rich contextual text that lives in the parent markdown document.
+
+## Dependencies
+- `122_image_documents` (complete) — the image-doc pipeline: `Document.is_image`/`image_path`, `describe_image`, the binary index path, `BOR_IMAGES` toggle, the vision description as content+summary.
+- `124_image_chips_and_answers` (complete) — auto-cite for image docs, `BOR_ANSWER_IMAGES` toggle, the `show_image` tool.
+- Code dependencies (all complete): phase 30 summary pipeline, phase 118 summary seeding, phase 119 read-docs citation tier.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The `image_context` field (task 01):** `Document.image_context: str | None = None` (TEXT, nullable). Stores the surrounding text extracted from the markdown file that references the image — alt text + N paragraphs before and after the reference. NULL for image docs that were not found to have a markdown reference (standalone images, images referenced in non-markdown formats, pre-phase rows). Migration: one additive, reversible migration (A13 precedent: `0023_documents_image_context.py`).
+- **Markdown image extraction (task 02):** a new module-level function `extract_image_refs(content: str) -> list[ImageRef]` in `app/rag/importer.py` (or `app/rag/md_images.py` if preferred) that parses markdown content and extracts: (a) the `![alt_text](path)` pattern via regex; (b) for each reference, the N paragraphs before and after the line containing the reference (configurable, default 2); (c) the line number of the reference for context window calculation. The regex: `r'!\[([^\]]*)\]\(([^)]+)\)'` — captures alt text and the image path. The context window: split content into paragraphs (blank-line separated, respecting code fences), find the paragraph containing the reference, take N before and N after. Result: `ImageRef(path, alt_text, context_text, line_number)`.
+- **Enrichment flow (task 03):** after `_index_file` processes a markdown file, check if it contains image references. For each reference whose image path resolves to an existing image document in the same source, load the image doc and enrich its content: `new_content = f"{alt_text}\n\n{context}\n\n{original_description}"` — the alt text first (short, purposeful), then the surrounding context (why the image exists), then the vision description (what the image shows). Then re-chunk and re-embed the enriched content. If the image doc doesn't exist yet (not indexed), store the reference on the markdown doc's `image_context` field so the enrichment can happen when the image is later indexed.
+- **Enrichment at image-index time (task 04):** in `_index_image_file`, BEFORE calling `describe_image`, check if any markdown file in the same source references this image. If so, load the markdown content, extract the reference + context, and pass it to `describe_image` as additional context in the prompt (the vision model can acknowledge the context: "This diagram, referenced in `<markdown_path>` as `<alt_text>`, shows..."). This is the primary enrichment path — the image gets context during its own indexing. The `image_context` field on the image doc stores the extracted context text for retrieval display.
+- **Retrieval display (task 05):** when an image doc is in the suggested tier, the `<document>` block (which currently shows `doc.summary`) is extended to also show the `image_context` (if present) — a short "Referenced in `<source>/<markdown_path>`: `<alt_text>`" line before the description. This is a small addition to `build_document_block` in `app/rag/prompts.py` — only for `is_image` docs with non-NULL `image_context`.
+- **NOT touched:** the `BOR_IMAGES` toggle (the feature is gated by it, unchanged), the `BOR_ANSWER_IMAGES` toggle (unchanged), the `show_image` tool (unchanged), the image serve route (unchanged), the document viewer (unchanged), and the prune logic (unchanged). Existing image docs without context are unaffected — `image_context` is NULL, the prompt block shows only the description (byte-identical to pre-phase).
+- **Locked assumptions:** **A1** — `image_context` stores the surrounding text from the referencing markdown file. **A2** — enrichment happens at image-index time (the image doc picks up context from its markdown parent). **A3** — the vision model receives context in the prompt but the description remains the primary content. **A4** — retrieval display adds a short context line for enriched image docs; pre-phase image docs are byte-identical.
+
+## Tasks
+1. `01_migration_image_context.md` — `Document.image_context` column + migration.
+2. `02_extract_image_refs.md` — `extract_image_refs()` function for markdown image reference extraction.
+3. `03_enrich_image_description.md` — pass context to `describe_image`; enrich image doc content + re-embed.
+4. `04_store_image_context.md` — store context on image docs; handle the case where markdown is indexed before/after the image.
+5. `05_retrieval_display.md` — show context line for enriched image docs in the `<document>` block.
+6. `06_image_anchor_tests.md` — unit + integration + E2E tests.
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_anchor_context.py` (new, task 06) — `extract_image_refs` (basic reference, multiple references, references in code fences, references with no alt text, references in headings, edge cases); the enrichment pipeline (context extraction, content enrichment, re-chunking, re-embedding); the `describe_image` prompt extension (context included in the text part when provided); the retrieval display (context line present for enriched docs, absent for non-enriched).
+- Integration: `tests/integration/test_importer.py` (extend) — a markdown file referencing an image in the same source → the image doc has `image_context` set; the image description includes the context; the chunks are re-embedded with the enriched content. A markdown file referencing a non-existent image → the markdown doc's `image_context` is set (the image will be enriched when indexed). A standalone image (no markdown reference) → `image_context` is NULL (byte-identical to pre-phase).
+- E2E: `tests/e2e/test_image_anchor_context.py` (new, task 06) — isolated run: upload a fixture markdown file that references an image in the same archive → sync → the image doc has enriched context → ask a question that requires the context to answer correctly (the mock LLM should be able to use the context to give a better answer) → the `<document>` block shows the context line.
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] A markdown file referencing an image in the same source → the image document's description is enriched with alt text + surrounding context; the retrieval block shows the context line.
+- [ ] A standalone image (no markdown reference) → `image_context` is NULL; behavior byte-identical to pre-phase.
+- [ ] A markdown file referencing a non-existent image → the context is stored on the markdown doc; when the image is later indexed, it picks up the context.
+- [ ] `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 — `image_context` stores the surrounding text (alt text + N paragraphs before/after) from the referencing markdown file (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A2 — enrichment happens at image-index time: the image doc picks up context from its markdown parent (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A3 — the vision model receives context in the prompt but the description remains the primary content (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A4 — retrieval display adds a short context line for enriched image docs; pre-phase image docs are byte-identical (owner-confirmed 2026-09-26, roadmap confirmation).**
+
+## Commit
+```bash
+git add app/ alembic/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(rag): enrich image descriptions with markdown context (alt text + surrounding paragraphs)"
+```

.agents/phases/complete/125_image_anchor_context/01_migration_image_context.md

@@ -0,0 +1,34 @@
+# Task 01 — Migration: `Document.image_context` column
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — the `image_context` field
+
+## Objective
+Add `Document.image_context: str | None` (TEXT, nullable) to the database schema — the column that stores the surrounding text extracted from the markdown file referencing the image. One additive, reversible migration (A13 precedent).
+
+## Work
+1. `app/models.py` — add to `Document` (after `image_path`, L168):
+   ```python
+   #: Surrounding text from the markdown file that references this image
+   #: (phase 125, LOCKED A1): alt text + N paragraphs before/after the
+   #: reference. NULL for standalone images and pre-phase rows. The
+   #: embedding model embeds this alongside the vision description when
+   #: the image is enriched (task 03).
+   image_context: Mapped[str | None] = mapped_column(Text, default=None)
+   ```
+2. `alembic/versions/0023_documents_image_context.py` — new migration:
+   - `revision = "0023"`, `down_revision = "0022"`
+   - `upgrade()`: `op.add_column("documents", sa.Column("image_context", sa.Text(), nullable=True))`
+   - `downgrade()`: `op.drop_column("documents", "image_context")`
+   - Docstring following the `0022_documents_image.py` pattern: explain the column, its purpose, and that it's fully reversible.
+3. ASSUMPTION: none. The column is nullable (NULL for all pre-phase rows) and additive (no existing code breaks).
+
+## Testing & Quality
+- Unit: `tests/unit/test_models.py` (extend) — `Document(image_context="some context")` parses; `Document(image_context=None)` parses; the column is nullable (no NOT NULL constraint).
+- Integration: `tests/integration/test_migrations.py` (extend) — run `alembic upgrade head` (the new migration applies cleanly); run `alembic downgrade 0022` (the downgrade restores the 0022 schema); run `alembic upgrade head` again (idempotent). Assert that pre-phase image docs (NULL `image_context`) round-trip correctly.
+- Coverage: **>90%** on the touched modules.
+
+## Completion Criteria
+- [ ] `alembic upgrade head` applies the new migration cleanly.
+- [ ] `alembic downgrade 0022` + `upgrade head` round-trips the schema.
+- [ ] `Document` model has the `image_context` field; NULL is valid.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/125_image_anchor_context/02_extract_image_refs.md

@@ -0,0 +1,50 @@
+# Task 02 — Extract image references from markdown content
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — the `extract_image_refs()` function
+
+## Objective
+A pure function that parses markdown content and extracts all `![alt_text](path)` references, each with its alt text, the surrounding paragraph context (N before and N after), and the line number. Returns a list of `ImageRef` dataclasses.
+
+## Work
+1. `app/rag/md_images.py` — new module (or add to `app/rag/importer.py` if preferred — the executor's call, but a separate module keeps the importer lean):
+   - `@dataclass class ImageRef: path: str; alt_text: str; context: str; line_number: int` — the extracted reference with its context window.
+   - `CONTEXT_PARAGRAPHS: int = 2` — configurable number of paragraphs before/after (the default gives ~2-4 sentences of surrounding text).
+   - `def extract_image_refs(content: str, context_paragraphs: int = CONTEXT_PARAGRAPHS) -> list[ImageRef]`:
+     - Split content into lines.
+     - Track code fence state (a fenced code block is NOT context — image references inside code fences are just text, not actual references).
+     - For each line, check for the image reference regex: `r'!\[([^\]]*)\]\(([^)]+)\)'`.
+     - When a reference is found:
+       - Record the line number (1-indexed).
+       - Find the paragraph containing this line (paragraphs are separated by blank lines, but code fences are atomic).
+       - Collect N paragraphs before and N after the reference paragraph.
+       - The `context` is the joined paragraphs (excluding the reference line itself, which is already captured as `alt_text` + `path`).
+       - The `alt_text` is the captured group (may be empty).
+       - The `path` is the captured group (may be relative or absolute).
+     - Return the list of `ImageRef` objects.
+   - Edge cases to handle:
+     - References inside code fences → skip (the reference is literal text, not an actual image).
+     - Multiple references on the same line → extract each separately.
+     - References with no alt text (`![](image.png)`) → `alt_text = ""`.
+     - References with no surrounding text (start/end of file) → context is whatever is available.
+     - Image paths with special characters (spaces, parentheses) → the regex should handle common cases; edge cases with nested parentheses in paths are acceptable to miss (they're rare in practice).
+2. ASSUMPTION: none. This is a pure function — no I/O, no LLM calls, no database access.
+
+## Testing & Quality
+- Unit: `tests/unit/test_md_images.py` (new, task 06) — test `extract_image_refs` against various inputs:
+  - Single reference: `![alt](image.png)` → one `ImageRef` with alt="alt", context from surrounding paragraphs.
+  - Multiple references: two `![...]` on different lines → two `ImageRef`s, each with its own context.
+  - Reference in code fence: ```` ![alt](image.png) ```` → skipped (not extracted).
+  - Reference with no alt text: `![](image.png)` → `alt_text = ""`.
+  - Reference at start of file → context is only paragraphs after.
+  - Reference at end of file → context is only paragraphs before.
+  - Reference in a heading: `## ![alt](image.png)` → extracted, but context is the surrounding text (the heading line itself is not included in context).
+  - Empty content → empty list.
+  - Content with no references → empty list.
+  - Verify that `line_number` is 1-indexed and correct.
+- Coverage: **>90%** on the new module.
+
+## Completion Criteria
+- [ ] `extract_image_refs("![alt](img.png)")` returns one `ImageRef` with correct alt, path, context, and line number.
+- [ ] References inside code fences are skipped.
+- [ ] Multiple references are extracted separately with correct context windows.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/125_image_anchor_context/03_enrich_image_description.md

@@ -0,0 +1,49 @@
+# Task 03 — Enrich image descriptions with context
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — pass context to `describe_image`; enrich image doc content + re-embed
+
+## Objective
+When indexing an image file, check if any markdown file in the same source references it. If so, extract the alt text and surrounding context, and pass it to `describe_image` so the vision model can produce a context-aware description. Store the extracted context on the image doc's `image_context` field.
+
+## Work
+1. `app/rag/summarizer.py` — extend `describe_image`:
+   - Add an optional `context: str | None = None` parameter.
+   - When `context` is provided, prepend it to the DESCRIBE_PROMPT text part:
+     ```python
+     context_prefix = f"\n\nThis image is referenced in documentation with the following context:\n{context}" if context else ""
+     messages = [{
+         "role": "user",
+         "content": [
+             {"type": "text", "text": DESCRIBE_PROMPT + context_prefix},
+             {"type": "image_url", "image_url": {"url": data_url}},
+         ],
+     }]
+     ```
+   - The context prefix teaches the vision model what the image is for, enabling a more useful description. The existing DESCRIBE_PROMPT (the locked instruction) is unchanged — the context is appended after it.
+   - The context is NOT stored on the doc (that's task 04's job); this task only passes it to the LLM.
+2. `app/rag/importer.py` — in `_index_image_file`, BEFORE calling `describe_image`:
+   - Check if any markdown file in the same source references this image. The simplest approach: scan all `.md`/`.markdown` files in the same source directory for references to this image's filename. Use `extract_image_refs` from task 02.
+   - For each markdown file that references this image, collect the `ImageRef` objects where the image path matches (handle both relative paths like `image.png` and paths like `folder/image.png`).
+   - If references are found, combine them into a single context string:
+     ```
+     Referenced in <source>/<markdown_path>:
+     - Alt text: "<alt_text>"
+       Context: <context_paragraphs>
+     ```
+   - Pass this context to `describe_image` as the `context` parameter.
+   - Store the combined context string on the image doc's `image_context` field (this is the primary storage — the retrieval display in task 05 reads from here).
+3. `app/rag/importer.py` — in `_index_image_file`, after `describe_image` returns:
+   - If `image_context` is set (from step 2), the image doc's `content` should be enriched: `content = f"{image_context}\n\n{description}"` — the context first (for retrieval), then the description. Then the normal chunk pipeline embeds this enriched content.
+   - If `image_context` is NULL (no markdown reference found), the content is just the description (byte-identical to pre-phase).
+   - The `summary` field: for image docs, `summary = content` (the phase-122 convention). So the summary is also enriched.
+4. ASSUMPTION: none. The context extraction uses the `extract_image_refs` function from task 02. The `describe_image` extension is backward-compatible (the `context` parameter defaults to `None`).
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_anchor_context.py` (task 06) — `describe_image` with `context=None` → same behavior as pre-phase (the DESCRIBE_PROMPT is unchanged); `describe_image` with `context="some context"` → the prompt includes the context prefix; the enriched content is `context + "\n\n" + description`.
+- Integration: `tests/integration/test_importer.py` (extend) — seed a source with both a markdown file referencing an image and the image file itself → sync with `images=True` → the image doc has `image_context` set, its `content` includes the context, its chunks are embedded from the enriched content. A standalone image (no markdown reference) → `image_context` is NULL, `content` is just the description.
+- Coverage: **>90%** on the touched modules.
+
+## Completion Criteria
+- [ ] An image referenced in a markdown file → the description is context-aware (the LLM receives the context), and the image doc's `content` includes the context.
+- [ ] A standalone image → `image_context` is NULL, `content` is just the description (byte-identical to pre-phase).
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/125_image_anchor_context/04_store_image_context.md

@@ -0,0 +1,48 @@
+# Task 04 — Store context on markdown docs for future image enrichment
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — handle the case where markdown is indexed before/after the image
+
+## Objective
+When a markdown file is indexed and references an image that doesn't yet exist as a document (e.g., the image hasn't been synced yet, or it's in a different source), store the image references on the markdown doc's `image_context` field. This enables a post-indexing enrichment pass that can pick up the context when the image is later indexed.
+
+## Work
+1. `app/rag/importer.py` — in the markdown/text branch of `_index_file` (after the Document upsert, before the chunk pipeline):
+   - After extracting the title (L505-509), check if the file is markdown (`full_path.suffix.lower() in (".md", ".markdown")`).
+   - Call `extract_image_refs(content)` to get all image references.
+   - For each reference, check if an image document already exists in the same source with a matching path. Use a database query: `select(Document).where(Document.source == source, Document.path == image_ref.path, Document.is_image == True)`.
+   - For references where the image document DOES NOT exist, store the reference info on the markdown doc's `image_context` field:
+     ```python
+     # Build a structured context string for references to non-existent images
+     missing_refs = [r for r in image_refs if not image_exists_in_source(session, source, r.path)]
+     if missing_refs:
+         doc.image_context = _format_missing_image_refs(missing_refs, source)
+     ```
+   - `_format_missing_image_refs(refs, source) -> str`: formats the missing references as a structured string:
+     ```
+     IMAGE_CONTEXT:
+     - [image.png] (line 42): "Alt text here" — 2 paragraphs of context
+     - [diagram.jpg] (line 100): "" — 1 paragraph of context
+     ```
+     This format is parseable by the enrichment pass (task 04b).
+   - For references where the image document DOES exist, the enrichment happens in task 03 (at image-index time). The markdown doc's `image_context` remains NULL.
+2. `app/rag/importer.py` — a new helper `_format_missing_image_refs(refs, source) -> str` (module-level, pure function):
+   - Takes a list of `ImageRef` objects and the source name.
+   - Returns a formatted string as described above.
+   - Used by both `_index_file` (markdown branch) and the enrichment pass.
+3. `app/rag/importer.py` — after `_index_file` returns for all files in a source (in `import_sources`), run a **post-indexing enrichment pass**:
+   - Query all image documents in the source that have `image_context IS NULL` (not yet enriched).
+   - For each, check if any markdown document in the same source has `image_context` set (contains references to this image).
+   - If a match is found, extract the reference info from the markdown doc's `image_context`, enrich the image doc (same logic as task 03: re-call `describe_image` with context, update `content`, re-embed chunks).
+   - This pass handles the case where the markdown was indexed first (storing references) and the image is indexed later.
+4. ASSUMPTION: none. The enrichment pass is idempotent — if an image doc already has `image_context` set, it's skipped. The markdown doc's `image_context` is not cleared after enrichment (it's useful for retrieval display too).
+
+## Testing & Quality
+- Unit: `tests/unit/test_image_anchor_context.py` (task 06) — `_format_missing_image_refs` (single ref, multiple refs, empty list → empty string); the enrichment pass (markdown with missing refs → image doc enriched when found; image doc already enriched → skipped).
+- Integration: `tests/integration/test_importer.py` (extend) — seed a source with a markdown file referencing an image that doesn't exist yet → sync → the markdown doc has `image_context` set; then add the image file → sync again → the image doc is enriched with the context from the markdown doc. A markdown file referencing an image that exists → the image doc is enriched at index time (task 03 path).
+- Coverage: **>90%** on the touched modules.
+
+## Completion Criteria
+- [ ] A markdown file referencing a non-existent image → the markdown doc's `image_context` stores the reference info.
+- [ ] When the image is later indexed (or re-synced), it picks up the context from the markdown doc.
+- [ ] A markdown file referencing an existing image → the image is enriched at index time (task 03 path), the markdown doc's `image_context` is NULL.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/125_image_anchor_context/05_retrieval_display.md

@@ -0,0 +1,38 @@
+# Task 05 — Retrieval display: show context line for enriched image docs
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — show context line for enriched image docs in the `<document>` block
+
+## Objective
+When an enriched image doc (one with non-NULL `image_context`) appears in the suggested tier, the `<document>` block shows a short context line before the description — so the LLM knows why the image exists in the documentation.
+
+## Work
+1. `app/rag/prompts.py` — extend the document block builder (`_document_block_body`, L438):
+   - Currently it returns `doc.summary` (stripped). For image docs with `image_context`, prepend a context line:
+     ```python
+     summary = (doc.summary or "").strip()
+     if doc.is_image and doc.image_context:
+         # Extract the first reference's alt text for a short context line
+         # The image_context is formatted as "Referenced in <source>/<path>: ..."
+         # Show: "Referenced in <path>: <alt_text>"
+         context_line = _extract_context_line(doc.image_context)
+         if context_line:
+             summary = f"{context_line}\n\n{summary}"
+     return summary
+     ```
+   - `_extract_context_line(image_context: str) -> str | None`: parses the `image_context` string (set by task 04) and extracts a short context line:
+     ```python
+     # image_context format: "Referenced in <source>/<markdown_path>:\n- [image.png] (line 42): \"Alt text here\""
+     # Return: "Referenced in <markdown_path>: \"Alt text here\""
+     ```
+     If parsing fails or the format is unexpected, return `None` (graceful degradation — the summary shows without the context line).
+2. ASSUMPTION: none. The context line is short (one line) so it doesn't bloat the prompt. Pre-phase image docs (NULL `image_context`) are byte-identical — the `if doc.is_image and doc.image_context` guard ensures this.
+
+## Testing & Quality
+- Unit: `tests/unit/test_prompts.py` (extend) — `_document_block_body` for a non-image doc → unchanged (byte-identical to pre-phase); for an image doc with `image_context = None` → unchanged (byte-identical to pre-phase); for an image doc with `image_context` set → the summary includes the context line before the description; `_extract_context_line` (valid format → extracts the line; invalid format → returns None).
+- Integration: `tests/integration/test_chat_api.py` (extend) — a grounded turn whose suggested tier contains an enriched image doc → the `<documents>` section in the system prompt includes the context line; a non-enriched image doc → no context line.
+- Coverage: **>90%** on the touched modules.
+
+## Completion Criteria
+- [ ] An enriched image doc in the suggested tier → the `<document>` block shows a context line before the description.
+- [ ] A non-enriched image doc → byte-identical to pre-phase (no context line).
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/125_image_anchor_context/06_image_anchor_tests.md

@@ -0,0 +1,57 @@
+# Task 06 — Tests: unit, integration, and E2E for image-anchor context
+
+**Phase:** `125_image_anchor_context` · **Source:** `00_phase.md` — the full test suite
+
+## Objective
+Comprehensive tests across all new logic: the `extract_image_refs` function, the enrichment pipeline, the `describe_image` context extension, the retrieval display, and the end-to-end flow.
+
+## Work
+1. `tests/unit/test_md_images.py` (new) — tests for `extract_image_refs`:
+   - Single reference with alt text and surrounding paragraphs.
+   - Multiple references on different lines, each with correct context windows.
+   - References inside code fences (skipped).
+   - References with no alt text (`![](image.png)`).
+   - References at start/end of file (context is partial).
+   - References in headings.
+   - Empty content, content with no references.
+   - Verify `line_number` is 1-indexed and correct.
+   - Edge cases: nested brackets in alt text, special characters in paths.
+2. `tests/unit/test_image_anchor_context.py` (new) — tests for the enrichment pipeline:
+   - `describe_image` with `context=None` → same behavior as pre-phase.
+   - `describe_image` with `context="..."` → the prompt includes the context prefix.
+   - `_extract_context_line` (valid format → extracts the line; invalid format → returns None).
+   - `_document_block_body` for enriched vs non-enriched image docs.
+   - `_format_missing_image_refs` (single ref, multiple refs, empty list).
+   - The enrichment pass (markdown with missing refs → image enriched; image already enriched → skipped).
+3. `tests/integration/test_importer.py` (extend) — integration tests:
+   - Seed a source with a markdown file referencing an image → the image doc has `image_context` set.
+   - A standalone image (no markdown reference) → `image_context` is NULL.
+   - A markdown file referencing a non-existent image → the markdown doc stores the reference info.
+   - Re-sync after adding the missing image → the image doc is enriched.
+   - Verify that the enriched image doc's chunks are embedded from the enriched content.
+4. `tests/integration/test_chat_api.py` (extend) — integration tests:
+   - A grounded turn whose suggested tier contains an enriched image doc → the done frame's system prompt includes the context line.
+   - A non-enriched image doc → no context line (byte-identical to pre-phase).
+5. `tests/e2e/test_image_anchor_context.py` (new) — isolated E2E suite:
+   - Module apps: `BOR_IMAGES=true` for this suite's app instance.
+   - KB fixture: upload an archive containing a markdown file that references an image within the same archive (e.g., `docs/guide.md` references `diagram.png`).
+   - Sync → the image doc is enriched with the markdown context.
+   - Ask a question that requires the context to answer correctly (the mock LLM should use the context line to give a better answer).
+   - Verify the `<document>` block in the prompt includes the context line (via the saved chat record).
+   - A standalone image (no markdown reference) → the answer is byte-identical to pre-phase.
+   - Run in isolation: `uv run pytest tests/e2e/test_image_anchor_context.py -v --no-cov`.
+6. Run the full test suite: `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+
+## Testing & Quality
+- All new logic is covered by unit tests (the `extract_image_refs` function, the enrichment pipeline, the context extraction/display).
+- Integration tests cover the full import + chat flow with seeded data.
+- E2E tests cover the real user path: upload → sync → ask → verify enriched answer.
+- The mock LLM should be configured to acknowledge the context line in its answer (extend the mock's prompt parser to recognize the context line format).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_md_images.py -v --no-cov` passes.
+- [ ] `uv run pytest tests/unit/test_image_anchor_context.py -v --no-cov` passes.
+- [ ] `uv run pytest tests/integration/test_importer.py -v --no-cov` passes (extended).
+- [ ] `uv run pytest tests/e2e/test_image_anchor_context.py -v --no-cov` passes in isolation.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `ruff` + `pyright` clean.
+- [ ] No regression in existing E2E suites (run `test_image_documents.py` and `test_answer_images.py` to verify).

.agents/phases/complete/126_pdf_support/00_phase.md

@@ -0,0 +1,79 @@
+# Phase 126 — PDF support: PDFs become first-class, retrievable documents
+
+**Source:** `TODO.md` — "add PDF support" (implied by the image handling assessment: "PDFs: Not supported. No PDF parsing library is in pyproject.toml.")
+**Story:** n/a (new file format support).
+**Context:** `app/config.py` — `Settings` (`import_extensions` L343, `import_extension_set` L733 — the extension filter; `images` L379, `image_extensions` L390, `image_dir` L413 — the image pipeline); `app/rag/importer.py` — `iter_importable_files` (L235, extension walk via `match_extension`), `import_sources` (L279, `prune` L283), `_index_file` (L435 — text branch: `read_text`, sha256 over text, Document upsert, chunk + embed pipeline), `_index_image_file` (L801 — binary branch: bytes digest, persistent copy, `describe_image`), `_store_summary` (L582), `_prune` (L649). `app/rag/chunker.py` — format-aware chunker (markdown, yaml, json, py, txt dispatch). `app/rag/summarizer.py` — `describe_image` (L208, vision model), `generate_summary` (L182, lite model). `app/rag/retriever.py` — `_selection_order` (L666), `select_suggested` (L864), `source_ref_with_image` (L945). `app/models.py` — `Document` (L102), `Chunk` (L171). `app/rag/llm.py` — the LLM client. `app/api/docs.py` — document content endpoint. `app/rag/archive_upload.py` — archive unpack (PDFs in archives should also be indexed).
+
+## Objective
+PDF files become first-class, retrievable documents: text is extracted page by page, embedded images are extracted and described (joining the standalone image pipeline), and the full PDF content is chunked, embedded, and summarized — all behind a new `BOR_IMPORT_EXTENSIONS` token (`pdf`).
+
+## Dependencies
+- `122_image_documents` (complete) — the image-doc pipeline: `describe_image`, `Document.is_image`/`image_path`, the vision model description path. Embedded PDF images reuse this pipeline.
+- `125_image_anchor_context` (complete) — the `image_context` field and enrichment pipeline (PDF-embedded images can be enriched if referenced by a markdown file in the same source).
+- Code dependencies (all complete): phase 30 summary pipeline, phase 118 summary seeding, the chunker, the LLM client.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Dependency (task 01):** add `pymupdf` (PyMuPDF, the `fitz` package) to `pyproject.toml` dependencies. PyMuPDF is chosen over `pdfplumber` because it natively supports both text extraction AND embedded image extraction in a single API, and it's a well-maintained package with good performance. The `fitz` module is the import name.
+- **PDF parsing module (task 02):** `app/rag/pdf.py` — new module with:
+  - `def extract_pdf_text(pdf_path: Path) -> str`: extracts text from all pages, joined with `---PAGE-N---` separators (where N is 1-indexed). The separators enable the chunker to respect page boundaries.
+  - `def extract_pdf_images(pdf_path: Path) -> list[PdfImage]`: extracts embedded images from all pages. Returns a list of `PdfImage` dataclasses: `page: int`, `index: int` (image index on the page), `width: int`, `height: int`, `data: bytes`, `mime: str` (derived from the image type code via PyMuPDF's `page.get_image_info()`).
+  - `_mime_from_image_info(info: dict) -> str`: maps PyMuPDF's image type codes to MIME types (e.g., `2` → `image/jpeg`, `3` → `image/png`, `4` → `image/gif`, `8` → `image/webp`, `9` → `image/tiff`). Falls back to `application/octet-stream` for unknown types.
+  - All functions are pure (except I/O for reading the PDF file) — fully unit-testable with a temp PDF fixture.
+- **PDF chunking (task 03):** extend `app/rag/chunker.py`'s `chunk_document` dispatch to handle `.pdf` files. The PDF chunker:
+  - Splits on `---PAGE-N---` separators first (one chunk per page, or sub-split if a page is too large).
+  - Each chunk keeps its page anchor (e.g., "Page 3:" prefix) so hits are readable in context.
+  - Code blocks within PDFs are handled by the existing paragraph packing (PDFs don't have code fences, so paragraph boundaries = blank lines).
+  - The `HARD_MAX_CHARS` cap (1200) still applies.
+  - For very large PDFs (>50 pages), the chunk target is reduced to keep individual chunks manageable.
+- **PDF indexing (task 04):** in `app/rag/importer.py`'s `_index_file`:
+  - Add a new branch for `.pdf` files (checked AFTER the image branch, BEFORE the text branch):
+    ```python
+    if full_path.suffix.lower() == ".pdf":
+        return await _index_pdf_file(session, source, rel, full_path, llm, summary, raw_date)
+    ```
+  - `_index_pdf_file`:
+    1. Extract text via `extract_pdf_text` (task 02).
+    2. Extract embedded images via `extract_pdf_images` (task 02).
+    3. Create the PDF document row with the extracted text as `content`, the file's sha256 (over the text) as `content_hash`, and the title from the PDF's metadata (if available) or the file stem.
+    4. Chunk and embed the text (task 03's chunker handles `.pdf`).
+    5. Generate a lite summary of the PDF content.
+    6. For each embedded image:
+       - If the image extension matches `BOR_IMAGE_EXTENSIONS` and `BOR_IMAGES` is on: create a standalone image document (reuse `_index_image_file`'s logic, but the image bytes come from the PDF, not a file on disk). The image's `path` is `<pdf_source>/<pdf_path>#page=<N>#img=<index>` (a synthetic path that uniquely identifies the embedded image).
+       - If the image extension doesn't match or `BOR_IMAGES` is off: log a warning and skip the image.
+       - The embedded image's description becomes the image doc's content+summary (the phase-122 pipeline).
+    7. The PDF document's content includes inline references to embedded images: after each page's text, append `[Embedded image: <image_type> on page <N>]` (a placeholder that the LLM can use to know images exist, even if they're not described).
+- **PDF in archives (task 05):** PDFs inside uploaded archives should be indexed too. The archive unpack (`app/rag/archive_upload.py`) already extracts all files matching the import extensions. Add `pdf` to the archive's accepted file types (archives already unpack everything; the extension filter in `iter_importable_files` handles the rest).
+- **NOT touched:** the `BOR_IMAGES` toggle (PDF embedded images reuse the existing image pipeline, gated by it), the `show_image` tool (unchanged), the image serve route (unchanged), the document viewer (PDFs are served as text content, not as binary PDFs — the viewer renders the extracted text), and the prune logic (unchanged).
+- **Locked assumptions:** **A1** — `pymupdf` is the PDF parser (text + image extraction). **A2** — one document per PDF (not per page); pages are separated by `---PAGE-N---` markers. **A3** — embedded images become standalone image documents (reusing the phase-122 pipeline). **A4** — PDFs are served as extracted text in the document viewer (not as binary PDFs).
+
+## Tasks
+1. `01_pdf_dependency.md` — add `pymupdf` to `pyproject.toml`.
+2. `02_pdf_parser.md` — `app/rag/pdf.py`: text extraction, image extraction, MIME mapping.
+3. `03_pdf_chunking.md` — extend the chunker to handle `.pdf` files.
+4. `04_pdf_indexing.md` — `_index_pdf_file` in the importer: text + embedded images + summary.
+5. `05_pdf_archive_and_tests.md` — PDFs in archives, unit + integration + E2E tests.
+
+## Testing & Quality
+- Unit: `tests/unit/test_pdf.py` (new, task 05) — `extract_pdf_text` (multi-page PDF → text with page separators; single-page PDF → text without extra separators; empty PDF → empty string); `extract_pdf_images` (PDF with embedded images → list of `PdfImage` with correct page/index/size/data/mime; PDF with no images → empty list); `_mime_from_image_info` (known types → correct MIME; unknown type → fallback).
+- Integration: `tests/integration/test_importer.py` (extend) — seed a source with a PDF file → sync → the PDF document has extracted text, chunks, and embedding; embedded images (if `BOR_IMAGES=true`) become image documents; a PDF without embedded images → no image docs.
+- E2E: `tests/e2e/test_pdf_support.py` (new, task 05) — isolated run: upload a PDF via the admin upload flow → sync → the PDF appears on the Sources page → open the document viewer → the extracted text renders; ask a question the PDF answers → the chat grounds on the PDF content.
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] A PDF file in a git/local source or uploaded archive becomes a document with extracted text, chunks, embedding, and summary.
+- [ ] With `BOR_IMAGES=true`: embedded images in the PDF become standalone image documents (described by the vision model).
+- [ ] With `BOR_IMAGES=false`: embedded images are skipped (logged), the PDF text is indexed normally.
+- [ ] The PDF renders as extracted text in the document viewer.
+- [ ] `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 — `pymupdf` (PyMuPDF) is the PDF parser; it handles both text and embedded image extraction (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A2 — one document per PDF; pages are separated by `---PAGE-N---` markers in the content (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A3 — embedded images become standalone image documents, reusing the phase-122 pipeline (gated by `BOR_IMAGES`) (owner-confirmed 2026-09-26, roadmap confirmation).**
+- **A4 — PDFs are served as extracted text in the document viewer (not as binary PDFs) (owner-confirmed 2026-09-26, roadmap confirmation).**
+
+## Commit
+```bash
+git add app/ pyproject.toml tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(import): add PDF support — text extraction, embedded images, chunking"
+```

.agents/phases/complete/126_pdf_support/01_pdf_dependency.md

@@ -0,0 +1,19 @@
+# Task 01 — Add `pymupdf` dependency
+
+**Phase:** `126_pdf_support` · **Source:** `00_phase.md` — the `pymupdf` dependency
+
+## Objective
+Add `pymupdf` to `pyproject.toml` dependencies. PyMuPDF provides both PDF text extraction and embedded image extraction via the `fitz` module.
+
+## Work
+1. `pyproject.toml` — add `pymupdf>=1.24,<2.0` to the `dependencies` list (after the existing dependencies, before the dev group). Version pin: `1.24` is a stable release with good text and image extraction support; `<2.0` follows the project's convention of pinning major versions.
+2. ASSUMPTION: none. `pymupdf` is a pure-Python package with optional C extensions (the binary wheels are available for common platforms).
+
+## Testing & Quality
+- No code tests needed — this is a dependency addition.
+- Verify: `uv sync` completes without errors; `import fitz` works in a Python shell.
+
+## Completion Criteria
+- [ ] `uv sync` completes successfully.
+- [ ] `import fitz` works; `fitz.VersionBind` shows the installed version.
+- [ ] `uv run pytest` still green (no regression from the dependency addition).

.agents/phases/complete/126_pdf_support/02_pdf_parser.md

@@ -0,0 +1,173 @@
+# Task 02 — PDF parser module: `app/rag/pdf.py`
+
+**Phase:** `126_pdf_support` · **Source:** `00_phase.md` — text extraction, image extraction, MIME mapping
+
+## Objective
+A new `app/rag/pdf.py` module with pure functions for PDF text extraction, embedded image extraction, and MIME type mapping. All functions are I/O-bound only (read a PDF file, return parsed data) — fully unit-testable with temp PDF fixtures.
+
+## Work
+1. `app/rag/pdf.py` — new module:
+   ```python
+   """PDF parsing utilities (phase 126).
+
+   Pure functions for extracting text and embedded images from PDF files
+   using PyMuPDF (the ``fitz`` module).
+   """
+   from __future__ import annotations
+
+   import hashlib
+   import logging
+   from dataclasses import dataclass
+   from pathlib import Path
+
+   import fitz  # pymupdf
+
+   logger = logging.getLogger("app.pdf")
+
+   #: Page separator used in extracted text (chunker splits on this).
+   PAGE_SEPARATOR = "---PAGE-{page}---"
+
+   @dataclass
+   class PdfImage:
+       """One embedded image from a PDF page."""
+       page: int           #: 1-indexed page number
+       index: int          #: image index on the page (0-based, from fitz)
+       width: int
+       height: int
+       data: bytes         #: raw image bytes
+       mime: str           #: MIME type (e.g., "image/png")
+
+   #: Mapping from PyMuPDF image type codes to MIME types.
+   #: Type codes: 2=JPEG, 3=PNG, 4=GIF, 8=TIFF, 9=WebP (per fitz docs).
+   _TYPE_TO_MIME: dict[int, str] = {
+       2: "image/jpeg",
+       3: "image/png",
+       4: "image/gif",
+       8: "image/tiff",
+       9: "image/webp",
+   }
+
+   def _mime_from_image_info(info: dict) -> str:
+       """Map a PyMuPDF image info dict to a MIME type.
+
+       Falls back to ``application/octet-stream`` for unknown types.
+       """
+       # Try the 'ext' key first (file extension), then the 'type' code.
+       ext = info.get("ext", "").lower()
+       if ext == "png":
+           return "image/png"
+       if ext in ("jpg", "jpeg"):
+           return "image/jpeg"
+       if ext == "gif":
+           return "image/gif"
+       if ext == "webp":
+           return "image/webp"
+       if ext == "tiff" or ext == "tif":
+           return "image/tiff"
+       # Fallback to type code.
+       type_code = info.get("type")
+       if type_code is not None:
+           return _TYPE_TO_MIME.get(type_code, "application/octet-stream")
+       return "application/octet-stream"
+
+   def extract_pdf_text(pdf_path: Path) -> str:
+       """Extract text from all pages of a PDF, joined with page separators.
+
+       Returns the full text with ``---PAGE-N---`` separators between pages.
+       Returns an empty string if the PDF has no text or cannot be opened.
+       """
+       try:
+           doc = fitz.open(str(pdf_path))
+       except Exception as e:
+           logger.warning("pdf: could not open %s — %s", pdf_path, e)
+           return ""
+
+       parts: list[str] = []
+       for page_num in range(len(doc)):
+           page = doc[page_num]
+           text = page.get_text("text").strip()
+           if text:
+               parts.append(f"{PAGE_SEPARATOR.format(page=page_num + 1)}\n{text}")
+           else:
+               # Even empty pages get a separator (for chunker consistency).
+               parts.append(f"{PAGE_SEPARATOR.format(page=page_num + 1)}")
+       doc.close()
+       return "\n\n".join(parts)
+
+   def extract_pdf_images(pdf_path: Path) -> list[PdfImage]:
+       """Extract all embedded images from a PDF.
+
+       Returns a list of ``PdfImage`` dataclasses, one per embedded image.
+       Images are extracted in page order, then by their index on the page.
+       Returns an empty list if the PDF has no embedded images or cannot
+       be opened.
+       """
+       try:
+           doc = fitz.open(str(pdf_path))
+       except Exception as e:
+           logger.warning("pdf: could not open %s for image extraction — %s", pdf_path, e)
+           return []
+
+       images: list[PdfImage] = []
+       for page_num in range(len(doc)):
+           page = doc[page_num]
+           image_list = page.get_images(full=True)
+           for img_index, img_info in enumerate(image_list):
+               try:
+                   xref = img_info[0]
+                   # Get the raw image bytes.
+                   pix = fitz.Pixmap(doc, xref)
+                   # Convert to RGB if needed (CMYK → RGB).
+                   if pix.n - pix.alpha > 3:
+                       pix = fitz.Pixmap(fitz.csRGB, pix)
+                   data = pix.tobytes("png") if pix.n == 4 else pix.tobytes("jpeg")
+                   # Determine the best bytes representation.
+                   # If the image is grayscale or has alpha, use PNG.
+                   # Otherwise, use JPEG for smaller size.
+                   if pix.alpha > 0 or pix.n <= 2:
+                       data = pix.tobytes("png")
+                       mime = "image/png"
+                   else:
+                       data = pix.tobytes("jpeg")
+                       mime = "image/jpeg"
+                   # Fallback: if tobytes fails, use the raw data.
+                   if not data:
+                       data = pix.tobytes()
+                       mime = _mime_from_image_info(img_info)
+
+                   images.append(PdfImage(
+                       page=page_num + 1,
+                       index=img_index,
+                       width=pix.width,
+                       height=pix.height,
+                       data=data,
+                       mime=mime,
+                   ))
+                   pix = None  # free the pixmap
+               except Exception as e:
+                   logger.warning(
+                       "pdf: could not extract image page=%d index=%d — %s",
+                       page_num + 1, img_index, e,
+                   )
+       doc.close()
+       return images
+   ```
+2. ASSUMPTION: none. The module uses only `fitz` (from `pymupdf`) and stdlib.
+
+## Testing & Quality
+- Unit: `tests/unit/test_pdf.py` (task 05) — create temp PDF fixtures using `fitz` itself:
+  - A single-page PDF with text → `extract_pdf_text` returns the text with one page separator.
+  - A multi-page PDF → text with multiple page separators.
+  - A PDF with no text (image-only) → empty string.
+  - A PDF with embedded images → `extract_pdf_images` returns the correct list.
+  - A PDF with no embedded images → empty list.
+  - `_mime_from_image_info` (known types → correct MIME; unknown → fallback).
+  - Error handling: non-existent PDF → empty string / empty list (no exception).
+- Coverage: **>90%** on the new module.
+
+## Completion Criteria
+- [ ] `extract_pdf_text` returns correct text with page separators for a multi-page PDF.
+- [ ] `extract_pdf_images` returns correct image data for a PDF with embedded images.
+- [ ] `_mime_from_image_info` maps known type codes correctly; unknown types get the fallback.
+- [ ] Non-existent or unreadable PDFs return empty results (no exceptions).
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/126_pdf_support/03_pdf_chunking.md

@@ -0,0 +1,56 @@
+# Task 03 — PDF chunking: extend the chunker for `.pdf` files
+
+**Phase:** `126_pdf_support` · **Source:** `00_phase.md` — extend the chunker to handle `.pdf` files
+
+## Objective
+Extend `app/rag/chunker.py`'s `chunk_document` dispatch to handle `.pdf` files. PDF chunks are split on page separators (`---PAGE-N---`), with each page as a logical unit.
+
+## Work
+1. `app/rag/chunker.py` — extend the `chunk_document` dispatch:
+   - Add `.pdf` to the suffix check that dispatches to the paragraph packer (PDFs don't have a format-specific splitter like markdown's heading-based splitting).
+   - The PDF chunker uses the same `chunk_text` function as `txt` (paragraph packing), but with page-aware splitting:
+     ```python
+     def _chunk_pdf(content: str, rel: str, target: int, overlap: int) -> list[str]:
+         """Chunk PDF content, respecting page separators.
+         
+         Pages are the primary split boundary. Each page's text is packed
+         into chunks of ``target`` chars with ``overlap`` chars carry-over.
+         """
+         # Split on page separators.
+         pages = re.split(r'---PAGE-\d+---', content)
+         # pages[0] is empty (content starts with the separator).
+         result: list[str] = []
+         for i, page_text in enumerate(pages[1:], start=1):
+             page_text = page_text.strip()
+             if not page_text:
+                 continue
+             # Prepend the page anchor for readability.
+             anchored = f"Page {i}:\n{page_text}"
+             # Chunk the anchored text using paragraph packing.
+             chunks = chunk_text(anchored, target=target, overlap=overlap)
+             result.extend(chunks)
+         return result
+     ```
+   - Register `.pdf` in the `chunk_document` dispatch table:
+     ```python
+     CHUNKERS: dict[str, Callable] = {
+         ...
+         ".pdf": _chunk_pdf,
+     }
+     ```
+2. ASSUMPTION: none. The PDF chunker reuses the existing `chunk_text` paragraph packer — it only adds page-aware splitting.
+
+## Testing & Quality
+- Unit: `tests/unit/test_chunker.py` (extend) — add PDF-specific tests:
+  - A single-page PDF → one or more chunks with "Page 1:" prefix.
+  - A multi-page PDF → chunks with correct "Page N:" prefixes.
+  - An empty PDF → empty list.
+  - A very large page (>HARD_MAX_CHARS) → split by line (the `chunk_text` behavior).
+  - Verify that page separators in the input are removed from the output chunks.
+- Coverage: **>90%** on the touched code.
+
+## Completion Criteria
+- [ ] `chunk_document` dispatches `.pdf` files to the page-aware chunker.
+- [ ] Chunks have "Page N:" prefixes and no page separator markers.
+- [ ] Multi-page PDFs produce chunks with correct page anchors.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/126_pdf_support/04_pdf_indexing.md

@@ -0,0 +1,262 @@
+# Task 04 — PDF indexing: `_index_pdf_file` in the importer
+
+**Phase:** `126_pdf_support` · **Source:** `00_phase.md` — text + embedded images + summary
+
+## Objective
+Add PDF indexing to the importer: `_index_pdf_file` extracts text, creates the document, chunks + embeds, generates a summary, and handles embedded images.
+
+## Work
+1. `app/rag/importer.py` — add the import:
+   ```python
+   from app.rag.pdf import extract_pdf_text, extract_pdf_images, PdfImage
+   ```
+2. `app/rag/importer.py` — in `_index_file`, add the PDF branch (AFTER the image branch, BEFORE the text branch):
+   ```python
+   # Phase 126: PDF files take the PDF index path.
+   if full_path.suffix.lower() == ".pdf":
+       return await _index_pdf_file(
+           session, source=source, rel=rel, full_path=full_path,
+           llm=llm, summary=summary, raw_date=raw_date,
+       )
+   ```
+3. `app/rag/importer.py` — new `_index_pdf_file` function (follow the `_index_file` text branch pattern):
+   ```python
+   async def _index_pdf_file(
+       session: Session,
+       *,
+       source: str,
+       rel: str,
+       full_path: Path,
+       llm: Embedder,
+       summary: ImportSummary,
+       raw_date: datetime | None = None,
+   ) -> None:
+       """Index one PDF file: extract text, create doc, chunk + embed,
+       summarize, and extract embedded images.
+       """
+       settings = llm.settings
+       # Extract text.
+       content = extract_pdf_text(full_path)
+       if not content:
+           # No text in the PDF — still create a doc (it might have
+           # embedded images), but with empty content.
+           logger.warning("import: PDF has no extractable text source=%s path=%s", source, rel)
+       
+       # Digest over the extracted text (content identity).
+       digest = hashlib.sha256(content.encode("utf-8")).hexdigest() if content else hashlib.sha256(b"").hexdigest()
+       
+       # Get PDF metadata for the title.
+       title = _extract_pdf_title(full_path, fallback=full_path.stem)
+       
+       # Date: use the file's mtime (D2 fallback) — PDFs don't have
+       # standard creation dates accessible via the filesystem.
+       if raw_date is None:
+           raw_date = file_mtime_datetime(full_path)
+       
+       # Upsert the document row.
+       doc = session.scalar(select(Document).where(Document.source == source, Document.path == rel))
+       if doc is None:
+           doc = Document(
+               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),
+           )
+           session.add(doc)
+       else:
+           # Check for content change.
+           if doc.content_hash == digest and doc.content == content:
+               summary.unchanged += 1
+               logger.info("import: unchanged source=%s path=%s", source, rel)
+               # Summary backfill (phase 118, A2).
+               if doc.summary is None:
+                   await _store_summary(
+                       session, doc=doc, source=source, rel=rel,
+                       content=content, llm=llm, summary=summary, backfill=True,
+                   )
+               if doc.created_at_manual:
+                   return
+               target = normalize_doc_date(raw_date)
+               if target != doc.created_at:
+                   doc.created_at = target
+                   session.commit()
+                   summary.dates_updated += 1
+               return
+           
+           doc.full_path = str(full_path)
+           doc.title = title
+           doc.content = content
+           doc.content_hash = digest
+           doc.indexed_at = datetime.now(UTC)
+           doc.created_at = normalize_doc_date(raw_date)
+           doc.created_at_manual = False
+       
+       session.flush()
+       
+       # Chunk and embed.
+       if content:
+           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()
+               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 PDF at %d chars after endpoint token cap: %s",
+                       target // 2, rel,
+                   )
+                   target //= 2
+       
+       session.commit()
+       
+       # Verb count.
+       if doc.content_hash == digest and doc.content == content and doc.id in [d.id for d in []]:
+           # This is a bit awkward — we need to track whether this was
+           # new or updated. Use the session's identity map.
+           pass  # handled by the unchanged path above
+       else:
+           summary.added += 1 if doc.id not in session.identity_map else 0
+           # Actually, let's just use the verb tracking from _index_file.
+           # The simplest approach: track added/updated before the upsert.
+       
+       # Generate summary (phase 30, A2).
+       await _store_summary(
+           session, doc=doc, source=source, rel=rel,
+           content=content, llm=llm, summary=summary, backfill=False,
+       )
+       
+       # Extract and index embedded images.
+       await _index_pdf_embedded_images(
+           session, source=source, rel=rel, full_path=full_path,
+           llm=llm, summary=summary, raw_date=raw_date,
+       )
+       
+       logger.info("import: %s source=%s path=%s chunks=%d",
+                   "added" if newly_created else "updated", source, rel, len(doc.chunks))
+   ```
+   
+   Wait — the above is getting complex. Let me simplify. The key insight is that `_index_pdf_file` should follow the same pattern as `_index_file` but with PDF-specific extraction. Let me refactor.
+
+   Actually, let me simplify this significantly. The `_index_pdf_file` function should:
+   1. Extract text
+   2. Upsert the document
+   3. Chunk + embed
+   4. Generate summary
+   5. Extract embedded images
+   6. Log the result
+
+   The unchanged/hash path is the same as `_index_file` — check the hash, skip if unchanged.
+
+4. `app/rag/importer.py` — `_extract_pdf_title(full_path, fallback) -> str`:
+   - Open the PDF with `fitz`, try to get the metadata title (`doc.metadata.get("title", "")`).
+   - If no title in metadata, return the file stem (the fallback).
+   - Strip whitespace and limit to 500 chars (the `Document.title` column width).
+
+5. `app/rag/importer.py` — `_index_pdf_embedded_images(session, source, rel, full_path, llm, summary, raw_date)`:
+   - Extract embedded images via `extract_pdf_images(full_path)`.
+   - For each image:
+     - If `settings.images` is False → skip (log a debug message).
+     - If the image extension doesn't match `settings.image_extension_set` → skip (log a warning).
+     - Create a synthetic path for the embedded image: `<rel>#page=<N>#img=<index>.<ext>` (e.g., `report.pdf#page=3#img=0.png`).
+     - Call `_index_image_file` with the synthetic path and the image bytes (the `_index_image_file` function expects a `full_path` on disk — we need to either write a temp file or refactor `_index_image_file` to accept bytes directly).
+     - **Alternative approach:** instead of calling `_index_image_file`, handle the embedded image inline: copy the bytes to `settings.image_dir`, describe them via `describe_image`, create the image doc row, chunk + embed the description. This avoids the temp file and the `_index_image_file` refactoring.
+
+   Let me go with the inline approach — it's simpler and avoids refactoring `_index_image_file`:
+   ```python
+   async def _index_pdf_embedded_images(...):
+       images = extract_pdf_images(full_path)
+       for img in images:
+           ext = _ext_from_mime(img.mime)  # "image/png" → ".png"
+           if ext not in settings.image_extension_set:
+               logger.warning("import: PDF embedded image has unsupported extension: %s", img.mime)
+               continue
+           
+           # Write to image_dir.
+           img_id = uuid.uuid4()
+           img_filename = f"{img_id}{ext}"
+           img_dir_path = Path(settings.image_dir)
+           img_dir_path.mkdir(parents=True, exist_ok=True)
+           img_path = str(img_dir_path / img_filename)
+           Path(img_path).write_bytes(img.data)
+           
+           # Describe the image.
+           description = await _describe_or_skip(
+               llm, data=img.data, source=source, rel=f"{rel}#page={img.page}#img={img.index}",
+               mime=img.mime, full_path=Path(img_path),
+           )
+           if description is None:
+               summary.images_failed += 1
+               Path(img_path).unlink(missing_ok=True)
+               continue
+           
+           # Create the image doc row.
+           img_doc = Document(
+               source=source,
+               path=f"{rel}#page={img.page}#img={img.index}{ext}",
+               full_path=img_path,
+               title=f"Embedded image from {full_path.stem} page {img.page}",
+               content=description,
+               content_hash=hashlib.sha256(img.data).hexdigest(),
+               indexed_at=datetime.now(UTC),
+               created_at=normalize_doc_date(raw_date),
+               is_image=True,
+               image_path=img_path,
+           )
+           session.add(img_doc)
+           session.flush()
+           
+           # Chunk + embed the description.
+           chunks_text = chunk_document(description, img_doc.path, 
+                                        settings.chunk_target_chars, settings.chunk_overlap_chars)
+           img_doc.chunks = [
+               Chunk(document_id=img_doc.id, position=i, content=c)
+               for i, c in enumerate(chunks_text)
+           ]
+           session.flush()
+           try:
+               vectors = await llm.embed([c.content for c in img_doc.chunks])
+               for row, vec in zip(img_doc.chunks, vectors, strict=True):
+                   row.embedding = vec
+           except EmbeddingError:
+               pass  # fail soft, like the text path
+           
+           # Summary = description (phase-122 convention for image docs).
+           img_doc.summary = description
+           is_summary_chunk = Chunk(
+               document_id=img_doc.id, position=-1, content=description,
+               is_summary=True,
+           )
+           img_doc.chunks.append(is_summary_chunk)
+           session.flush()
+       
+       session.commit()
+   ```
+
+6. ASSUMPTION: none. The embedded image indexing reuses the same patterns as standalone image indexing (phase 122).
+
+## Testing & Quality
+- Unit: `tests/unit/test_pdf.py` (extend) — `_extract_pdf_title` (PDF with metadata title → returns it; PDF without → returns fallback).
+- Integration: `tests/integration/test_importer.py` (extend) — seed a source with a PDF file → sync → the PDF document has extracted text, chunks, and embedding; embedded images (if `BOR_IMAGES=true`) become image documents.
+- Coverage: **>90%** on the touched modules.
+
+## Completion Criteria
+- [ ] A PDF file in a source → the PDF document has extracted text, chunks, embedding, and summary.
+- [ ] With `BOR_IMAGES=true`: embedded images become image documents.
+- [ ] With `BOR_IMAGES=false`: embedded images are skipped.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.

.agents/phases/complete/126_pdf_support/05_pdf_archive_and_tests.md

@@ -0,0 +1,60 @@
+# Task 05 — PDFs in archives and full test suite
+
+**Phase:** `126_pdf_support` · **Source:** `00_phase.md` — PDFs in archives, unit + integration + E2E tests
+
+## Objective
+Ensure PDFs inside uploaded archives are indexed, and write the full test suite (unit, integration, E2E).
+
+## Work
+1. `app/rag/archive_upload.py` — no code changes needed. Archives are unpacked into `upload_dir`, and the extension walk (`iter_importable_files`) already filters by `import_extension_set`. Adding `pdf` to the set means PDFs in archives are automatically picked up. Verify that the archive unpack doesn't skip `.pdf` files (it shouldn't — archives unpack all files).
+
+2. `app/config.py` — no code changes needed. `pdf` is added to `BOR_IMPORT_EXTENSIONS` by the user (the config already accepts any well-formed extension via `import_extensions`). Document it in `.env.example` alongside the existing extension list:
+   ```
+   # BOR_IMPORT_EXTENSIONS=md,markdown,txt,yaml,yml,json,py,pdf
+   ```
+
+3. `tests/unit/test_pdf.py` (new) — comprehensive unit tests:
+   - Create temp PDF fixtures using `fitz`:
+     - Single-page PDF with text → `extract_pdf_text` returns text with one page separator.
+     - Multi-page PDF (3 pages) → text with 3 page separators.
+     - PDF with no text (blank pages) → empty string.
+     - PDF with embedded images (draw shapes, add text) → `extract_pdf_images` returns the images.
+     - PDF with no embedded images → empty list.
+     - `_mime_from_image_info` (all known type codes → correct MIME; unknown → fallback).
+     - `_extract_pdf_title` (PDF with metadata → returns title; PDF without → returns fallback).
+     - Error handling: non-existent PDF → empty results.
+   - `tests/unit/test_chunker.py` (extend) — PDF-specific chunking tests:
+     - Single-page PDF → correct chunks with "Page 1:" prefix.
+     - Multi-page PDF → correct chunks with "Page N:" prefixes.
+     - Empty PDF → empty list.
+     - Large page → split by line.
+
+4. `tests/integration/test_importer.py` (extend) — integration tests:
+   - Seed a source with a PDF file (create a temp PDF fixture) → sync → the PDF document has extracted text, chunks, and embedding.
+   - A PDF with embedded images + `BOR_IMAGES=true` → embedded images become image documents.
+   - A PDF with embedded images + `BOR_IMAGES=false` → embedded images are skipped.
+   - A PDF with no text → document is created with empty content (no chunks, no embedding).
+   - A PDF referenced in a markdown file → the markdown doc stores the reference info (phase 125 enrichment path).
+
+5. `tests/e2e/test_pdf_support.py` (new) — isolated E2E suite:
+   - Module apps: one app with `BOR_IMAGES=true`, one with `BOR_IMAGES=false`.
+   - KB fixture: create a test PDF with text and an embedded image (using `fitz` in the test setup). Upload via the admin upload flow → sync.
+   - Verify: the PDF appears on the Sources page → open the document viewer → the extracted text renders → ask a question the PDF answers → the chat grounds on the PDF content.
+   - With `BOR_IMAGES=true`: the embedded image appears as a source chip (if retrieved).
+   - With `BOR_IMAGES=false`: no image chip, the PDF text is indexed normally.
+   - Run in isolation: `uv run pytest tests/e2e/test_pdf_support.py -v --no-cov`.
+
+6. Run the full test suite: `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+
+## Testing & Quality
+- All new logic covered by unit tests (PDF parsing, chunking, title extraction).
+- Integration tests cover the full import flow with seeded PDF data.
+- E2E tests cover the real user path: upload → sync → view → ask.
+- No regression in existing tests (run `test_image_documents.py` and `test_image_anchor_context.py` to verify).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_pdf.py -v --no-cov` passes.
+- [ ] `uv run pytest tests/integration/test_importer.py -v --no-cov` passes (extended).
+- [ ] `uv run pytest tests/e2e/test_pdf_support.py -v --no-cov` passes in isolation.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `ruff` + `pyright` clean.
+- [ ] No regression in existing E2E suites.

.agents/phases/complete/127_sync_incremental_folder_summaries/00_phase.md

@@ -0,0 +1,38 @@
+# Phase 127 — Incremental folder summaries: sync rewrites only the directories its changed files touch
+
+**Source:** `TODO.md` L3 — "On sync brain of reese rewrites all the summaries for every directory. So even if just one file changed this can result in 700+ directory summary rewrites in production which can take a very long time."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/api/sync.py` — `_run_sync` step 5 (the changed-KB full-regeneration call to `generate_folder_summaries`, the unchanged-walk gap probe, the `_summary_hook` progress closure, the `SyncStatus` phase machine); `app/rag/folder_summaries.py` — `folder_of`, `group_by_folder` (the recursive-subtree concept), `_candidates`, `_stored_keys`, `missing_folder_summaries`, `generate_folder_summaries` (full / `only_missing` modes, manual-row skip, fail-soft, prune pass, `on_progress` hook, "only flushes — the caller commits"); `app/rag/importer.py` — `ImportSummary` (L212, counts only — no path tracking), the `summary.added += 1` / `summary.updated += 1` increment sites (grep them: the text path ~L794, the image path ~L1068, the PDF path ~L1328, ~L1730, ~L1994) and `_prune` (L2015, deletes vanished docs); `scripts/import_docs.py` — the CLI caller (passes no changed set — full regeneration stays its contract); `tests/unit/test_folder_summaries.py`, `tests/unit/test_importer.py`, `tests/unit/test_sync_button.py` — the existing suites to extend; `tests/e2e/test_sync_summary_visibility.py` — the sync E2E pattern (local `kind=local` source fixture, autouse truncate cleanup, mock-only).
+
+## Objective
+A KB-changing sync regenerates folder summaries for ONLY the folders affected by the documents that actually changed (each changed document's folder chain up to its source root) — one changed file rewrites a handful of rows, not the whole table. Unchanged folders keep their stored rows byte-identical (text AND `updated_at`). Full regeneration remains available and stays the exact behavior for callers that pass no change set (the CLI, any future full-regen need); the unchanged-walk gap probe is untouched.
+
+## Dependencies
+- `126_pdf_support` (complete) — last completed phase; this phase builds on the shipped sync pipeline (phases 32/64/98), the folder-summary generator (phases 94/96/97/98) and the importer.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Change tracking (task 01):** `ImportSummary` gains `changed_paths: list[tuple[str, str]] = field(default_factory=list)` — one `(source, path)` entry per document that was **added, updated, or pruned** in the run, in the order encountered (added/updated in walk order, pruned in `_prune` order). Recorded at EVERY `summary.added += 1` / `summary.updated += 1` site with the site's `(source, rel)` / `(doc.source, doc.path)`, and in `_prune` for each deleted doc (record before `db.delete`). No dedupe needed: a document is added-or-updated at most once per run and pruned docs are gone; the consumer builds a set anyway. `unchanged` / `summary_backfilled` / `dates_updated` NEVER record (their contract is no-regeneration, phase 106/118). The `log()` line is unchanged (the count is derivable: `len(changed_paths) == added + updated + pruned`).
+- **Affected keys (task 02):** `app/rag/folder_summaries.py` gains a pure helper `affected_folder_keys(changed: Iterable[tuple[str, str]]) -> set[tuple[str, str]]` — for each `(source, path)`: the source-root key `(source, "")` plus every folder prefix obtained by walking `folder_of` from the document's nearest folder up to `""` (the SAME one concept `group_by_folder` pass 1 uses — a doc under `a/b/` affects `a/b`, `a`, and the root). `generate_folder_summaries` gains `changed_docs: Sequence[tuple[str, str]] | None = None`:
+  - `None` (default) → today's full regeneration, byte-identical (the CLI path and any explicit full-regen call).
+  - given → `keys = sorted(set(candidates) & affected_folder_keys(changed_docs))`; the generation loop, the manual-row skip (`kept_manual`), the per-folder fail-soft, and the `on_progress` hook (whose `total` becomes the affected count — the sync status's `summaries_total` then reports the affected count through the existing hook) all run over exactly those keys. An affected folder with NO stored row (a gap in an affected folder) is generated like any other candidate. Missing rows in UNaffected folders stay the unchanged-walk gap probe's job (untouched).
+  - the prune pass runs in BOTH modes, unchanged (vanished folders' rows are dropped there, manual rows exempt — the phase-97 rule).
+  - `only_missing=True` (the gap-fill) is untouched and orthogonal.
+- **Sync wiring (task 03):** `app/api/sync.py` `_run_sync` step 5, the changed-KB branch only: `generate_folder_summaries(fs_db, llm, changed_docs=summary.changed_paths, on_progress=_summary_hook)`; the unchanged-walk gap probe branch is byte-identical. The module docstring's step-5 description and the `SyncStatus` docstring get updated to the incremental contract. The success log line names the change count (`sync: folder_summaries changed=N stats=…` — the stats dict stays log-only, the detail shape untouched, phase-98 convention).
+
+## Tasks
+1. `01_importer_changed_paths.md` — `ImportSummary.changed_paths` recorded at every added/updated/prune site.
+2. `02_folder_summaries_affected_mode.md` — `affected_folder_keys` + `generate_folder_summaries(changed_docs=…)`.
+3. `03_sync_wiring.md` — the sync's changed-KB branch passes the change set; docstrings + logging.
+4. `04_e2e_incremental_sync.md` — dedicated Playwright E2E, run in isolation.
+
+## Testing & Quality
+- Unit/integration: every behavior above — the change-set contents/order (all three doc kinds + prune), the affected-keys math (nested folders, roots, multi-source, `#page=`-fragment paths), the generator's changed mode (only-affected upserts, untouched rows byte-identical text AND `updated_at`, manual skip, fail-soft, prune pass, hook total), the CLI no-change path (byte-identical full regen), the sync status's `summaries_total` = affected count.
+- Coverage: **>90%** on new/modified code (`app/`).
+- E2E: one dedicated Playwright file, run in isolation (`uv run pytest tests/e2e/test_incremental_folder_summaries.py -v --no-cov`), mock-only.
+
+## Completion Criteria
+- [ ] a one-file change in a folder rewrites exactly that folder's chain (folder + ancestors + source root) — sibling and other-source rows keep their `updated_at` and text
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%
+- [ ] `uv run pytest tests/e2e/test_incremental_folder_summaries.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (CLI full regen, gap probe, manual rows, phase machine, keep-final-counts)
+- [ ] one atomic Conventional Commit with `--no-gpg-sign` per the AGENTS.md git protocol

.agents/phases/complete/127_sync_incremental_folder_summaries/01_importer_changed_paths.md

@@ -0,0 +1,36 @@
+# Task 01 — `ImportSummary.changed_paths`: the importer records which documents it changed
+
+**Phase:** `127_sync_incremental_folder_summaries` · **Source:** `TODO.md:3` — "On sync brain of reese rewrites all the summaries for every directory. So even if just one file changed this can result in 700+ directory summary rewrites in production which can take a very long time."
+
+## Objective
+`ImportSummary` carries the identity of every document the run added, updated, or pruned — `(source, path)` tuples — so the sync path can scope the folder-summary regeneration to exactly the folders those documents touch.
+
+## Work
+1. `app/rag/importer.py` — `ImportSummary` (L212): add the field with a docstring comment matching the house style:
+   ```python
+   #: Documents this run ADDED, UPDATED, or PRUNED, as (source, path)
+   #: tuples in encounter order (added/updated in walk order, pruned in
+   #: _prune order). Drives the sync's incremental folder-summary
+   #: regeneration (phase 127): len(changed_paths) == added + updated +
+   #: pruned. Unchanged / backfilled / date-only refreshes NEVER record.
+   changed_paths: list[tuple[str, str]] = field(default_factory=list)
+   ```
+2. `app/rag/importer.py` — record at every increment site. Grep `summary.added +=` and `summary.updated +=` (currently the text path ~L794/796, the image path ~L1068/1070, the PDF path ~L1328/1330, ~L1730, ~L1994/1996 — the exact set may have shifted; the rule is: **every** site). At each, immediately beside the counter increment, append the site's identity: `summary.changed_paths.append((source, rel))` (the variables each site already has — `source` + `rel` for the index paths; where a site only has the `doc` row, use `(doc.source, doc.path)`).
+3. `app/rag/importer.py` — `_prune` (L2015): in the delete loop, for each document that is actually deleted (i.e. NOT skipped by the images-off guard and NOT skipped by the phase-126 embedded-image parent rule), append `(doc.source, doc.path)` to `summary.changed_paths` BEFORE `session.delete(...)` — `_prune` needs the summary passed in (add a `summary: ImportSummary | None = None` parameter, recorded only when given; the existing callers — `import_sources`'s prune call — pass it; any other caller keeping `None` stays byte-identical). Check every existing `_prune` call site and update only the `import_sources` one.
+4. `app/rag/importer.py` — do NOT touch `ImportSummary.log()` (the new count is derivable) and do NOT touch the sync's `detail` dict shape (task 03 keeps it log-only).
+
+ASSUMPTION: one entry per changed document is enough (no per-file verb) — the consumer only needs folder keys, and the verb is already in the counters.
+
+## Testing & Quality
+- Unit: `tests/unit/test_importer.py` (extend) or a focused new file —
+  - a walk with 2 added + 1 updated + 1 pruned doc (text files, a temp source dir) → `changed_paths` holds exactly those 4 `(source, path)` pairs, added/updated in walk order, the pruned pair last (or in `_prune` order);
+  - an images-on run with a changed image file records its `(source, rel)` (the image increment site);
+  - a PDF run with a changed PDF records its pair (the PDF increment site);
+  - an unchanged re-run (all `unchanged`) → `changed_paths` empty;
+  - a backfill/date-only run (phase 118/106 shapes, if covered by existing fixtures) → still empty.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] `ImportSummary()` default construction gives `changed_paths == []` (no migration of existing construction sites)
+- [ ] every `added`/`updated`/`pruned` increment in the importer has a matching `changed_paths` append (a grep audit passes: same count of sites)
+- [ ] `uv run pytest tests/unit -q` green; full suite green; no behavior change in completed work

.agents/phases/complete/127_sync_incremental_folder_summaries/02_folder_summaries_affected_mode.md

@@ -0,0 +1,51 @@
+# Task 02 — `affected_folder_keys` + `generate_folder_summaries(changed_docs=…)`: regenerate only the folders a change touches
+
+**Phase:** `127_sync_incremental_folder_summaries` · **Source:** `TODO.md:3` — "On sync brain of reese rewrites all the summaries for every directory. So even if just one file changed this can result in 700+ directory summary rewrites in production which can take a very long time."
+
+## Objective
+The folder-summary generator can be told the set of changed documents and then regenerates ONLY the candidate folders whose recursive subtree contains at least one of them — the change's folder chain per document, plus each source root — with every existing guarantee (manual skip, fail-soft, prune pass, progress hook) intact.
+
+## Work
+1. `app/rag/folder_summaries.py` — new pure helper (place it next to `folder_of` / `group_by_folder`, with a docstring tying it to the recursive-subtree concept):
+   ```python
+   def affected_folder_keys(
+       changed: Iterable[tuple[str, str]],
+   ) -> set[tuple[str, str]]:
+       """The candidate folder keys a changed-document set invalidates.
+
+       For each ``(source, path)``: the source-root key ``(source, "")``
+       plus every folder prefix of *path* — ``folder_of`` walked from the
+       document's nearest folder up to ``""`` — the SAME prefix walk
+       ``group_by_folder`` pass 1 uses (one concept): a doc under
+       ``a/b/`` affects ``a/b``, ``a``, and the source root. A
+       root-level file (``folder_of(path) == ""``) affects ONLY the
+       source root. Embedded-image fragment paths (``x.pdf#page=…#img=…``,
+       phase 126) fold into their parent's folder chain with no special
+       case — ``folder_of`` never sees a ``/`` inside the fragment.
+       Returns a set; the generator sorts it (deterministic order).
+       """
+   ```
+   Empty input → empty set.
+2. `app/rag/folder_summaries.py` — `generate_folder_summaries`: add the kwarg `changed_docs: Sequence[tuple[str, str]] | None = None` (after `only_missing`, before `on_progress` — keyword-only section). Inside, after `candidates = _candidates(_catalog_rows(db))` and the `existing` fetch:
+   - `keys = sorted(candidates)` stays the full-mode default;
+   - when `changed_docs is not None`: `keys = sorted(set(candidates) & affected_folder_keys(changed_docs))` — generation is restricted to affected CANDIDATES (a folder that exists in the catalogue but is unaffected keeps its row; an affected folder with no stored row — a gap — is a candidate and gets generated);
+   - `only_missing=True` keeps its exact current semantics (restricts to missing candidates; the two kwargs are never combined by any caller — document that in the docstring);
+   - the generation loop, `kept_manual` skip, per-folder `LLMError` fail-soft, and the `on_progress(i + 1, len(keys), source, folder_path)` hook are untouched code — `total` simply becomes the affected count when restricted;
+   - the prune pass is untouched (runs in both modes, deletes rows for folders that dropped below the minimum, manual rows exempt).
+   Update the function docstring: the new mode, the one-line contract ("a document's change invalidates exactly its folder chain + source root — the folders whose subtree summary text can change"), and that `changed_docs=None` is the byte-identical full regeneration (the `scripts/import_docs.py` CLI).
+3. `scripts/import_docs.py` — verify (do not modify) that the CLI call passes no `changed_docs` — it must stay a full regeneration.
+
+ASSUMPTION: the intersection (`candidates & affected`) is the correct restriction — an affected folder that no longer has any document is handled by the prune pass, not by generation; an unaffected folder's summary cannot change because its subtree's documents and their first-summary-lines are untouched.
+
+## Testing & Quality
+- Unit: `tests/unit/test_folder_summaries.py` (extend) —
+  - `affected_folder_keys`: a root-level file → `{(src, "")}`; `a/b/c.md` → `{(src, ""), (src, "a"), (src, "a/b")}`; mixed multi-source input; an embedded-image fragment path (`img.pdf#page=2#img=0` under `dir/`) → the `dir` chain; empty input → empty.
+  - `changed_docs=` mode over a seeded catalogue (3 sources, nested folders, a manual row, a failing folder): exactly the affected keys are upserted (fake LLM counts calls — one per non-manual affected key); unaffected rows keep their stored `summary` AND `updated_at` (assert both); manual affected row → `kept_manual`, untouched; a failing affected folder → `failed`, its previous row kept, others still land; the hook fires `len(affected)` times with `total == len(affected)`; the prune pass still drops a vanished folder's row;
+  - `changed_docs=None` over the same catalogue → the pre-task full-regeneration behavior (all candidates, byte-identical stats shape).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] `affected_folder_keys` is a pure function unit-tested on nested / root / multi-source / fragment paths
+- [ ] `generate_folder_summaries(db, llm)` (no new kwarg) behaves exactly as before (existing suite green, unchanged)
+- [ ] restricted mode leaves every unaffected row byte-identical (text AND `updated_at`)
+- [ ] `uv run pytest tests/unit -q` green; full suite green

.agents/phases/complete/127_sync_incremental_folder_summaries/03_sync_wiring.md

@@ -0,0 +1,25 @@
+# Task 03 — Sync wiring: the changed-KB branch regenerates only affected folders
+
+**Phase:** `127_sync_incremental_folder_summaries` · **Source:** `TODO.md:3` — "On sync brain of reese rewrites all the summaries for every directory. So even if just one file changed this can result in 700+ directory summary rewrites in production which can take a very long time."
+
+## Objective
+`POST /api/sync` passes the import's change set into the folder-summary generator, so a one-file sync burns `lite` calls only for that file's folder chain. The status phase machine, progress hook, gap probe, and terminal conventions are unchanged in behavior (the hook's `total` now naturally reports the affected count).
+
+## Work
+1. `app/api/sync.py` — `_run_sync`, step 5, the CHANGED-KB branch (the `if summary.added + summary.updated > 0:` arm that currently calls `generate_folder_summaries(fs_db, llm, on_progress=_summary_hook)`): pass `changed_docs=summary.changed_paths`. The else arm (unchanged walk → `missing_folder_summaries` gap probe → `only_missing=True`) stays byte-identical, including the no-gap skip's "stays `import`" phase behavior.
+2. `app/api/sync.py` — logging: the changed-KB branch's existing `logger.info("sync: folder_summaries stats=%s", folder_stats)` becomes `logger.info("sync: folder_summaries changed=%d stats=%s", len(summary.changed_paths), folder_stats)` (PLAN §9 ample logging — the owner can see how many folders a sync actually rewrote). The gap-fill log line is unchanged.
+3. `app/api/sync.py` — docstrings: the module docstring's step-5 paragraph (the "full regeneration" sentence) and the `SyncStatus` docstring's `summaries_done`/`summaries_total` note — update to the incremental contract: on a changed KB the phase runs over the CHANGED set's folder keys (the hook's `total` is the affected count, not the table's candidate count); on an unchanged walk the gap-fill total is the missing count (as before); terminal states keep the final counts (the phase-64 convention, unchanged).
+4. Verify: the `detail` dict shape is untouched (no new key — the stats stay log-only, phase-98 convention); `GET /api/sync/status` shape is untouched (the chunk-free status fields are already there; no new fields in this phase).
+
+## Testing & Quality
+- Unit/integration: extend the sync unit suite (`tests/unit/test_sync_button.py` and/or the sync-pipeline test file that fakes `import_sources` + `generate_folder_summaries` — inspect the existing fakes first):
+  - a changed-KB sync (fake import returning 1 updated doc) → `generate_folder_summaries` receives `changed_docs=` equal to the fake's change set (assert on the fake's captured kwargs) and the success detail is unchanged in shape;
+  - an unchanged walk with a gap → still `only_missing=True`, no `changed_docs` (the gap probe is orthogonal);
+  - the status during the summaries phase reports `summaries_total == len(affected keys)` (fake generator whose hook total is its key count — follow the existing phase-machine test pattern).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a changed-KB sync calls the generator with `changed_docs=summary.changed_paths`; an unchanged walk calls it exactly as before
+- [ ] `GET /api/sync/status` and the success `detail` shapes are byte-identical to pre-phase
+- [ ] docstrings + log lines reflect the incremental contract
+- [ ] `uv run pytest tests/unit -q` green; full suite green

.agents/phases/complete/127_sync_incremental_folder_summaries/04_e2e_incremental_sync.md

@@ -0,0 +1,24 @@
+# Task 04 — E2E: a one-file change rewrites only that folder's summary chain
+
+**Phase:** `127_sync_incremental_folder_summaries` · **Source:** `TODO.md:3` — "On sync brain of reese rewrites all the summaries for every directory. So even if just one file changed this can result in 700+ directory summary rewrites in production which can take a very long time."
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) proving the owner-visible fix end to end: after a first full sync, changing ONE file in ONE folder and re-syncing re-stamps exactly that folder's chain (the folder + its ancestors + the source root) and leaves every other stored row byte-identical.
+
+## Work
+1. `tests/e2e/test_incremental_folder_summaries.py` (new) — follow `tests/e2e/test_sync_summary_visibility.py`'s house pattern exactly (module-level app fixture over the shared E2E Postgres, host temp-dir `kind=local` source registered via the admin git-sources API, autouse cleanup that truncates `documents`/`chunks`/`query_log`/`steering_notes`/`kb_overview`/`git_sources`/`folder_summaries` and waits for no running sync, mock-only — `E2E_REAL_LLM=1` unsupported). No slow-LLM proxy needed: the assertions are on POST-terminal DB state + the terminal status (the keep-final-counts convention), not on in-flight sampling.
+   KB fixture — one local source `incsum/` (temp dir) with FOUR folders `alpha/`, `bravo/`, `charlie/`, `delta/`, two markdown docs each, plus one root-level doc: the generator's candidate set is exactly 5 rows (source root + 4 folders — the recursive-subtree ≥ 1 rule).
+2. Test → observable mapping (Playwright Mapping Rule):
+   - `test_first_sync_generates_all_rows` — admin sync #1 settles `success`; the `folder_summaries` table holds exactly the 5 rows (the mock's deterministic `FOLDER_SUMMARY_MODE` canned text names each folder — `tests/e2e/mock_llm.py`'s existing canned reply), each `updated_at` non-null.
+   - `test_one_file_change_restamps_only_that_folders_chain` — after test 1's state is re-seeded (autouse truncates, so seed again): re-run sync #1, capture each row's `(summary, updated_at)`; then modify ONE doc inside `alpha/` (change its content), sync #2 settles `success`; assert: `alpha` + the source root rows have a NEW `updated_at` (strictly after the captured ones) and the canned text; `bravo`/`charlie`/`delta` rows are byte-identical (same `summary` AND same `updated_at`); the terminal `GET /api/sync/status` keeps `summaries_done == summaries_total == 2` (the affected count — alpha + root, the keep-final-counts convention) and `detail.added/updated/unchanged/pruned` show the single-file change.
+   - `test_pruned_file_restamps_only_its_chain_and_prunes_the_vanished_folder` — seed + full sync; capture; delete `bravo/`'s LAST doc (the folder vanishes) and modify one doc in `charlie/`; sync settles; assert: the `bravo` row is PRUNED (gone — the prune pass), the source root + `charlie` rows re-stamped, `alpha`/`delta` byte-identical.
+3. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_incremental_folder_summaries.py -v --no-cov`), the mock-only gate, the fixture layout, and the test→observable table (the house format).
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's unit/integration coverage bar (>90% on `app/`) is already carried by tasks 01–03; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_incremental_folder_summaries.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the three tests above map 1:1 to the TODO's observable: one changed file → a handful of rewrites, not 700+
+- [ ] no behavior change in completed phases (the full-regen first sync, the gap probe, the phase machine)

.agents/phases/complete/128_sync_label_mobile/00_phase.md

@@ -0,0 +1,32 @@
+# Phase 128 — The sync label shows on mobile, count always visible
+
+**Source:** `TODO.md` L4 — "The `Syncing… name/of/file/here (2/3)` doesn't show up on mobile, it needs to" (the item is truncated in the TODO; ASSUMPTION A1 — read as: the running label must be fully visible on mobile, with the `(n/m)` position never clipped off-screen).
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `frontend/index.html` L449–451 — the `#sync-btn` / `#sync-label` markup (one span holds the whole label string); `frontend/assets/sources.js` — `fmtSyncLabel(kind, currentFile, done, total)` (~L650) and `fmtSyncPhaseLabel(status)` (~L669) build the running labels as ONE string, the poll loop applies them to `#sync-label` + the button `title` + `#sync-result` (the aria-live announcer — the untruncated text rides both, A4 convention); `frontend/assets/styles.css` — `.sync-label` (~L2067: `inline-block`, `max-width: min(16rem, 40vw)`, ellipsis, `nowrap`) and the mobile media query (~L5323: `.sync-btn { width: 100%; }`, `.sync-label { max-width: none; min-width: 0; }` — with `max-width: none` the inline-block sizes to its FULL content, so the label's tail — where `(n/m)` lives — runs off-screen: the reported bug); `tests/unit/test_frontend_sync_upload.py` — the pinned frontend label tests to update.
+
+## Objective
+On a phone, the running sync label is fully visible: the file path ellipsizes to fit, and the `(n/m)` position sits in its own non-shrinking span that is NEVER clipped — in the import phase (`Syncing… <file> (2/3)`) and the summaries phase (`Summarizing folders… <folder> (n/m)`). Desktop renders the same content with its existing visual layout (the cap, the ellipsis, the title/aria-live untruncated text all preserved).
+
+## Dependencies
+- `127_sync_incremental_folder_summaries` (todo) — pipeline order only; code dependencies are the completed phase-64/98 label contract.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Markup (task 01):** `#sync-label` gains two child spans — `<span class="sync-label-main"></span><span class="sync-label-count" hidden></span>` (static markup in `index.html`). The JS builders no longer return one string: a single `setSyncLabel(mainText, countText)` helper writes `textContent` into the parts (the createElement/textContent house rule — no HTML strings) and toggles the count span's `hidden` (absent count → hidden, empty). The FULL untruncated label (`mainText + (countText ? " " + countText : "")`) is still set on the button `title` and `#sync-result` exactly as today (A4 — screen readers hear the whole thing).
+- **Label mapping (task 01):** main/count per state — prelude (null phase, no file): main `"Syncing…"`, no count; import: main `"Syncing… <file>"`, count `"(n/m)"` while `total > 0`; overview: main `"Writing KB overview…"`, no count; summaries: main `"Summarizing folders… <folder>"` (no folder part while `current_summary` is null), count `"(n/m)"`; upload: main `"Importing"`, no count (phase-90 contract — the upload status carries no file or counts); idle/settle labels (`"Sync sources"`, `"Synced HH:MM"`): main only. `fmtSyncPhaseLabel`'s decision tree is preserved 1:1 — only the OUTPUT shape changes (string → parts).
+- **CSS (task 02):** `.sync-label` becomes a flex row (`display: inline-flex; align-items: baseline; gap: 0.35rem; min-width: 0; max-width: min(16rem, 40vw);`); `.sync-label-main { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }`; `.sync-label-count { flex: 0 0 auto; white-space: nowrap; }`. Mobile media query (the existing block at ~L5323): `.sync-label { max-width: none; flex: 1 1 auto; min-width: 0; }` — the label fills the full-width pill, the main part ellipsizes against the remaining width, the count span stays visible at the right edge. The `#sync-result` mobile clip (visually-hidden) is untouched.
+
+## Tasks
+1. `01_label_parts.md` — markup + `setSyncLabel` part builders in `sources.js` (all label states, A4 untruncated text preserved).
+2. `02_mobile_css.md` — the flex-part CSS + the mobile media query.
+3. `03_e2e_mobile_label.md` — dedicated Playwright E2E, run in isolation.
+
+## Testing & Quality
+- Unit: `tests/unit/test_frontend_sync_upload.py` — the pinned label outputs updated to the part shape (main/count per state, the byte-identical label strings where they must hold: prelude, upload, settle); the `title`/`#sync-result` untruncated text pins stay.
+- E2E: one dedicated Playwright file, run in isolation, mobile viewport, slow-LLM pattern.
+- Coverage: **>90%** on new/modified code (frontend: the JS is covered by the pinned unit tests + the E2E; `app/` untouched this phase).
+
+## Completion Criteria
+- [ ] at a phone viewport (390×844) the running label is fully in the viewport — file path ellipsized, `(n/m)` visible — in BOTH the import and summaries phases
+- [ ] desktop label visually unchanged (same strings, same cap/ellipsis, same `title`/`#sync-result` untruncated text)
+- [ ] `uv run pytest tests/e2e/test_sync_label_mobile.py -v --no-cov` green in isolation
+- [ ] `uv run pytest` (unit + integration) green; no behavior change in completed phases

.agents/phases/complete/128_sync_label_mobile/01_label_parts.md

@@ -0,0 +1,29 @@
+# Task 01 — `#sync-label` becomes parts: the file path ellipsizes, the `(n/m)` count is pinned
+
+**Phase:** `128_sync_label_mobile` · **Source:** `TODO.md:4` — "The `Syncing… name/of/file/here (2/3)` doesn't show up on mobile, it needs to" (A1: fully visible on mobile, count never clipped)
+
+## Objective
+The label's string is split into a shrinks-to-fit main part (prefix + file/folder path) and a pinned count part (`(n/m)`), so CSS can ellipsize the path while the position always stays on-screen. Every existing label state keeps its exact rendered text.
+
+## Work
+1. `frontend/index.html` (L449–451) — inside `#sync-label`, replace the bare text with the two part spans (the initial text lives in the main span so the pre-JS idle label renders):
+   ```html
+   <span class="sync-label" id="sync-label"><span class="sync-label-main">Sync sources</span><span class="sync-label-count" hidden></span></span>
+   ```
+2. `frontend/assets/sources.js` — one new helper where `fmtSyncLabel`/`fmtSyncPhaseLabel` live (~L650): `setSyncLabel(mainText, countText = "")` — sets `syncLabelMain.textContent = mainText`; if `countText`: `syncLabelCount.textContent = countText`, `syncLabelCount.hidden = false`; else `syncLabelCount.textContent = ""`, `hidden = true`; then sets the UNTRUNCATED full label — `mainText + (countText ? " " + countText : "")` — on `syncBtn.title` and `syncResult.textContent` (the A4 convention: title + aria-live always carry the whole thing). Get the part elements once at `mount` scope (the `querySelector` house pattern; null-guard like `syncLabel`).
+   - `fmtSyncLabel(kind, currentFile, done, total)` → return the PARTS: `main = currentFile ? `${prefix} ${currentFile}` : prefix` (prefix `"Syncing…"` / `"Importing"` as today), `count = total > 0 ? `(${done}/${total})` : ""`; call `setSyncLabel(main, count)`. The byte-identical full strings hold: `"Syncing…"` (no file), `"Syncing… <file>"` (no total), `"Syncing… <file> (n/m)"`, `"Importing"`.
+   - `fmtSyncPhaseLabel(status)` → same decision tree (overview / summaries / fall-through), emitting parts: overview → `("Writing KB overview…", "")`; summaries → `(`Summarizing folders…${folder}`, `(${status.summaries_done}/${status.summaries_total})`)` with the folder part omitted while `current_summary` is null (as today) — the count is ALWAYS emitted in this phase (the hook always carries a total); fall-through → the `fmtSyncLabel` parts. The full-string shape is byte-identical to the pre-task strings.
+   - Every OTHER call site that writes `#sync-label` (idle `"Sync sources"`, settle `"Synced HH:MM"`, the 202/409 click fallback, the re-attach `initSyncButton` path) goes through `setSyncLabel(main)` — count hidden.
+   - The upload job keeps the bare `"Importing"` (no file, no counts — phase-90 contract).
+3. `tests/unit/test_frontend_sync_upload.py` — update the pinned label tests to the part shape: pin the main/count pair per state (prelude, import with/without total, overview, summaries with/without folder, upload, idle, settle) AND the `title` / `#sync-result` untruncated concatenation (the A4 pins).
+
+ASSUMPTION (A1 restated): the truncated TODO item is satisfied by "label fully visible on mobile + count never clipped" — no wrapping, no progress bar.
+
+## Testing & Quality
+- Unit: the updated pins above green; no HTML strings anywhere in the label path (textContent only).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] every running/idle/settle label renders the SAME full string as pre-task on desktop (the part concatenation is byte-identical)
+- [ ] the count span is `hidden` whenever there is no `(n/m)` to show
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/128_sync_label_mobile/02_mobile_css.md

@@ -0,0 +1,46 @@
+# Task 02 — CSS: the label parts flex — path ellipsizes, count pinned, mobile fully visible
+
+**Phase:** `128_sync_label_mobile` · **Source:** `TODO.md:4` — "The `Syncing… name/of/file/here (2/3)` doesn't show up on mobile, it needs to" (A1: fully visible on mobile, count never clipped)
+
+## Objective
+The label's two parts are laid out so the path can ellipsize against whatever width is available — and on a phone, where the pill is full-width, the path ellipsizes and the `(n/m)` count sits pinned at the right edge, always on-screen.
+
+## Work
+1. `frontend/assets/styles.css` — replace the `.sync-label` rule (~L2067, the phase-64 comment block above it stays, updated to name the parts):
+   ```css
+   .sync-label {
+     display: inline-flex;
+     align-items: baseline;
+     gap: 0.35rem;
+     min-width: 0;
+     max-width: min(16rem, 40vw);
+   }
+   .sync-label-main {
+     min-width: 0; /* the flex item that shrinks — what engages the ellipsis */
+     overflow: hidden;
+     text-overflow: ellipsis;
+     white-space: nowrap;
+   }
+   .sync-label-count {
+     flex: 0 0 auto; /* NEVER clipped — the (n/m) position is the point */
+     white-space: nowrap;
+     font-family: var(--mono); /* the .sync-result mono language (position reads as data) */
+   }
+   ```
+   (The old `display: inline-block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; vertical-align: bottom;` moves to `.sync-label-main` — `vertical-align` is gone: the flex row aligns it.)
+2. `frontend/assets/styles.css` — the mobile media query block (~L5323, the "full-width LABELED pills" comment): update the two sync rules:
+   ```css
+   .sync-btn { width: 100%; }
+   .sync-label { max-width: none; flex: 1 1 auto; min-width: 0; }
+   ```
+   — the label now fills the full-width pill; `.sync-label-main` (min-width: 0 inside a flex row that can shrink) ellipsizes against the width left by the pinned count; the count stays visible at the right edge. Do NOT touch the `#sync-result` visually-hidden clip, the `#sync-btn` aria-label, or the other mobile rules in that block.
+3. Audit: grep for every `.sync-label` reference in `styles.css` — the only rules are the base + this mobile block (the phase-64/98 history is in comments). Confirm no other stylesheet (theme override, page-scoped) styles the label; the built-in theme must stay byte-identical in the no-row case (B4 — no `ui_settings` dependency here, this is static CSS).
+
+## Testing & Quality
+- The visual gate is the E2E (task 03) — desktop vs mobile bounding-box + text assertions; no new Python surface.
+- Coverage: **>90%** on new/modified code (CSS has no direct coverage — the E2E + unit pins carry it).
+
+## Completion Criteria
+- [ ] desktop: long paths still ellipsize inside the `min(16rem, 40vw)` cap, count visible after the ellipsis
+- [ ] mobile (390 px): label fills the pill, path ellipsized, `(n/m)` on-screen at the right edge (the E2E asserts bounding boxes)
+- [ ] `uv run pytest` green; no behavior change in completed phases

.agents/phases/complete/128_sync_label_mobile/03_e2e_mobile_label.md

@@ -0,0 +1,24 @@
+# Task 03 — E2E: the running sync label is fully visible with its count on mobile (and unchanged on desktop)
+
+**Phase:** `128_sync_label_mobile` · **Source:** `TODO.md:4` — "The `Syncing… name/of/file/here (2/3)` doesn't show up on mobile, it needs to" (A1: fully visible on mobile, count never clipped)
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) proving the label's geometry: at a phone viewport the rendered `#sync-label` fits the viewport with the `(n/m)` count span visible in BOTH long spans (import + summaries); at a desktop viewport the label keeps its pre-phase strings and cap.
+
+## Work
+1. `tests/e2e/test_sync_label_mobile.py` (new) — follow `tests/e2e/test_sync_summary_visibility.py`'s house pattern (module app fixtures over the shared E2E Postgres, host temp-dir `kind=local` source, autouse truncate cleanup, mock-only). Use the SLOW app (the `tests/e2e/slow_llm.py` proxy, `SLOW_DELAY_S = 1.5` as there) so each phase span outlives the UI's 2 s poll — the rendered-label assertions are deterministic, not races.
+   KB fixture — one local source `synclabel/` with TWO files in `alpha/` and TWO in `bravo/` (the summaries phase then has 3 candidate folders: root + 2 — a non-trivial `(n/m)`).
+2. Test → observable mapping (Playwright Mapping Rule):
+   - `test_mobile_label_fits_viewport_with_count_in_import` — admin page on the sources view at viewport **390×844** (mobile); click **Sync sources**; while the import phase is running (the page's own 2 s poll): the rendered `#sync-label`'s bounding box is INSIDE the viewport (left ≥ 0, right ≤ 390) — the bug's direct negation; `.sync-label-count` is visible (`boundingBox` non-null, not clipped: its right edge ≤ the button's right edge) with text matching `\(\d+/\d+\)` once a file is in flight; `.sync-label-main` carries `Syncing… <file>` (the file part may be visually ellipsized — assert the button `title` carries the UNTRUNCATED label, A4).
+   - `test_mobile_label_shows_summaries_count` — same mobile viewport; through to the summaries phase: `.sync-label-main` matches `Summarizing folders…` (folder part optional), `.sync-label-count` matches `\(\d+/3\)` and stays visible; settle: the button leaves the running label (`Synced HH:MM` or the phase-32 terminal shape), the count span hidden/empty.
+   - `test_desktop_label_unchanged` — viewport 1280×800; same sync: during import the FULL rendered label text (main + count concatenation) matches `Syncing… <full source/relative/path> (n/m)` — the pre-phase byte-identical string — and the label's width respects the `min(16rem, 40vw)` cap (bounding box width ≤ 256 px + slack); `title` carries the same untruncated string.
+3. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_sync_label_mobile.py -v --no-cov`), the mock-only + slow-proxy rationale (re-sized from the phase-98 suite's comment), the fixture layout, the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% bar is carried by task 01's updated unit pins (frontend JS); this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_sync_label_mobile.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the mobile tests fail against the pre-phase markup/CSS (the count ran off-screen) — i.e. the suite actually pins the fix
+- [ ] no behavior change in completed phases (label strings, phase machine, aria-live)

.agents/phases/complete/129_sync_chunk_progress/00_phase.md

@@ -0,0 +1,36 @@
+# Phase 129 — The sync label shows what chunk we're on out of how many
+
+**Source:** `TODO.md` L5 — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (ASSUMPTION A6, owner-confirmed 2026-09-27: "chunk" = the current file's EMBEDDING CHUNKS; position reported at BATCH granularity — `n` = first chunk of the in-flight token-budgeted embed batch — because the transport embeds batches per HTTP call and per-chunk calls would be a latency regression; the summary-chunk embed is excluded from the counter; label `Syncing… <file> (2/3) · chunk 14/38`).
+**Story:** n/a (TODO-derived phase, Protocol B append; a NEW feature — distinct from phase 128's mobile fix, per the owner).
+**Context:** `app/rag/llm.py` — `LLMClient.embed(texts)` (L346: iterates `self._batch_texts(texts)` — token-budgeted batches, `BOR_EMBED_BATCH_SIZE` cap, `_REQUEST_TOKEN_BUDGET` ≈ 2800 chars), `_embed_batch` (L289: the halving backstop on `_TooLarge`), `self.embed_batches` counter (L249); `app/rag/importer.py` — `import_sources` (L408, the per-file `progress(source, rel, done, total)` hook fired BEFORE each `_index_file`), `_index_file` (L647 — text branch → `_replace_content_chunks`, image branch → `_index_image_file`, PDF branch → `_index_pdf_file`), `_replace_content_chunks` (L603 — chunks the content, `llm.embed([c.content for c in doc.chunks])` in ONE call, token-cap re-chunk retry loop), `_store_summary` (embeds the ONE summary chunk — EXCLUDED from the counter); `app/api/sync.py` — `SyncStatus` (the phase-64/98 progress fields: `current_file`, `files_done/total`, `phase`, `current_summary`, `summaries_done/total`; `_run_sync`'s `_hook` closure convention; terminal-state clearing); `frontend/assets/sources.js` — the phase-128 part builders (`setSyncLabel`, `.sync-label-main` / `.sync-label-count`); `tests/e2e/slow_llm.py` + `tests/e2e/test_sync_summary_visibility.py` — the slow-proxy sampling pattern.
+
+## Objective
+While a file is being imported, the sync status (endpoint + button label) shows the file's embedding-chunk position: `Syncing… <file> (2/3) · chunk 14/38` — 14 = the first chunk of the embed batch in flight, 38 = the file's total content chunks. The position climbs through the file's batches and is cleared when the file (or the run) moves on. Everything that passes no callback stays a zero-cost no-op (the CLI, the chat path).
+
+## Dependencies
+- `128_sync_label_mobile` (todo) — the label's part structure (`.sync-label-main` + pinned count span) is the carrier; this phase adds the pinned chunk span.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The embed hook (task 01):** `LLMClient.embed(texts, on_progress: Callable[[int, int], None] | None = None)` — before EACH top-level batch request, `on_progress(first_1based, len(texts))` where `first_1based` = 1 + the cumulative chunk counts of the already-sent batches. `None` (every existing caller — the chat retrieval path, `embed_one`, the summarizer, the CLI) is a zero-cost guarded no-op. The `_embed_batch` halving backstop does NOT sub-report — the top-level loop reports batch starts; a halved batch means the position is approximate (document in the docstring; the backstop is rare by construction).
+- **Importer plumbing (task 02):** `import_sources(..., on_chunk_progress: Callable[[int, int], None] | None = None)` — a new keyword-only param, plumbed: `import_sources` → `_index_file(..., on_chunk=...)` (all three branches: text, image, PDF — the PDF branch's content embed is the same `_replace_content_chunks` call; the image branch's ONE description-chunk embed reports `1/1` — acceptable, it IS the file's only chunk) → `_replace_content_chunks(..., on_chunk=...)` → `llm.embed([...], on_progress=on_chunk)`. The token-cap re-chunk retry re-embeds with the NEW (smaller-target) chunk list — the hook naturally reports against the new total (no special case). `_store_summary`'s single summary-chunk embed NEVER receives the hook (the counter is content chunks only — no `1/1` noise after the real progress ends). The `scripts/import_docs.py` CLI passes nothing — byte-identical.
+- **Sync status (task 03):** `SyncStatus` gains `current_chunk: int = 0` and `chunks_total: int = 0` (documented: the current file's embed-batch position — 0/0 before the first batch and in terminal states). `_run_sync`: reset to 0/0 at run start (with the other progress fields); a closure `_chunk_hook(chunk, total)` (the file's `_hook` convention) sets them; passed as `on_chunk_progress` to `import_sources`. CLEARED (0/0) when the import phase ends — set at the `phase = "overview"` and `phase = "summaries"` transitions AND in both terminal states (the `current_file` clearing points — same convention, same spots). `GET /api/sync/status` exposes both fields (0/0 idle — the dataclass defaults). The `SyncStatus` docstring + module docstring get the chunk-position paragraph (the phase-64/98 style).
+- **UI (task 04):** `sources.js` — the import-phase label gains a THIRD pinned part `.sync-label-chunk` (markup in `index.html`'s `#sync-label`, `hidden` by default): when `status.chunks_total > 0` the import fall-through emits `· chunk ${status.current_chunk}/${status.chunks_total}` into it; every other phase/state leaves it hidden/empty (the summaries phase has its own `(n/m)` — no chunk part; the prelude has no file yet). The UNTRUNCATED concatenation (main + count + chunk part) rides the button `title` + `#sync-result` (A4). The pinned unit tests (`tests/unit/test_frontend_sync_upload.py`) gain the chunk-part pins.
+
+## Tasks
+1. `01_llm_embed_hook.md` — `LLMClient.embed`'s optional per-batch `on_progress`.
+2. `02_importer_chunk_progress.md` — `import_sources` → `_index_file` → `_replace_content_chunks` → `embed` plumbing.
+3. `03_sync_status_chunk_fields.md` — `SyncStatus` fields, the closure, clearing, the endpoint.
+4. `04_ui_chunk_part.md` — the label's chunk part + unit pins.
+5. `05_e2e_chunk_progress.md` — dedicated Playwright E2E, run in isolation.
+
+## Testing & Quality
+- Unit/integration: the embed hook's call sequence (batch boundaries, `None` no-op, halving-approximate documented); the importer plumbing (hook fires per file with its own total; the CLI path unchanged; the summary-chunk embed never fires it); the sync status (fields in the endpoint JSON, reset per run, cleared at phase transitions + terminal, 0/0 idle).
+- Coverage: **>90%** on new/modified code (`app/`).
+- E2E: one dedicated Playwright file, run in isolation, slow-LLM sampling.
+
+## Completion Criteria
+- [ ] `GET /api/sync/status` reports `current_chunk` climbing 1 → N with `chunks_total` = the file's true content-chunk count while a file imports (E2E, sampled)
+- [ ] the rendered mobile/desktop label shows `· chunk n/m` during the import phase only; the untruncated text rides `title` + `#sync-result`
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%
+- [ ] `uv run pytest tests/e2e/test_sync_chunk_progress.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (chat embed path, CLI import, the phase-64/98 label contract minus the new part)

.agents/phases/complete/129_sync_chunk_progress/01_llm_embed_hook.md

@@ -0,0 +1,28 @@
+# Task 01 — `LLMClient.embed`'s optional per-batch `on_progress` hook
+
+**Phase:** `129_sync_chunk_progress` · **Source:** `TODO.md:5` — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (A6: batch-granularity chunk position)
+
+## Objective
+`embed` can report, before each top-level batch request, which chunk of the input list starts that batch — `on_progress(first_1based, total)` — so a caller can render `chunk n/m`. No callback → zero-cost no-op, byte-identical behavior for every existing caller.
+
+## Work
+1. `app/rag/llm.py` — `LLMClient.embed` (L346): new keyword-only param `on_progress: Callable[[int, int], None] | None = None`. In the batch loop, BEFORE `await self._embed_batch(chunk)` (and before the try/except, so a failing batch still announced its start):
+   ```python
+   if on_progress is not None:
+       on_progress(len(out) + 1, len(texts))  # first chunk of THIS batch (1-based), total
+   ```
+   (`len(out)` = chunks already embedded in earlier batches — the accumulator's length is exactly that, since each batch's vectors extend it 1:1.)
+   Docstring: the contract — called once per TOP-LEVEL batch, before the request, with `(first_chunk_1based, total_chunks)`; the `_embed_batch` halving backstop does not sub-report (a halved batch makes the position approximate — documented; the backstop is rare by construction, phase-114 `_TooLarge` handling); `None` is a zero-cost guarded no-op (every pre-task caller — chat retrieval, `embed_one`, the summarizer, the importer — passes nothing and is byte-identical).
+2. Do NOT touch `_batch_texts` / `_embed_batch` internals, `embed_batches` counting, or `embed_one`.
+
+## Testing & Quality
+- Unit: `tests/unit/` (extend the existing LLM-client test file — inspect `tests/unit/test_llm*.py` first):
+  - N texts sized to force ≥ 3 batches (shrink the token budget via settings or pick chunk lengths against `_REQUEST_TOKEN_BUDGET`) → `on_progress` called with `(1, N)`, `(k2, N)`, … `total` always `len(texts)`, first-indices strictly increasing, each = previous first + previous batch size (assert against `_batch_texts`'s actual partition — call it directly to get the expected boundaries);
+  - `on_progress=None` → the call sequence and return value are identical to pre-task (the existing suite is the pin);
+  - empty `texts` → no hook calls (the early return).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] the hook fires per top-level batch with the correct `(first, total)` pair (unit-pinned)
+- [ ] every existing `embed`/`embed_one` call site is untouched and its tests green
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/129_sync_chunk_progress/02_importer_chunk_progress.md

@@ -0,0 +1,28 @@
+# Task 02 — Importer plumbing: `on_chunk_progress` from `import_sources` to the content-chunk embed
+
+**Phase:** `129_sync_chunk_progress` · **Source:** `TODO.md:5` — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (A6: batch-granularity chunk position)
+
+## Objective
+`import_sources` accepts an optional `on_chunk_progress` callback that fires with the CURRENT FILE's content-chunk position while that file's chunks embed — so the sync status can attribute the position to the file its per-file `progress` hook already named.
+
+## Work
+1. `app/rag/importer.py` — `import_sources` (L408): new keyword-only param `on_chunk_progress: Callable[[int, int], None] | None = None` (documented in the docstring next to the `progress` paragraph: same "only when provided — `None` callers pay nothing" rule; it carries the in-flight FILE's chunk position, not the file identity — the per-file `progress` hook owns that).
+2. `app/rag/importer.py` — the processing loop's `_index_file` call: pass `on_chunk=on_chunk_progress` (a new keyword-only param on `_index_file`, default `None`).
+3. `app/rag/importer.py` — `_index_file`:
+   - the TEXT branch → `_replace_content_chunks(session, doc=doc, llm=llm, content=content, rel=rel, on_chunk=on_chunk)`;
+   - the IMAGE branch (`_index_image_file`) and the PDF branch (`_index_pdf_file`) → pass `on_chunk` through to THEIR `_replace_content_chunks` calls (the image branch's one description-chunk embed reports `1/1` — it IS the file's only chunk; the PDF branch's content embed is the primary target). Verify each branch's embed path: if a branch embeds chunks somewhere other than `_replace_content_chunks`, route the hook there too (one hook per branch, content chunks only).
+4. `app/rag/importer.py` — `_replace_content_chunks` (L603): new keyword-only param `on_chunk: Callable[[int, int], None] | None = None`, forwarded to `llm.embed([c.content for c in doc.chunks], on_progress=on_chunk)`. The token-cap re-chunk retry loop (the `while True` that halves `target`) re-embeds with the new chunk list — the hook reports against the NEW total automatically (no special case; document it in the docstring). The `doc.chunks = []` empty-content `break` never embeds (no hook fire).
+5. `_store_summary` (and its summary-chunk `embed_one`/`embed` call) NEVER receives the hook — the counter is content chunks only (A6: no `1/1` noise after the real progress ends). The `scripts/import_docs.py` CLI passes nothing — byte-identical (verify the call site).
+
+## Testing & Quality
+- Unit: `tests/unit/test_importer.py` (extend) —
+  - a text file that chunks into ≥ 2 batches (size the fixture against the token budget, or monkeypatch `_batch_texts`) with a fake `on_chunk_progress` recorder → the recorder sees `(first, total)` pairs with `total == the file's chunk count`, one batch-run per file, and a SECOND file in the same run gets its OWN sequence (the position restarts per file — the recorder's `(first, total)` pairs never mix the two files' totals);
+  - the image branch (images toggle on, a fixture image) → the recorder sees exactly `(1, 1)` for that file;
+  - `on_chunk_progress=None` (the CLI shape) → no recorder, behavior byte-identical (the existing suite is the pin);
+  - the summary-chunk embed never fires the hook (the recorder's call count == the content-embed batches only).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a multi-batch file's embed position is fully observable through `import_sources(on_chunk_progress=…)` (unit-pinned)
+- [ ] the CLI path and the summary-chunk embed are untouched (byte-identical, verified by the existing suite)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/129_sync_chunk_progress/03_sync_status_chunk_fields.md

@@ -0,0 +1,43 @@
+# Task 03 — `SyncStatus` chunk fields: `current_chunk` / `chunks_total` on the status endpoint
+
+**Phase:** `129_sync_chunk_progress` · **Source:** `TODO.md:5` — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (A6: batch-granularity chunk position)
+
+## Objective
+`GET /api/sync/status` carries the in-flight file's embed-chunk position (`current_chunk`, `chunks_total`) so the UI can render `· chunk n/m` — reset per run, cleared when the import phase ends, 0/0 idle (the phase-64/98 field conventions).
+
+## Work
+1. `app/api/sync.py` — `SyncStatus` dataclass: add
+   ```python
+   # Phase 129: the current file's EMBED chunk position — the first
+   # chunk of the in-flight token-budgeted batch and the file's total
+   # content chunks (the LLMClient.embed hook, batch granularity).
+   # 0/0 before the first batch, during the prelude/overview/summaries
+   # phases, and in terminal states.
+   current_chunk: int = 0
+   chunks_total: int = 0
+   ```
+   Update the `SyncStatus` docstring (the phase-64/98 progress-field paragraph) to name the new fields and their clearing contract.
+2. `app/api/sync.py` — `_run_sync`:
+   - run start: `_status.current_chunk = 0`, `_status.chunks_total = 0` (with the other progress-field resets);
+   - the closure (the file's `_hook` convention — closures capture the module `_status`):
+     ```python
+     def _chunk_hook(chunk: int, total: int) -> None:
+         _status.current_chunk = chunk
+         _status.chunks_total = total
+     ```
+     passed to `import_sources(..., on_chunk_progress=_chunk_hook)` (alongside the existing `progress=_hook`);
+   - CLEARING (0/0) at every point the import phase ends — the `_status.phase = "overview"` assignment, the `_status.phase = "summaries"` assignment, and BOTH terminal states (the success and except blocks where `_status.current_file = None` — the phase-64 keep-final-FILE-counts convention does NOT extend to the sub-file chunk position: the file counts survive the terminal for the result line's context, the chunk position is a sub-position of a file that's done — it clears, like `current_file`);
+   - the unchanged-walk / no-sync-idle paths never set them (defaults 0/0).
+3. `app/api/sync.py` — `sync_status` endpoint: add `"current_chunk": _status.current_chunk, "chunks_total": _status.chunks_total` to the returned dict (place them after the `files_*` fields; the dataclass defaults make idle 0/0 with no special-casing). Update the endpoint docstring's field list (the phase-98 paragraph) and the module docstring's status paragraph with the chunk-position contract.
+
+## Testing & Quality
+- Unit/integration: extend the sync unit suite (the file that fakes `import_sources` — inspect `tests/unit/test_sync_button.py` and the sync-pipeline test first):
+  - idle → `current_chunk == 0`, `chunks_total == 0` in the JSON (the dataclass defaults — the endpoint shape test);
+  - a running sync whose fake `import_sources` invokes `on_chunk_progress(1, 38)` then `(13, 38)` → the status between ticks reports the pair (assert on `_status` directly or via the endpoint through the existing app fixture);
+  - phase transition to `overview`/`summaries` → the fields are 0/0 again; terminal success/failed → 0/0 while `files_done`/`files_total` keep their final values (the convention split, pinned).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] the status endpoint JSON carries both fields; idle is 0/0; a running import reports the hook's pair
+- [ ] the fields clear at phase transitions + terminal states while the file counts keep-final (pinned test)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/129_sync_chunk_progress/04_ui_chunk_part.md

@@ -0,0 +1,25 @@
+# Task 04 — The label's chunk part: `Syncing… <file> (2/3) · chunk 14/38`
+
+**Phase:** `129_sync_chunk_progress` · **Source:** `TODO.md:5` — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (A6: batch-granularity chunk position)
+
+## Objective
+The running sync label shows the chunk position as a third pinned part — rendered ONLY while `chunks_total > 0` (the import phase, after the file's first batch), hidden in every other state — and the untruncated full label (main + count + chunk part) keeps riding the button `title` + `#sync-result` (A4).
+
+## Work
+1. `frontend/index.html` — `#sync-label` (the phase-128 two-part markup): add the third part after the count span: `<span class="sync-label-chunk" hidden></span>`.
+2. `frontend/assets/styles.css` — `.sync-label-chunk { flex: 0 0 auto; white-space: nowrap; font-family: var(--mono); }` (the same pinned-part language as `.sync-label-count` — place it right after that rule; both mono parts read as data).
+3. `frontend/assets/sources.js` —
+   - get the chunk part at `mount` scope (the phase-128 `querySelector` pattern, null-guarded);
+   - `setSyncLabel(mainText, countText = "", chunkText = "")` — the new third arg: when `chunkText`, set `.sync-label-chunk.textContent` + `hidden = false`, else `""` + `hidden = true`; the UNTRUNCATED concatenation for `title` + `#sync-result` becomes `mainText` + (count? `" " + countText`) + (chunk? `" " + chunkText`) (A4 — the announcer hears the whole `Syncing… <file> (2/3) · chunk 14/38`);
+   - the import fall-through (the `fmtSyncPhaseLabel` fall-through / the 202/409 click label site — everywhere the import label is emitted with a status): `chunkText = status.chunks_total > 0 ? `· chunk ${status.current_chunk}/${status.chunks_total}` : ""` — every OTHER state (prelude, overview, summaries, upload, idle, settle) passes no chunk text (the part hides): the summaries phase's own `(n/m)` count is its position — no chunk part there;
+   - the `title`/`#sync-result` set on EVERY running label (the house rule) automatically carries the chunk part via the concatenation.
+4. `tests/unit/test_frontend_sync_upload.py` — extend the phase-128 part pins: the import state with `chunks_total > 0` emits the chunk part (`· chunk 14/38` for the fixture values) and the untruncated `title` string is `Syncing… <file> (2/3) · chunk 14/38`; the import state with `chunks_total == 0` (before the first batch) hides the part; every other state's pins stay (the part hidden).
+
+## Testing & Quality
+- Unit: the pins above green; textContent-only (no HTML strings in the label path).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] `· chunk n/m` renders only while `chunks_total > 0`; hidden in all other states (unit-pinned)
+- [ ] the untruncated full label (with the chunk part) rides `title` + `#sync-result` (A4, unit-pinned)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed phases (phase-128 pins still pass)

.agents/phases/complete/129_sync_chunk_progress/05_e2e_chunk_progress.md

@@ -0,0 +1,24 @@
+# Task 05 — E2E: the chunk position climbs through a large file's embed batches, endpoint + label
+
+**Phase:** `129_sync_chunk_progress` · **Source:** `TODO.md:5` — "The `Syncing… name/of/file/here (2/3)` needs to show what chunk we're on out of how many" (A6: batch-granularity chunk position)
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) proving the feature at both surfaces: the endpoint's `current_chunk` climbs 1 → N with `chunks_total` = the file's true chunk count, and the rendered label shows `· chunk n/m` while the file's embed span runs (then the part clears).
+
+## Work
+1. `tests/e2e/test_sync_chunk_progress.py` (new) — house pattern from `tests/e2e/test_sync_summary_visibility.py` (module app fixtures over the shared E2E Postgres, host temp-dir `kind=local` source, autouse truncate cleanup, mock-only, the `tests/e2e/slow_llm.py` proxy).
+   Sizing (the phase-98 rationale, re-sized for batches): the fixture is ONE local source `chunkprog/` holding ONE large markdown file (`big.md`, ~60 KB, ~30+ chunks at the default target — compute the expected chunk count deterministically in the test by calling `chunk_document` with the app's settings, the same function the importer uses — and assert `chunks_total` equals it) plus ONE tiny second file (the file counter then reads `(1/2)` → `(2/2)`, proving the chunk position restarts per file). `SLOW_DELAY_S` sized so each embed batch outlives the recorder's ~100 ms cadence (the proxy delays EVERY LLM call — embeds included — so the import span is densely sampled).
+2. Test → observable mapping (Playwright Mapping Rule):
+   - `test_endpoint_reports_the_chunk_position` (the slow leg — tight-poll recorder on `GET /api/sync/status`, the phase-64 recorder pattern): while `phase == "import"`: some ticks have `chunks_total == <expected chunk count>` and `current_chunk` strictly climbing from 1 toward `chunks_total` (batch granularity — the sequence's LAST tick before the file ends is `chunks_total` or its final batch's first index; assert the climb + the total, not a contiguous run); while the second (tiny) file is in flight the position restarts (a later tick has `current_chunk == 1` with `chunks_total == 1`); the terminal state has `current_chunk == 0` and `chunks_total == 0` while `files_done == files_total == 2` (the keep-final-file-counts split, the phase-129 convention).
+   - `test_label_shows_the_chunk_part` (the slow leg — UI, the page's own 2 s poll): at the import span the rendered `#sync-label` parts: `.sync-label-main` matches `Syncing… chunkprog/big.md`, `.sync-label-count` matches `(1/2)`, and at some tick `.sync-label-chunk` is visible matching `· chunk \d+/\d+` with the total == the expected chunk count; the button `title` carries the UNTRUNCATED concatenation (A4 — assert it contains `· chunk` on the same tick); after the file's embed span the chunk part is hidden (`.sync-label-chunk.hidden` true) while the file label continues.
+3. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_sync_chunk_progress.py -v --no-cov`), the mock-only gate, the sizing rationale (why the file is ~60 KB, why the slow proxy's delay doubles as the batch sampler), the fixture layout, the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% `app/` bar is carried by tasks 01–03; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_sync_chunk_progress.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the endpoint's `chunks_total` equals the deterministic `chunk_document` count for the fixture (the total is the file's TRUE chunk count, not a batch count)
+- [ ] the chunk part renders only during the import phase and clears at the phase transition/terminal (UI-pinned)
+- [ ] no behavior change in completed phases (the phase-64/98 label contract + the keep-final-counts convention hold)

.agents/phases/complete/130_chat_answer_clusters/00_phase.md

@@ -0,0 +1,36 @@
+# Phase 130 — Chat answer clusters: chips row, images row, bottom-right actions cluster
+
+**Source:** `TODO.md` L6 — "The chat output is getting messy. I think it's because the `source-chip`, `source-image`, `tune-btn`, `retry-btn`, and `save-as-doc-btn` end up in the same div which causes them to push each other in weird ways. Those three buttons should be in a button cluster in the bottom right. We don't need to display the `source-chip` for images, just the image itself is fine. `source-chips` should show up before images in their own cluster, then images in their own cluster to keep things organized."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `frontend/assets/app.js` — `appendSources` (~L1561: builds the FIRST `.msg-meta` row, interleaving a `.source-image` figure after each chip for refs carrying `image_url`), `appendRelated` (~L1618: the "Nearby docs" row, appended LAST among meta rows), `appendSourceImageFigure` (~L1660: the compact figure; on `img` error it removes the figure and the chip remains), `appendAnswerImage` (~L1735: the `.answer-image` figure — appended by callers right BEFORE `appendSources`), `appendTuneButton` (~L484, admin-gated), `appendRetryButton` (~L598), `appendSaveAsDocButton` (~L793, admin + docs-repo gated; `margin-inline-start: auto` pushes it right), `markLastRetryable` (~L620: re-appends the Retry button on the last bubble and re-appends the save button after it — "the auto margins split the free space"), `appendStoppedNote` / `appendFailedNote` (~L520/~L560: join the first `.msg-meta` row); `frontend/assets/styles.css` — the `.msg-meta`, `.source-chip`, `.source-image`, `.tune-btn`, `.retry-btn`, `.save-as-doc-btn` rules (grep each — the auto-margin rules live here); `frontend/index.html` — no chat markup changes expected (the bubble DOM is JS-built); E2E image-KB fixture patterns in `tests/e2e/test_chat_image_questions.py` / `test_image_documents.py` (the mock's `IMAGE_DESCRIPTION_MODE` canned vision reply makes image docs retrievable).
+
+## Objective
+A completed brain bubble's metadata reads as organized clusters, top to bottom: the answer text → the answer figure (phase 124, unchanged) → the **source chips row** (text documents only — an image document gets NO chip, just its figure) → the **source images row** (all retrieved image figures) → the "Nearby docs" row (unchanged) → the **actions row** (a right-aligned cluster holding Tune / Retry / Save-as-doc and the Stopped/Failed notes) — never one soup div where buttons push chips around.
+
+## Dependencies
+- `129_sync_chunk_progress` (todo) — pipeline order only; code dependencies are the completed chat-render contract (phases 26/49/59/113/120/122/124).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Row structure per brain bubble (top → bottom):** (1) answer text; (2) `.answer-image` figure — the phase-124 position is UNCHANGED (below the text, before the source rows — A3); (3) `.msg-meta` chips row (`role=list`, `aria-label="Sources"`) — one `.source-chip` per NON-image ref; refs with `image_url` contribute NO chip (ASSUMPTION A3 — the figure is the citation for image docs); (4) `.msg-meta.msg-images` images row (`role=list`, `aria-label="Source images"`) — one `.source-image` figure per image ref, in ref order; the row is absent when there are no image refs; (5) `.msg-meta.related-docs` — the phase-113 row, UNCHANGED in content, placed after the images row (ASSUMPTION A4); (6) `.msg-meta.msg-actions` actions row (`role=list`, `aria-label="Answer actions"`) — the ONLY row the action buttons + the stopped/failed notes join (ASSUMPTION A7).
+- **Call order at every render site** (the `done` branch, the empty-answer fallback, the stop finalize, the phase-14 restore path): answer image → `appendSources` (now builds the chips row AND the images row) → `appendRelated` → the action buttons/notes. The current "buttons claim the FIRST `.msg-meta` row" behavior is REPLACED — the buttons get-or-create `.msg-actions` instead.
+- **Image-load failure (ASSUMPTION A3):** `appendSourceImageFigure`'s `img` error handler replaces the figure IN PLACE with a plain `.source-chip` anchor for that document (same `documentUrl` href, same modal click behavior, the label as text) — the citation survives a lost byte copy; no broken-image icon.
+- **Actions row:** one get-or-create `.msg-actions` per bubble (the house pattern). DOM order = Tune, Retry, Save-as-doc (each present per its gate — non-admins see only Retry; a stopped bubble sees the note + Retry). The note (`appendStoppedNote` / `appendFailedNote`) joins this row. `markLastRetryable`'s re-append logic moves the Retry button into `.msg-actions` and DROPS the save-button re-append hack (row-level alignment replaces the per-button `margin-inline-start: auto` — CSS task). ARIA: `role=list` + `role=listitem` on every child (the existing convention).
+- **CSS:** `.msg-actions { justify-content: flex-end; }` (the right-aligned cluster — "bottom right" = the bubble's last row, right edge); remove the per-button auto margins (`.save-as-doc-btn`'s `margin-inline-start: auto` + the tune/retry auto margins the `markLastRetryable` comment names); the chips row keeps its wrap; `.msg-images` wraps with the `.msg-meta` gap; the row ORDER is DOM order (no positioning tricks); mobile: rows stack naturally, the actions row stays right-aligned.
+
+## Tasks
+1. `01_sources_clusters.md` — `appendSources`/figure split: chips-only row + images-only row, no chip for image docs, the in-place chip fallback.
+2. `02_actions_cluster.md` — the `.msg-actions` row: the three buttons + the notes, `markLastRetryable` rework, ARIA kept.
+3. `03_css_clusters.md` — the cluster CSS (actions right-aligned, auto margins removed, images row).
+4. `04_e2e_clusters.md` — dedicated Playwright E2E, run in isolation.
+
+## Testing & Quality
+- Unit: the frontend unit suite — the pinned behaviors that move (the button-row target, the no-chip-for-images rule, the fallback) — inspect `tests/unit/test_frontend_*.py` for the chat-render pins and update them.
+- E2E: one dedicated Playwright file, run in isolation, image-KB fixture (text doc + image doc both cited).
+- Coverage: **>90%** on new/modified code (frontend: unit pins + E2E; `app/` untouched this phase).
+
+## Completion Criteria
+- [ ] a bubble citing a text doc + an image doc renders: chips row (text chip only, NO chip for the image) → images row (the figure) → actions row (bottom right) — asserted in the DOM, not the pixels
+- [ ] Tune/Retry/Save-as-doc sit in ONE `.msg-actions` row, right-aligned; non-admin sees only Retry; the restore path renders the identical structure
+- [ ] an image whose bytes 404 renders as its plain chip (the citation survives)
+- [ ] `uv run pytest tests/e2e/test_chat_answer_clusters.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (chips still open the modal, the related row, the answer figure's position, the ARIA names)

.agents/phases/complete/130_chat_answer_clusters/01_sources_clusters.md

@@ -0,0 +1,26 @@
+# Task 01 — Sources split: chips-only row, then images-only row; no chip for image docs
+
+**Phase:** `130_chat_answer_clusters` · **Source:** `TODO.md:6` — "...We don't need to display the `source-chip` for images, just the image itself is fine. `source-chips` should show up before images in their own cluster, then images in their own cluster to keep things organized."
+
+## Objective
+`appendSources` stops interleaving figures after chips. It builds the chips row from the NON-image refs only, then (when any image ref exists) a separate images row holding all the figures — chips cluster first, images cluster second, image documents cited by their figure alone.
+
+## Work
+1. `frontend/assets/app.js` — `appendSources(wrap, sources)`:
+   - Partition the refs: `imageRefs = sources.filter(s => s.image_url)`, `textRefs = sources.filter(s => !s.image_url)` (the `image_url` presence is the existing image-doc signal — phase 122).
+   - CHIPS ROW: build it (the existing `.msg-meta` + `role=list` + `aria-label="Sources"` + per-chip `documentUrl`/modal click/`title`/clipped `aria-label` code) from `textRefs` ONLY. Skip the row entirely when `textRefs` is empty (an image-only citation still gets its images row + the actions row).
+   - IMAGES ROW: when `imageRefs.length > 0`, build a SECOND `.msg-meta` row — add the `msg-images` class, `role=list`, `aria-label="Source images"` — and append one `appendSourceImageFigure` per image ref (in ref order). No chips in this row.
+   - Preserve the existing post-build clipped-chip `aria-label` pass (the `scrollWidth > clientWidth` check) over the chips row only.
+   - The row ORDER in `.msg-body` is: answer figure (appended by the caller before `appendSources`, phase 124 — unchanged) → chips row → images row. `appendRelated` (the next caller) lands after both (task 02's call-order change guarantees the actions row is last).
+2. `frontend/assets/app.js` — `appendSourceImageFigure(meta, s)`: the `img` error handler currently does `fig.remove()` (the chip remains — but there is no chip for image docs anymore). Change it to the IN-PLACE CHIP FALLBACK: build a plain `.source-chip` anchor for `s` (the same `documentUrl` href + `title` + left-click → modal handler the chips row uses; `textContent`/`aria-label` = the `source/path` label) and `replaceWith` the figure (the citation survives a lost byte copy — ASSUMPTION A3). The figure's fetch-summary swap is untouched.
+3. `frontend/assets/app.js` — `appendRelated`: the related tier's refs ALSO carry `image_url` for image docs (phase 122 — `appendSourceImageFigure(row, s)` is called there today). Keep the related row's own behavior (its chips + figures) — the related row is a separate tier and is NOT reorganized by this phase (ASSUMPTION A4: it stays where it is, below the citation clusters). Do not change `appendRelated`'s chip/figure logic.
+
+## Testing & Quality
+- Unit: the frontend unit suite — inspect `tests/unit/test_frontend_*.py` for any `appendSources`/figure pins and update: no chip emitted for an `image_url` ref; the images row is built only when image refs exist; the in-place fallback replaces the figure with a chip (the figure's `img` error path).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a mixed citation (1 text + 2 image refs) renders a 1-chip row then a 2-figure row — no chip for either image
+- [ ] an image-only citation renders NO chips row and a figures-only images row
+- [ ] a figure whose bytes 404 becomes its plain chip in place (the citation survives)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/130_chat_answer_clusters/02_actions_cluster.md

@@ -0,0 +1,23 @@
+# Task 02 — The actions row: Tune / Retry / Save-as-doc + the notes in one bottom-right cluster
+
+**Phase:** `130_chat_answer_clusters` · **Source:** `TODO.md:6` — "...Those three buttons should be in a button cluster in the bottom right."
+
+## Objective
+The three action buttons (and the Stopped/Failed notes) stop joining whatever the first `.msg-meta` row happens to be. They get-or-create a dedicated `.msg-actions` row — the bubble's LAST row, right-aligned by CSS (task 03) — so chips and images can never push the buttons around.
+
+## Work
+1. `frontend/assets/app.js` — a shared helper next to the button appenders: `getActionsRow(wrap)` — find or create the bubble's `.msg-meta.msg-actions` row inside `.msg-body` (`role=list`, `aria-label="Answer actions"`), the house get-or-create pattern (the same shape as the current "reuse the `.msg-meta` row when it exists" code, but scoped to the `msg-actions` class so it NEVER grabs the chips row).
+2. `frontend/assets/app.js` — `appendTuneButton` (~L484), `appendRetryButton` (~L598), `appendSaveAsDocButton` (~L793): replace their "reuse the first `.msg-meta` row" logic with `getActionsRow(wrap)`; keep everything else (the gates, the one-button-per-bubble guards, the icons, the `role=listitem` when the row is `role=list`).
+3. `frontend/assets/app.js` — `appendStoppedNote` (~L520) + `appendFailedNote` (~L560): join the actions row via `getActionsRow(wrap)` instead of the first `.msg-meta` row (ASSUMPTION A7 — the notes are answer-status markers; the actions row is their home). Keep the `failed-detail` textContent contract (no HTML from error strings).
+4. `frontend/assets/app.js` — `markLastRetryable` (~L620): the retry button is removed from EVERY bubble and re-appended — but now into `getActionsRow(lastBrainWrap)`. DELETE the save-button re-append hack (the `saveDocBtn.parentElement.appendChild(saveDocBtn)` block) — the row's `justify-content: flex-end` (task 03) right-aligns the whole cluster; DOM order inside the row is the insertion order (Tune, Retry, Save-as-doc per their gates). Update the function's comment (the "auto margins split the free space" rationale is gone).
+5. Call-order audit: at every site that renders a COMPLETED brain bubble (the `done` branch, the empty-answer fallback, the stop finalize, the phase-14 restore), confirm the order is answer figure → `appendSources` → `appendRelated` → action buttons/notes, so `.msg-actions` is the LAST row (the "bottom right" = the bubble's bottom, right edge). If a site appends actions before `appendRelated`, reorder the calls (the DOM order decides the visual order — no CSS tricks).
+
+## Testing & Quality
+- Unit: the frontend unit suite — update the pins that target the button row: the buttons/notes land in `.msg-actions` (not the chips row); `markLastRetryable` moves the Retry button into the actions row and no longer re-appends the save button.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a bubble with sources + all three buttons renders the actions row LAST, containing exactly the gated buttons (the notes when present)
+- [ ] a non-admin bubble's actions row holds only Retry (the gate unchanged)
+- [ ] the restore path renders the identical row (a saved chat re-opens with the buttons in `.msg-actions`)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/130_chat_answer_clusters/03_css_clusters.md

@@ -0,0 +1,33 @@
+# Task 03 — CSS: the cluster rows (actions right-aligned, auto margins removed, images row)
+
+**Phase:** `130_chat_answer_clusters` · **Source:** `TODO.md:6` — "...Those three buttons should be in a button cluster in the bottom right. ... `source-chips` should show up before images in their own cluster, then images in their own cluster to keep things organized."
+
+## Objective
+The cluster layout is CSS: the actions row right-aligns its buttons as a cluster (no per-button auto margins), the images row wraps its figures like the chips row wraps chips, and the rows stack in DOM order with the existing `.msg-meta` rhythm.
+
+## Work
+1. `frontend/assets/styles.css` — grep the current button-row rules (`.tune-btn`, `.retry-btn`, `.save-as-doc-btn`, and any `margin-inline-start: auto` on them — the `markLastRetryable`/phase-59 comments name the auto-margin mechanism; `.save-as-doc-btn`'s is explicit in the app.js comment at ~L653). Remove the per-button auto margins (the buttons become plain flex items of the actions row).
+2. `frontend/assets/styles.css` — add the cluster rules (place them with the other `.msg-meta` / chip / figure rules — the house grouping):
+   ```css
+   /* Phase 130: the actions cluster — the bubble's LAST row, right-aligned.
+      The row's justify does the "bottom right" (no per-button auto margins). */
+   .msg-meta.msg-actions {
+     justify-content: flex-end;
+   }
+   /* Phase 130: the source-IMAGES cluster — wraps like the chips row. */
+   .msg-meta.msg-images {
+     flex-wrap: wrap;
+     gap: 0.4rem; /* match the .msg-meta chip gap (read the existing value) */
+   }
+   ```
+   (Match the EXISTING `.msg-meta` gap/align values — read the rule first; do not invent new spacing values that diverge from the chips row.)
+3. Audit: confirm the chips row (`.msg-meta` with `role=list`) and the related row (`.msg-meta.related-docs`) rules are untouched; the `.source-image` figure styles are untouched (they were already sized for a row context); mobile: the rows stack naturally (the `.msg-body` flex gap handles it) — verify in the mobile media query block that no rule pins the actions row left; the actions row stays right-aligned at every width.
+
+## Testing & Quality
+- Visual gate: the E2E (task 04) — bounding-box assertions (the actions row's buttons' right edge ≈ the row's right edge; the row is the last `.msg-meta` in the bubble).
+- Coverage: **>90%** on new/modified code (CSS has no direct coverage — the E2E + unit pins carry it).
+
+## Completion Criteria
+- [ ] the actions cluster is right-aligned by `.msg-actions` alone (the per-button auto margins are gone — grep confirms)
+- [ ] the images row wraps its figures with the chips row's gap
+- [ ] `uv run pytest` green; no behavior change in completed phases

.agents/phases/complete/130_chat_answer_clusters/04_e2e_clusters.md

@@ -0,0 +1,26 @@
+# Task 04 — E2E: the answer renders as organized clusters (DOM-asserted), live + restored
+
+**Phase:** `130_chat_answer_clusters` · **Source:** `TODO.md:6` — "The chat output is getting messy. ... Those three buttons should be in a button cluster in the bottom right. We don't need to display the `source-chip` for images ... `source-chips` should show up before images in their own cluster, then images in their own cluster to keep things organized."
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) proving the owner-visible fix in the real DOM: a grounded answer citing a text doc AND an image doc renders the chips row (text chip only, NO chip for the image) before the images row (the figure), and the buttons sit in one right-aligned `.msg-actions` row that is the bubble's last row — on the live turn and after a page reload (the phase-14 restore path).
+
+## Work
+1. `tests/e2e/test_chat_answer_clusters.py` (new) — house pattern (module app fixture over the shared E2E Postgres, autouse cleanup, mock-only). KB fixture: follow `tests/e2e/test_chat_image_questions.py` / `test_image_documents.py`'s image-KB pattern — a local source with ONE text doc (the mock's grounded-answer trigger, e.g. the existing "use your tools" / read flow that cites a doc) and ONE image doc (the mock's `IMAGE_DESCRIPTION_MODE` canned description makes it retrievable; the done frame's `sources` must carry both refs — the image ref with `image_url`). Inspect those suites first and reuse their fixture builders — do not invent a new mock flow unless the existing done-frame shape cannot cite both docs in one answer (if a new mock trigger is needed, add it to `tests/e2e/mock_llm.py` in the house style: a user-message marker, a deterministic reply, a module-header docstring entry).
+   Run as ADMIN (the whoami gate — the Tune + Save-as-doc buttons exist; the Retry button exists for everyone) with a configured docs repo (the `docsRepoConfigured` gate for Save-as-doc — follow the existing admin chat E2E setup).
+2. Test → observable mapping (Playwright Mapping Rule):
+   - `test_answer_clusters_render_in_order` — send the question; on `done`: the LAST brain bubble's `.msg-body` direct children include, in order: the `.answer-image` (if the mock offers one — else skip) → a `.msg-meta` chips row containing EXACTLY the text doc's `.source-chip` and NO `.source-chip` for the image doc (assert by the chip's `source/path` label) → a `.msg-meta.msg-images` row containing the image's `.source-image` figure (the `img` loaded, the caption = the canned description/summary) → (the related row, if present) → a `.msg-meta.msg-actions` row that is the bubble's LAST `.msg-meta`, containing the `.tune-btn`, `.retry-btn`, `.save-as-doc-btn` (all three — admin); the actions row's buttons are right-aligned (the rightmost button's bounding-box right edge ≈ the row's right edge, slack for the row padding) and the row's bounding box is BELOW the images row's (the "bottom right" geometry).
+   - `test_image_without_chip_keeps_its_citation_via_figure` — in the same bubble: the image doc is cited (the figure's `href` = its `documentUrl`, left-click opens the same-page modal — the phase-26 affordance) and there is NO `.source-chip` whose label is the image's `source/path` (the owner's exact ask).
+   - `test_restore_renders_the_same_clusters` — the turn auto-saves (phase-66); reload the page; the restored last brain bubble has the IDENTICAL structure (chips row text-only, images row, `.msg-actions` last with the gated buttons — the restore path renders through the same appenders).
+   - `test_non_admin_sees_retry_only_actions` — a second, non-admin browser context on a FRESH chat (no admin cookie): send the same question; the `.msg-actions` row holds ONLY the `.retry-btn` (Tune/Save gated out — the phase-16/59 gates unchanged).
+3. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_chat_answer_clusters.py -v --no-cov`), the mock-only gate, the fixture + mock-trigger notes, the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% bar is carried by tasks 01–02's updated frontend unit pins; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_chat_answer_clusters.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the DOM order assertion (chips → images → actions-last) is pinned for BOTH the live and the restored bubble
+- [ ] the suite fails against the pre-phase markup (buttons inside the chips row) — i.e. it actually pins the fix
+- [ ] no behavior change in completed phases (modal navigation, the related tier, the ARIA names)

.agents/phases/complete/131_read_line_ranges/00_phase.md

@@ -0,0 +1,51 @@
+# Phase 131 — `read` gains line ranges: grep finds the line, read(offset, limit) reads it
+
+**Source:** `TODO.md` L7 — "The agent is struggling with huge documents. It can search for the text it wants and it finds the text, including line number, but then it gets stuck saying 'However, read takes a path, not a line number.' and can't figure out how to read that part of the document. Does the read tool support that? If not, it should. If it does, improve the description so the agent doesn't get stuck. I have a huge test pdf (the DND player's handbook) in test_sources called 'pdf_tests.tar' that you can use for testing. It's a massive pdf. The question the agent got stuck on was 'What are the components of the find traps spell?' which is toward the end of the players handbook so it will need to search and read specific lines. I've been setting BOR_READ_MAX_CHARS to 24000 to keep things relatively quick so the agent realizes quickly its answer isn't in the first few pages."
+(LOCKED A2, owner-confirmed 2026-09-27: the parameter names are `offset`/`limit` — 1-based line number + line count — mirroring the pi-harness `read` tool the model was trained on, the phase-70 "harness-aligned surface" anchor.)
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/rag/agent.py` — `AGENT_TOOLS` (L258+: the `ls`/`read`/`grep` pi.dev-shaped schemas; the `read` schema at ~L304 takes ONLY `path`; the `grep` description promises `source/path:line: text` locators), `_execute_tool` (L1266+, the `read` branch at ~L1348: `arg` resolution, the `ALREADY_IN_CONTEXT` dedupe on `holder.read_docs`, the `BOR_READ_MAX_CHARS` truncation with `TRUNCATION_MARKER` + `READ_TRUNCATION_NOTICE` (~L506 — today it points at `grep` and then dead-ends), the `holder.read_truncations` tuples), `AgentHolder` (the `read_docs` / `read_truncations` bookkeeping); `app/rag/llm.py` — `ToolCallPiece` (the `arguments` dict the model sends); `tests/e2e/mock_llm.py` — the scripted tool-call flows (the "use your tools" / multi-read / grep patterns — the module header documents each trigger); `tests/unit/test_agent.py` — the read-branch unit suite (the `ALREADY_IN_CONTEXT` pins, the truncation pins); `test_sources/players_handbook.pdf` (the DND player's handbook from `pdf_tests.tar` — on disk, untracked); `settings.read_max_chars` (`BOR_READ_MAX_CHARS`).
+
+## Objective
+The agent stops dead-ending on huge documents: `read` accepts an optional 1-based line `offset` + line-count `limit`, the truncation notice and tool descriptions teach the grep → read(offset/limit) workflow, and the dedupe rules allow the ONE case that matters — re-reading a range of a document whose first read was truncated — while still refusing pointless re-reads of text already in context. The owner's repro (the handbook, "find traps", `BOR_READ_MAX_CHARS=24000`) passes as an integration test.
+
+## Dependencies
+- `130_chat_answer_clusters` (todo) — pipeline order only; code dependencies are the completed agent surface (phases 70/72/95/118).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Schema + teaching (task 01):** `read` gains two OPTIONAL integer params — `offset` ("The first line to read, 1-based. Omit it to read from the beginning of the document.") and `limit` ("The maximum number of lines to read. Omit it to read as many lines as fit under the character cap."). `required` stays `["path"]`. The `read` description keeps its existing teaching and GAINS the workflow: for a very large document, use `grep` to find where your text is (it reports line numbers), then `read` that part with `offset` + `limit`; re-reading a document already read in full adds nothing. `READ_TRUNCATION_NOTICE` (L506) is REWRITTEN to end the dead-end: "…The rest is NOT shown. Use grep (pattern) to find what you need — it reports line numbers — then read that part with `offset` (1-based first line) and `limit` (number of lines)." The `grep` description gets the light touch: "read the winner with `read` — for a large document, use the reported line number as `offset`."
+- **Execution (task 02):** in `_execute_tool`'s read branch:
+  - Validation: `offset`/`limit`, when present, must be ints ≥ 1 (NOT bools — the house `isinstance(x, int) and not isinstance(x, bool)` guard); a bad value → a teaching refusal echoing the bad value ("`offset` and `limit` are whole line numbers ≥ 1 — you passed `…`") — counts in nothing, consumes a round (the phase-72 refusal style).
+  - The dedupe matrix (`known` = the `read_docs` (source, path) set; `truncated` = the set of (source, path) from `holder.read_truncations`):
+    | call | doc in `known` | previously truncated | result |
+    |---|---|---|---|
+    | plain `read(path)` | no | — | full read (truncate at the cap as today) |
+    | plain `read(path)` | yes | yes | NEW teaching line (no re-emit, no count): "You already have the first {shown} characters of {source}/{path} in your context. To read the rest, find where your text is with grep (it reports line numbers), then call read with `offset` (1-based first line) and `limit` (lines)." — `{shown}` from the matching `read_truncations` tuple |
+    | plain `read(path)` | yes | no | `ALREADY_IN_CONTEXT` (byte-identical to today) |
+    | `read(path, offset, limit)` | yes | yes | ALLOWED (the stuck-scenario fix — the range the model names is exactly the part it does NOT have) |
+    | `read(path, offset, limit)` | yes | no | `ALREADY_IN_CONTEXT` (the full text is already in context — the range is a subset) |
+    | `read(path, offset, limit)` | no | — | ALLOWED (a range read of an unread doc) |
+  - `offset > total_lines` (the doc's `len(content.splitlines())`) → teaching refusal: "{source}/{path} is {total_lines} lines long — `offset` {offset} is past the end. Use a smaller offset (grep reports the exact line numbers)." Counts in nothing.
+  - Result shape: line 1 `Document {source}/{path}:` + line 2 `date: YYYY-MM-DD` stay BYTE-IDENTICAL for plain reads (the E2E mock's `_READ_RESULT_PREFIX` contract); a RANGE read inserts a third line `lines: {offset}-{end} of {total_lines}` (the actual end = min(offset + limit − 1, total_lines); the model sees the true extent), then the image-doc marker (as today), then the slice (`"\n".join(lines[offset-1 : offset-1+limit])`).
+  - The cap still applies to the SLICE: `len(slice) > settings.read_max_chars` → cut + `TRUNCATION_MARKER` + the (rewritten) notice; the `read_truncations` tuple for a range read is `(arg, cap, len(slice))` — the slice's requested size (documented: for range reads the tuple's `chars_total` is the slice length, not the document's).
+  - A range read appends the doc to `read_docs` ONCE (the `known` set prevents a re-append) — so a later plain read of a range-read doc is `ALREADY_IN_CONTEXT` (the model has committed to this doc; the range result's `lines:` line told it what it holds).
+- **Handbook repro (task 03):** an integration test that imports `test_sources/players_handbook.pdf` as a local source (the mock LLM's deterministic embed/summary fakes — the in-process `tests/fakes.py` pattern; the handbook is ~1.5 MB of text ≈ 1200 chunks — in-process embedding is fast, keep the test under ~60 s) and drives the agent turn "What are the components of the find traps spell?" with `BOR_READ_MAX_CHARS=24000`: a scripted fake (the `test_agent.py` pattern) — round 1 → a `grep` tool call (pattern "find traps"), round 2 (the grep result carries the real line number) → a `read(path, offset=<that line>, limit=40)` call, round 3 → the answer echoing the read result's content (the phase-94 "read document reached the context" echo convention). Assert the echo contains the handbook's actual find-traps text (grep it from the extracted PDF text in the test — do not hardcode the handbook wording).
+- **Mock flow + E2E (task 04):** `tests/e2e/mock_llm.py` gains ONE scripted flow (house style — a user-message marker, deterministic reply, module-header docstring entry): the marker `read the lines` → request 1: a `grep` tool call (a canned pattern); request 2 (a `tool`-role grep result with a `source/path:line:` line present): a `read` tool call with `offset` = the parsed line number and `limit` = 30; request 3 (the read result present): the answer "Found it at line N." + the first 80 chars of the read result (the existing read-echo shape). `tests/e2e/test_read_line_ranges.py` (dedicated, in isolation, mock-only): a KB fixture with ONE large doc (> 24000 chars, the marker line `TRAP_COMPONENTS_LINE` near line ~1500), `BOR_READ_MAX_CHARS=24000`; ask a question containing the marker → assert the SSE `tool` frames (grep, then read with `offset`/`limit` args) and the final answer echoing the marker line; a second test: a plain read of the large doc truncates with the REWRITTEN notice (the notice names `offset`/`limit` — assert the `tool_result`/result surface carries it).
+
+## Tasks
+1. `01_tool_surface.md` — the schema, the descriptions, the rewritten truncation notice.
+2. `02_range_read_execution.md` — the read branch: validation, the dedupe matrix, the slicing, the result shape.
+3. `03_handbook_repro.md` — the integration repro (the handbook + the owner's exact question) + the unit matrix.
+4. `04_mock_flow_e2e.md` — the mock-LLM `read the lines` flow + the dedicated E2E.
+
+## Testing & Quality
+- Unit: the full dedupe matrix (6 rows), the validation refusals, the slice math (boundaries, offset past EOF, 1-line docs), the result shapes (plain reads byte-identical — the existing pins must pass unchanged), the cap on slices.
+- Integration: the handbook repro (the owner's scenario, the owner's `BOR_READ_MAX_CHARS=24000`).
+- E2E: one dedicated Playwright file, run in isolation, mock-only.
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] `read(path, offset, limit)` returns exactly the named lines with the `lines: a-b of N` header; plain reads are byte-identical to pre-phase
+- [ ] a truncated first read followed by a range read SUCCEEDS (the stuck scenario is gone); every other re-read is refused with the teaching
+- [ ] the handbook integration test answers the find-traps question from the real PDF text (no hardcoded wording)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_read_line_ranges.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (the grep/ls surfaces, the plain-read contract, the `ALREADY_IN_CONTEXT` full-read refusal)

.agents/phases/complete/131_read_line_ranges/01_tool_surface.md

@@ -0,0 +1,43 @@
+# Task 01 — The tool surface: `offset`/`limit` on `read`, the descriptions, the rewritten notice
+
+**Phase:** `131_read_line_ranges` · **Source:** `TODO.md:7` — "The agent is struggling with huge documents. It can search for the text it wants and it finds the text, including line number, but then it gets stuck saying 'However, read takes a path, not a line number.' ... Does the read tool support that? If not, it should. If it does, improve the description so the agent doesn't get stuck."
+
+## Objective
+The model's contract for `read` names the line-range capability (LOCKED A2: `offset`/`limit`, 1-based, pi-harness shape) and the truncation dead-end is rewritten into the working workflow: grep for the line numbers, then read that range.
+
+## Work
+1. `app/rag/agent.py` — `AGENT_TOOLS`, the `read` entry (~L304): add to `properties`:
+   ```python
+   "offset": {
+       "type": "integer",
+       "description": (
+           "The first line to read, 1-based. Omit it to read from the "
+           "beginning of the document. Use it to read a specific part "
+           "of a large document — grep reports the line numbers of "
+           "what you found."
+       ),
+   },
+   "limit": {
+       "type": "integer",
+       "description": (
+           "The maximum number of lines to read, starting at offset. "
+           "Omit it to read as many lines as fit under the character "
+           "cap. Keep it small — you are reading a part, not the "
+           "document."
+       ),
+   },
+   ```
+   `required` stays `["path"]`.
+2. `app/rag/agent.py` — the `read` `description`: keep the existing sentences (the `<documents>`-summaries teaching, the no-re-read rule, the truncation/`grep` paragraph — but REPLACE the truncation paragraph with the workflow): "Very large documents are truncated: you receive the first part plus a TRUNCATED notice naming how many more characters exist. To read the rest: use `grep` (pattern) to find where your text is — it reports line numbers — then call `read` again on the same document with `offset` (1-based first line) and `limit` (number of lines) to read exactly that part. Do not re-read a document you have already read in full — its full text is already in your prompt."
+3. `app/rag/agent.py` — `READ_TRUNCATION_NOTICE` (~L506): rewrite the tail (keep the `TRUNCATED — this document is {total} characters; only the first {shown} are in your context. The rest is NOT shown.` opening): "Use grep (pattern) to find what you need — it reports line numbers — then read that part with `offset` (1-based first line) and `limit` (number of lines)."
+4. `app/rag/agent.py` — the `grep` `description`: the "read the winner with `read`" sentence becomes "read the winner with `read` — for a large document, use the reported line number as `offset`".
+5. `tests/unit/test_agent.py` — update/extend the `AGENT_TOOLS` schema pins: the `read` schema has `offset`/`limit` (integer, optional — `required` is still `["path"]`), the descriptions contain the `offset`/`limit` teaching (the pinned substrings), and `READ_TRUNCATION_NOTICE` names both parameters.
+
+## Testing & Quality
+- Unit: the schema/notice pins above green; the `ls`/`grep` schemas' OTHER pins unchanged (byte-identical where not rewritten).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a model reading `AGENT_TOOLS` knows: grep → line number → `read(offset, limit)` (schema + descriptions + notice all agree)
+- [ ] the old dead-end sentence ("use grep to locate the rest" with no way to act on the line number) is gone from the notice
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/131_read_line_ranges/02_range_read_execution.md

@@ -0,0 +1,49 @@
+# Task 02 — Range-read execution: validation, the dedupe matrix, the slice, the result shape
+
+**Phase:** `131_read_line_ranges` · **Source:** `TODO.md:7` — "The agent is struggling with huge documents. ... then it gets stuck saying 'However, read takes a path, not a line number.' and can't figure out how to read that part of the document."
+
+## Objective
+`_execute_tool`'s read branch executes `offset`/`limit`: it validates the arguments with teaching refusals, applies the six-row dedupe matrix (the truncated-then-range case is the one that must succeed), slices the document's lines, and shapes the result so plain reads stay byte-identical while range reads carry their `lines: a-b of N` extent.
+
+## Work
+1. `app/rag/agent.py` — `_execute_tool`, the `read` branch (~L1348): after `arg` is resolved and before the dedupe check, parse the range args:
+   ```python
+   offset = call.arguments.get("offset")
+   limit = call.arguments.get("limit")
+   ```
+   with a helper `_read_range_args(offset, limit)` returning `(ok, error_line, offset, limit)`:
+   - absent/None → ok, `(1, None)` semantics = plain read (no range);
+   - present but not `isinstance(x, int) and not isinstance(x, bool)`, or `< 1` → the teaching refusal: "`offset` and `limit` are whole line numbers — pass integers ≥ 1 (you passed offset={offset!r}, limit={limit!r})." (echo the bad values; counts in nothing, consumes a round — the phase-72 refusal style, a new pinned constant `BAD_RANGE_ARGS`);
+   - ok → the (offset, limit) pair (either may be None — `offset` without `limit` reads to the end, `limit` without `offset` is treated as `offset=1` — document both in the constant's docstring).
+2. `app/rag/agent.py` — the dedupe matrix (the phase-131 design table; `truncated_pairs = {(source, path) of holder.read_truncations}` — build it from the holder's tuples, matching on the RESOLVED pair, not the raw arg string):
+   - plain read + in `known` + truncated → the new pinned teaching line `REREAD_TRUNCATED` ("You already have the first {shown} characters of {source}/{path} in your context. To read the rest, find where your text is with grep (it reports line numbers), then call read with `offset` (1-based first line) and `limit` (lines).") — `{shown}` from the matching tuple; no re-emit, `tool_calls` NOT incremented (a refusal);
+   - plain read + in `known` + not truncated → `ALREADY_IN_CONTEXT` (the existing byte-identical path — do not touch that constant);
+   - range read + in `known` + truncated → PROCEED (the fix);
+   - range read + in `known` + not truncated → `ALREADY_IN_CONTEXT`;
+   - range read + not in `known` → PROCEED.
+   (The current code's dedupe check runs on the RAW arg before resolution for speed — keep that fast path for the plain-read `ALREADY_IN_CONTEXT` case; the truncated-set check needs the resolved pair, so it runs after `_resolve_path`, exactly where the `doc` is known. Restructure minimally: the raw-arg fast path handles "plain read + known"; everything else resolves first, then consults the matrix.)
+3. `app/rag/agent.py` — the slice + result (after `doc` is resolved and the matrix passed):
+   - `lines = doc.content.splitlines()`; `total_lines = len(lines)`;
+   - `offset > total_lines` → the teaching refusal `OFFSET_PAST_END` ("{source}/{path} is {total_lines} lines long — `offset` {offset} is past the end. Use a smaller offset (grep reports the exact line numbers).") — no count;
+   - `end = min(offset + (limit or 1) - 1, total_lines)`; `slice_lines = lines[offset - 1 : end]`; `slice_text = "\n".join(slice_lines)`;
+   - `holder.read_docs.append(doc)` (the `known` check already guarantees no duplicate); `holder.tool_calls += 1` (a range read is a successful call — the plain-read convention);
+   - result: plain read → EXACTLY today's bytes (header, date, marker, content/truncated-content — the existing code path untouched); range read →
+     ```
+     Document {source}/{path}:
+     date: YYYY-MM-DD
+     lines: {offset}-{end} of {total_lines}
+     {marker}{slice_text}
+     ```
+     (the `lines:` line replaces the position the marker/`TRUNCATION_MARKER` occupy in the plain read — for a range read the marker line comes after `lines:` exactly as after the date line in the plain read);
+   - the cap on the slice: `len(slice_text) > settings.read_max_chars` → `slice_text[:cap]` + `\n{TRUNCATION_MARKER}\n{READ_TRUNCATION_NOTICE.format(shown=cap, total=len(slice_text))}` and `holder.read_truncations.append((arg, cap, len(slice_text)))` — for range reads the tuple's `chars_total` is the SLICE's requested size (document in the `AgentHolder.read_truncations` field comment: "for range reads the slice length, not the document's").
+4. `tests/unit/test_agent.py` — the full matrix (six rows, each pinned): the six dedupe outcomes; `BAD_RANGE_ARGS` (a float, a string, a bool, a 0, a negative); `OFFSET_PAST_END` (offset = total+1 on a 10-line doc); the slice math (offset=1/limit=None → the whole doc; offset=total → the last line; limit overshoot → `end` clamps to `total_lines`; a 1-line doc; offset past EOF); the result shapes (the plain-read pins pass UNCHANGED — byte-identical; a range read's `lines: a-b of N` line + slice; the cap on a huge slice + the tuple's slice-length `chars_total`).
+
+## Testing & Quality
+- Unit: the matrix + the pins above — this task's suite.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] the six-row matrix is pinned one test per row (the truncated-then-range row PASSES — the stuck scenario's unit proof)
+- [ ] plain reads are byte-identical to pre-phase (the existing pins green, unmodified)
+- [ ] a range read's result names its true extent (`lines: a-b of N`) and respects the cap
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/131_read_line_ranges/03_handbook_repro.md

@@ -0,0 +1,30 @@
+# Task 03 — The handbook repro: "find traps" on the real D&D player's handbook
+
+**Phase:** `131_read_line_ranges` · **Source:** `TODO.md:7` — "I have a huge test pdf (the DND player's handbook) in test_sources called 'pdf_tests.tar' that you can use for testing. It's a massive pdf. The question the agent got stuck on was 'What are the components of the find traps spell?' which is toward the end of the players handbook so it will need to search and read specific lines. I've been setting BOR_READ_MAX_CHARS to 24000 to keep things relatively quick so the agent realizes quickly its answer isn't in the first few pages."
+
+## Objective
+The owner's exact incident is an integration test: the real `players_handbook.pdf` is indexed, the agent is asked the find-traps question with the owner's `BOR_READ_MAX_CHARS=24000`, and the scripted agent loop performs the grep → read(offset/limit) dance against the REAL document and lands an answer grounded in the handbook's actual find-traps text.
+
+## Work
+1. `tests/integration/test_read_line_ranges_handbook.py` (new) — the house integration pattern (inspect `tests/integration/` for the agent-loop test that runs a scripted fake LLM against a real-ish pipeline — `tests/unit/test_agent.py`'s fake-LLM/scripted-rounds pattern is the model; lift it into an integration test that ALSO runs the real PDF extraction + real chunking/embedding fakes from `tests/fakes.py`):
+   - Fixture: a temp source dir containing `test_sources/players_handbook.pdf` (copy — never mutate the untracked fixture), registered/imported with the REAL importer (`import_sources`, the mock embed/summary fakes — the in-process fakes make the ~1200-chunk embed fast; keep the whole test under ~60 s; if the import is slower, the test may pre-import once at module scope and share it across its tests).
+   - The scripted fake (deterministic, the `test_agent.py` round pattern):
+     - round 1 (no tool results yet) → a `grep` tool call, `pattern="find traps"` (lowercase — grep is case-insensitive);
+     - round 2 (the grep result carries `…:LINE: …find traps…` — parse the REAL line number from the grep result the loop produced, do not hardcode it) → a `read` tool call: `path` = the handbook's `source/path`, `offset` = the parsed line, `limit` = 40;
+     - round 3 (the read result present) → the answer: the read result's content, verbatim (the phase-94 "the read document reached the context" echo convention — the loop's reply IS the slice).
+   - Settings: `BOR_READ_MAX_CHARS=24000` (the owner's env — the handbook is far longer, so round 1's plain-read alternative would truncate; the script goes straight to grep, but the setting must be in force for the notice/teaching path to be realistic).
+2. Assertions (the observable contract):
+   - the final answer contains the handbook's REAL find-traps text — derive the expected substring at test time: extract the PDF's text (the phase-126 `extract_pdf_text`), grep it for the find-traps passage in the test itself (the same way the model does), and assert the ANSWER contains that passage's first 60 chars (NO hardcoded handbook wording — the test stays true if the fixture is re-extracted);
+   - the agent's `read` call carried `offset`/`limit` (assert on the fake's captured round-2 tool call: `offset == the grep-reported line`, `limit == 40`);
+   - the loop made exactly 3 rounds (grep → range read → answer) with `tool_calls == 2` (the owner's stuck loop made 2 and dead-ended — the fixed loop closes in 3).
+3. `tests/integration/test_read_line_ranges_handbook.py` — a SECOND test, the plain-read-first variant: the fake round 1 does a PLAIN `read(path)` (the handbook truncates at 24000 with the rewritten notice), round 2 does `read(path, offset=<grep line>, limit=40)` AFTER a grep — asserting the truncated-then-range matrix row works on the REAL document (the `REREAD_TRUNCATED` teaching is never needed because the model went straight to the range — the matrix row itself is unit-pinned in task 02; here the end-to-end path is the point).
+
+## Testing & Quality
+- Integration: this file IS the task's suite (plus task 02's unit matrix).
+- Coverage: **>90%** on new/modified code (the test file is covered by the suite run; `app/` changes are task 02's).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/integration/test_read_line_ranges_handbook.py -v` green in ~60 s (the owner's scenario passes on the real PDF)
+- [ ] the expected text is derived from the fixture at test time (grep the extracted text — no hardcoded handbook wording)
+- [ ] the read call's `offset` is the grep-reported line (parsed, not literal)
+- [ ] no behavior change in completed phases

.agents/phases/complete/131_read_line_ranges/04_mock_flow_e2e.md

@@ -0,0 +1,31 @@
+# Task 04 — The mock flow `read the lines` + the dedicated E2E
+
+**Phase:** `131_read_line_ranges` · **Source:** `TODO.md:7` — "The agent is struggling with huge documents. ... Does the read tool support that? If not, it should. If it does, improve the description so the agent doesn't get stuck."
+
+## Objective
+The E2E mock deterministically performs the grep → read(offset/limit) dance, and a dedicated, in-isolation Playwright suite pins the full SSE surface: the `tool` frames carry the range args, the answer is grounded in the large doc's tail, and the truncation notice now teaches the workflow instead of dead-ending.
+
+## Work
+1. `tests/e2e/mock_llm.py` — one new scripted flow in the house style (a user-message marker + a module-header docstring entry, exactly like the existing "use your tools" / multi-read / grep flows — read the module header first and match its format):
+   - Marker: the user message containing `read the lines` (a dedicated trigger — no overlap with the existing grep-flow trigger; if the existing grep flow's trigger could also match, make the new marker more specific, e.g. `read the lines of` — the header documents the exact string).
+   - Flow (classified by the count of `tool`-role results in the messages, the house pattern):
+     - 0 results → a `grep` tool call, `pattern="LINE_MARKER"` (a canned constant the fixture doc contains);
+     - a `tool`-role grep result present (a line matching `^[\w/]+:(\d+):` — parse the FIRST match's line number) → a `read` tool call: `path` = the grep result's `source/path`, `offset` = the parsed line number, `limit` = 30 (structured `tool_calls`, no reasoning — the terminal-shape convention);
+     - the read result present (a `tool`-role result whose content starts with `Document `) → the forced answer, byte-stable: `Found it at line N.` (N = the offset the model passed — parse it from the `read` call's arguments in the messages) + the first 80 chars of the read result's content (the phase-94 read-echo convention — proves the RANGE reached the model's context).
+2. `tests/e2e/test_read_line_ranges.py` (new) — dedicated, in isolation, mock-only, house pattern (module app fixture, temp local source, autouse cleanup):
+   - KB fixture: ONE large markdown doc `linedoc/big.md` — ~100 KB, generated deterministically in the test (numbered filler lines `Line <i>: …`, so line numbers are exact), with the marker line `LINE_MARKER the trap components are documented here` at a known line ~1500 (far beyond the 24000-char cap — the doc's first 24000 chars hold NO marker);
+   - app env: `BOR_READ_MAX_CHARS=24000` (the owner's setting — the plain read MUST truncate).
+   - Test → observable mapping (Playwright Mapping Rule):
+     - `test_range_read_flow_over_sse` — send a question containing `read the lines` → the SSE `tool` frames, in order: the `grep` call (args `pattern="LINE_MARKER"`), then the `read` call (args: `path` = the doc's `source/path`, `offset` an int == the marker's true line, `limit` == 30 — assert on the frame's args, not a substring); the `done` frame's answer contains `Found it at line <N>` (N == the marker's line) and the marker text's first 80 chars (the read-echo — the range reached the context); NO truncation-notice dead-end (the answer is the grounded echo, not a "I can't read that part" shape — assert the marker text is present).
+     - `test_plain_read_truncation_notice_teaches_the_workflow` — a SECOND trigger (reuse the mock's existing plain-read flow on this large doc — the `read` of `linedoc/big.md` truncates at 24000): the surfaced truncation (the `tool_result` frame / the result the model sees — assert on the SSE `tool_result` surface per A15) contains the REWRITTEN notice text naming `offset` and `limit` (the pinned substrings `"offset"` + `"limit"` in the notice — the old dead-end wording is gone).
+3. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_read_line_ranges.py -v --no-cov`), the mock-only gate, the fixture's determinism (the generated line numbers), the `BOR_READ_MAX_CHARS=24000` rationale (the owner's env), the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% `app/` bar is carried by tasks 01–02; the handbook integration repro by task 03; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_read_line_ranges.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the `read` tool frame carries REAL `offset`/`limit` ints (parsed from the grep result — the mock does the owner's exact dance)
+- [ ] the truncation notice surfaces the workflow teaching (the dead-end is gone)
+- [ ] no behavior change in completed phases (the existing mock flows' triggers still fire unchanged)

.agents/phases/complete/132_image_upload_feedback/00_phase.md

@@ -0,0 +1,35 @@
+# Phase 132 — Chat image upload: visible "uploading" feedback
+
+**Source:** `TODO.md` L8 — "Uploading an image in the chat provides no feedback to the user. The user clicks the paperclick, selects and image, presses 'send' and then nothing happens. No loading bar, no 'uploading image', no indication. This results in the user spamming 'send' over and over because they think it's frozen. We need to visually show the user's image is uploading."
+(A5, owner-confirmed 2026-09-27: the affordance = a spinner + "Uploading image…" in the preview strip AND the Send button disabled with the label "Uploading…" — the double-spam is blocked visually, not just by the internal guard.)
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `frontend/assets/app.js` — `handleSend` (~L2700: the `attachedImage` branch — the `attachUpload` double-fire guard, `await uploadAttachedImage(attachedImage.file)` with NO visual state between the await's start and its resolution, then `image = { path, src, alt }` + `runTurn`), `uploadAttachedImage` (~L2641: the `POST /api/chat-images` multipart — every failure path is an out-of-turn banner + null), `showAttachPreview` / `clearAttachedImage` (~L2680: the strip's reveal/clear — static markup, only `textContent`/`src` move), `setUiState` (the turn-state owner — NOT used for the upload: the upload is a PRE-turn operation, `uiState` stays `idle`, the turn loader must not spin during the upload); `frontend/index.html` L280–322 — the static attach markup (`#attach-preview` with `img` + `.attach-preview-name` + `#attach-remove`; `#send-btn` with `#send-label`); `frontend/assets/styles.css` — the `.attach-preview*` / `.send-btn` rules (the existing `:disabled` styles); `tests/unit/test_frontend_sync_upload.py` or a sibling — the pinned frontend JS unit pattern.
+
+## Objective
+Between the user pressing Send and the upload resolving, the UI proves the image is moving: the preview strip shows a spinner + "Uploading image…" (the remove button disabled), and the Send button is disabled with the label "Uploading…". When the upload resolves — success proceeds to the turn exactly as today; failure clears the state and keeps the existing banner + the typed text + the attachment for the retry. No frozen-looking gap, no visible double-send.
+
+## Dependencies
+- `131_read_line_ranges` (todo) — pipeline order only; code dependencies are the completed phase-123 attach/upload contract.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **State scope (task 01):** the uploading state is the `attachedImage` branch of `handleSend` — from just after the `attachUpload = true` guard until the `attachUpload = false` line (success AND failure paths — the helper never throws). `setUiState` is NOT touched (the upload is pre-turn; `uiState` stays `idle`; the turn's own thinking/streaming feedback starts only when `runTurn` does). The `attachUpload` guard stays exactly as is (the visual state reinforces it — the disabled Send is the user-facing half).
+- **Preview strip (task 01):** the static markup gains ONE status element inside `#attach-preview`: `<span class="attach-preview-status" hidden><svg spinner…></svg><span class="attach-preview-status-text">Uploading image…</span></span>`. The JS sets `attachPreview.classList.add("is-uploading")` + un-hides the status + `attachRemove.disabled = true` on entry; on exit it removes the class + hides the status + `attachRemove.disabled = false`. The thumbnail + filename stay visible (the user watches THEIR image uploading).
+- **Send button (task 01):** `sendBtn.disabled = true` + `sendLabel.textContent = "Uploading…"` on entry; on exit (both paths) `sendBtn.disabled = false` + `sendLabel.textContent = "Send"` — restored BEFORE the success path calls `runTurn` (the turn's `setUiState("thinking")` then takes over the button as usual) and BEFORE the failure path returns (the banner + editable input + the still-attached image).
+- **Reduced motion (task 02):** the spinner animation is still under `prefers-reduced-motion` (the house `@media (prefers-reduced-motion: reduce)` block pattern).
+
+## Tasks
+1. `01_upload_state.md` — the static markup + the uploading state in `handleSend` (enter/exit on both paths).
+2. `02_css_upload_state.md` — the strip's uploading styles + the disabled Send + reduced motion.
+3. `03_e2e_upload_feedback.md` — dedicated Playwright E2E, run in isolation.
+
+## Testing & Quality
+- Unit: the pinned frontend JS suite — the state transitions (the strip's class/status/remove-disabled, the Send's disabled/label) on entry, on success exit, on failure exit (the banner path).
+- E2E: one dedicated Playwright file, run in isolation, with a route-delayed upload (Playwright `page.route` delaying `POST /api/chat-images`) so the in-flight window is observable.
+- Coverage: **>90%** on new/modified code (frontend: unit pins + E2E; `app/` untouched this phase).
+
+## Completion Criteria
+- [ ] while the upload is in flight: the strip shows the spinner + "Uploading image…", the remove button is disabled, the Send button is disabled with "Uploading…" (E2E-asserted mid-flight)
+- [ ] a second Send press during the flight does nothing (no second upload request — E2E request count)
+- [ ] success: the indicator clears and the turn proceeds exactly as pre-phase (the user bubble carries the image); failure: the indicator clears, the banner shows, the text + attachment remain
+- [ ] `uv run pytest tests/e2e/test_image_upload_feedback.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (the phase-123 upload contract, the A5 path-never-bytes rule, the out-of-turn banner)

.agents/phases/complete/132_image_upload_feedback/01_upload_state.md

@@ -0,0 +1,49 @@
+# Task 01 — The uploading state: markup + `handleSend` enter/exit on both paths
+
+**Phase:** `132_image_upload_feedback` · **Source:** `TODO.md:8` — "Uploading an image in the chat provides no feedback to the user. ... We need to visually show the user's image is uploading."
+
+## Objective
+The `attachedImage` branch of `handleSend` enters a visible uploading state the moment the upload starts and clears it the moment the upload resolves — success or failure — so the user always sees whether the app is moving.
+
+## Work
+1. `frontend/index.html` (L280–284, the `#attach-preview` block) — add the status element INSIDE the strip (after the name span, before the remove button), static + hidden by default (the house "ships hidden" rule):
+   ```html
+   <span class="attach-preview-status" hidden>
+     <svg class="attach-preview-status-icon" aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M21 12a9 9 0 1 1-6.2-8.56"/></svg>
+     <span class="attach-preview-status-text">Uploading image…</span>
+   </span>
+   ```
+   (The spinner arc is the house loading glyph — check `#turn-loader`'s icon for the exact shape and reuse it; the spinner's spin animation is the CSS task. `aria-hidden` on the svg — the text carries the meaning; the strip's `role`/label are untouched.)
+2. `frontend/assets/app.js` — get the new elements at module scope with the existing attach-family consts (L313–316, the null-guard pattern): `attachStatus = document.querySelector(".attach-preview-status")`, `attachStatusText` (not needed — the text is static), alongside `attachPreview`/`attachRemove`.
+3. `frontend/assets/app.js` — two tiny helpers next to `showAttachPreview`/`clearAttachedImage`:
+   ```js
+   function enterUploadState() {
+     if (attachPreview) attachPreview.classList.add("is-uploading");
+     if (attachStatus) attachStatus.hidden = false;
+     if (attachRemove) attachRemove.disabled = true;
+     sendBtn.disabled = true;
+     sendLabel.textContent = "Uploading…";
+   }
+   function exitUploadState() {
+     if (attachPreview) attachPreview.classList.remove("is-uploading");
+     if (attachStatus) attachStatus.hidden = true;
+     if (attachRemove) attachRemove.disabled = false;
+     sendBtn.disabled = false;
+     sendLabel.textContent = "Send";
+   }
+   ```
+   (The label literals "Send"/"Uploading…" — check the idle label's exact current text in the markup/`setUiState` and match it byte-for-byte; if `setUiState` owns the idle label restore, use its restore helper instead of a literal — inspect first.)
+4. `frontend/assets/app.js` — `handleSend`, the `attachedImage` branch (~L2700):
+   - after the `attachUpload = true;` line, BEFORE `await uploadAttachedImage(...)`: `enterUploadState();`
+   - on the `attachUpload = false;` line (the helper never throws — this is reached on BOTH success and failure): `exitUploadState();` — the success path then continues to `image = { path, src, alt }` + the rest of the send (the turn's `setUiState` takes the button over); the failure path (`path === null`) returns with the banner shown, the input text intact, and the attachment still attached (the strip is back in its normal preview state — the user can retry or remove).
+   - Do NOT touch the `attachUpload` guard, the `uploadAttachedImage` helper, or `clearAttachedImage` (the New-chat reset already hides the strip — the uploading class is transient and never persists: if a New chat happened mid-upload, the strip is hidden; the class on a hidden element is harmless, and `exitUploadState` still clears it when the upload resolves).
+
+## Testing & Quality
+- Unit: the pinned frontend JS suite (extend `tests/unit/test_frontend_sync_upload.py` or the chat-frontend pin file — inspect what exists): the state transitions — entry sets the class/status/unhides/disables remove/disables Send with "Uploading…"; exit (success) clears everything and restores "Send"; exit (failure) clears everything the same way (the banner is the failure's signal, not the strip's); a second `handleSend` during the flight is a no-op (the existing `attachUpload` guard pin).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] the uploading state is entered exactly once per upload (after the guard, before the await) and exited on BOTH resolution paths
+- [ ] `uiState`/`setUiState`/the turn loader are untouched (the upload is pre-turn — the loader spins only when the turn starts)
+- [ ] the idle label after exit matches the pre-phase idle label byte-for-byte
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/132_image_upload_feedback/02_css_upload_state.md

@@ -0,0 +1,54 @@
+# Task 02 — CSS: the strip's uploading look, the disabled Send, reduced motion
+
+**Phase:** `132_image_upload_feedback` · **Source:** `TODO.md:8` — "Uploading an image in the chat provides no feedback to the user. ... We need to visually show the user's image is uploading."
+
+## Objective
+The uploading state reads as "in motion": the strip's thumbnail dims with a spinning arc + the "Uploading image…" text beside it, and the Send button shows the disabled affordance the app already has for a disabled Send — no new color, no new weight, the existing `--ink-soft`/opacity language.
+
+## Work
+1. `frontend/assets/styles.css` — with the other `.attach-preview*` rules (grep the existing block first — read the strip's current layout: the thumbnail, the name, the remove button):
+   ```css
+   /* Phase 132: the uploading state — the strip proves the image is
+      moving (the TODO: no feedback → the user spams Send). The
+      thumbnail dims, the spinner arc spins, the status text stands in
+      the name's place. */
+   .attach-preview.is-uploading .attach-preview-img {
+     opacity: 0.5;
+   }
+   .attach-preview.is-uploading .attach-preview-name {
+     visibility: hidden; /* keep the layout; the status takes its spot */
+   }
+   .attach-preview-status {
+     display: inline-flex;
+     align-items: center;
+     gap: 0.35rem;
+     color: var(--ink-soft);
+     font-size: 0.85rem; /* the strip's small text (match the name's size) */
+     min-width: 0;
+   }
+   .attach-preview-status-icon {
+     width: 14px;
+     height: 14px;
+     flex: 0 0 auto;
+     animation: spin 1s linear infinite; /* the .sync-icon spinner (the house spin keyframes) */
+   }
+   @media (prefers-reduced-motion: reduce) {
+     .attach-preview-status-icon { animation: none; }
+   }
+   .attach-preview.is-uploading .attach-preview-remove {
+     opacity: 0.5; /* the disabled attribute's visual half (the house :disabled language) */
+   }
+   ```
+   (Match the EXISTING values — the strip's font sizes, the `spin` keyframes' name (verify they exist — the `.sync-icon.is-spinning` rule uses `spin`), the disabled-button opacity. If the strip's name span has `overflow: hidden; text-overflow: ellipsis` (a long filename), the status span inherits the row's clamp — verify the "Uploading image…" text never clips at 320 px; if it does, let the status text wrap or ellipsize per the strip's existing pattern.)
+2. `frontend/assets/styles.css` — verify the `#send-btn:disabled` rule exists and reads as disabled (the Send is disabled via the `disabled` attribute — the existing rule applies; if the disabled Send currently looks identical to the enabled one, add the house `opacity`/`cursor: wait` there — inspect the current rule first, do not invent a new visual).
+3. Theme audit: every value used is a theme variable or a neutral (no raw hex/rgb — the B4 byte-identical built-in theme contract; the status text's `--ink-soft` on the strip's background meets 4.5:1 — the strip's bg is `--bg-soft` or similar, verify the pair's contrast the way the theme phases did).
+
+## Testing & Quality
+- Visual gate: the E2E (task 03) — the status is visible mid-flight, the thumbnail is dimmed (an `opacity` computed-style assertion is optional — the visibility of the status text is the pin).
+- Coverage: **>90%** on new/modified code (CSS has no direct coverage — the E2E + unit pins carry it).
+
+## Completion Criteria
+- [ ] the uploading strip shows the spinning arc + "Uploading image…" with the dimmed thumbnail (E2E-asserted mid-flight)
+- [ ] `prefers-reduced-motion` stills the arc (the house block)
+- [ ] the disabled Send reads as disabled (the existing rule, verified)
+- [ ] `uv run pytest` green; no behavior change in completed phases

.agents/phases/complete/132_image_upload_feedback/03_e2e_upload_feedback.md

@@ -0,0 +1,25 @@
+# Task 03 — E2E: the upload window shows "uploading", blocks the double-send, then the turn proceeds
+
+**Phase:** `132_image_upload_feedback` · **Source:** `TODO.md:8` — "Uploading an image in the chat provides no feedback to the user. The user clicks the paperclick, selects and image, presses 'send' and then nothing happens. ... This results in the user spamming 'send' over and over because they think it's frozen. We need to visually show the user's image is uploading."
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) proving the owner-visible fix: while `POST /api/chat-images` is in flight (route-delayed so the window is observable), the strip shows the uploading state, the Send button is disabled with "Uploading…", a second press produces NO second upload request — and once the upload resolves, the state clears and the turn proceeds exactly as pre-phase.
+
+## Work
+1. `tests/e2e/test_image_upload_feedback.py` (new) — house pattern (module app fixture over the shared E2E Postgres, autouse cleanup, mock-only). The app boots with `BOR_IMAGES=1` (the `/api/config` `images: true` gate reveals `#attach-btn` — follow `tests/e2e/test_chat_image_questions.py`'s app env). KB fixture: a minimal local source with ONE text doc (the mock's grounded answer for a plain question — the turn after the upload needs to complete normally).
+2. The upload window (Playwright's `page.route`): intercept `POST /api/chat-images` — `route.waitForRequest`-style: the handler DELAYS (e.g. `await asyncio.sleep(2.0)` in the route handler, or `page.route` + a fixture that holds the response) then `route.continue_()` — the server's real handler runs, the response is just late. Count the intercepted upload requests (a module counter) for the double-send assertion. A small PNG fixture (the house test image — reuse the existing one the image E2E suites use; do not commit a new binary if one exists).
+3. Test → observable mapping (Playwright Mapping Rule):
+   - `test_upload_window_shows_uploading_and_blocks_resend` — admin or anonymous (chat is public — anonymous is the simpler context) page on the chat view; click `#attach-btn` → `#attach-file` set_input_files (the small PNG); the strip is revealed (the phase-123 preview — `#attach-preview` not hidden, the thumbnail's `src` set); type a question; click Send. MID-FLIGHT (poll for the state within the delayed window): `#attach-preview` has the `is-uploading` class; `.attach-preview-status` is visible (not hidden) with the text "Uploading image…"; `#attach-remove` is disabled; `#send-btn` is disabled with `#send-label` text "Uploading…". THEN press `#send-btn` twice more (the user's exact spam — the button is disabled so the presses are no-ops; also try an Enter-to-submit while disabled — the form submit's `sendBtn.disabled` guard) → after the window, the upload-request counter is EXACTLY 1 (no double upload, no second turn).
+   - `test_upload_success_clears_and_turn_proceeds` — the SAME flow, past the window: the `is-uploading` class is gone, `.attach-preview-status` hidden, `#attach-remove` enabled, `#send-label` back to the idle "Send"; the strip HIDEs with the send (the phase-123 contract — the preview clears when the question goes out); the user bubble renders with the attached image (the phase-123 `attachBubbleImage` — the data-URL `img`), and the turn completes (the mock's grounded answer streams to `done` — the brain bubble is non-empty).
+   - `test_upload_failure_clears_state_and_keeps_the_draft` — a SECOND app/route that FAILS the upload (the route aborts or the handler is pointed at a 413 shape — the simplest: `route.abort("failed")` → `uploadAttachedImage`'s network-drop banner path): mid-flight the uploading state is visible (same assertions); after resolution: the state is CLEARED (no `is-uploading`, Send re-enabled with "Send"), the out-of-turn banner is shown ("Couldn't attach the image — try again." — the network-drop copy), the input text is INTACT, and the strip is back in its normal preview (the attachment remains for the retry — `#attach-preview` not hidden, no `is-uploading`).
+4. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_image_upload_feedback.py -v --no-cov`), the mock-only gate, the route-delay rationale (the in-flight window is otherwise ~50 ms — unsamplable), the fixture notes, the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% bar is carried by task 01's unit pins; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_image_upload_feedback.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the mid-flight assertions are deterministic (the route delay makes the window ≥ 2 s — the UI's no-poll direct state, asserted by waiting for the class, not a race)
+- [ ] exactly ONE upload request per Send-press sequence (the spam is visibly AND functionally dead)
+- [ ] no behavior change in completed phases (the phase-123 upload contract, the A5 path-never-bytes rule, the out-of-turn banner)

.agents/phases/complete/133_pdf_screenshot_fallback/00_phase.md

@@ -0,0 +1,43 @@
+# Phase 133 — Garbage PDF text is detected; the page-screenshot vision fallback extracts it
+
+**Source:** `TODO.md` L9 — "test_sources/hnb_2026_guide.tar.gz contains a pdf that is being read as binary. Figure out why. It contains images, tables, and text but none of that is being extracted correctly. Instead, the raw xml is being embedded and the preview shows the entire document as lines like `<illustrator:StartupProfile>Web</illustrator:StartupProfile>`. This project should support this kind of PDF and should be able to extract it correctly, even if that means screenshotting the pages and reading each one as an image to preserve formatting when text/image/table extraction isn't working."
+
+**FINDING (diagnosed 2026-09-27, before phase authoring — the evidence, verified against the real fixture):**
+1. The archive holds ONE file: `HBI-2026-Guide-Year-Round_260704_131221.pdf` (6.2 MB, 48 pages, PDFium-produced, **Adobe Illustrator export** — the raw bytes carry 222 × `illustrator:StartupProfile` + 138 × `<x:xmpmeta` uncompressed XMP blocks).
+2. The CURRENT code (phase 126 onward) extracts it CORRECTLY: `extract_pdf_text` returns 2,585 lines, **0 XML-ish**; a full real-importer run stores clean content (`---PAGE-N---` blocks, "2026 U.S. Benefits Guide" first page), the title, and vision-described embedded images.
+3. The garbage the owner saw is the **pre-126 import**: `pdf` was already in `BOR_IMPORT_EXTENSIONS` in the local `.env` (untracked — predates the parser) BEFORE `126_pdf_support` shipped (commit `e0f11e7`, 2026-09-27 09:36). The generic text path (`importer.py` L689: `read_text(encoding="utf-8", errors="replace").replace("\x00", "")`) read the raw PDF bytes — the uncompressed XMP/structure blocks survive as literal text (reproduced: 138,170 non-empty lines, **46% XML-ish** — `<</Pages 2 0 R /Type/Catalog>>`, `<illustrator:StartupProfile>Web</…>`, exactly the owner's preview) — and that garbage was chunked + embedded.
+4. **Production fix is a re-sync**: the importer's content-hash delta sees the old garbage row's digest ≠ the newly extracted text's digest → the next sync re-indexes the file as `updated` with clean content (deploy phase 126 first — it is already on `main`). No migration needed. This is documented here, not a code task.
+
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/rag/pdf.py` (phase 126 — `extract_pdf_text` (L109, `page.get_text("text")` per page, `PAGE_SEPARATOR` blocks, fail-soft `""`), `extract_pdf_images` (L145), the fitz import); `app/rag/importer.py` — `_index_pdf_file` (the phase-126 PDF branch: extract → doc row → digest over extracted text → chunk + embed → lite summary → embedded images via `_describe_or_skip` (L1779)); `app/rag/summarizer.py` — `describe_image` (L208: ONE chat-model call, multimodal user message, `data: bytes` + `mime`, returns `str | None`, no app-level retry); `ImportSummary` (L212, the stats counters + `log()` line); `tests/e2e/mock_llm.py` — the `IMAGE_DESCRIPTION_MODE` canned vision reply (deterministic for the E2E); `test_sources/hnb_2026_guide.tar.gz` (the untracked fixture, 2.6 MB compressed).
+
+## Objective
+Two guarantees, one for today and one for the class of problem: (a) the owner's guide is pinned as a regression — it imports through the real pipeline with CLEAN content (the root cause is documented above: a pre-126 binary-text import, self-healed by a re-sync); (b) any future PDF whose extracted text is GARBAGE (XML/binary soup, empty text layer) is DETECTED by a deterministic gate and falls back to the owner's specified path — every page rendered to a screenshot and read by the vision model, preserving what the text layer couldn't.
+
+## Dependencies
+- `132_image_upload_feedback` (todo) — pipeline order only; code dependencies are the completed phase-126 PDF pipeline + the phase-122 vision path.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The gate (task 02):** `app/rag/pdf.py` gains `is_usable_pdf_text(text: str) -> bool` — pure, deterministic, unit-testable. Unusable when ANY of: `text.strip() == ""` (the empty text layer — the fallback's other target); the fraction of non-empty lines that look like XML is ≥ 0.30 (a line is XML-ish: `re.search(r"</?[A-Za-z_][\w:.-]*[\s/>=]", line)` — covers `<tag>`, `</tag>`, `<tag attr=`, and the PDF-structure `<</Key…` noise); the non-printable fraction (U+FFFD replacement chars + C0 control chars, over the whole text) is ≥ 0.05 (the binary-soup signal — the pre-126 read is 46% XML-ish AND heavy on U+FFFD; a real document about XML with ≥ 30% tag-like lines is a documented false-positive cost — ASSUMPTION A8). Applied in `_index_pdf_file` AFTER `extract_pdf_text` (the extractor stays pure).
+- **The fallback (task 03):** when the gate fails, `_index_pdf_file` takes the owner's specified path — "screenshotting the pages and reading each one as an image": `app/rag/pdf.py` gains `render_pdf_pages(pdf_path: Path, dpi: int = 150) -> list[bytes]` (one PNG per page, PyMuPDF `page.get_pixmap(dpi=dpi).tobytes("png")`, in page order; an unreadable page → a zero-byte entry the caller replaces with the placeholder — no page index may shift); for each page, `describe_image(llm, data=png, mime="image/png")` — the phase-122 vision call, fail-soft per page (`None` → the placeholder line). The stored `content` = `PAGE_SEPARATOR` blocks of the page descriptions (`---PAGE-N---\n<description or "page N — description unavailable">`) — the SAME separator convention as the text path, so the chunker's page-boundary handling works unchanged. `is_image` stays `False` (it is a PDF document whose content happens to be vision text). The digest is over the constructed content (the phase-126 convention — the fallback output is stable for a stable file, so re-syncs don't re-burn vision: a cached row re-imports as unchanged). ONE loud log line (PLAN §9): `pdf: text layer unusable for <source>/<path> (xml_frac=… nonprint=…) — falling back to N page screenshots`. `ImportSummary` gains `pdfs_screenshotted: int = 0` (the counter + the `log()` field; the sync `detail` shape stays untouched — the stats log-only convention).
+- **The regression pin (task 01):** the real guide, imported through the REAL importer (the fake LLM with a multimodal `chat` override for the embedded images), must land clean content — 0/low XML-ish fraction + the real first-page text present. The fixture stays the tar.gz (the test extracts it into `tmp_path` — never the repo, `test_sources/` is untracked).
+
+## Tasks
+1. `01_diagnosis_regression_test.md` — the FINDING is documented in this overview; the task pins the real guide's clean import as a regression integration test.
+2. `02_pdf_text_gate.md` — `is_usable_pdf_text` (the heuristic) + the pre-126-garbage reproduction fixture.
+3. `03_page_screenshot_fallback.md` — `render_pdf_pages` + `_index_pdf_file`'s fallback branch + the stats counter.
+4. `04_e2e_garbage_pdf.md` — dedicated Playwright E2E, run in isolation (the real guide's happy path + a synthetic garbage PDF's fallback path).
+
+## Testing & Quality
+- Unit: the gate (clean text, the REAL pre-126 garbage string — reproduced by reading the fixture with the old `errors="replace"` recipe, XML-heavy text, empty text, a borderline document about XML); `render_pdf_pages` (page count, PNG magic bytes, the zero-byte unreadable-page placeholder); the fallback content assembly (separators, placeholders, the digest stability).
+- Integration: the real-guide regression (task 01).
+- E2E: one dedicated Playwright file, run in isolation, mock-only (the `IMAGE_DESCRIPTION_MODE` canned reply is the fallback's vision surface).
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] the real guide imports with clean content through the real pipeline (the regression test green — the owner's exact file)
+- [ ] a PDF whose text layer is XML/binary garbage (synthetic) lands with the vision-described page content — the owner's specified fallback fires end to end
+- [ ] a clean PDF NEVER burns a single vision call for the fallback (the gate is the only gate — the happy path is byte-identical to phase 126)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_garbage_pdf.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (the phase-126 clean-PDF path, the image pipeline, the sync)
+- [ ] the production stale row is fixed by a re-sync (documented above — verify post-deploy: the guide's content no longer shows XML lines)

.agents/phases/complete/133_pdf_screenshot_fallback/01_diagnosis_regression_test.md

@@ -0,0 +1,30 @@
+# Task 01 — The regression pin: the real guide imports CLEAN through the real pipeline
+
+**Phase:** `133_pdf_screenshot_fallback` · **Source:** `TODO.md:9` — "test_sources/hnb_2026_guide.tar.gz contains a pdf that is being read as binary. Figure out why. ... This project should support this kind of PDF and should be able to extract it correctly"
+
+## Objective
+The owner's exact file is a permanent regression: importing `test_sources/hnb_2026_guide.tar.gz`'s PDF through the REAL importer (extraction, digest, chunking, summary, embedded images) lands CLEAN content — the pre-126 XML-garbage import can never come back, and the phase-126 happy path on this 48-page Illustrator PDF is pinned.
+
+## Work
+1. `tests/integration/test_pdf_hnb_guide_regression.py` (new) — the house integration pattern (the local compose Postgres, the `tmp_path` fixture, the `tests/fakes.py` `FakeEmbedder`):
+   - Fixture: extract `test_sources/hnb_2026_guide.tar.gz` into `tmp_path` (the test's local source dir — `test_sources/` is untracked, the tar.gz is the stable reference; the extraction is ~6 MB, seconds). The inner file keeps its name (`HBI-2026-Guide-Year-Round_260704_131221.pdf`).
+   - The fake LLM: `FakeEmbedder` with (a) `settings = Settings(_env_file=".env")` (the real extension set — `pdf` is in the owner's live config; a `_env_file=None` fake would silently skip the PDF — the exact trap that hid this class before) and (b) a `chat` override that returns a deterministic string for MULTIMODAL user content (the `list`-of-parts shape `describe_image` sends — the fake's string-only `chat` crashes on it; the override: `"A rendered page of the guide (test vision description)."` — the docstring names it as the task-03-style vision mock the `fakes.py` comment anticipates).
+   - Import with `import_sources([dir], llm)` (the real walk + the real PDF branch).
+2. Assertions (the observable contract):
+   - `summary.added == 1` (the guide PDF) — the file is ADMITTED by the walk and indexed through the PDF branch (not the text branch: if the text branch ever ran on it again, the content assertions below fail);
+   - the stored `content` is CLEAN: the XML-ish line fraction (< the task-02 gate's 0.30 threshold — assert < 0.05 to be strict: the real extraction is 0/2,585) AND the non-printable fraction < 0.01;
+   - the real first-page text is present: `"2026 U.S. Benefits Guide"` in `content` (pinned fixture text — the file is a stable untracked fixture; if the owner ever re-cuts it, the test failure names the regression, which is the point);
+   - `is_image is False`, `title == "HBI-2026-Guide-Year-Round_260704_131221"` (the stem fallback — the PDF's metadata carries no title, only PDFium creator/producer), the content starts with `---PAGE-1---`;
+   - the embedded-image docs (the phase-126 `#page=…#img=…` rows) got the FAKE vision description (the multimodal `chat` was called — assert `llm.chat_calls` contains ≥ 1 multimodal message) or are absent when the fake "fails" (not this test's scope — the fail-soft is the phase-126 contract).
+   - Wall-time guard: the test completes in < 120 s (48 pages × in-process fakes; if it drifts, the test is too heavy — the suite must stay fast).
+3. Header docstring: the FINDING summary (the pre-126 root cause in two lines — see the phase overview's FINDING block), the run command (`uv run pytest tests/integration/test_pdf_hnb_guide_regression.py -v`), the fixture provenance.
+
+## Testing & Quality
+- Integration: this file IS the task's suite.
+- Coverage: **>90%** on new/modified code (test-only task — the bar is carried by the suite run).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/integration/test_pdf_hnb_guide_regression.py -v` green (DB up: `podman compose up -d db`)
+- [ ] the test fails if the PDF is ever routed through the text branch again (a temporary experiment moving the branch order must break it — the pin has teeth)
+- [ ] the test does not commit the extracted PDF (it lives in `tmp_path`; `git status` stays clean of binaries)
+- [ ] no behavior change in completed phases

.agents/phases/complete/133_pdf_screenshot_fallback/02_pdf_text_gate.md

@@ -0,0 +1,54 @@
+# Task 02 — `is_usable_pdf_text`: the deterministic garbage gate
+
+**Phase:** `133_pdf_screenshot_fallback` · **Source:** `TODO.md:9` — "...even if that means screenshotting the pages and reading each one as an image to preserve formatting when text/image/table extraction isn't working."
+
+## Objective
+A pure, deterministic predicate decides whether an extracted PDF text layer is real content or garbage (the pre-126 XML/binary soup class, the empty text layer class) — so the screenshot fallback has exactly one trigger, unit-testable without any PDF.
+
+## Work
+1. `app/rag/pdf.py` — new module-level predicate (place it after `extract_pdf_text`, with a docstring citing the FINDING — the pre-126 `read_text(errors="replace")` soup, the 46%-XML-ish reproduction, the owner's `<illustrator:StartupProfile>` preview):
+   ```python
+   #: A line "looks like XML" when it carries a tag-shaped token — the
+   #: pre-126 garbage's signature (raw XMP blocks, PDF-structure noise).
+   _XMLISH_LINE_RE = re.compile(r"</?[A-Za-z_][\w:.-]*[\s/>=]")
+
+   def is_usable_pdf_text(text: str) -> bool:
+       """Whether an extracted PDF text layer is REAL content (not garbage).
+
+       Unusable (→ the page-screenshot fallback) when ANY of:
+       * ``text.strip() == ""`` — the empty text layer (a scanned/image-
+         only PDF has nothing to read);
+       * ≥ :data:`XMLISH_LINE_FRACTION` (0.30) of the non-empty lines
+         match :data:`_XMLISH_LINE_RE` — the raw-XMP / binary-soup
+         signature (the FINDING's reproduced pre-126 read is 46%);
+       * ≥ :data:`NONPRINT_CHAR_FRACTION` (0.05) of all characters are
+         non-printable (U+FFFD replacement chars + C0 controls) — the
+         ``errors="replace"`` binary-soup signal.
+
+       Pure + deterministic (no PDF, no I/O) — the unit tests pin the
+       thresholds against the REAL reproduced garbage string, not a
+       hand-drawn one. A real document ABOUT xml whose tag-like lines
+       reach 30% is a documented false positive (ASSUMPTION A8 — the
+       fallback still extracts it correctly via vision; the cost is a
+       few vision calls).
+       """
+   ```
+   with the two threshold constants (`XMLISH_LINE_FRACTION = 0.30`, `NONPRINT_CHAR_FRACTION = 0.05`) — named, documented, not magic. Non-empty-line counting: `line.strip()` truthy (house convention); the non-printable set: `"\ufffd"` + `unicodedata.category(ch).startswith("C")` (or an explicit C0 range check — pick one, document it; exclude the structural `\\n`/`\\t` the extractor legitimately emits — Cc category would catch them, so use the explicit set: `"\ufffd"` + control chars EXCEPT `\\t\\n\\r` — document the exclusion).
+2. `tests/unit/test_pdf.py` (extend — the phase-126 suite) — the gate's pins:
+   - clean text (a few real paragraphs + the `---PAGE-N---` separators) → `True`;
+   - THE REAL GARBAGE: reproduce the pre-126 read in the test — read `test_sources/hnb_2026_guide.tar.gz`'s PDF (extract to `tmp_path` — share a module-scoped fixture with the integration test's pattern, or a smaller inline reproduction: the test may instead read the tar.gz's PDF bytes with `read_text(errors="replace").replace("\\x00", "")` and pin `is_usable_pdf_text(garbage) is False` — the REAL string, the owner's exact file, the airtight pin);
+   - the empty text layer (`""` / whitespace) → `False`;
+   - an XML-heavy layer (≥ 30% tag-like lines) → `False`;
+   - a borderline document ABOUT xml (29% tag-like lines, printable) → `True` (the threshold's edge, from below) and 31% → `False` (from above);
+   - the U+FFFD-heavy soup (5%+ replacement chars, few tags) → `False` (the second signal fires alone);
+   - the structural `\\n`/`\\t` exclusion (text full of newlines/indents is printable).
+
+## Testing & Quality
+- Unit: the pins above — this task's suite.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] `is_usable_pdf_text` is pure (no PDF dependency) and pinned on the REAL reproduced garbage string (the owner's file, not a lookalike)
+- [ ] both failure signals (XML-ish fraction, non-printable fraction) are tested independently
+- [ ] the thresholds are named constants with the false-positive cost documented
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/133_pdf_screenshot_fallback/03_page_screenshot_fallback.md

@@ -0,0 +1,51 @@
+# Task 03 — The screenshot fallback: unusable text layer → render pages, read each by vision
+
+**Phase:** `133_pdf_screenshot_fallback` · **Source:** `TODO.md:9` — "...should be able to extract it correctly, even if that means screenshotting the pages and reading each one as an image to preserve formatting when text/image/table extraction isn't working."
+
+## Objective
+When the gate (task 02) says the text layer is garbage or empty, `_index_pdf_file` takes the owner's specified path: every page is rendered to a PNG screenshot and read by the vision model — the stored content is the page-anchored descriptions, so tables/images/whatever the text layer lost are preserved as the model saw them on the page.
+
+## Work
+1. `app/rag/pdf.py` — new pure renderer:
+   ```python
+   def render_pdf_pages(pdf_path: Path, dpi: int = 150) -> list[bytes]:
+       """Render every page of *pdf_path* to a PNG (page order, 1-based
+       meaning — list index i is page i+1).
+
+       The fallback's visual input (ASSUMPTION A8: fixed 150 DPI — the
+       balance of vision legibility vs data-URL payload; a page that
+       cannot be rendered yields b"" (the caller's placeholder — the
+       page index NEVER shifts, so ---PAGE-N--- stays truthful).
+       A file that cannot be OPENED yields [] (the caller's existing
+       empty-content path — the doc lands with the no-extractable-text
+       behavior, unchanged).
+       """
+   ```
+   PyMuPDF: `page.get_pixmap(dpi=dpi).tobytes("png")` per page, per-page try/except (the `extract_pdf_text` fail-soft style — log a warning per skipped page).
+2. `app/rag/importer.py` — `_index_pdf_file`: after `content = extract_pdf_text(full_path)`, insert the gate branch (BEFORE the doc-row upsert, so the digest/chunk/summary pipeline runs on the FINAL content exactly once):
+   ```python
+   if not is_usable_pdf_text(content):
+       summary.pdfs_screenshotted += 1
+       content = await _fallback_page_screenshots(session, source=source, rel=rel,
+                                                  full_path=full_path, llm=llm)
+   ```
+   with the new module-level helper `_fallback_page_screenshots` (place it near `_index_pdf_file`):
+   - `pages = render_pdf_pages(full_path)`;
+   - the loud one-line log (PLAN §9, the FINDING's signature): `logger.warning("pdf: text layer unusable for %s/%s — falling back to %d page screenshots", source, rel, len(pages))` (the gate's fractions ride the log at DEBUG: `logger.debug("pdf: gate xml_frac=%.2f nonprint=%.2f …")` — computed by a small `_gate_fractions(text)` helper the unit tests pin too, if the warning wants them — optional, keep the required line exact);
+   - per page (index i, page = i+1): `png = pages[i]`; if `png == b""` → `block_text = f"page {page} — description unavailable"`; else `desc = await describe_image(llm, data=png, mime="image/png")` (the phase-122 call — `settings` default, `context` None); `desc is None` or blank → the same placeholder (fail-soft per page — a dead vision endpoint must not sink the doc, the phase-122 fail-soft spirit); else `block_text = desc.strip()`;
+   - `content = "\n\n".join(f"{PAGE_SEPARATOR.format(page=p)}\n{block}" for p, block in ...)` — the SAME separator convention as `extract_pdf_text` (the chunker's page-boundary handling works unchanged);
+   - an ALL-failed render (`pages == []` or every page placeholder) → return `""` (the existing empty-content path — the doc lands as a zero-text doc, the phase-126 no-extractable-text behavior);
+   - the embedded-image extraction (`extract_pdf_images` + `_describe_or_skip`) still runs AFTER the gate branch on BOTH paths — the fallback doc's embedded images join the pipeline exactly as a clean PDF's do (the screenshots are the CONTENT; the extracted images are the citation figures — both, no conflict).
+3. `app/rag/importer.py` — `ImportSummary`: add `pdfs_screenshotted: int = 0` (documented: "PDFs whose text layer failed the gate and took the page-screenshot vision fallback (phase 133)") + the field in `log()`'s format string (append to the existing line — the house ample-logging shape).
+4. `app/rag/importer.py` — the digest: the fallback's constructed content is what the sha256 runs over (the existing `digest = hashlib.sha256(content.encode(...))` line — no change needed, just verify it runs AFTER the gate branch so a fallback doc's row is stable across re-syncs: same pages + same vision model → same descriptions → same digest → unchanged on the next sync, no vision re-burn. If `describe_image`'s reply is non-deterministic in production, note it in the docstring — the re-burn is then a cost, not a bug).
+
+## Testing & Quality
+- Unit: `tests/unit/test_pdf.py` (extend) — `render_pdf_pages`: a 2-page temp PDF (built with fitz in the test — the phase-126 fixture pattern) → 2 PNGs (magic bytes `\\x89PNG`), page order; an unreadable path → `[]`; a corrupted page (if constructible — else the b"" path via a monkeypatched `get_pixmap` raising) → the zero-byte entry at its index, the index intact.
+- Unit: `tests/unit/test_importer.py` (extend) — the fallback branch, with a REAL tiny garbage PDF (build one in the test: a fitz page whose inserted text is ONLY XML-ish lines — `<foo:bar>x</foo:bar>` repeated — so the gate fails deterministically) + a fake LLM whose multimodal `chat` returns a canned page description: the stored doc's content = `---PAGE-1---\\n<canned>` (the separator convention), `summary.pdfs_screenshotted == 1`, the loud warning logged (the caplog pin); a CLEAN tiny PDF (the phase-126 fixtures) → `pdfs_screenshotted == 0` and the vision multimodal `chat` is NEVER called for the fallback (only the embedded-image describes — the gate never burns vision on a clean layer).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a garbage-text PDF lands with the page-screenshot content (the synthetic test: `---PAGE-N---` + the canned descriptions)
+- [ ] a clean PDF's path is byte-identical to phase 126 (no fallback, no extra vision calls, `pdfs_screenshotted == 0`)
+- [ ] the fallback is fail-soft per page (a dead vision call → the placeholder line, the doc still lands)
+- [ ] `uv run pytest tests/unit -q` green; no behavior change in completed work

.agents/phases/complete/133_pdf_screenshot_fallback/04_e2e_garbage_pdf.md

@@ -0,0 +1,29 @@
+# Task 04 — E2E: the real guide stays clean, a synthetic garbage PDF takes the screenshot path
+
+**Phase:** `133_pdf_screenshot_fallback` · **Source:** `TODO.md:9` — "...the raw xml is being embedded and the preview shows the entire document as lines like `<illustrator:StartupProfile>Web</illustrator:StartupProfile>`. This project should support this kind of PDF and should be able to extract it correctly, even if that means screenshotting the pages and reading each one as an image..."
+
+## Objective
+A dedicated, mock-only Playwright suite (A16 — one per phase, run in isolation) pins both legs of the guarantee at the user surface: (a) the owner's REAL guide, imported through the admin sync, previews CLEAN text (no XML lines — the exact complaint, negated); (b) a synthetic PDF whose text layer is pure XML garbage takes the screenshot fallback end to end — its content is the mock's canned vision descriptions, and the preview shows them.
+
+## Work
+1. `tests/e2e/test_garbage_pdf.py` (new) — house pattern (module app fixture over the shared E2E Postgres, host temp-dir `kind=local` source registered via the admin git-sources API, autouse truncate cleanup, mock-only — `E2E_REAL_LLM=1` unsupported: the fallback's vision surface is the deterministic `IMAGE_DESCRIPTION_MODE` canned reply).
+   App env: `BOR_IMPORT_EXTENSIONS` must include `pdf` (the owner's live config — the app fixture's env, the phase-126/127 suites' pattern) and `BOR_IMAGES=1` (the embedded-image pipeline is live).
+2. Fixtures (two local sources, two tests):
+   - `hnb/` — the REAL guide: extract `test_sources/hnb_2026_guide.tar.gz` into the temp dir (module-scoped, once — the 6 MB extraction is seconds).
+   - `garbagedoc/` — a synthetic garbage PDF built IN the test with PyMuPDF (the fixture pattern from task 03's unit test, lifted here): 2 pages, each page's ONLY text = repeated XML-ish lines (`<illustrator:StartupProfile>Web</illustrator:StartupProfile>` × ~20 — the owner's exact line shape, so the test is a faithful reproduction of the report), plus one small embedded raster image per page (fitz `insert_image` from a tiny PNG built in the test — the fallback's embedded-image leg runs too).
+3. Test → observable mapping (Playwright Mapping Rule):
+   - `test_real_guide_previews_clean_text` — admin sync over `hnb/` settles `success`; `GET /api/documents/content?source=hnb&path=<the guide's pdf>` (the PREVIEW surface — the endpoint the document viewer's content uses): the body contains `"2026 U.S. Benefits Guide"` (the real first-page text) and NO line matching the XML-ish regex (the owner's complaint, asserted on the served content, not the DB); the document viewer page (`/document.html?source=hnb&path=…`) renders that content (the preview shows real text, not `<illustrator:…>` lines).
+   - `test_garbage_pdf_takes_the_screenshot_path` — admin sync over `garbagedoc/` settles `success`; the stored doc's content (the same content endpoint): starts with `---PAGE-1---`, contains the mock's CANNED vision description (the `IMAGE_DESCRIPTION_MODE` reply's deterministic text — assert the first 40 chars) for BOTH pages (2 separators, 2 descriptions), and contains NO `<illustrator:StartupProfile>` line (the garbage text layer is NOT what got stored — the screenshot path replaced it); the sync's `detail` is `success` with `added == 1` (the garbage PDF is a normal import — the fallback is invisible in the status shape; the loud log line is server-side, PLAN §9).
+   - `test_clean_pdf_never_burns_the_fallback` — a third source `cleandoc/` with ONE small clean PDF (fitz, real prose text): sync → the stored content is the PROSE (the text layer, byte-faithful to the extraction) — NOT the canned vision description (the fallback did not fire on a clean layer — the gate's no-false-negative pin at the E2E level).
+4. Header docstring: the run-in-isolation command (`uv run pytest tests/e2e/test_garbage_pdf.py -v --no-cov`), the mock-only gate + why (the canned vision reply makes the fallback deterministic), the fixture provenance (the real tar.gz + the synthetic builder), the test→observable table.
+
+## Testing & Quality
+- E2E: this file IS the task's suite — run in isolation, green.
+- Coverage: the phase's >90% `app/` bar is carried by tasks 02–03; the real-guide regression by task 01; this task adds the in-isolation Playwright gate.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_garbage_pdf.py -v --no-cov` green in isolation (DB up: `podman compose up -d db`)
+- [ ] the real guide's PREVIEW (the owner's exact surface) is clean — the `<illustrator:StartupProfile>` line is asserted ABSENT on the served content
+- [ ] the synthetic garbage PDF's stored content is the canned vision descriptions (the fallback fired end to end, mock-deterministic)
+- [ ] the clean PDF is byte-faithful to its text layer (no false-positive fallback)
+- [ ] no behavior change in completed phases (the phase-126 pipeline, the sync, the document viewer)

.agents/phases/complete/134_sync_cancel/00_phase.md

@@ -0,0 +1,36 @@
+# Phase 134 — The owner can cancel a running sync from the Sources page
+
+**Source:** `TODO.md` L3 — "Need to be able to cancel a sync after I've clicked the button."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/api/sync.py` — `SyncStatus` (the four-state dataclass: `idle` / `running` / `success` / `failed`, phase-64 progress fields, phase-98 phase-machine fields), the module-level `_status` + `_task`, `POST /api/sync` (202 / 409 one-sync-at-a-time), `GET /api/sync/status`, and `_run_sync` — the in-process `asyncio` background task: the blocking git prelude (`scripts.git_sync.clone_or_pull` → `subprocess.run`, no await inside), then `await import_sources(...)` (per-file LLM awaits — a cancellation point between files), then `await regenerate_overview(...)` and `await generate_folder_summaries(...)` (both only on a changed KB / gap). The module docstring's shutdown contract: `CancelledError` is deliberately NOT swallowed — app shutdown cancels the task, and swallowing would mask a real stop. `import_sources` closes its own private session in a `finally` (leak-safe under a mid-import cancel). `frontend/assets/sources.js` — the sync-button lifecycle: `enterSyncRunningState` (live click + re-attach + every running tick), `settleSyncButton` (every terminal), `applySyncSuccess` / `applySyncFailure` / `applySyncIdle`, `startSyncPolling` (the 2 s two-job decision tree, 7 branches), `initSyncButton` (load-time re-attach). `frontend/index.html` — the `#sync-btn` markup (the Sources view section). E2E patterns: `tests/e2e/test_sync_button.py` (per-module app on a dedicated port, the `file://` fixture repo, the `_wait_sync_done` status-poll helper), `tests/e2e/slow_llm.py` (the delay-injecting proxy that makes a run's duration deterministic), `tests/e2e/mock_llm.py`. Unit: `tests/unit/test_sync_button.py`; integration: `tests/integration/test_sync_api.py`.
+
+## Objective
+A sync that is already running can be stopped by the owner: while a run is in flight the Sources page shows a **Cancel** button; one click requests the cancel, the pipeline stops at the next boundary, the run lands in a new `cancelled` terminal state (reported by the status endpoint and rendered by the UI as a neutral result — cancel is intent, not failure), and the controls settle back to the retry-ready idle state. A subsequent sync starts cleanly (the partial run leaves a consistent KB — the importer's content-hash delta makes the next run idempotent).
+
+## Dependencies
+- `133_pdf_screenshot_fallback` (todo) — pipeline order only; no code dependency.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The fifth state — `cancelled`** (ASSUMPTION A1): `SyncStatus.state` becomes `Literal["idle", "running", "success", "failed", "cancelled"]`. It is TERMINAL like `success` / `failed`: carries `finished_at`, clears `current_file` / `phase` / `current_summary` but keeps the run's final `files_done` / `files_total` and summary counts (the phase-64/98 keep-final-counts convention), `detail = {}`, and **`error = None`** (no error string — the UI never treats it as a failure: no error banner, no error modal, just the neutral "Sync cancelled" result line). `GET /api/sync/status` gains nothing structurally — the `state` key simply reports `"cancelled"`.
+- **`POST /api/sync/cancel`** (same `router`, so `require_admin` — 403 anonymous): while a run is in flight → set the module-level `_cancel_event` (an `asyncio.Event`, next to `_status` / `_task`) AND call `_task.cancel()` (unblocks whatever `await` the pipeline is parked on — e.g. a per-file LLM call inside the import) → **202** `{"detail": "cancel requested"}`. No run in flight (`_task` None or done) → **409** `{"detail": "no sync is running"}`. `start_sync` resets `_cancel_event` (clear) when it starts a run.
+- **Cancellation semantics — cooperative, best-effort** (ASSUMPTION A2): `_run_sync` gains (a) a private `_check_cancelled()` helper that raises `asyncio.CancelledError()` when `_cancel_event.is_set()`, called at the pipeline boundaries — the top of the per-source loop (before each clone/pull or local-dir check), immediately before `import_sources(...)`, and immediately before the `if summary.added + summary.updated > 0:` block (covers the overview + summaries spans); and (b) an `except asyncio.CancelledError:` clause (placed before the existing `except Exception`): if `_cancel_event.is_set()` → land the run in the `cancelled` terminal state + one INFO log line (PLAN §9: `sync: cancelled by user state=cancelled`), then `raise` (the task ends cancelled — `_task.done()` is True, the status object stays authoritative); otherwise (no user cancel — the app-shutdown path) → `raise` unchanged (the module docstring's shutdown contract holds: an unrequested cancellation is never swallowed). Consequence the UI/tests may rely on: a git subprocess already running at the cancel moment runs to completion (the blocking `subprocess.run` has no await inside) — the cancel takes effect at the NEXT boundary (after that source's git ops, between files, or before overview/summaries). During the import span the `_task.cancel()` from the endpoint interrupts at the next per-file await.
+- **The UI** (ASSUMPTION A3): a `#sync-cancel-btn` button in the same sync-control area as `#sync-btn` (`frontend/index.html`), `hidden` by default; secondary button styling consistent with the theme (contrast ≥4.5:1, `:focus-visible` ring — house UI rules). `sources.js` rules: SHOWN + ENABLED only while a SYNC run is running (`enterSyncRunningState` with `kind === "sync"` — the upload job is NOT cancellable in this phase, so the cancel button stays hidden while only the upload run drives the button); HIDDEN + DISABLED by `settleSyncButton` (every terminal/idle settle) and by every `applySync*` path. Click → `requestCancel()`: the cancel button disables IMMEDIATELY (never stale, no double request), `POST /api/sync/cancel`; 403 → the whoami-backstop hide-everything branch (same as the other endpoints); 409 → a harmless race (the run ended between ticks — the poll settles on the next tick, no error copy); 202 → the button stays disabled until the terminal (the poll's new `cancelled` branch settles everything); any other non-2xx → the phase-55 neutral retry copy in `#sync-result` ("Couldn't cancel the sync — try again.") + the cancel button re-enables. New poll-tree branch (after the `failed` branch, before the idle branch): `syncStatus.state === "cancelled"` → stop polling, settle the main button to "Sync sources", `#sync-result` = "Sync cancelled" (the aria-live announcer reads it), hide the error banner, hide the cancel button, `emitSyncStatus`. `initSyncButton` re-attach: `state === "cancelled"` → the same neutral settle (a page reload during/right after a cancel shows "Sync cancelled", never a stuck running state).
+
+## Tasks
+1. `01_backend_cancel_state.md` — the `cancelled` state, `POST /api/sync/cancel`, and the cooperative cancel mechanics in `_run_sync`.
+2. `02_frontend_cancel_button.md` — the `#sync-cancel-btn` UI: show/hide rules, the cancel request lifecycle, the `cancelled` terminal branch in the poll tree + re-attach.
+3. `03_e2e_sync_cancel.md` — the dedicated Playwright E2E (the slow-LLM cancel window, the API contract, the full UI lifecycle, the clean re-sync after cancel).
+
+## Testing & Quality
+- Unit: the cancel endpoint's contract (202/409/403), `_check_cancelled`, the `CancelledError` conversion (event set → `cancelled` state + re-raise; event unset → re-raise with the state untouched), the `SyncStatus` reset on a fresh start (a stale cancel event cannot bleed into the next run).
+- Integration: a real run started through the API is cancelled mid-run → the status reports `cancelled` (with `error: None`); a second run after the cancel completes successfully (the restart is clean).
+- E2E: one dedicated Playwright file, run in isolation (`tests/e2e/test_sync_cancel.py`) — the mock-only app with the `slow_llm` proxy for a deterministic cancel window.
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] `POST /api/sync/cancel` (admin): 202 while a run is in flight, 409 `no sync is running` otherwise, 403 anonymous
+- [ ] a cancelled run lands in the `cancelled` terminal state (`error: None`, final counts kept) and the status endpoint reports it
+- [ ] the app-shutdown cancel contract is preserved (an unrequested `CancelledError` is never swallowed — a unit test pins it)
+- [ ] the UI: the Cancel button is visible exactly while a sync run is running, the `cancelled` terminal settles to "Sync cancelled" with no error banner/modal, and a re-sync after a cancel succeeds
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_sync_cancel.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (the uncancelled run is byte-identical: same states, same labels, same 409 double-trigger)

.agents/phases/complete/134_sync_cancel/01_backend_cancel_state.md

@@ -0,0 +1,63 @@
+# Task 01 — Backend: the `cancelled` state, `POST /api/sync/cancel`, and the cooperative cancel in `_run_sync`
+
+**Phase:** `134_sync_cancel` · **Source:** `TODO.md:3` — "Need to be able to cancel a sync after I've clicked the button."
+
+## Objective
+The sync API can stop its own in-flight run: a new admin-only `POST /api/sync/cancel` requests the cancel; `_run_sync` converts a user-requested cancellation into a new `cancelled` terminal state (never an error); the shutdown-cancel contract is untouched.
+
+## Work
+1. `app/api/sync.py` — the state machine:
+   - `SyncStatus.state`: `Literal["idle", "running", "success", "failed", "cancelled"]` (the docstring's four-state paragraph becomes five; `cancelled` is terminal like `success` / `failed`).
+   - Module level, next to `_status` / `_task`: `_cancel_event = asyncio.Event()`.
+   - `start_sync`: reset the run's cancellation — `_cancel_event.clear()` before `_task = asyncio.create_task(_run_sync())` (a stale event from a previous cancelled run must never bleed into the next run).
+2. `app/api/sync.py` — the endpoint (same `router` → `require_admin` applies, 403 anonymous):
+   ```python
+   @router.post("/cancel", status_code=202)
+   async def cancel_sync() -> dict[str, str]:
+       if _task is None or _task.done():
+           raise HTTPException(status_code=409, detail="no sync is running")
+       _cancel_event.set()
+       _task.cancel()
+       return {"detail": "cancel requested"}
+   ```
+   202 is answered the moment the request is REGISTERED (the run may already be terminal — the UI's poll then settles on the terminal state; a 202-then-immediate-404-style race is impossible because the status object, not the task, is authoritative).
+3. `app/api/sync.py` — `_run_sync` mechanics:
+   - A private helper: `def _check_cancelled() -> None:` — `if _cancel_event.is_set(): raise asyncio.CancelledError()`.
+   - Call it at the boundaries: (a) the top of the per-source loop (before the `kind == "git"` / `kind == "local"` split), (b) immediately before `await import_sources(...)`, (c) immediately before the `if summary.added + summary.updated > 0:` block (covers both the overview and the summaries spans).
+   - New `except asyncio.CancelledError:` clause placed BEFORE the existing `except Exception`:
+     ```python
+     except asyncio.CancelledError:
+         if _cancel_event.is_set():
+             _status.state = "cancelled"
+             _status.finished_at = datetime.now(UTC)
+             _status.error = None
+             _status.current_file = None
+             _status.phase = None
+             _status.current_summary = None
+             logger.info(
+                 "sync: cancelled by user state=cancelled files_done=%d files_total=%d",
+                 _status.files_done, _status.files_total,
+             )
+             raise
+         raise  # app shutdown — the module-docstring contract: never swallow an unrequested cancel
+     ```
+     The terminal keeps `files_done` / `files_total` and the summary counts (the phase-64/98 keep-final-counts convention); `detail` stays `{}` (a partial run reports no counts — ASSUMPTION A1: `error` is None, `detail` is empty).
+   - Update the module docstring: the state machine is five-state; the cancel semantics are cooperative (a git subprocess in flight at the cancel moment runs to completion — the cancel lands at the next boundary); the `CancelledError` paragraph now names BOTH conversion paths (user-requested → `cancelled` state + re-raise; unrequested → re-raise).
+4. `GET /api/sync/status` — no shape change; update its docstring (the `state` value set now includes `cancelled`; `error` is null in that state).
+5. Unit tests — `tests/unit/test_sync_button.py` (extend) or a new `tests/unit/test_sync_cancel.py` (your call — the existing file owns the endpoint's contract, so extending it is the default):
+   - `POST /api/sync/cancel` anonymous → 403; idle (never started, and after a terminal run) → 409 with the exact detail `no sync is running`.
+   - A started run: the endpoint returns 202 `{"detail": "cancel requested"}`, sets the event, and cancels the task (drive `_run_sync` with a controllable await — e.g. a monkeypatched `import_sources` that awaits a `asyncio.Event` the test controls — then cancel via the endpoint and assert the task finished + `_status.state == "cancelled"`, `error is None`, `finished_at` set, final counts kept, `detail == {}`).
+   - The shutdown contract pin: cancel the task WITHOUT setting the event (bare `task.cancel()`) → `_status.state` is NOT `cancelled` (stays `running` — the task died mid-run without a terminal state, exactly as today's shutdown path does) and the `CancelledError` propagated.
+   - The stale-event pin: a run that was cancelled, then a FRESH run starts → `_cancel_event` is cleared (the new run completes to `success` with no cancel request).
+
+## Testing & Quality
+- Unit: the behaviors in Work step 5 (the suite above IS the task's unit layer).
+- Integration: `tests/integration/test_sync_api.py` (extend) — start a real run against the `file://` fixture pattern the file already uses (a slow/many-file fixture or a monkeypatched delay at the per-file hook seam — follow the file's existing fakes), `POST /api/sync/cancel` while running → poll `GET /api/sync/status` → `state == "cancelled"` (and `error is None`); then a second full run → `state == "success"` (the restart after a partial cancel is clean — the importer's hash delta re-imports what the cancel skipped).
+- Coverage: **>90%** on new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_sync_button.py tests/integration/test_sync_api.py -v` green (plus the new test file, if split)
+- [ ] the five-state machine is exercised in tests: `cancelled` is reachable ONLY through a user-requested cancel (the unrequested-cancel pin is green)
+- [ ] the module docstring names the cooperative boundary semantics (a future reader sees why a long clone can outlive the click)
+- [ ] `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change for the uncancelled run (the existing sync tests stay green untouched)

.agents/phases/complete/134_sync_cancel/02_frontend_cancel_button.md

@@ -0,0 +1,45 @@
+# Task 02 — Frontend: the `#sync-cancel-btn` and the `cancelled` terminal branch in the poll tree
+
+**Phase:** `134_sync_cancel` · **Source:** `TODO.md:3` — "Need to be able to cancel a sync after I've clicked the button."
+
+## Objective
+The Sources page shows a Cancel button exactly while a sync run is in flight (live click, re-attached run, every running poll tick); clicking it requests the cancel and the UI settles into the neutral "Sync cancelled" terminal — no error banner, no modal, never stale.
+
+## Work
+1. `frontend/index.html` (the Sources view section, next to `#sync-btn`): add the cancel control —
+   ```html
+   <button type="button" id="sync-cancel-btn" class="sync-cancel-btn" hidden>Cancel</button>
+   ```
+   - `hidden` by default (anonymous-safe + the idle state; the module reveals it, the same convention as `#sync-btn`).
+   - A visible "Cancel" label (no icon-only — WCAG 2.4 name/role; the accessible name is the text).
+   - `frontend/assets/styles.css`: `.sync-cancel-btn` — a secondary button style consistent with the theme (the house tokens, contrast ≥4.5:1 on `--surface`, `:focus-visible` ring like the other buttons, disabled state). No layout regression on the sync-control row (mobile included — the row already wraps; verify the 360 px case).
+2. `frontend/assets/sources.js` — the lifecycle (all inside the existing sync section; the §7.4 never-stale contract applies exactly as to the main button):
+   - Element lookup: `const syncCancelBtn = root.querySelector("#sync-cancel-btn");`
+   - Show/hide helpers: `showSyncCancelBtn()` (unhide + enable + `aria-label="Cancel sync"`) / `hideSyncCancelBtn()` (hide + disable).
+   - `enterSyncRunningState(kind, …, status)`: when `kind === "sync"` → `showSyncCancelBtn()`; when `kind === "upload"` → `hideSyncCancelBtn()` (the upload job is NOT cancellable in this phase — the cancel button belongs to the sync run only).
+   - `settleSyncButton(label)`: always `hideSyncCancelBtn()` (every terminal/idle settle — sync success/failed/cancelled, upload success/failed, both idle).
+   - `requestCancel()` + the click listener (armed next to `syncBtn.addEventListener("click", startSync)`):
+     - `syncCancelBtn.disabled = true` FIRST (never stale, one request at a time), `#sync-result` cleared.
+     - `POST /api/sync/cancel`: 403 → the whoami-backstop branch (stop polling, hide the main button, `applySyncIdle()`) — the same depth as every other 403 in this module; 409 → NO-OP (the run ended between the tick and the click — the poll settles on the next tick; the cancel button is hidden by that settle; no error copy); 202 → nothing (the button stays disabled — the poll's `cancelled` branch settles everything); any other non-2xx / network failure → `#sync-result` = "Couldn't cancel the sync — try again." (the phase-55 neutral retry copy) + `syncCancelBtn.disabled = false` (the run is still going — the owner can retry).
+   - New terminal branch in `startSyncPolling`'s tick — placed AFTER the `failed` branch and BEFORE the upload-success branch:
+     ```js
+     if (syncStatus.state === "cancelled") {
+       stopSyncPolling();
+       applySyncCancelled(syncStatus);
+       return;
+     }
+     ```
+   - `applySyncCancelled(status)`: `settleSyncButton("Sync sources")` (re-enables the main button, hides the cancel button), `syncResult.textContent = "Sync cancelled"`, `hideSyncError()`, `emitSyncStatus(status)`. No modal, no error styling (ASSUMPTION A1 — cancel is intent).
+   - `initSyncButton` re-attach: `status.state === "cancelled"` → `applySyncCancelled(status)` (a reload during/right after a cancel shows the neutral result, never a stuck running state).
+   - Update the section-header docstring (the decision tree gains the `cancelled` branch — the tree's "7" becomes "8" — and the cancel button's show/hide contract is documented there, the house pattern).
+3. No change to the upload job, the main sync button's existing labels, or the `bor:sync-status` event shape (the `cancelled` state simply flows through `emitSyncStatus` — the event's `detail` is the status object, as for every other state).
+
+## Testing & Quality
+- No JS unit layer in this repo — the UI contract is pinned by the phase's E2E (task 03) and by the never-stale rules above.
+- Coverage: **>90%** on new/modified code (test-only-for-`app/` task — the bar is carried by the suite run; the JS is covered by the E2E).
+
+## Completion Criteria
+- [ ] the Cancel button is visible + enabled ONLY while a sync run is running (hidden on boot/idle, hidden while only the upload run drives the button, hidden on every terminal)
+- [ ] clicking Cancel settles to "Sync cancelled" in `#sync-result` with the main button re-enabled, the cancel button hidden, no error banner and no modal
+- [ ] a 409 cancel (race) is silent; a failed cancel request shows the neutral retry copy and re-enables the button (the run keeps going)
+- [ ] `uv run ruff check . && uv run pyright` clean; the page renders with no console errors (verified in the E2E, task 03)

.agents/phases/complete/134_sync_cancel/03_e2e_sync_cancel.md

@@ -0,0 +1,36 @@
+# Task 03 — E2E: `tests/e2e/test_sync_cancel.py` (the dedicated Playwright suite, run in isolation)
+
+**Phase:** `134_sync_cancel` · **Source:** `TODO.md:3` — "Need to be able to cancel a sync after I've clicked the button."
+
+## Objective
+The owner's cancel path is pinned end to end against the REAL pipeline: a real `file://` fixture sync whose duration is long enough to cancel (the `slow_llm` proxy), the API contract (403/409/202), the UI lifecycle (Cancel button visible → click → "Sync cancelled" settle), and the clean re-sync after a partial run.
+
+## Work
+1. `tests/e2e/test_sync_cancel.py` (new) — the `test_sync_button.py` module-app pattern, adapted:
+   - **Ports/env:** per-module app on its own port — `APP_PORT = int(os.environ.get("E2E_APP_PORT_SYCNCEL", "8133"))`; `BOR_STATIC_DIR`, `BOR_RELEVANCE_THRESHOLD=0.30` (mock-calibrated, the conftest pattern), `BOR_ADMIN_PASSWORD` / `BOR_SESSION_SECRET` from `e2e.conftest`, `BOR_GIT_SOURCES=file://<fixture repo>`, a dedicated `BOR_SOURCES_DIR`.
+   - **The slow-LLM proxy:** spawn `tests/e2e/slow_llm.py` the conftest way (the `SLOW_LLM_DELAY_S` env — 0.3 s is a good default: ~40 fixture files → ~12+ s of import — a wide, deterministic cancel window against the UI's 2 s poll) in front of the mock LLM (the `mock_llm` fixture from `e2e.conftest`); `BOR_LLM_BASE_URL` points at the proxy.
+   - **The fixture repo** (module-scoped, `tmp_path_factory`, real `git` subprocess — the `sync_git_repo` pattern): ~40 small A9-format `.md` files under a `notes/` folder (each one unique enough to import independently; ONE sentinel file — `Marker: RESE-CANCEL-SENTINEL-4f1e` — the assertion target for the re-sync).
+   - **`_wait_sync_state(page, app_url, states, timeout_s)`** — the `test_sync_button._wait_sync_done` helper generalized to a set of terminal states (here `{"cancelled"}` and `{"success", "failed"}` for the re-sync).
+2. Tests (Playwright Mapping Rule — each test names the behavior it pins):
+   - `test_anonymous_cancel_403` — anonymous: `POST /api/sync/cancel` → 403 (the admin-only surface, same as the other two endpoints); `#sync-cancel-btn` is never revealed (the whoami gate).
+   - `test_cancel_when_idle_409` — logged-in, no run in flight: `POST /api/sync/cancel` → 409 with the exact detail `no sync is running`; the Cancel button is hidden in the UI (boot + idle).
+   - `test_admin_cancel_lifecycle` — the owner's exact flow:
+     1. login (lands on `/sources.html`);
+     2. click `#sync-btn` → `#sync-label` "Syncing…", the main button disabled, **`#sync-cancel-btn` visible + enabled** (within the 2 s poll tick — the running state is already entered synchronously by the 202);
+     3. confirm via the status endpoint that the run is `running` (the deterministic layer — `page.request` poll at ~100 ms, the `slow_llm` module's convention);
+     4. click `#sync-cancel-btn` → the cancel button disables immediately (never stale);
+     5. `_wait_sync_state(…, {"cancelled"})` → the status endpoint reports `state == "cancelled"` with `error is None`;
+     6. the UI settles (timeout-bound): main button ENABLED + label "Sync sources", `#sync-cancel-btn` hidden, `#sync-result` text "Sync cancelled", the error banner hidden, no error modal in the DOM;
+     7. **the re-sync is clean:** click `#sync-btn` again → "Synced HH:MM" (the `SYNCED_LABEL` regex) + `#sync-result` includes "40 added" (or the fixture's file count — the first FULL pass; the cancelled run's partial import is idempotent under the hash delta — assert the sentinel row is present in the catalog via the drill-down tree, the `_expect_fixture_row` pattern) → the cancel never corrupted the KB.
+   - Wall-time guard: the whole module < 120 s (40 files × 0.3 s proxy delay + the re-sync's 40 × 0.3 s — if it drifts, cut the file count, not the guard).
+3. Header docstring: the story ("the owner's TODO item, L3"), the run command (`uv run pytest tests/e2e/test_sync_cancel.py -v --no-cov`), the isolation note (per-module app, dedicated port — the combined-run convention), the slow-LLM provenance (the proxy is the only thing that makes the cancel window deterministic).
+
+## Testing & Quality
+- E2E: this file IS the task's suite; it runs in ISOLATION (`--no-cov`, the AGENTS.md rule 9 gate) with the DB up (`podman compose up -d db`) and git on PATH.
+- Coverage: **>90%** on new/modified code (test-only task — the bar is carried by the suite run).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_sync_cancel.py -v --no-cov` green in isolation
+- [ ] the cancel window is deterministic (the test does not race the 2 s poll — the `slow_llm` delay is the gate; a rerun on a quiet machine passes)
+- [ ] the re-sync after a cancel imports the FULL fixture (the sentinel row present — a partial cancel never leaves a corrupted or permanently-incomplete KB)
+- [ ] the `cancelled` state's `error` is null end to end (the UI can never render it as a failure)

.agents/phases/complete/135_git_source_branch/00_phase.md

@@ -0,0 +1,40 @@
+# Phase 135 — A git source can pin the branch it mirrors
+
+**Source:** `TODO.md` L4 — "Need to be able to specify the branch for a git source"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/models.py::GitSource` (id, url, kind, path, ignore_paths, include_hidden, token, added_at — no branch column; the phase-121 `token` column is the nullable-write-only precedent); `alembic/versions/` (0023 is the newest; every migration is reversible — the house rule); `app/schemas.py` — `GitSourceIn` / `GitSourceOut` / `GitSourceRow` / `GitSourcePatchIn` (the token field is the write-trimmed precedent; the output shapes use `extra="forbid"`); `app/api/git_sources.py` — `POST` (the `_create_git_row` / `_create_local_row` split, the fixed-detail 422s, the token normalization), `PATCH /{source_id}` (the per-field present-wins tri-state — the token's absent/None = no change, `""` = clear, non-empty = replace), `GET` (DB rows vs the env-fallback synthetic rows); `scripts/git_sync.py::clone_or_pull(url, dest)` (fresh clone with full history; the shallow probe + one-time `git fetch --unshallow` self-heal (phase 107 D11); `git pull --ff-only` — the fail-loud D12 contract); the TWO call sites that resolve effective sources and clone git rows: `app/api/sync.py::_run_sync` and `scripts/import_docs.py::_resolve_sources` (both already pass `clone_url_for(row)` + `repo_name(row.url)`); `file_commit_dates` (walks the checkout — untouched); the UI: `frontend/index.html` — the add form `#git-source-form` (the url + token inputs) and the per-row editor dialog `#ignore-editor-dialog` (the source line, the ignore textarea, the token field); `frontend/assets/git-sources.js` — `loadSources` / `makeRow` (the "hidden on" text-tag idiom in the source cell), `wireAddForm` (`opts.body(value, token)` builds the POST body), the dialog open/save handlers (the PATCH body builder), the `toggleHidden` never-stale lifecycle as the per-row control precedent.
+
+## Objective
+A git source can specify the branch it mirrors: the owner gives a branch when adding a git source (or edits it per-row later), the clone/pull honors it (a fresh clone checks the branch out; an existing checkout tracks it), BOTH entry points — the Sync button and the `import_docs` CLI — honor it, and every row without a branch (all existing rows + the env-fallback rows) behaves byte-identically to today (default branch, `git pull --ff-only`).
+
+## Dependencies
+- `134_sync_cancel` (todo) — pipeline order only; no code dependency (independent surfaces).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The column** (ASSUMPTION B1): `git_sources.branch` — `TEXT NULL`, server default NULL; alembic **0024** (reversible — `add_column` / `drop_column`, no data migration: NULL = "the repo's default branch", so every existing row is unchanged by definition). `GitSource.branch: Mapped[str | None] = mapped_column(Text, nullable=True)`.
+- **Validation** (ASSUMPTION B2): a pure helper `validate_branch_name(raw: str) -> str` in `app/rag/git_sources.py` (next to `normalize_credential` — the write-path helper home; the API layer maps its `ValueError` to the fixed-detail 422). Contract: trim → reject empty; reject length > 200; reject anything not matching `^[A-Za-z0-9._/-]+$` (alphanumerics + dot, underscore, hyphen, slash — whitespace/`@`/`~`/`^`/`:`/`?`/`*`/`[`/backslash are all out); reject a name containing `..` or `//`; reject a leading `-`, `.`, or `/`; reject a trailing `/` or `.`; reject `HEAD` (case-insensitive — git's refname; a branch literally named `head` is a documented cost of the simple rule). Returns the trimmed value. The API's 422 detail is the FIXED string `not a valid branch name` (never echoes the input — the house credential-safety discipline, applied for consistency).
+- **The write paths** (ASSUMPTION B3): `GitSourceIn.branch: str | None` (optional at create — absent/empty → NULL; trimmed in the schema before the length constraint, the `_trim_url` precedent). `GitSourcePatchIn.branch: str | None = None` — TRI-STATE exactly like the token: absent/None = no change; `""` = clear (stored NULL); non-empty = set (re-validated). A `branch` on a LOCAL row (POST or PATCH) → 422 fixed detail `branch is only valid for git sources` (local rows are walked, not cloned). `GitSourceOut.branch: str | None` + `GitSourceRow.branch: str | None` (env-fallback synthetic rows report `None` — no DB row to store one on, the `ignore_paths: []` precedent).
+- **`clone_or_pull(url, dest, branch: str | None = None)`** (ASSUMPTION B4): `branch=None` → the EXISTING code path byte-identical (same argv: clone without `--branch`; probe; unshallow-if-shallow; `git pull --ff-only`). A fresh clone with a branch → `git clone --branch <b> url dest`. An existing checkout with a branch → (1) the HEAD GUARD first: `git rev-parse --abbrev-ref HEAD` — if the result is not `<b>` → `GitSyncError("checkout <dest> is on branch '<current>' but the source specifies branch '<b>' — remove and re-add the source to switch branches")` (ASSUMPTION B5 — fail loud, the D12 convention; NO silent checkout switch in this phase: the checkout may serve other rows' documents, and a switch would silently re-map the source's file set; phase 136's explicit-ref reset makes the ref unambiguous later without changing this guard); (2) the shallow probe + one-time unshallow (unchanged); (3) `git fetch origin <b>`; (4) `git merge --ff-only FETCH_HEAD` (the single-fetch ff pull — the sequence phase 136 extends with its reset fallback).
+- **Wiring:** both call sites pass `row.branch` — `app/api/sync.py::_run_sync` and `scripts/import_docs.py::_resolve_sources`: `clone_or_pull(clone_url_for(row), sources_root / repo_name(row.url), row.branch)`. Env-fallback synthetic rows carry `branch=None` (the `GitSource(url=…, kind="git")` constructor default). `file_commit_dates`, the checkout naming (`repo_name` stays on the BARE url), and the ignore/hidden/date maps are untouched.
+- **The UI** (ASSUMPTION B6): the add form gains an optional `#git-source-branch` text input (maxlength 200, `autocomplete="off"`, hint "optional — default: the repo's default branch") between the URL and Token fields; the submit body becomes `(url, token, branch) => ({ url, ...(branch ? { branch } : {}), ...(token ? { token } : {}) })` — a blank branch OMITS the key (NULL). The per-row editor dialog gains a `#ignore-editor-branch` field (visible for GIT rows only — local rows' dialogs hide it; it opens prefilled from `s.branch ?? ""`; the PATCH body for a git row ALWAYS includes `branch: <trimmed value>` — empty = the tri-state's clear leg, so clearing a branch is a deliberate empty save, unlike the token's blank = keep). Every STORED git row with a branch shows a `branch: <name>` text tag in the source cell (the "hidden on" tag idiom — text + background, WCAG: the text IS the signal, never color alone).
+
+## Tasks
+1. `01_branch_column.md` — the alembic 0024 migration, the `GitSource.branch` column, the schema fields, the migration round-trip test.
+2. `02_branch_api.md` — `validate_branch_name` + POST/PATCH/GET wiring (the tri-state, the local-row 422, the env rows).
+3. `03_clone_pull_branch.md` — `clone_or_pull(…, branch)` (the `--branch` clone, the HEAD guard, the fetch+ff sequence) + both call sites.
+4. `04_branch_ui.md` — the add-form field, the per-row editor field, the row tag.
+5. `05_e2e_git_source_branch.md` — the dedicated Playwright E2E (the two-branch `file://` fixture, the UI add-with-branch → sync → branch content, the fail-loud mismatch, the API contracts).
+
+## Testing & Quality
+- Unit: `validate_branch_name` (the full accept/reject matrix); `clone_or_pull`'s argv sequences with mocked `subprocess` (the `tests/unit/test_git_sync.py` pattern — fresh-clone `--branch`, the existing-checkout guard → probe → fetch → merge, the mismatch raise, `branch=None` byte-identical).
+- Integration: the migration round-trip (0024); the API round-trips (create/patch/list, the tri-state, the 422s); a real `file://` two-branch clone through `clone_or_pull` (the `tests/integration/test_import_docs_git.py` pattern) + the sync pipeline importing the branch's content.
+- E2E: one dedicated Playwright file, run in isolation.
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] a git source added with a branch mirrors THAT branch (fresh clone + subsequent pulls) through both the Sync button and the CLI — pinned by the E2E + the integration test
+- [ ] a row with no branch (all existing rows + env rows) behaves byte-identically to pre-phase (the `branch=None` argv pin is green)
+- [ ] invalid branch names are rejected with the fixed 422 (never echoing input); a branch on a local row is a 422; the PATCH tri-state (set/change/clear) round-trips
+- [ ] setting a branch on an existing checkout on a different branch fails the sync LOUDLY with the remove-and-re-add message (no silent switch)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_git_source_branch.py -v --no-cov` green in isolation
+- [ ] no behavior change in completed phases (the token/ignore/hidden round-trips, the sync pipeline, the CLI — all existing tests green untouched)

.agents/phases/complete/135_git_source_branch/01_branch_column.md

@@ -0,0 +1,38 @@
+# Task 01 — The `git_sources.branch` column: migration 0024, the model field, the schema fields
+
+**Phase:** `135_git_source_branch` · **Source:** `TODO.md:4` — "Need to be able to specify the branch for a git source"
+
+## Objective
+The registry can store a per-source branch: a reversible alembic 0024 adds the nullable `branch` column, the ORM model carries it, and the four API schema shapes report/accept it — with NULL meaning "the repo's default branch" so every existing row is unchanged.
+
+## Work
+1. `alembic/versions/0024_git_source_branch.py` (new) — follow the shape of `0021_git_source_token.py` (read it first):
+   - `revision = "0024"`, `down_revision = "0023"` (verify the actual latest revision id in `alembic/versions/` at execution time — the file numbering is the convention, the `down_revision` chain is the truth).
+   - `upgrade`: `op.add_column("git_sources", sa.Column("branch", sa.Text(), nullable=True))`.
+   - `downgrade`: `op.drop_column("git_sources", "branch")` (reversible — the house rule; NULL = default branch means no data migration in either direction).
+2. `app/models.py::GitSource` — add:
+   ```python
+   #: The branch to mirror (phase 135): NULL = the repo's default branch
+   #: (every pre-phase-135 row and every env-fallback row — byte-identical
+   #: clone/pull behavior). A non-NULL value is validated at the API
+   #: boundary (app.rag.git_sources.validate_branch_name) — the column
+   #: itself is plain Text.
+   branch: Mapped[str | None] = mapped_column(Text, nullable=True)
+   ```
+3. `app/schemas.py` (the four shapes — each docstring gains its phase-135 paragraph):
+   - `GitSourceIn.branch: str | None = Field(default=None, max_length=200)` — optional at create (absent → NULL); a `field_validator` trims before the length constraint runs (the `_trim_url` precedent) — note the API layer treats a trimmed-EMPTY value as absent at create and as the tri-state's clear leg at PATCH (document that split in the docstring).
+   - `GitSourceOut.branch: str | None` — the stored value (NULL → null in the response); the shape keeps `extra="forbid"` (no new omission risk — the field is explicit).
+   - `GitSourceRow.branch: str | None` — DB rows report the stored value; env-fallback synthetic rows report `None` (the `ignore_paths: []` / `include_hidden: False` precedent — no DB row to store one on).
+   - `GitSourcePatchIn.branch: str | None = None` — the tri-state (absent/None = no change; `""` = clear; non-empty = set — the token's precedent, documented in the docstring).
+4. `uv run alembic upgrade head` against the dev DB (and `downgrade -1` + `upgrade head` once — the reversibility proof).
+5. `tests/integration/test_migration_0024.py` (new — the `test_migration_0021.py` pattern): the upgrade adds the nullable column to a table WITH pre-existing rows (all report NULL — the byte-identical guarantee), a row can take a branch value, the downgrade drops the column.
+
+## Testing & Quality
+- Integration: the migration round-trip (the suite above).
+- Coverage: **>90%** on new/modified code (the model/schema surface is exercised by task 02's API tests — this task's own gate is the migration test + the suite run).
+
+## Completion Criteria
+- [ ] `uv run alembic upgrade head && uv run alembic downgrade -1 && uv run alembic upgrade head` succeeds on a scratch DB (the reversibility proof)
+- [ ] pre-existing rows read `branch: None` (the integration test asserts on seeded rows — no backfill, no default)
+- [ ] `uv run pytest tests/integration/test_migration_0024.py -v` green
+- [ ] `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/135_git_source_branch/02_branch_api.md

@@ -0,0 +1,52 @@
+# Task 02 — API: branch validation, POST/PATCH/GET wiring (the tri-state, the local-row 422, the env rows)
+
+**Phase:** `135_git_source_branch` · **Source:** `TODO.md:4` — "Need to be able to specify the branch for a git source"
+
+## Objective
+The admin API accepts, validates, stores, and reports a branch per git source: a pure `validate_branch_name` helper is the single choke point, POST stores it (git rows only), PATCH edits it with the token's tri-state, and GET/POST-201/PATCH-200 report it — invalid names get a fixed-detail 422 that never echoes the input.
+
+## Work
+1. `app/rag/git_sources.py` — the pure validator (next to `normalize_credential`; no DB, no logging of the raw value beyond the fixed reason):
+   ```python
+   _BRANCH_RE = re.compile(r"^[A-Za-z0-9._/-]+$")
+
+   def validate_branch_name(raw: str) -> str:
+       """Trim + validate a branch name (phase 135, ASSUMPTION B2).
+
+       Returns the trimmed name; raises ValueError (fixed reason strings,
+       for logs only — the API maps to the fixed-detail 422) when the
+       name is empty, > 200 chars, outside the safe charset
+       ([A-Za-z0-9._/-]+), contains ".." or "//", starts with "-"/"."/"",
+       ends with "/" or ".", or is HEAD (case-insensitive).
+       """
+   ```
+   (The leading-slash check is `startswith("/")`; write the helper with the checks in this order: trim → empty → length → charset → `..`/`//` → leading → trailing → HEAD.)
+2. `app/api/git_sources.py`:
+   - `_create_git_row`: after the URL contract (and the token normalization — order: URL shape → credential normalization → duplicate check → branch): `branch = (payload.branch or "").strip()`; if `branch`: `validate_branch_name` → store; else store `None`. A `ValueError` → `HTTPException(422, detail="not a valid branch name")` (FIXED detail — the input is never echoed).
+   - `_create_local_row`: `payload.branch` present and non-empty after strip → `HTTPException(422, detail="branch is only valid for git sources")` (local rows are walked, not cloned — the fixed detail, the kind-field rules' precedent).
+   - `patch_git_source`: a new independent present-wins field — `if payload.branch is not None:` the row must be `kind == "git"` (local → the same fixed 422); `""` → `row.branch = None` (the tri-state's clear leg); non-empty → `validate_branch_name` → set. No Integrity interaction (branch never touches a unique index) — no 409 path. Update the docstring's field list (ignore_paths / include_hidden / token / branch).
+   - `list_git_sources`: DB rows report `branch=row.branch`; env-fallback rows report `branch=None`. Update the docstring.
+   - `create_git_source` / `patch_git_source` responses: include `branch=row.branch` in the `GitSourceOut` construction.
+   - The module docstring's route summary gains the branch clauses (the house one-paragraph-per-route contract).
+3. Unit tests — `tests/unit/test_git_sources_branch.py` (new; the validator has no existing home):
+   - Accept: `main`, `release/1.2`, `feature_x`, `a.b/c`, `v2-rc.1` (trim applied: `"  main  "` → `main`).
+   - Reject (each → `ValueError`): `""`, `"   "`, 201 chars, `a b`, `a@b`, `a~b`, `a:b`, `a?b`, `a*b`, `a[b`, `a\b`, `a..b`, `a//b`, `-x`, `.x`, `/x`, `x/`, `x.`, `HEAD`, `head`, `HeAd`.
+4. Integration tests — `tests/integration/test_git_sources_api.py` (extend — the file already owns this router's contract):
+   - POST a git source with `branch: "release"` → 201 reports `branch: "release"`; GET reports it.
+   - POST with an invalid branch (`"a..b"`) → 422 `not a valid branch name` (the detail is EXACT — no input echo); the row is not created.
+   - POST a LOCAL source with a branch → 422 `branch is only valid for git sources`.
+   - PATCH the tri-state: set (`"hotfix/x"`) → 200 reports it; change (`"hotfix/y"`); clear (`""`) → 200 reports `null`; absent (PATCH `{"include_hidden": true}` only) → the branch is untouched.
+   - PATCH a local row's branch → 422.
+   - Env-fallback rows (empty table + `BOR_GIT_SOURCES` env): GET reports `branch: null` for every synthetic row.
+   - The existing token/ignore/hidden round-trips stay green (no regression).
+
+## Testing & Quality
+- Unit: the validator matrix (step 3).
+- Integration: the API round-trips (step 4).
+- Coverage: **>90%** on new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_git_sources_branch.py tests/integration/test_git_sources_api.py -v` green
+- [ ] every 422 detail is a fixed string (a grep of the new code shows no f-string echoing the branch input)
+- [ ] the tri-state matches the token's semantics field-for-field (the PATCH docstring documents both)
+- [ ] `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/135_git_source_branch/03_clone_pull_branch.md

@@ -0,0 +1,48 @@
+# Task 03 — `clone_or_pull(…, branch)` and both call sites (sync pipeline + CLI)
+
+**Phase:** `135_git_source_branch` · **Source:** `TODO.md:4` — "Need to be able to specify the branch for a git source"
+
+## Objective
+The git plumbing honors a row's branch: a fresh clone checks it out (`--branch`), an existing checkout is tracked (fetch + ff-merge of that ref) with a fail-loud guard when the checkout is on a different branch, and `branch=None` keeps the pre-phase argv byte-identical — wired through BOTH entry points (the Sync button and the `import_docs` CLI).
+
+## Work
+1. `scripts/git_sync.py::clone_or_pull` — the new optional parameter (the module docstring's clone/pull paragraph + the function docstring gain the branch contract):
+   ```python
+   def clone_or_pull(url: str, dest: Path | str, branch: str | None = None) -> Path:
+   ```
+   - **`branch is None`** — the EXISTING code path, byte-identical: clone without `--branch`; `rev-parse --is-shallow-repository` probe; `fetch --unshallow` while shallow; `git pull --ff-only`. (The argv pin in the unit tests is the proof.)
+   - **Fresh clone + branch** (`dest` absent or no `.git`): `git clone --branch <b> url dest`.
+   - **Existing checkout + branch**, in order:
+     1. HEAD GUARD: `git rev-parse --abbrev-ref HEAD` → let `current` be the result. If `current != branch` → `GitSyncError(f"checkout {dest} is on branch '{current}' but the source specifies branch '{branch}' — remove and re-add the source to switch branches")` (ASSUMPTION B5 — fail loud per D12; the message names the checkout and both branch names — no URL, so no credential exposure).
+     2. the shallow probe + one-time `git fetch --unshallow` self-heal (UNCHANGED from today — the phase-107 D11 contract).
+     3. `git fetch origin <b>` → `git merge --ff-only FETCH_HEAD` (the single-fetch ff pull of the specified ref — the sequence phase 136 extends with its reset fallback; a non-ff merge still fails loud HERE — the force-push fix is phase 136, not this one).
+   - All commands go through `run_git` (the A11 single invocation site — unchanged).
+2. The call sites — pass `row.branch`:
+   - `app/api/sync.py::_run_sync` (the per-source loop, the `kind == "git"` arm): `root = clone_or_pull(clone_url_for(row), sources_root / repo_name(row.url), row.branch)`.
+   - `scripts/import_docs.py::_resolve_sources` (the same shape): `root = clone_or_pull(clone_url_for(row), sources_root / repo_name(row.url), row.branch)`.
+   - Both files' docstrings/comments name the branch argument (the phase-106/121 comment style). Env-fallback synthetic rows carry `branch=None` (the `GitSource(url=…, kind="git")` constructor — no argument needed, the model default is None — verified by the env-fallback integration path).
+   - `file_commit_dates(root)` is untouched (it walks whatever the checkout holds — for a branch checkout that is the branch's tree, exactly the head-of-branch semantics the owner asked for).
+3. Unit tests — `tests/unit/test_git_sync.py` (extend — the mocked-`subprocess` argv pattern the file already uses):
+   - `branch=None` fresh + existing: the argv sequence is byte-identical to the pre-phase expectations (the existing tests stay green + add an explicit argv-equality pin if the file doesn't already pin it).
+   - Fresh clone + `branch="release"`: `["git", "clone", "--branch", "release", url, dest]`.
+   - Existing + matching HEAD (`rev-parse --abbrev-ref HEAD` → `"release"`): the sequence `rev-parse --abbrev-ref HEAD` → `rev-parse --is-shallow-repository` → (`fetch --unshallow` when the probe says shallow) → `fetch origin release` → `merge --ff-only FETCH_HEAD`.
+   - Existing + mismatched HEAD (`"main"` vs `branch="release"`): raises `GitSyncError` whose message contains both branch names and the checkout path — and NO fetch/merge argv was invoked (the guard is first).
+   - The mismatch message never contains the URL (credential-safety — even for a plain URL the message is URL-free).
+4. Integration tests — `tests/integration/test_import_docs_git.py` (extend — the real-`git`-`file://` pattern the file already uses):
+   - Build a two-branch fixture repo (real git: `main` with file A, `release` with file B — different content per branch).
+   - `clone_or_pull(url, dest, "release")` fresh → the checkout's HEAD branch is `release` and file B is present (file A absent).
+   - A second `clone_or_pull` after the origin gains a commit on `release` → ff-merged (file B updated, no error).
+   - The mismatch case: clone fresh with no branch (HEAD = `main`), then `clone_or_pull(url, dest, "release")` → `GitSyncError` (the remove-and-re-add message), the checkout untouched (still on `main`).
+   - The full sync pipeline with a branch row: a `git_sources` row (`kind="git"`, `branch="release"`) → `_run_sync`'s source resolution imports file B (the `tests/integration/test_sync_api.py` fixture shape) — or at minimum `_resolve_sources`-level for the CLI path (follow whichever seam the file already exercises; the E2E, task 05, pins the button path end to end).
+
+## Testing & Quality
+- Unit: the argv matrix (step 3) — the `branch=None` byte-identical pin is the regression gate for every existing deployment.
+- Integration: the real-git two-branch scenarios (step 4).
+- Coverage: **>90%** on new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_git_sync.py tests/integration/test_import_docs_git.py -v` green
+- [ ] `branch=None` produces the exact pre-phase argv (the pin is in the suite — a future refactor that rewrites the default path breaks it)
+- [ ] the mismatch fails loud BEFORE any fetch (the unit test asserts no fetch argv after the guard)
+- [ ] both entry points pass `row.branch` (a grep of the two call sites + the integration test covering each)
+- [ ] `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/135_git_source_branch/04_branch_ui.md

@@ -0,0 +1,43 @@
+# Task 04 — UI: the add-form field, the per-row editor field, and the row tag
+
+**Phase:** `135_git_source_branch` · **Source:** `TODO.md:4` — "Need to be able to specify the branch for a git source"
+
+## Objective
+The Sources manager (git-sources view) lets the owner see, set, change, and clear a source's branch: an optional Branch input in the add form, a Branch field in the per-row editor dialog (git rows only, prefilled, empty-save = clear), and a `branch: <name>` text tag on every stored git row that has one — all on the §7.4 never-stale lifecycle.
+
+## Work
+1. `frontend/index.html` (the `#view-git-sources` section):
+   - **The add form** (`#git-source-form`) — between the URL field and the Token field:
+     ```html
+     <label for="git-source-branch">Branch <span class="field-hint">optional — default: the repo's default branch</span></label>
+     <input id="git-source-branch" name="branch" type="text" maxlength="200" autocomplete="off" placeholder="main, release/1.2, …">
+     ```
+     (The visible `<label for=…>` is the WCAG input-label rule, same as the url/token fields.)
+   - **The per-row editor dialog** (`#ignore-editor-dialog`) — after the source line, before the ignore textarea:
+     ```html
+     <label for="ignore-editor-branch">Branch</label>
+     <input id="ignore-editor-branch" type="text" maxlength="200" autocomplete="off" placeholder="(default branch)">
+     <p class="ignore-editor-branch-hint">Leave empty for the repo's default branch.</p>
+     ```
+     The hint uses the existing `.field-hint` / muted-copy idiom (match the token field's hint styling — no new CSS class unless the existing one doesn't fit).
+2. `frontend/assets/git-sources.js`:
+   - **Element lookups:** `const branchInput = root.querySelector("#git-source-branch");` and `const ignoreBranchInput = root.querySelector("#ignore-editor-branch");` (next to the existing token lookups).
+   - **Add form:** thread the branch through `wireAddForm` — the opts object gains `branchInput`, and the git-kind body builder becomes `body: (url, token, branch) => ({ url, ...(branch ? { branch } : {}), ...(token ? { token } : {}) })` (a blank branch OMITS the key — the token's blank-omits precedent; the submit handler reads `branchInput.value.trim()` and clears it on 201 alongside the url/token — the credential-free inputs clear together).
+   - **Per-row editor dialog:**
+     - Open: for a git row (`s.kind === "git"`) — prefill `ignoreBranchInput.value = s.branch ?? ""` and show the field; for a local row — hide the field (label + input + hint) and the save body OMITS `branch` (local rows can't take one — the API's 422 is the backstop, the UI simply doesn't offer it).
+     - Save: the PATCH body for a git row ALWAYS includes `branch: ignoreBranchInput.value.trim()` (empty = the tri-state's clear leg — a deliberate empty save clears the branch, unlike the token's blank = keep; the docstring/section comment documents the asymmetry), composed with the existing `ignore_paths` + conditional `token` (the token stays the blank = keep tri-state — untouched).
+     - The never-stale lifecycle mirrors the existing save handler: the Save button disables in flight, 200 → close the dialog + `loadSources()` (the row re-renders from the server — the tag appears/disappears), failure → the dialog's error line (the existing pattern) + the inputs keep the user's text.
+   - **The row tag** (`makeRow` / the source-cell builder): when `s.id && s.branch` — append a text tag `branch: <name>` in the source cell, next to the existing "hidden on" tag (the SAME tag idiom: a span with the tag class — text + background, never color alone; the tag text is the signal). Env-fallback rows (no `s.id`) and NULL-branch rows show no tag. Update the source cell's `aria-label`/`title` to include the branch (the hover precision idiom).
+   - The module's section-header docstring gains the phase-135 paragraph (the house pattern — the field, the tri-state asymmetry, the tag rule).
+3. No new API surface, no new fetches — the branch rides the existing POST/PATCH/GET payloads (task 02's shapes).
+
+## Testing & Quality
+- No JS unit layer in this repo — the UI contract is pinned by the phase's E2E (task 05).
+- Coverage: **>90%** on new/modified code (frontend-only task — the bar is carried by the suite run + the E2E).
+
+## Completion Criteria
+- [ ] adding a git source with a branch sends `branch` (non-blank) / omits it (blank) — pinned by the E2E's request assertions
+- [ ] the dialog prefills the stored branch; saving an empty value clears it (the row's tag disappears after `loadSources`); local rows' dialogs never show the field
+- [ ] a stored git row with a branch shows the `branch: <name>` text tag (visible, text-based, in the source cell)
+- [ ] the 360 px case renders (the form + dialog don't overflow — verified in the E2E's viewport assertions where applicable)
+- [ ] no console errors on the view (the E2E pins it)

.agents/phases/complete/135_git_source_branch/05_e2e_git_source_branch.md

@@ -0,0 +1,44 @@
+# Task 05 — E2E: `tests/e2e/test_git_source_branch.py` (the dedicated Playwright suite, run in isolation)
+
+**Phase:** `135_git_source_branch` · **Source:** `TODO.md:4` — "Need to be able to specify the branch for a git source"
+
+## Objective
+The branch feature is pinned end to end against the REAL pipeline: a two-branch `file://` fixture repo, the owner adding a source WITH a branch through the UI (→ sync → the branch's content is indexed, not the default branch's), the row tag, the per-row editor's branch field (change + the fail-loud mismatch), and the API contracts (the tri-state, the fixed 422s, the local-row rejection).
+
+## Work
+1. `tests/e2e/test_git_source_branch.py` (new) — the per-module app pattern (`test_git_sources_admin.py` + `test_sync_button.py` combined):
+   - **Ports/env:** `APP_PORT = int(os.environ.get("E2E_APP_PORT_GITBR", "8134"))`; the standard module env (`BOR_STATIC_DIR`, the mock LLM base URL, `BOR_RELEVANCE_THRESHOLD=0.30`, `BOR_ADMIN_PASSWORD` / `BOR_SESSION_SECRET`, a dedicated `BOR_SOURCES_DIR`). **No `BOR_GIT_SOURCES` env** — the sources under test are DB rows (the UI adds them), so the env fallback stays empty.
+   - **The fixture repo** (module-scoped, `tmp_path_factory`, real `git`): two branches — `main` (file `notes/main-only.md` with `Marker: RESE-BRANCH-MAIN-7a31`) and `release` (file `notes/release-only.md` with `Marker: RESE-BRANCH-REL-9c2d`, plus a shared `notes/common.md` whose content DIFFERS between the branches — `main` says `VERSION: 1`, `release` says `VERSION: 2`). Both branches pushed to the repo (a local bare-ish fixture: the test builds `main`, commits, then `git checkout -b release`, edits, commits — a normal two-branch repo; the app clones it via `file://`).
+   - **Helpers:** `add_git_source(page, url, branch=None, token=None)` (fills the UI form — the branch field when given), `sync_and_wait(page, app_url)` (clicks `#sync-btn` and polls the status endpoint to a terminal state — the `_wait_sync_done` pattern), `catalog_has_doc(page, doc_name)` (the drill-down tree assertion, the `_expect_fixture_row` pattern).
+2. Tests:
+   - `test_add_with_branch_syncs_that_branch` — the owner's exact flow:
+     1. login (lands on the git-sources view — the `login` helper's `next` param or a nav click, per the existing suites);
+     2. add a source: url = `file://<fixture>`, branch = `release` → 201; the row appears with the `branch: release` tag (the text is in the source cell);
+     3. switch to the Sources/RAG view, `sync_and_wait` → `state == "success"`;
+     4. the catalog contains `release-only.md` (the branch's doc) AND `common.md` shows `VERSION: 2` (drill in and assert on the document's stored content via the document modal or the `GET /api/docs` row — follow the assertion idiom the dates suite uses for content checks); `main-only.md` is ABSENT (the default branch's doc was never indexed);
+     5. re-sync (idempotent): "0 added · 2 unchanged" (release's two files).
+   - `test_default_branch_source_unaffected` — a SECOND source row for the SAME url is impossible (the unique URL 409) — so this test uses a CLONE of the fixture (a second `file://` repo, identical history, `main` only): add it with NO branch → sync → `main-only.md` present, `release-only.md` absent (the `branch=None` path mirrors the pre-phase behavior — the byte-identical guarantee, observable through the UI).
+   - `test_row_editor_branch_change_fails_loud` — the fail-loud mismatch (ASSUMPTION B5, end to end):
+     1. take the `release` source from test 1's state (or a fresh module state — order the tests so the fixture state is explicit; the KB-truncate autouse fixture keeps them independent: re-add the source fresh);
+     2. open the per-row editor, change the branch field to `main`, save → the dialog closes, the row re-renders with the `branch: main` tag (the PATCH landed — the registry is updated);
+     3. sync → `state == "failed"`; the sanitized error banner/modal shows the fixed mismatch copy (assert on the user-visible fragment `remove and re-add the source` — the message is a fixed string, safe to pin);
+     4. restore: editor → branch field `release` → save → sync → success again (the guard is symmetric — back to the matching branch, the ff path works).
+   - `test_api_branch_contracts` — the API layer through `page.request` (admin cookie):
+     - POST a git source with `branch: "a..b"` → 422, detail EXACTLY `not a valid branch name` (no echo); the list is unchanged;
+     - POST a git source with `branch: "HEAD"` → 422 (same detail);
+     - PATCH the tri-state on a stored row: set `hotfix/x` → 200 reports it; clear with `""` → 200 reports `null`; a PATCH of `{"include_hidden": true}` leaves the branch untouched;
+     - POST a LOCAL source (an existing tmp dir) with `branch: "x"` → 422 `branch is only valid for git sources`;
+     - the token field is unaffected by all of the above (the existing token tests stay green — no regression pin needed here).
+   - Wall-time guard: the whole module < 180 s (three full syncs of a 3-file repo against the mock LLM — the `slow_llm` proxy is NOT needed: the branch assertions are about WHICH files land, not about a running window).
+3. Header docstring: the story (the TODO item, L4), the run command (`uv run pytest tests/e2e/test_git_source_branch.py -v --no-cov`), the isolation note (per-module app, dedicated port, DB rows not env), the fixture's two-branch shape.
+
+## Testing & Quality
+- E2E: this file IS the task's suite; it runs in ISOLATION (`--no-cov`, the AGENTS.md rule 9 gate) with the DB up (`podman compose up -d db`) and git on PATH.
+- Coverage: **>90%** on new/modified code (test-only task — the bar is carried by the suite run).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_git_source_branch.py -v --no-cov` green in isolation
+- [ ] the branch's content is what gets indexed (the sentinel docs on the right branch present, the wrong branch's doc absent — the feature's core promise)
+- [ ] the `branch=None` path imports the default branch exactly as pre-phase (the unaffected-source test)
+- [ ] the mismatch is LOUD (the failed sync names the remove-and-re-add fix — the owner is never left with a silently-wrong checkout)
+- [ ] every 422 detail is the fixed string (the test asserts on the exact detail, not a substring of the input)

.agents/phases/complete/136_force_push_reset/00_phase.md

@@ -0,0 +1,39 @@
+# Phase 136 — A force push no longer breaks the sync: the checkout resets to the head of the tracked branch
+
+**Source:** `TODO.md` L5 — "Force pushes break brain of reese git pull. Brain of reese should always have the head of the branch specified, so if pull fails due to force pushes it should just reset origin/<branch>"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `scripts/git_sync.py::clone_or_pull` — today's existing-checkout path: the shallow probe + one-time `git fetch --unshallow` self-heal (phase 107 D11), then `git pull --ff-only` — a force push is a NON-fast-forward, so `--ff-only` refuses → `GitSyncError` → the whole sync lands `failed` (the owner's reported break; this is the bug). Phase 135 (the immediately preceding todo phase) lands the `branch` parameter: for a branched row the sequence is already `git fetch origin <b>` + `git merge --ff-only FETCH_HEAD` behind the HEAD guard; for a `NULL`-branch row it is still the legacy `git pull --ff-only`. `run_git` is the A11 single git invocation site; the two call sites (`app/api/sync.py::_run_sync`, `scripts/import_docs.py::_resolve_sources`) are untouched in shape — `clone_or_pull`'s signature is theirs to satisfy; `file_commit_dates` walks the post-update checkout (a reset checkout yields the NEW head's per-file dates — exactly the head-of-branch semantics the owner asked for). The sync's failure path (`_run_sync`'s `except Exception` → the `failed` state + the sanitized error) is what a force push hits today — after this phase it no longer does.
+
+## Objective
+A force push (or any divergent remote head) never fails the sync: the existing-checkout update tries the fast-forward and, when that is impossible, **resets the checkout to the remote head of the tracked ref** — for a branched row `origin/<branch>` (the owner's verbatim "reset origin/<branch>"), for a `NULL`-branch row the head of the branch the checkout is on — with one loud log line. The checkout is a cache of the remote head (the app owns it, the KB is rebuilt from it on the same run), so "always the head of the branch" is the invariant this phase enforces.
+
+## Dependencies
+- `135_git_source_branch` (todo) — the `branch` parameter of `clone_or_pull` (the reset's target ref for branched rows) and the phase-135 HEAD guard, which stays in front of the update sequence.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The existing-checkout update sequence** (replaces BOTH today's `git pull --ff-only` path and phase 135's branch path — one unified sequence):
+  1. ref resolution: `branch` given → `ref = branch` (the HEAD guard from phase 135 runs FIRST, unchanged: checkout on a different branch → the remove-and-re-add `GitSyncError`); `branch` None → `ref = git rev-parse --abbrev-ref HEAD` (the checkout's own branch — the pre-phase default-branch behavior; if the result is `"HEAD"` (detached) → `GitSyncError` naming the checkout: the app never CREATES a detached checkout — a fresh clone always lands on a branch — so this is a genuinely broken checkout and fails loud per D12, not a force-push case).
+  2. the shallow probe + one-time `git fetch --unshallow` self-heal (UNCHANGED — phase 107 D11).
+  3. `git fetch origin <ref>` — a fetch FAILURE (network/auth, the branch gone from the remote, git missing) STILL raises `GitSyncError` (a loud failure — a force push is NOT a fetch failure; the owner's "if pull fails due to force pushes" scopes the reset to the merge step only).
+  4. try `git merge --ff-only FETCH_HEAD`.
+  5. **on merge failure — the reset fallback (this phase, ASSUMPTION C1):** capture `old = git rev-parse HEAD` and `new = git rev-parse FETCH_HEAD`, run `git reset --hard FETCH_HEAD`, log one WARNING line (PLAN §9): `git sync: divergent remote head on <dest> (force push) — reset <old[:7]> → <new[:7]> to origin/<ref>`, and RETURN the dest normally (the sync proceeds — a force push never fails a run). The merge's stderr is included in the log (diagnosability) but never in a user-facing error (there is no error — the run continues).
+- **Unchanged:** the fresh-clone path (with and without `--branch`); the `run_git` discipline; the two call sites; `file_commit_dates`; the sync's status/progress surface. The `branch=None` argv CHANGES by design (the legacy `git pull --ff-only` becomes the explicit fetch + ff-or-reset sequence — that IS the fix, and it applies to every row, branched or not).
+- **ASSUMPTION C2 — the dirty checkout:** the checkout is app-managed (a cache of the remote head; the KB is rebuilt from it by the same run's import), so local modifications are not expected and are not defended against: the `reset --hard` discards any by definition. No `git status` precheck (one fewer git call per source per sync; the house minimal-invocation discipline) — a dirty checkout simply resets, which is the desired end state either way.
+
+## Tasks
+1. `01_ff_or_reset.md` — the unified update sequence in `clone_or_pull` (ff-or-reset, the detached-HEAD fail-loud, the loud log) + the unit/integration matrix.
+2. `02_e2e_force_push_resync.md` — the dedicated Playwright E2E (a real force push of the fixture repo between two UI sync runs — the pre-phase behavior, a failed sync, is the regression pin).
+
+## Testing & Quality
+- Unit: the mocked-`subprocess` argv matrix in `tests/unit/test_git_sync.py` (ff success — no reset argv; ff failure — the rev-parse pair + `reset --hard FETCH_HEAD` + return, no raise; fetch failure — still raises; detached `NULL`-branch — raises; the phase-135 mismatch guard still fires before the update sequence).
+- Integration: real-`git` `file://` scenarios in `tests/integration/test_import_docs_git.py` (normal ff; a force push — the origin's history rewritten; an UNRELATED-history force push — different root commit; a branched row's force push — the reset targets `origin/<branch>`; `file_commit_dates` on the post-reset checkout reflects the new head).
+- E2E: one dedicated Playwright file, run in isolation (the owner's exact reproduction: sync → force push the origin → sync again → success + the new head's content).
+- Coverage: **>90%** on new/modified code (`app/` — the change lives in `scripts/`, exercised through the `app/` sync pipeline tests; the coverage bar is carried by the suite run).
+
+## Completion Criteria
+- [ ] a force push of a source's branch no longer fails the sync — the next sync succeeds and the checkout (and therefore the KB) holds the NEW head (pinned by the integration + E2E)
+- [ ] an unrelated-history force push (a rewritten root) is handled by the same reset (the E2E or integration covers it — pick the integration, the E2E stays on the owner's exact repro)
+- [ ] a genuinely broken fetch (git missing / unreachable origin / branch deleted upstream) STILL fails loud (the `GitSyncError` pins are green — the reset is scoped to the merge step only)
+- [ ] the WARNING log line lands on a reset (one line, the SHAs, the checkout path, `origin/<ref>` — no URL in it)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_force_push_resync.py -v --no-cov` green in isolation
+- [ ] the phase-135 behavior is preserved (the `--branch` clone, the mismatch guard, the `branch=None` fresh-clone argv — the pins from phase 135 stay green)

.agents/phases/complete/136_force_push_reset/01_ff_or_reset.md

@@ -0,0 +1,71 @@
+# Task 01 — `clone_or_pull`: ff-or-reset (the force push no longer fails the sync)
+
+**Phase:** `136_force_push_reset` · **Source:** `TODO.md:5` — "Force pushes break brain of reese git pull. Brain of reese should always have the head of the branch specified, so if pull fails due to force pushes it should just reset origin/<branch>"
+
+## Objective
+The existing-checkout update becomes: fetch the tracked ref → try the fast-forward → on a non-ff failure, reset the checkout hard to that ref's head and continue — with one loud WARNING line. A force push is now a logged, self-healing event, never a failed sync; genuinely broken fetches still fail loud.
+
+## Work
+1. `scripts/git_sync.py::clone_or_pull` — replace the existing-checkout tail (today: probe → unshallow-if-shallow → `git pull --ff-only`; phase 135's branch tail: HEAD guard → probe → unshallow-if-shallow → `fetch origin <b>` → `merge --ff-only FETCH_HEAD`) with the unified sequence from the phase overview:
+   ```python
+   # existing checkout (the fresh-clone path above is untouched):
+   if branch is not None:
+       # phase-135 HEAD guard, UNCHANGED (runs first, before any update):
+       current = run_git(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=dest).strip()
+       if current != branch:
+           raise GitSyncError(
+               f"checkout {dest} is on branch '{current}' but the source specifies "
+               f"branch '{branch}' — remove and re-add the source to switch branches"
+           )
+       ref = branch
+   else:
+       ref = run_git(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=dest).strip()
+       if ref == "HEAD":  # detached — the app never creates one (D12 fail-loud)
+           raise GitSyncError(
+               f"checkout {dest} is in a detached-HEAD state — remove and re-add the "
+               f"source to rebuild it"
+           )
+   shallow = run_git(["git", "rev-parse", "--is-shallow-repository"], cwd=dest).strip() == "true"
+   if shallow:
+       run_git(["git", "fetch", "--unshallow"], cwd=dest)
+   run_git(["git", "fetch", "origin", ref], cwd=dest)  # fetch failure STILL raises
+   try:
+       run_git(["git", "merge", "--ff-only", "FETCH_HEAD"], cwd=dest)
+   except GitSyncError as ff:
+       old = run_git(["git", "rev-parse", "HEAD"], cwd=dest).strip()
+       new = run_git(["git", "rev-parse", "FETCH_HEAD"], cwd=dest).strip()
+       run_git(["git", "reset", "--hard", "FETCH_HEAD"], cwd=dest)
+       logger.warning(
+           "git sync: divergent remote head on %s (force push) — reset %s → %s to "
+           "origin/%s (%s)", dest, old[:7], new[:7], ref, ff,
+       )
+   return dest
+   ```
+   Notes: the `branch=None` path deliberately LOSES the legacy `git pull --ff-only` (that is the fix — every row gets the ff-or-reset update); the `dest` in the log is the checkout path (NEVER the URL — credential-safety, the phase-121 discipline); the merge stderr rides the log only (the run continues — there is no user-facing error). Update the module + function docstrings (the D11/D12 paragraphs gain the phase-136 force-push contract: "a non-ff merge resets to the ref's head instead of failing — the checkout is a cache of the remote head").
+2. Unit tests — `tests/unit/test_git_sync.py` (extend — the mocked-`subprocess` argv pattern; the mock needs per-argv responses: `rev-parse --abbrev-ref HEAD` → the branch, `rev-parse --is-shallow-repository` → `false`, the ff merge → non-zero on the failure case, the `rev-parse HEAD` / `FETCH_HEAD` → SHAs, the reset → zero):
+   - `branch=None`, ff SUCCESS: argv sequence `rev-parse --abbrev-ref HEAD` → `rev-parse --is-shallow-repository` → `fetch origin <branch-from-HEAD>` → `merge --ff-only FETCH_HEAD` — and NO `reset` argv, NO `rev-parse HEAD/FETCH_HEAD` pair (the capture is only on failure).
+   - `branch=None`, ff FAILURE (merge exit ≠ 0): the sequence gains `rev-parse HEAD` → `rev-parse FETCH_HEAD` → `reset --hard FETCH_HEAD` — and the function RETURNS the dest (no raise).
+   - `branch="release"` (matching HEAD), ff failure: same reset tail, `fetch origin release` — the reset targets the branch's ref (the owner's verbatim "reset origin/<branch>").
+   - the phase-135 mismatch (`branch="release"`, HEAD `main`): STILL raises before any fetch (the guard is first — the phase-135 pin stays green).
+   - `branch=None` + detached HEAD (`rev-parse --abbrev-ref HEAD` → `"HEAD"`): raises the detached `GitSyncError` (no fetch, no reset).
+   - fetch FAILURE (non-zero): raises `GitSyncError` (NOT the reset path — the reset is scoped to the merge step; a deleted upstream branch / dead network still fails loud).
+   - the shallow self-heal still fires in front of the fetch (the `--unshallow` argv pin, unchanged).
+3. Integration tests — `tests/integration/test_import_docs_git.py` (extend — the real-`git` `file://` pattern):
+   - **Normal ff:** a fixture repo, `clone_or_pull` ×2 with a normal second commit → ff-merged, no reset (assert via `git -C dest log` — the second commit's message is the HEAD, no merge commit).
+   - **Force push (the owner's repro):** after the first clone, rewrite the origin's history (a NEW root commit — `git checkout --orphan` or `git reset --soft` + a fresh commit with different content — the origin's branch now diverges); `clone_or_pull` again → NO exception, the checkout's HEAD == the origin's new head (`git -C origin rev-parse <ref>` == `git -C dest rev-parse HEAD`), the working tree holds the NEW content.
+   - **Unrelated-history force push:** the rewritten origin has a DIFFERENT root commit (a fully unrelated tree) → the same reset path handles it (the ff merge of an unrelated history is exactly what `--ff-only` refuses).
+   - **Branched force push:** a two-branch fixture (the phase-135 shape), a row-shaped call `clone_or_pull(url, dest, "release")` after a force push of ONLY `release` → the reset lands `origin/release`'s head and `main`'s content is not involved.
+   - **`file_commit_dates` after a reset:** the dates map reflects the NEW head (the new root commit's date is what the walk returns for its files — the head-of-branch dates the owner asked for).
+   - **The sync pipeline end-to-end (the seam `tests/integration/test_sync_api.py` already exercises):** a forced-push fixture + a sync → `state == "success"` (the pre-phase code lands `failed` — this test is the regression pin at the API seam; if the file's existing fixtures make the seam awkward, the E2E, task 02, carries the API-seam pin and this step stays at the `clone_or_pull` level — document the choice in the test's docstring).
+
+## Testing & Quality
+- Unit: the argv matrix (step 2) — the ff-success pin (no reset argv) and the fetch-failure pin (still raises) are the two regression gates.
+- Integration: the real-git matrix (step 3).
+- Coverage: **>90%** on new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_git_sync.py tests/integration/test_import_docs_git.py -v` green
+- [ ] a force push (normal divergence AND unrelated history) resets instead of failing — pinned by real-git integration tests
+- [ ] the phase-135 pins (the mismatch guard, the `--branch` clone argv, the `branch=None` fresh-clone argv) stay green untouched
+- [ ] the WARNING line is the ONLY observable side effect of a reset besides the checkout state (no user-facing error, no status change — the run continues)
+- [ ] `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/136_force_push_reset/02_e2e_force_push_resync.md

@@ -0,0 +1,42 @@
+# Task 02 — E2E: `tests/e2e/test_force_push_resync.py` (the dedicated Playwright suite, run in isolation)
+
+**Phase:** `136_force_push_reset` · **Source:** `TODO.md:5` — "Force pushes break brain of reese git pull. Brain of reese should always have the head of the branch specified, so if pull fails due to force pushes it should just reset origin/<branch>"
+
+## Objective
+The owner's exact reproduction is pinned end to end: sync (clone + import) → force-push the origin (its history rewritten) → sync again → SUCCESS, and the KB holds the NEW head's content. Pre-phase, that second sync landed `failed` — this test is the regression pin for the fix.
+
+## Work
+1. `tests/e2e/test_force_push_resync.py` (new) — the `test_sync_button.py` module-app pattern:
+   - **Ports/env:** `APP_PORT = int(os.environ.get("E2E_APP_PORT_FPPUSH", "8135"))`; the standard module env (`BOR_STATIC_DIR`, the mock LLM, `BOR_RELEVANCE_THRESHOLD=0.30`, the admin/session secrets, `BOR_GIT_SOURCES=file://<fixture repo>`, a dedicated `BOR_SOURCES_DIR`).
+   - **The fixture repo** (module-scoped, `tmp_path_factory`, real `git` — the `sync_git_repo` pattern): `notes/doc.md` with `Marker: RESE-FPPUSH-V1-5e8a`, one commit, one branch.
+   - **The force-push helper:**
+     ```python
+     def _force_push_new_head(repo: Path, content: str) -> None:
+         """Rewrite the origin's history to a NEW root commit (a full
+         divergence — not just a new commit on top): delete the branch
+         ref and recreate it at a new orphan commit with `content`."""
+     ```
+     (Implementation at execution time: `git checkout --orphan newroot` → replace `notes/doc.md`'s content → commit → `git branch -M <branch>` / `git push --force` is not applicable to a local fixture — the test rewrites the repo IN PLACE: `git update-ref -d <branch>`, commit on the orphan, `git update-ref <branch> HEAD`. The app's next `git fetch` sees the divergent head. The exact ref mechanics are the executor's call — the OBSERVABLE contract is: the origin's single branch now points at a commit with UNRELATED history and the new content.)
+   - **`_wait_sync_state`** — the `test_sync_button._wait_sync_done` pattern (terminal `{"success", "failed"}`), plus a UI-level settle wait on `#sync-label`.
+2. Tests:
+   - `test_sync_survives_a_force_push` — the owner's exact flow:
+     1. login (lands on `/sources.html` — the button's home);
+     2. **run 1:** click `#sync-btn` → "Syncing…" → "Synced HH:MM" + "1 added"; the catalog shows `doc.md` (the drill-down assertion, the `_expect_fixture_row` pattern);
+     3. **the force push** (server-side, via the fixture helper — the test owns the origin repo): `_force_push_new_head(repo, "Marker: RESE-FPPUSH-V2-2b7f …")`;
+     4. **run 2:** click `#sync-btn` again → the status endpoint reaches `state == "success"` (NOT `failed` — the pre-phase regression: the `--ff-only` pull refused the divergent head and the run died) within the timeout; the UI settles to "Synced HH:MM" (the error banner is HIDDEN, no error modal);
+     5. **the KB holds the NEW head:** the document modal / `GET /api/docs` content for `notes/doc.md` contains `RESE-FPPUSH-V2-2b7f` (the reset's content flowed through the import — the digest delta re-indexed the file as `updated`; `#sync-result` shows "1 updated" or "0 added · 1 updated" — assert on the content, the counts are the secondary signal);
+     6. **run 3 (idempotent):** "0 added · 1 unchanged" (the checkout is stably at the new head — the reset was not a one-off fluke).
+   - `test_failed_pull_is_not_the_outcome` (the negative pin, cheap while the fixture exists): assert on the APP LOG or skip if the seam is awkward — PREFERRED: a direct API-level assertion instead — after the force push, `POST /api/sync` + poll → `state == "success"` (the same contract as run 2 without the UI; keeps the UI test focused). If the module app's fixture state makes two full UI+API passes heavy, fold it into the main test as step 4b (the API trigger of run 2) — document the choice in the docstring.
+   - Wall-time guard: the whole module < 120 s (three small syncs against the mock LLM — no `slow_llm` proxy needed: the point is the TERMINAL state, not a running window).
+3. Header docstring: the story (the TODO item, L5 — the owner's verbatim repro), the run command (`uv run pytest tests/e2e/test_force_push_resync.py -v --no-cov`), the isolation note (per-module app, dedicated port), and the pre-phase behavior it pins against (run 2 used to land `failed` — the test fails on the pre-phase code, which is the point).
+
+## Testing & Quality
+- E2E: this file IS the task's suite; it runs in ISOLATION (`--no-cov`, the AGENTS.md rule 9 gate) with the DB up (`podman compose up -d db`) and git on PATH.
+- Coverage: **>90%** on new/modified code (test-only task — the bar is carried by the suite run).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_force_push_resync.py -v --no-cov` green in isolation
+- [ ] the test FAILS on the pre-phase code (run 2 lands `failed` — verified by temporarily reverting the `clone_or_pull` change in a scratch branch, then restoring — the pin has teeth)
+- [ ] the NEW head's content is what the KB serves (the sentinel V2 in the document — the reset's observable end-to-end effect)
+- [ ] the third run is idempotent (the checkout is stably at the new head — no drift, no second reset)
+- [ ] no error banner / modal on a force-push resync (a reset is a logged event, not a user-facing failure)

.agents/phases/complete/137_pdf_image_context/00_phase.md

@@ -0,0 +1,48 @@
+# Phase 137 — PDF-embedded images always carry the document context in their summary
+
+**Source:** `TODO.md` L3 — "Images extracted from PDFs still don't have any relevant context in their summaries provided by the PDF. They're still just getting summarized 'as-is'. … Image summaries should always include the document context if the images come from a document (this includes markdown files) so the embedder can more effectively retrieve image sources."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/rag/pdf.py` (phase 126 — `extract_pdf_text` (L87, per-page `get_text("text")` with `---PAGE-N---` separators, fail-soft `""`), `extract_pdf_images` (L145, one `PdfImage` per occurrence: `page` 1-indexed, `index` 0-based, `data`, `mime`)); `app/rag/importer.py` — `_index_pdf_embedded_images` (L1091, the per-PDF embedded-image pass after its document commit), `_index_one_embedded_image` (L1182, the phase-122 pipeline inline: mime gate → synthetic path `<pdf>#page=N#img=I.<ext>` → byte-digest skip → `_markdown_image_context` (L1403, the phase-125 reference scan) → `_describe_or_skip` (L1742, the single describe seam) → copy write → chunk + embed → `_store_summary`), `_markdown_image_context` (L1403) + `_md_ref_block` (L1436, the `Referenced in <source>/<md>:` block writer), `_enrich_pending_images` (L1627, the phase-125 task-04 post-index pass — the shape of the new backfill pass), `ImportSummary` (L212, stats counters + `log()` — stats are log-only, the sync `detail` API shape never changes); `app/rag/summarizer.py` — `describe_image` (L208, ONE chat-model vision call, `context` appended after the locked `DESCRIBE_PROMPT` as a `\n\nThis image is referenced in documentation with the following context:\n` prefix — the wording phase 137 generalizes), `DESCRIBE_PROMPT` / `IMAGE_DESCRIPTION_MODE` (L78/L57 — the mock's key; byte-identity criteria below); `app/rag/prompts.py` — `_extract_context_line` (L470, renders only `Referenced in …:` blocks, everything else degrades to `None`), `_image_context_line` (L536), `_document_body` (L548, the phase-125 context-line lead); `app/models.py` — `Document.image_context` (L170, TEXT nullable, migration 0023); `tests/e2e/mock_llm.py` — the `IMAGE_DESCRIPTION_MODE` canned vision reply (L2472 branch, `IMAGE_DESCRIPTION_ANSWER` L865) and the phase-125 `CONTEXT_LINE_TRIGGER` pattern (the model for this phase's mock trigger); `tests/e2e/test_pdf_support.py` (the synthetic PDF fixture recipe: PyMuPDF build, `page2.insert_image(…, stream=PNG_1X1)`, images-on/off module apps); `test_sources/players_handbook.pdf` (293 pages, 586 embedded images — the real multi-page fixture), `test_sources/hnb_2026_guide.tar.gz` (the owner's example — stock-photo descriptions with no document context).
+
+## Objective
+Every image that comes from a document carries the document context in the text that gets embedded: the vision prompt for a PDF-embedded image includes WHERE it came from (source + PDF path + page) and the surrounding page text, so the model writes a description that names the document and what the image illustrates; the context is stored on `image_context` (idempotent, re-scanned on re-index) and rendered as a short locator line in the chat suggestion block; and every image document already in the KB is backfilled on the next sync. Markdown-referenced images (phase 125) keep working byte-for-byte; PDFs are the only importable format that embeds images, so this closes the TODO's gap completely.
+
+## Dependencies
+- `136_force_push_reset` (todo) — pipeline order only.
+- Code: the completed phase-126 PDF pipeline + the phase-122 vision seam + the phase-125 context machinery (all on `main`); and pending `133_pdf_screenshot_fallback` — its `is_usable_pdf_text` gate (task 02 of that phase) runs BEFORE this phase in the pipeline and is reused to suppress garbage page text in the context (ASSUMPTION A7).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The context block (task 02, ASSUMPTIONS A2/A3):** one block per embedded image, built from the PDF's own text —
+  ```
+  Extracted from <source>/<pdf path> (page <N>):
+  <page text, stripped, capped at PDF_IMAGE_CONTEXT_MAX_CHARS = 6000>
+  ```
+  The origin line is ALWAYS present (even when the page has no text — the owner's core complaint is "no mention of the document it came from"); the page-text line is omitted for a text-less page. If phase 133's gate exists (`app.rag.pdf.is_usable_pdf_text`) and says the PDF's text layer is unusable, the page text is dropped (origin line only — ASSUMPTION A7). When the image ALSO has phase-125 markdown reference blocks, the stored/passed context is the document block FIRST, then the markdown blocks (provenance → purpose — ASSUMPTION A2); the combining helper is one shared function used by the forward path AND the backfill (task 03) so the two can never drift.
+- **The seam (task 02, ASSUMPTION A5):** `describe_image`'s `context` prefix wording generalizes from "This image is referenced in documentation with the following context:" to neutral text that covers both provenance and reference (e.g. "This image is part of a document. The following context describes where it comes from and what it is used for:"). `DESCRIBE_PROMPT` (marker + locked instruction) stays byte-identical; `context=None` (standalone image) sends the bare prompt — byte-identical to today, so the phase-122 standalone path and every pre-existing E2E stay green.
+- **The forward path (task 02):** `_index_pdf_embedded_images` calls the new `extract_pdf_page_texts` ONCE per PDF (a `dict[int, str]` page → stripped text — task 01) and passes it to `_index_one_embedded_image`, which builds the combined context, passes it as `context` to `_describe_or_skip`, and stores the SAME value on `image_context` (the phase-125 task-03 rule: context follows the current source state on re-index — a re-indexed image re-scans; the digest-skip for unchanged images is UNCHANGED: an unchanged image keeps its (now context-carrying) content).
+- **The backfill (task 03, ASSUMPTION A4):** a post-index pass in `import_sources` next to `_enrich_pending_images` — the phase-118 A2 "best-effort until it sticks" shape. Candidates: `is_image=True` docs whose `path` matches the embedded-image pattern (`*.pdf#page=<N>#img=<I>.<ext>`) AND whose `image_context` does NOT start with `Extracted from ` (NULL or markdown-only) AND whose `image_path` copy still exists on disk. Per candidate: bytes from the copy, page text re-extracted from the parent PDF if it is still in the source (parent gone → origin line only, parsed from the doc's own synthetic path — no disk dependency), re-describe through the SAME seam, re-chunk + re-embed (`_replace_content_chunks`, one transaction per image), store the combined context. Idempotent by the stored-context gate: a success writes a context starting with `Extracted from ` → the doc never qualifies again. Fail-soft per image (a `None` description leaves the row untouched, counts `images_failed`, sync continues). New `ImportSummary.image_context_backfilled: int = 0` counter + `log()` field ONLY (the stats log-only convention — the sync `detail` API shape is untouched). One loud log line per backfilled image (PLAN §9).
+- **The display line (task 04, ASSUMPTION A6):** `_extract_context_line` learns the `Extracted from <source>/<pdf path> (page <N>):` header (regex; the page-text body is NEVER rendered — same rule as the `Context:` body) and renders it as `From <source>/<pdf path> (page <N>)`. A value carrying BOTH block kinds renders the clauses in stored order (`From …; Referenced in …`). A value with no parsable block degrades to `None` exactly as today (pre-phase rows, markdown `IMAGE_CONTEXT:` records on text docs — the `is_image` guard already excludes those).
+- **The E2E (task 05):** the mock gains ONE new trigger, following the phase-125 `CONTEXT_LINE_TRIGGER` pattern exactly: when the `IMAGE_DESCRIPTION_MODE` message's text part contains `Extracted from ` (the new provenance header), the canned reply becomes a context-aware description (fixed string, e.g. naming the document + page) instead of `IMAGE_DESCRIPTION_ANSWER` — the deterministic observable that the context REACHED the vision model. The suite uploads a synthetic PDF (text on page 1, one embedded PNG on page 2 — the `test_pdf_support.py` recipe) through the images-on module app, syncs, and asserts: the image doc's content/summary is the context-aware canned reply; its `image_context` starts with `Extracted from <source>/report.pdf (page 2)`; a chat question that retrieves the image shows the `From <source>/report.pdf (page 2)` line in the suggestion. A markdown-referencing case (a `.md` in the same archive referencing the synthetic path) asserts BOTH blocks, document first.
+
+## Tasks
+1. `01_pdf_page_texts.md` — `extract_pdf_page_texts` in `app/rag/pdf.py` (the shared per-page iteration, fail-soft) + unit tests on the real fixture PDFs.
+2. `02_embedded_image_document_context.md` — the document-context block builder + the forward path (build once per PDF, combine with markdown blocks, pass through the seam, store on `image_context`) + the generalized seam prefix + unit tests with a capturing fake LLM.
+3. `03_backfill_image_context.md` — the per-sync idempotent backfill pass + the `image_context_backfilled` counter + integration tests (existing row backfilled, idempotent no-op, parent-gone origin-only, standalone never touched).
+4. `04_retrieval_display_line.md` — `_extract_context_line` renders the `Extracted from` block as the one-line `From … (page N)` locator + unit tests (both-blocks ordering, degradation, pre-phase byte-identity).
+5. `05_e2e_pdf_image_context.md` — the mock's `Extracted from` trigger + the dedicated Playwright suite `tests/e2e/test_pdf_image_context.py`, run in isolation.
+
+## Testing & Quality
+- Unit: task 01 — `extract_pdf_page_texts` on `test_sources/players_handbook.pdf` (293 pages, spot-check known page text, page count, 1-indexed keys) and `pdf_horse_test.pdf`; an unreadable path → `{}` (fail-soft); `extract_pdf_text` output byte-identical after the shared-iteration refactor (the phase-126 regression pin). Task 02 — the block builder (page text capped at 6000, text-less page → origin line only, garbage gate drops the page text when 133's gate exists); the combining order (document first, markdown second; markdown-only and document-only cases); the seam message (context present → neutral prefix + combined text AFTER the byte-identical `DESCRIBE_PROMPT`; context=None → byte-identical pre-137 message); the forward path via a capturing fake LLM (the stored `image_context` == the context passed; the title/unchanged-skip rules untouched). Task 04 — the renderer (`Extracted from` alone, both blocks in stored order, unparseable → `None`, the `is_image` guard). Task 05 — the mock trigger (context-aware reply only when `Extracted from ` is in the text part; the bare `IMAGE_DESCRIPTION_ANSWER` otherwise — the phase-122/126 suites stay green without edits).
+- Integration: task 03 — a seeded PDF-embedded image row without context is backfilled through the real `import_sources` (the fake LLM records the context-bearing describe call; content/chunks/`image_context` updated); a second sync is a NO-OP (zero describe calls — the idempotency gate); a row whose parent PDF was deleted from the source gets the origin-line-only context; a standalone image (no `#page=`) is NEVER touched; a markdown-enriched row (context `Referenced in …`) gets the combined context (document block prepended).
+- E2E: one dedicated Playwright file, run in isolation (AGENTS.md §4/§9), mock-only.
+- Coverage: **>90%** on `app/` (`uv run pytest --cov=app --cov-report=term-missing`).
+
+## Completion Criteria
+- [ ] a (re)indexed PDF's embedded images are described with the document context: the vision message carries `Extracted from <source>/<pdf> (page N):` + the capped page text (the unit/integration proofs above), and the stored `image_context`/summary carry it too
+- [ ] a markdown-referenced PDF image carries BOTH blocks, document first — and a standalone image's describe message is byte-identical to pre-phase (the phase-122 regression pin)
+- [ ] an existing context-free image doc (e.g. one of the HNB-guide stock photos) is re-described WITH context on the next sync, and the following sync burns zero vision calls for it (the idempotency test)
+- [ ] the chat suggestion block for a backfilled/forward image leads with `From <source>/<pdf> (page N)`
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_pdf_image_context.py -v --no-cov` green in isolation; the pre-existing `test_pdf_support.py`, `test_image_anchor_context.py`, `test_image_documents.py` suites stay green UNEDITED
+- [ ] no behavior change in completed phases (the phase-122 standalone path, the phase-125 markdown enrichment, the phase-126 PDF text path, the sync API shape)
+- [ ] `uv run ruff check . && uv run pyright` green
+- [ ] one atomic Conventional Commits commit for the phase (`feat(rag): …`), `--no-gpg-sign`

.agents/phases/complete/137_pdf_image_context/01_pdf_page_texts.md

@@ -0,0 +1,32 @@
+# Task 01 — `extract_pdf_page_texts`: per-page text map for image context
+
+**Source:** `TODO.md` L3 — "Image summaries should always include the document context if the images come from a document … so the embedder can more effectively retrieve image sources." (This task builds the per-page text source the context block is made from; the item itself is implemented across tasks 01–05.)
+
+## Objective
+`app/rag/pdf.py` gains `extract_pdf_page_texts(pdf_path: Path) -> dict[int, str]` — one entry per page that has text, key = 1-indexed page number, value = the page's stripped text (the same `page.get_text("text")` read `extract_pdf_text` uses). Pages without text contribute nothing (no key). This is the raw material task 02 feeds the vision prompt: for one embedded image on page N, the document context is page N's text. The existing `extract_pdf_text` output stays **byte-identical** (the phase-126 contract — the `---PAGE-N---` blocks, blank-line join, fail-soft `""`).
+
+## Work
+1. Read `app/rag/pdf.py` in full (phase 126). Note `extract_pdf_text` (L87): open → per-page `get_text("text")` → strip → skip empties → `PAGE_SEPARATOR` prefix → `"\n\n"` join; fail-soft per page and per file.
+2. Refactor the shared page iteration into one private helper, e.g. `_iter_page_texts(doc) -> Iterator[tuple[int, str]]` yielding `(page_1_indexed, stripped_text)` for pages with non-empty text (the per-page try/except + warning logging moves into the helper, unchanged in behavior). `extract_pdf_text` becomes: open (fail-soft `""`) → consume the helper → build the separator-joined string. Its signature, output bytes, and log lines are UNCHANGED.
+3. Add the public function:
+   ```python
+   def extract_pdf_page_texts(pdf_path: Path) -> dict[int, str]:
+       """One entry per page of *pdf_path* that has text (1-indexed page → stripped text). …"""
+   ```
+   Same open/fail-soft contract as `extract_pdf_text` (unreadable file → `{}`, one warning — the `pdf:` logger prefix house style).
+4. Update the module docstring's function list (the file documents every public function at the top).
+5. Unit tests in `tests/unit/test_pdf.py` (the file that owns `app/rag/pdf` — extend it):
+   - `test_sources/players_handbook.pdf` (293 pages): 293 or fewer entries, keys 1-indexed, first key `1`, every value non-empty and stripped; spot-check one page's text equals the corresponding `extract_pdf_text` block body (parse a `---PAGE-N---` block and compare — the two functions must agree page-for-page).
+   - `test_sources/pdf_horse_test.pdf`: 1 page → exactly one entry (or `{}` if that page is text-less — assert against `extract_pdf_text`'s output for the same file, whatever it is).
+   - A missing path → `{}` (fail-soft, no raise).
+   - **Regression pin:** `extract_pdf_text` on both fixture files is byte-identical before/after the refactor (capture the current output NOW, in the test, by asserting the separator structure + a known substring from page 1 — do not hardcode a 300-page string).
+6. Run the phase-126 pdf unit tests + `uv run ruff check . && uv run pyright` — green before moving on.
+
+## Testing & Quality
+- The tests above ARE the task's tests; all in the existing `app/rag/pdf` unit-test file (no new file unless the house layout says otherwise — check `tests/unit/` first).
+- Coverage: `app/rag/pdf.py` stays >90% (the helper's per-page failure branch: reuse the existing unreadable-page test pattern if one exists; otherwise a temp file that fitz opens but fails mid-read is not worth fabricating — the existing coverage of that branch via `extract_pdf_text`'s tests carries over since both call sites share the helper).
+
+## Completion Criteria
+- [ ] `extract_pdf_page_texts` exists, is documented, fail-soft, and returns 1-indexed page → stripped text
+- [ ] `extract_pdf_text` output is byte-identical (the regression pin green on both fixture PDFs)
+- [ ] `uv run pytest tests/unit -k pdf -v --no-cov` green; `uv run ruff check . && uv run pyright` green

.agents/phases/complete/137_pdf_image_context/02_embedded_image_document_context.md

@@ -0,0 +1,72 @@
+# Task 02 — The forward path: document context into the vision prompt + `image_context`
+
+**Source:** `TODO.md` L3 — "Images extracted from PDFs still don't have any relevant context in their summaries … there are lots of stock photos in test_sources/hnb_2026_guide.tar.gz and they get summaries like 'A smiling woman with dark curly hair sits holding a grey laptop on her lap...' which has no mention of the document it came from or what it might have been helping to illustrate. … Image summaries should always include the document context if the images come from a document."
+
+## Objective
+When a PDF is (re)indexed, every embedded image's vision call and stored `image_context` carry a document-context block — `Extracted from <source>/<pdf path> (page <N>):` plus the page's text (capped) — combined with any phase-125 markdown reference blocks (document block first). The vision model therefore writes a description that names the document and the page, and the stored `content`/`summary`/`image_context` carry the same context the embedder needs. Standalone images and the phase-125 markdown-only shape are untouched.
+
+## Work
+1. Read, in full: `app/rag/importer.py` — `_index_pdf_embedded_images` (L1091), `_index_one_embedded_image` (L1182), `_markdown_image_context` (L1403), `_md_ref_block` (L1436), `_describe_or_skip` (L1742); `app/rag/summarizer.py` — `describe_image` (L208, esp. the `context_prefix` build near the message construction).
+2. **The block builder** in `app/rag/importer.py` (next to `_markdown_image_context`):
+   ```python
+   PDF_IMAGE_CONTEXT_MAX_CHARS = 6000  # ASSUMPTION A3 — module constant, no env var
+
+   def _pdf_image_context_block(
+       source: str, pdf_rel: str, page: int, page_texts: dict[int, str],
+       text_usable: bool = True,
+   ) -> str:
+       """The document-context block for one embedded image (phase 137, A2).
+
+       Always non-empty: the origin line is present even for a text-less
+       page. The page text is stripped, capped at
+       :data:`PDF_IMAGE_CONTEXT_MAX_CHARS` (overflow cut at the cap,
+       then ``TRUNCATION_MARKER`` on its own line — the summarizer's
+       existing truncation convention), and OMITTED entirely when the
+       page has no text OR when the phase-133 gate (see step 3) marks
+       the PDF's text layer unusable.
+       """
+   ```
+   Shape (exactly):
+   ```
+   Extracted from <source>/<pdf_rel> (page <N>):
+   <page text or — for a text-less page — nothing after the header line>
+   ```
+   `TRUNCATION_MARKER` lives in `app.rag.retriever` (import it there-from, the same way `app/rag/summarizer.py` does — L49).
+   (header line `Extracted from {source}/{pdf_rel} (page {page}):` — `page` is the 1-indexed page number (the forward path passes `img.page`; the task-03 backfill passes the page parsed from the synthetic path — taking a plain `int`, NOT a `PdfImage`, is deliberate so the backfill needs no fake `PdfImage`); NO "of M" total — the total page count is not on `PdfImage` and the origin line must stay a stable single line for the task-04 renderer's regex.)
+3. **The garbage-text guard (ASSUMPTION A7):** the phase-133 gate `is_usable_pdf_text` is added by pending `133_pdf_screenshot_fallback` (runs BEFORE this phase in the pipeline). In `_index_pdf_embedded_images`, import it defensively — module-level `from app.rag.pdf import extract_pdf_images, extract_pdf_page_texts` and, for the gate, `is_usable_pdf_text = getattr(_pdf_module, "is_usable_pdf_text", None)` (a small import-time probe or a try/except ImportError fallback) — and pass a `text_usable: bool` (default `True` when the gate is absent) down to `_index_one_embedded_image` → `_pdf_image_context_block`: `text_usable=False` → the block is the origin line only. Never import the gate unconditionally (the phase must run in isolation if 133 is skipped).
+4. **`_index_pdf_embedded_images`:** after the `settings.images` gate, call `extract_pdf_page_texts(full_path)` ONCE (task 01's function) and pass the resulting `page_texts` + `text_usable` to `_index_one_embedded_image` (add keyword params — the function signature is internal, no other callers: verify with `rg "_index_one_embedded_image"`).
+5. **`_index_one_embedded_image`:** where it currently computes `image_context = _markdown_image_context(...)` (the phase-125 task-03 scan), build the combined context with a NEW shared helper (task 03 reuses it — define it once, near the block builder):
+   ```python
+   def _combine_image_contexts(doc_block: str, md_blocks: str | None) -> str:
+       """Document block first, markdown reference block(s) second (A2).
+
+       ``md_blocks`` is ``None``/empty → the doc block alone; the doc
+       block is ALWAYS present for embedded images (it is the provenance
+       — never empty). Markdown-only values (no doc block) are produced
+       by the standalone path only and never pass through this helper.
+       """
+   ```
+   Set `image_context = _combine_image_contexts(block, md)` — everything downstream is unchanged (the `context=` arg of `_describe_or_skip`, the `content = f"{image_context}\n\n{description}"` enrichment, the row write, `_store_summary`).
+6. **The seam prefix (ASSUMPTION A5):** in `app/rag/summarizer.py`'s `describe_image`, replace the context prefix
+   `"\n\nThis image is referenced in documentation with the following context:\n{context}"`
+   with neutral wording covering both provenance and reference, e.g.
+   `"\n\nThis image is part of a document. The following context describes where it comes from and what it is used for:\n{context}"`.
+   `DESCRIBE_PROMPT` (marker + locked instruction) is UNTOUCHED; `context=None` still yields the bare prompt (byte-identical — assert it). Update `describe_image`'s docstring (`*context*` no longer means "markdown reference context" only — it means "the document/reference context built by the importer") and `_describe_or_skip`'s docstring likewise.
+7. Unit tests (extend the importer's existing image tests — `rg "_markdown_image_context|_index_one_embedded_image" tests/unit`):
+   - **Block builder:** page with text → header + text; text capped at exactly 6000 + `TRUNCATION_MARKER` (build a page of ~7000 chars); text-less page → header line only; `text_usable=False` → header line only even with text present.
+   - **Combining:** doc-only; doc + markdown (doc block first, blank-line join — assert the exact joined string); markdown shape never lost (the `Referenced in …` block byte-identical inside the combined value).
+   - **Forward path with a capturing fake LLM** (the importer's existing fake pattern — `chat` records the message list): a PDF with page text + one embedded image → the `describe_image` message's text part == `DESCRIBE_PROMPT` + neutral prefix + combined context (assert the prefix bytes explicitly); the stored `Document.image_context` == the same combined value; `content`/`summary` == `context + "\n\n" + description`.
+   - **Regression pins:** standalone image (no markdown, no PDF) → message byte-identical to pre-phase (capture the current message in a test by asserting `DESCRIBE_PROMPT` is the entire text part — `context=None`); markdown-only reference for a STANDALONE image (the phase-125 path) → still the markdown block with the (now neutral) prefix — the stored value is byte-identical (only the prompt prefix wording moved, not the stored data).
+   - The phase-126 unchanged-image digest skip is untouched (an unchanged embedded image still re-describes nothing — add/keep the existing test).
+8. `uv run pytest tests/unit -k "pdf or image" -v --no-cov`, then the full unit suite; `uv run ruff check . && uv run pyright` — green before moving on.
+
+## Testing & Quality
+- The tests in step 7; every one deterministic (fake LLM, fixture PDFs — no network, no real model).
+- Coverage: new/modified lines in `app/rag/importer.py` + `app/rag/summarizer.py` covered by these tests (the cap boundary, both guard branches, both combining branches).
+
+## Completion Criteria
+- [ ] a (re)indexed PDF's embedded images reach the vision model with `Extracted from <source>/<pdf> (page N):` + the (capped) page text, and the stored `image_context`/`content`/`summary` carry the same value
+- [ ] a markdown-referenced embedded image carries BOTH blocks, document first (exact-string test)
+- [ ] the standalone image's describe message is byte-identical to pre-phase; `DESCRIBE_PROMPT` unchanged
+- [ ] garbage-text guard: when the phase-133 gate exists and fails, the block is the origin line only; when the gate is absent, the block behaves normally (the phase runs in isolation)
+- [ ] `uv run pytest --no-cov` green (full suite); `uv run ruff check . && uv run pyright` green

.agents/phases/complete/137_pdf_image_context/03_backfill_image_context.md

@@ -0,0 +1,45 @@
+# Task 03 — Backfill: existing PDF-embedded image docs gain the document context on the next sync
+
+**Source:** `TODO.md` L3 — "Images extracted from PDFs still don't have any relevant context in their summaries … That context is critical in the image summaries. Image summaries should always include the document context if the images come from a document …" (The forward path of task 02 only fixes images that get (re)indexed; this task fixes the images ALREADY in the KB — e.g. the HNB-guide stock photos the owner cited — without waiting for a byte change.)
+
+## Objective
+A per-sync, idempotent, best-effort pass (the phase-118 A2 "until it sticks" shape, next to the phase-125 `_enrich_pending_images` post-index pass) re-describes every PDF-embedded image document that is missing the document-context block: bytes come from the `image_dir` copy, the page text is re-extracted from the parent PDF when it is still in the source (parent gone → origin line only), the new context-aware description goes through the SAME seam, and the row's `content`/`summary`/`image_context`/chunks are replaced. After a success the doc never qualifies again; a failure leaves the row untouched and retries next sync.
+
+## Work
+1. Read, in full: `_enrich_pending_images` (L1627 — the shape to mirror: driven by committed doc rows, idempotent, fail-soft, one transaction per image, deletes nothing), the per-source loop in `import_sources` (L525–590: `source = root.name`, the `_enrich_pending_images` call site at L587), `ImportSummary` (L212 + its `log()` method — the stats log-only convention: new field + log field, the sync `detail` API shape never changes), `_store_summary` (the image-aware summary store — the description IS the summary, stored verbatim), `_replace_content_chunks` (the per-image re-chunk + re-embed), `_pdf_image_context_block` / `_combine_image_contexts` / `extract_pdf_page_texts` (tasks 01–02).
+2. **The candidate query + gate** in a new function `async def _backfill_image_contexts(session, *, source: str, root: Path, llm: Embedder, summary: ImportSummary) -> None` in `app/rag/importer.py`:
+   - Select this source's `Document` rows with `is_image.is_(True)`.
+   - A doc is a CANDIDATE iff ALL hold:
+     1. its `path` parses as the phase-126 embedded-image synthetic path `<pdf_rel>#page=<N>#img=<I>.<ext>` (module-level compiled regex, e.g. `^.+\.pdf#page=(?P<page>\d+)#img=(?P<img>\d+)(?P<ext>\.\w+)$` — parse out `pdf_rel`, page, index, ext; non-matches — standalone images, screenshot-fallback PDFs are `is_image=False` anyway — are NEVER touched);
+     2. its `image_context` is `NULL` OR does not start with `"Extracted from "` (the idempotency gate — a markdown-only `"Referenced in …"` value STILL qualifies: the doc block is missing);
+     3. its `image_path` names a file that exists on disk (the `image_dir` copy — the bytes source; missing → debug log, skip, the doc stays as-is).
+   - If no candidates → return (the common case after the one-time backfill — zero cost per sync).
+3. **Per candidate** (fail-soft, one transaction per image, mirroring `_enrich_pending_images`'s error handling):
+   - `page_texts`: call `extract_pdf_page_texts(root / pdf_rel)` ONCE per unique `pdf_rel` across the candidates (a local cache dict in the pass — one parent may own many images); parent missing/unreadable → `page_texts = {}` AND `text_usable = True` (origin line only — the origin is still valuable and needs no disk); parent present → apply the same phase-133 gate probe as task 02 (shared helper if task 02 factored one out — reuse it, do not duplicate the probe).
+   - Build `doc_block = _pdf_image_context_block(source, pdf_rel, page, page_texts, text_usable=text_usable)` (`page` from the regex — the builder takes a plain `int`, task 02), then `combined = _combine_image_contexts(doc_block, existing_md_blocks)` — where `existing_md_blocks` = the doc's current `image_context` if it starts with `"Referenced in "` (the markdown blocks are kept verbatim — re-scanning the disk for them is NOT the pass's job: the phase-125 pass owns the markdown context and ran first this sync), else `None`.
+   - `data = Path(doc.image_path).read_bytes()` (OSError → skip, debug log).
+   - `description = await _describe_or_skip(llm, data=data, source=source, rel=doc.path, full_path=Path(doc.image_path), context=combined)` — the SAME seam (the mime comes from the copy's extension, exactly like the forward path). `None` → the row is UNTOUCHED (no rollback of anything — nothing was written), `summary.images_failed += 1`, warning, move on (the next sync retries — the gate still matches).
+   - Write: `content = f"{combined}\n\n{description}"`; `image_context = combined`; `indexed_at = now`; then `_replace_content_chunks(...)` (same call shape as the forward path, L1311) in the image's own transaction (an embed failure rolls back THIS image only — `summary.errors += 1`, error line, the copy stays, move on); then `_store_summary(...)` (the image convention — the description is the summary, verbatim); commit; `summary.image_context_backfilled += 1`; one loud log line (PLAN §9): `import: backfilled image context source=<source> path=<doc.path> chunks=<n>`.
+   - Deliberately UNCHANGED on the row: `content_hash` (the byte digest — the image identity is untouched), `created_at`/`created_at_manual` (the SOURCE did not change — the phase-106 date rules do not apply), `title`, `image_path`.
+4. **The counter:** `ImportSummary` gains `image_context_backfilled: int = 0` (docstring: "PDF-embedded image docs whose stored `image_context` was backfilled with the document-context block (phase 137, task 03) — the one-time best-effort pass; a success never repeats, a failure retries next sync") + its field in `ImportSummary.log()` (the per-turn/per-sync log line — append it next to `images_failed`; the sync `detail` API response shape is NOT changed — the stats log-only convention, phase 133).
+5. **The call site:** in `import_sources`'s per-source loop, immediately AFTER the existing `await _enrich_pending_images(...)` (L587 — enrichment first: it owns the markdown-FIRST case and may set `image_context`; the backfill then prepends the document block to whatever is there). The pass is driven by committed rows (like the enrichment pass), so it is safe under `limit`.
+6. **Integration tests** (extend the importer's existing integration file — `rg "_enrich_pending_images" tests/integration`):
+   - **Backfill happy path:** seed the DB with a PDF-embedded image row (the phase-126 synthetic path, `image_context=NULL`, `content`/`summary` = a bare description, an `image_path` pointing at a temp file with the image bytes) + the parent PDF on disk with page text; run the REAL `import_sources` over the source (fake LLM that records describe calls and returns a fixed context-aware reply); assert: exactly ONE describe call whose context carries `Extracted from <source>/<pdf> (page N):` + the page text; the row's `image_context` starts with `Extracted from `; `content`/`summary` = combined context + new description; chunks replaced; `image_context_backfilled == 1`.
+   - **Idempotency:** run `import_sources` a second time over the same source → ZERO describe calls, the row byte-identical (the gate no longer matches), `image_context_backfilled == 0`.
+   - **Parent gone:** the parent PDF is deleted from the source dir → the describe call's context is the origin line ONLY (no page-text line); the row is still backfilled (the gate matches again next sync iff it failed — here it succeeds once).
+   - **Markdown-only row:** `image_context = "Referenced in <source>/doc.md:\n- Alt text: \"x\""` (the phase-125 shape) → the backfilled `image_context` = doc block + blank line + the markdown block VERBATIM (document first).
+   - **Standalone image never touched:** an `is_image` row whose `path` has no `#page=` (a plain `pic.png`) with `image_context=NULL` → zero describe calls for it, across two runs.
+   - **Fail-soft:** a candidate whose describe call returns `None` (the fake fails once) → the row untouched, `images_failed == 1`; a second run with a healthy fake → backfilled.
+7. `uv run pytest tests/integration -k "image or import" -v --no-cov`, then the full unit + integration suites; `uv run ruff check . && uv run pyright` — green before moving on.
+
+## Testing & Quality
+- The tests in step 6 (real `import_sources`, fake LLM, temp dirs + seeded session — the house integration pattern; no network, no real model).
+- Coverage: every gate branch (pattern non-match, gate match, missing copy, parent gone), the happy path, idempotency, the fail-soft paths — all new lines covered.
+
+## Completion Criteria
+- [ ] an existing context-free PDF-embedded image doc is re-described WITH the document context on the next sync (integration test), counted in the new log-only `image_context_backfilled` counter
+- [ ] the pass is idempotent: the following sync burns zero vision calls for a backfilled doc (integration test)
+- [ ] a parent-gone image gets the origin-line-only context; a markdown-enriched row keeps its markdown block verbatim, document block prepended
+- [ ] standalone images and non-embedded rows are never touched; a describe failure leaves the row untouched and retries next sync
+- [ ] the sync `detail` API shape is unchanged (the new counter is log-only — verify the sync response schema test still passes unedited)
+- [ ] `uv run pytest --no-cov` green; `uv run ruff check . && uv run pyright` green

.agents/phases/complete/137_pdf_image_context/04_retrieval_display_line.md

@@ -0,0 +1,36 @@
+# Task 04 — The suggestion-block display line: `From <source>/<pdf> (page N)`
+
+**Source:** `TODO.md` L3 — "…so the embedder can more effectively retrieve image sources." (The summary itself now carries the context via tasks 02/03; this task makes the context VISIBLE in the chat suggestion block the way phase 125 did for markdown references — a short locator line, never the page-text body.)
+
+## Objective
+`_extract_context_line` in `app/rag/prompts.py` renders the phase-137 document-context block — `Extracted from <source>/<pdf path> (page <N>):` — as the one-line clause `From <source>/<pdf path> (page <N>)`, so a PDF-embedded image's `<document>` suggestion body leads with where the image came from (before its description), exactly the way an enriched markdown image leads with `Referenced in …`. A context value carrying BOTH block kinds renders both clauses in stored order. Everything that parses to nothing degrades to `None` exactly as today (pre-phase rows, the `IMAGE_CONTEXT:` pending record, unparseable text).
+
+## Work
+1. Read, in full: `_extract_context_line` (L470), `_image_ctx_clause` (L459), `_image_context_line` (L536), `_document_body` (L548) in `app/rag/prompts.py` — the phase-125 task-05 renderer: header regex `_IMAGE_CTX_HEADER_RE` (`^Referenced in (?P<ref>.+):$`), the alt-bullet regex, the clause join (`"Referenced in " + "; ".join(clauses)`), and the `expecting_alt` state machine.
+2. Add the header regex for the new block (next to `_IMAGE_CTX_HEADER_RE`): `_PDF_CTX_HEADER_RE = re.compile(r"^Extracted from (?P<loc>.+) \(page (?P<page>\d+)\):$")` — `loc` is the `<source>/<pdf path>` locator (greedy to the last ` (page N):` — the pdf path may itself contain spaces).
+3. Extend the state machine in `_extract_context_line` to handle the new header:
+   - A `Extracted from …` header STARTS a pdf clause: it needs NO following bullet (unlike the `Referenced in` header, whose next line MUST be the alt bullet or the block is dropped — the pdf block's next line is page-text body or the next header, and none of it changes the clause).
+   - Its clause text: `From {loc} (page {page})`.
+   - Clause JOINING: the current code prefixes `"Referenced in "` to the joined clauses — that prefix belongs to the REFERENCED clauses only. Restructure so each clause carries its own prefix: referenced clauses stay `Referenced in <ref>: "<alt>"` (byte-identical output for markdown-only values — the phase-125 regression pin), pdf clauses are `From <loc> (page N)`; the join is still `"; "` between clauses IN STORED ORDER (document block first per ASSUMPTION A2 → a both-blocks value renders `From a.pdf (page 2); Referenced in docs/a.md: "alt"`).
+   - A pdf clause followed by page-text body lines: the body lines are skipped by the existing "any other line is context body" fall-through — verify the state machine does not mis-read a page-text line that LOOKS like a header (e.g. a line of page text starting with `Referenced in ` — the existing spurious-header rule already handles the referenced case by demanding the alt bullet; a spurious `Extracted from … (page N):` line inside page text would emit a clause — accept that: it is the stored context the importer wrote, not model text; document it in the docstring).
+   - A value with NO parsable header of either kind → `None` (unchanged).
+   - Update `_extract_context_line`'s docstring (the stored value can now carry the `Extracted from` block first — tasks 02/03 write it — plus the markdown blocks) and the module-level comment block above the regexes (the phase-137 note).
+4. `_image_context_line` / `_document_body` need NO changes (the `is_image` guard + the renderer call already do the right thing) — verify with a read, and note it in the commit message if so.
+5. Unit tests (extend the prompts test file — `rg "_extract_context_line|_document_body" tests/unit`):
+   - pdf block alone → `"From <source>/guide.pdf (page 2)"` exactly.
+   - pdf block + page-text body (multi-line, including a blank line and a line starting with `Referenced in ` without the alt bullet) → the same single clause (the spurious referenced header is dropped by the existing rule).
+   - markdown block alone → byte-identical to the pre-task output (the phase-125 pin: `Referenced in docs/a.md: "alt a"; docs/b.md` from the existing test's shape).
+   - BOTH blocks in stored order (pdf first, markdown second — the tasks 02/03 combined shape) → `From <source>/guide.pdf (page 2); Referenced in docs/a.md: "alt"`.
+   - garbage/unparseable value → `None` (unchanged); the `IMAGE_CONTEXT:` pending record → `None` (unchanged).
+   - `_document_body` end-to-end: an `is_image` doc with the combined context → body leads with the one-line rendering, then the summary; a non-image doc with a non-NULL `image_context` → byte-identical body (the `is_image` guard).
+6. `uv run pytest tests/unit -k prompt -v --no-cov`, then the full unit suite; `uv run ruff check . && uv run pyright` — green before moving on.
+
+## Testing & Quality
+- The tests in step 5; the markdown-only byte-identity pin is the load-bearing one (phase 125's display contract must not move).
+- Coverage: the new header branch, both orderings, the degradation paths — all covered by step 5.
+
+## Completion Criteria
+- [ ] a PDF-embedded image doc's suggestion `<document>` body leads with `From <source>/<pdf> (page N)` (unit test), never rendering the page-text body
+- [ ] a both-blocks context renders `From …; Referenced in …` in stored order; a markdown-only context renders byte-identically to pre-phase (the phase-125 pin green UNEDITED)
+- [ ] unparseable values and the `IMAGE_CONTEXT:` record degrade to `None` as before; non-image docs are byte-identical
+- [ ] `uv run pytest --no-cov` green; `uv run ruff check . && uv run pyright` green

.agents/phases/complete/137_pdf_image_context/05_e2e_pdf_image_context.md

@@ -0,0 +1,58 @@
+# Task 05 — The dedicated E2E: `tests/e2e/test_pdf_image_context.py` (mock trigger + the story suite)
+
+**Source:** `TODO.md` L3 — the whole item, end to end: "Images extracted from PDFs still don't have any relevant context in their summaries … Image summaries should always include the document context if the images come from a document (this includes markdown files) so the embedder can more effectively retrieve image sources." (AGENTS.md §4/§9: every phase carries its own Playwright E2E file, run in isolation; this is this phase's gate.)
+
+## Objective
+One new Playwright suite proving the story through the REAL UI + REAL pipeline with the deterministic mock LLM: (a) an uploaded PDF's embedded image is described WITH the document context (the context-aware canned reply is the witness that the context reached the vision model), stored on `image_context`/`content`/`summary`; (b) the chat suggestion for that image leads with the `From <source>/<pdf> (page N)` line; (c) a markdown reference in the same source COMBINES with the document context, document block first. Plus the one mock-LLM change that makes (a) observable.
+
+## Work
+1. Read, in full: `tests/e2e/test_pdf_support.py` (the module-app pattern: `_app_env` with the port/env overrides, `zip_path` fixture — the PyMuPDF PDF build: `doc.new_page().insert_text((72, 72), PAGE_ONE)`, `page2.insert_image(fitz.Rect(72, 150, 73, 151), stream=PNG_1X1)`, `doc.set_metadata({"title": PDF_TITLE})`, zip to `<source>.zip`; the `_truncate_all`, `_upload_zip` (admin login → git-sources page → `#archive-upload-file`/`#archive-upload-btn` → result line), `_sync_via_ui` (RAG page `#sync-btn` → `#sync-label` "Syncing…" → synced label + `#sync-result`), and `seeded` module fixture), `tests/e2e/test_image_anchor_context.py` (the `ANCHOR_QUESTION = "quote the image reference — what is shown in the homelab network diagram?"` pattern + the mock-calibrated gate env values + the standalone-doc "no reference line" witness), `tests/e2e/mock_llm.py` — the `IMAGE_DESCRIPTION_MODE` branch (L2472), `IMAGE_DESCRIPTION_ANSWER` (L865), `CONTEXT_LINE_TRIGGER` (L1886) + its branch (L2532, `_seeded_image_doc` / `_seed_context_line`), and the docstring's behavior list at the top (every new mock behavior is documented there).
+2. **The mock change** (the ONLY edit to `tests/e2e/mock_llm.py`):
+   - New constant next to `IMAGE_DESCRIPTION_ANSWER`:
+     ```python
+     #: The phase-137 witness — the mock's vision reply when the
+     #: ``IMAGE_DESCRIPTION_MODE`` message's text part carries the
+     #: document-context block (its ``Extracted from …`` header). It
+     #: names the document + page (the context reached the model — the
+     #: deterministic proof) and keeps the diagram wording of
+     #: :data:`IMAGE_DESCRIPTION_ANSWER` so the story question's
+     #: token-overlap retrieval still grounds on the image doc.
+     IMAGE_DESCRIPTION_CONTEXT_ANSWER = (
+         "From report.pdf, page 2: a network diagram of the homelab "
+         "server room: a core router on top, a core switch in the "
+         "middle, and three labeled subnets at the bottom — VLAN 10 "
+         "office, VLAN 20 lab, and VLAN 30 storage — with a legend of "
+         "cable runs. Title: Homelab Network Map."
+     )
+     ```
+   - In the `IMAGE_DESCRIPTION_MODE` branch: `answer = IMAGE_DESCRIPTION_CONTEXT_ANSWER if "Extracted from " in user else IMAGE_DESCRIPTION_ANSWER` — the `Extracted from ` probe is the phase-137 provenance header (the importer's block builder — task 02); the bare path (standalone images, the pre-137 embedded shape, every existing suite's PDFs) stays on `IMAGE_DESCRIPTION_ANSWER` — byte-identical.
+   - Document the new branch behavior in the mock's top docstring (the house rule — every behavior is listed).
+   - NO other mock change: the `CONTEXT_LINE_TRIGGER` branch already echoes the seeded image doc's block FIRST line — which is now the task-04 `From …` rendering for PDF images (zero mock work for the display assertion).
+3. **The suite** `tests/e2e/test_pdf_image_context.py` (run in isolation: `uv run pytest tests/e2e/test_pdf_image_context.py -v --no-cov`):
+   - Module app: ONE images-ON app, the `test_pdf_support.py` pattern — new env port (`E2E_APP_PORT_PDF_IMG_CTX`, default 8154 — check `8152/8153` are taken by test_pdf_support and pick the next free), scratch dirs via `tmp_path_factory`, the mock's port from the session `mock_llm` fixture; assert `/api/config` `images` is True in the seed (the suite is void otherwise).
+   - **Fixture archive 1** (`zip_path`): ONE PDF at the root, source `e2e-pdf-imgctx`, `report.pdf` — page 1 = `PAGE_ONE` text, page 2 = `PAGE_TWO` text + the 1×1 PNG embedded (the phase-126 recipe; define `PAGE_ONE`/`PAGE_TWO`/`PDF_TITLE`/`PNG_1X1` locally — do NOT import from test_pdf_support; the suites must stay standalone).
+   - **Seed 1** (module): `_truncate_all` → `_upload_zip` → `_sync_via_ui` (expected result line: the 2-added counts — the PDF doc + the image doc).
+   - **Test 1 — the forward path (the TODO's core complaint):** DB assertions (`SessionLocal`, like test_pdf_support's `seeded`):
+     - the image doc exists at `e2e-pdf-imgctx/report.pdf#page=2#img=0.png`, `is_image=True`;
+     - its `image_context` STARTS WITH exactly `Extracted from e2e-pdf-imgctx/report.pdf (page 2):` and CONTAINS the `PAGE_TWO` text (the document context reached the store — the owner's "no mention of the document it came from" is gone);
+     - its `content` == `image_context + "\n\n" + IMAGE_DESCRIPTION_CONTEXT_ANSWER` and `summary` == `content` (the image convention) — the CONTEXT-AWARE reply is the witness the describe call carried the context (the bare `IMAGE_DESCRIPTION_ANSWER` string must NOT appear in `content`).
+   - **Test 2 — the display line in chat:** the `ANCHOR_QUESTION` pattern (`"quote the image reference — what is shown in the homelab network diagram?"` — the diagram wording is in `IMAGE_DESCRIPTION_CONTEXT_ANSWER`, so the same retrieval grounds), the mock-calibrated gate env (the test_image_anchor_context values); assert the final answer contains `From e2e-pdf-imgctx/report.pdf (page 2)` (the mock's `CONTEXT_LINE_TRIGGER` echo of the block's first line — the task-04 rendering) and does NOT contain `stands alone` (the standalone witness is absent).
+   - **Fixture archive 2** (`zip_md_path`): the SAME PDF + `notes.md` at the root containing `![network diagram](report.pdf#page=2#img=0.png)` plus a paragraph of surrounding context (the phase-125 reference shape) — source `e2e-pdf-imgctx-md`.
+   - **Seed 2** (module): `_truncate_all` → upload archive 2 → sync (expected counts: PDF + image + the markdown doc).
+   - **Test 3 — markdown + document combined, document first:** the image doc's `image_context` == `Extracted from e2e-pdf-imgctx-md/report.pdf (page 2):` + `PAGE_TWO` text + `"\n\n"` + the markdown block starting `Referenced in e2e-pdf-imgctx-md/notes.md:` (assert the STARTS-WITH document block AND the `Referenced in` block's presence AND the document block's index < the `Referenced in` block's index — document first, ASSUMPTION A2); the chat display answer (the same anchor question) contains BOTH `From e2e-pdf-imgctx-md/report.pdf (page 2)` and `Referenced in e2e-pdf-imgctx-md/notes.md`.
+   - **Test 4 — standalone parity witness:** a plain standalone image upload in the SAME seeded source is overkill; instead assert against seed 1's KB: NO other `is_image` doc exists (the suite's KB is exactly the PDF + its image), and the mock's bare branch is pinned by test_pdf_support running green unedited (do not duplicate it).
+4. **Regression run (the load-bearing gate):** `uv run pytest tests/e2e/test_pdf_support.py tests/e2e/test_image_anchor_context.py tests/e2e/test_image_documents.py -v --no-cov` — all three green UNEDITED (the mock change must not move their canned replies — the bare describe path is byte-identical; the `CONTEXT_LINE_TRIGGER` echo of a markdown-enriched doc is byte-identical).
+5. `uv run ruff check . && uv run pyright` — green. (The suite itself is linted like its siblings; no type-check burden on the mock constants.)
+
+## Testing & Quality
+- The suite in step 3 IS the phase's E2E deliverable; deterministic end to end (mock LLM, fixture PDFs built in tmp dirs — `test_sources/` is never touched, the house rule from phase 133's fixture handling).
+- The mock edit is covered by the suite's tests 1–3 (the trigger) + the regression run step 4 (the non-trigger).
+- Coverage gate (app/) is unaffected by test files; the phase's >90% comes from tasks 01–04.
+
+## Completion Criteria
+- [ ] `tests/e2e/test_pdf_image_context.py` exists and passes IN ISOLATION: `uv run pytest tests/e2e/test_pdf_image_context.py -v --no-cov`
+- [ ] the embedded image's stored summary names the document + page (the context-aware canned reply — test 1); `image_context` leads with `Extracted from <source>/report.pdf (page 2):` + the page text
+- [ ] the chat suggestion for the image leads with `From <source>/report.pdf (page 2)` (test 2, via the existing `CONTEXT_LINE_TRIGGER` echo — no new display mock branch)
+- [ ] a markdown-referenced PDF image shows BOTH the document and the reference context, document first (test 3)
+- [ ] `test_pdf_support.py`, `test_image_anchor_context.py`, `test_image_documents.py` green UNEDITED after the mock change
+- [ ] `uv run ruff check . && uv run pyright` green

.agents/phases/complete/138_markdown_blockquotes/00_phase.md

@@ -0,0 +1,45 @@
+# Phase 138 — Markdown blockquotes render: `>` quotes become styled `<blockquote>`s
+
+**Source:** `TODO.md` L3 — "Markdown formatted ">" quotes aren't rendering"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `frontend/assets/markdown.js` — the shared escape-first renderer (loaded by all three pages: `index.html` chat, `document.html` viewer, `shared.html`): step 1 fence protection (`\u0000CODEn\u0000`), step 1b table protection (`\u0000TABLEn\u0000`, phase 44), step 2 `inline(escapeHtml(text))` (the inline chain: code → strong → em → h3/h4 → ul → ol), step 3 the paragraph pass (split on `\n{2,}`; the block-element guard `/^<(h\d|ul|ol|pre|li)/`), step 4 restore. Today a `>` line is escaped to `&gt;` and renders as literal text in a `<p>` (verified: `renderMarkdown("> quoted")` → `<p>&gt; quoted</p>`). `frontend/assets/styles.css` — the `:root` palette (`--ink-soft` 8.2:1 on `--surface`, `--line`, the `--brand-*` family; the `:root`-drift unit test parses the built-ins from this file — no second copy) and the chat-bubble / viewer typography. `tests/unit/test_markdown_tables.py` — the frontend source-pin + node-behavior unit pattern (`HAVE_NODE` skip); `tests/e2e/test_markdown_tables.py` — the phase-44 E2E pattern (mock flow with table output + the document viewer).
+
+## Objective
+`>`-prefixed lines in any rendered markdown — a chat answer, the thinking block, a saved/shared chat (restore), the document viewer — render as a semantic `<blockquote class="md-quote">` with theme-safe styling; every non-quote input renders byte-identical to today (the phase-44 table suite and the renderer-dependent unit suites stay green unedited).
+
+## Dependencies
+- `137_pdf_image_context` (complete) — pipeline order only; the code dependencies are the shared renderer + `styles.css` on `main`.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The pass (task 01):** a new line-block pass in `markdown.js` BETWEEN step 2 (`inline(escapeHtml(text))`) and step 3 (paragraphs) — at that point the text is escaped (a quote line starts with `&gt;`) and already inline-transformed (bold/emphasis/code work inside quotes for free — the pass never re-transforms). Group the maximal run of consecutive lines matching `^\s*&gt;+ ?` into ONE `<blockquote class="md-quote">…</blockquote>`: strip the leading `&gt;` run plus ONE optional space from each member (nested `>>` / `>>>` collapses to one level — ASSUMPTION A1), join members with `<br>` (the paragraph convention). A BLANK line terminates the group (a re-quoted line starts a new `<blockquote>` — simple, predictable). The step-3 guard extends to `/^<(h\d|ul|ol|pre|li|blockquote)/` so the paragraph pass leaves the block alone (no `<p>` wrap).
+- **Precedence is untouched:** fences protect first (step 1 — a `>` inside a code block never reaches the pass), tables protect second (step 1b — cell content is escaped inside the `<td>` markup and restored in step 4, AFTER the pass). No other pass changes.
+- **In-quote structure (documented limit):** a markdown STRUCTURE inside a quote (a `- list` line, a `# heading` line) renders as plain text inside the blockquote — the inline chain runs before the pass, so its line-start transforms never see the post-strip text. Inline (code/strong/em) still works. Acceptable — the scope is quote rendering (owner L3).
+- **The CSS (task 02):** `.md-quote` in `styles.css` — theme-safe from the EXISTING `:root` palette only: left border + horizontal padding + vertical margin + a muted text color carrying a ≥4.5:1 contrast comment on the bubble surface (the house comment convention, cf. `--ink-soft`'s `/* 8.2:1 on --surface */`). ONE rule set serves all three contexts (chat `.bubble`, `.thinking-text`, the document viewer) — a scoped override only if the E2E proves a clash.
+- **Byte-identity (task 03):** any input without a quote line renders byte-identical to the pre-phase renderer — pinned by the node behavior check and by the unedited `test_markdown_tables.py` / `test_thinking_scroll.py` / `test_document_viewer.py` suites.
+- **E2E (task 03):** dedicated `tests/e2e/test_markdown_blockquotes.py`, run in isolation (AGENTS.md rules 4/9), mock-only.
+
+## Tasks
+1. `01_blockquote_pass.md` — the blockquote pass in `markdown.js` + the paragraph-guard extension.
+2. `02_blockquote_css.md` — the `.md-quote` styling in `styles.css` (theme-safe, WCAG AA contrast).
+3. `03_unit_and_e2e.md` — unit source-pins + node behavior + the dedicated Playwright E2E.
+
+## Testing & Quality
+- Unit: `tests/unit/test_markdown_blockquotes.py` (new — the phase-44 pattern): source pins (pass order fences → tables → escape+inline → **blockquotes** → paragraphs → restore; the guard regex includes `blockquote`; the exact `<blockquote class="md-quote">` marker; the `.md-quote` CSS rule references palette vars only) + node behavior (single-line quote, multi-line group, nested collapse, XSS quote inert, fence-wins, a table cell containing `>` untouched, non-quote input byte-identical).
+- E2E: `tests/e2e/test_markdown_blockquotes.py` (new), in isolation.
+- Coverage: **>90%** on `app/` (the gate runs the full suite — this phase adds no `app/` code, so the suite staying green IS the gate).
+
+## Completion Criteria
+- [ ] `>` quotes render as a styled `<blockquote class="md-quote">` in the chat answer, the thinking block, saved/shared chats (restore), and the document viewer
+- [ ] nested `>>` collapses to one level; a `>` inside a code fence or a table cell is untouched
+- [ ] non-quote input renders byte-identical (the phase-44 / renderer-dependent suites pass unedited)
+- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run pytest tests/e2e/test_markdown_blockquotes.py -v --no-cov` green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] one `--no-gpg-sign` Conventional Commit; phase dir moved to `.agents/phases/complete/` by the pipeline gate
+
+## Locked decisions
+- **A1 — nested quotes (`>>`, `>>>`) collapse to a single `<blockquote>` level (owner-confirmed 2026-09-30, roadmap confirmation).**
+- **A2 — the quote style is a left border + padding + muted text color (NO background fill), built from the existing `:root` palette only (owner-confirmed 2026-09-30, roadmap confirmation).**
+
+## Commit
+```bash
+git add frontend/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(ui): render markdown blockquotes in chat, viewer, and shared pages"
+```

.agents/phases/complete/138_markdown_blockquotes/01_blockquote_pass.md

@@ -0,0 +1,22 @@
+# Task 01 — The blockquote pass in the shared renderer
+
+**Phase:** `138_markdown_blockquotes` · **Source:** `TODO.md:3` — "Markdown formatted ">" quotes aren't rendering"
+**Story:** n/a
+
+## Objective
+`renderMarkdown` turns runs of `>`-prefixed lines into `<blockquote class="md-quote">` elements — after the escape + inline step, before the paragraph pass — with fences and tables keeping their precedence and non-quote input byte-identical.
+
+## Work
+1. `frontend/assets/markdown.js` — new pass between the step-2 `text = inline(escapeHtml(text))` and the step-3 paragraph `.map(...)`: split the text on `\n`; group the maximal run of consecutive lines matching `^\s*&gt;+ ?` (the escaped quote marker); strip the `&gt;` run + one optional space from each member (nested `>>`/`>>>` collapses to one level — ASSUMPTION A1); join members with `<br>`; emit `<blockquote class="md-quote">…</blockquote>`. A blank line terminates the group.
+2. `frontend/assets/markdown.js` — extend the step-3 block-element guard from `/^<(h\d|ul|ol|pre|li)/` to `/^<(h\d|ul|ol|pre|li|blockquote)/` so the paragraph pass leaves the block alone (no `<p>` wrap).
+3. `frontend/assets/markdown.js` — update the module docstring: pass order is now fences → tables → escape+inline → **blockquotes** → paragraphs → restore; document the group rule (blank line terminates; nested collapses) and the documented limit (a list/heading line INSIDE a quote renders as plain text — the inline chain ran first; inline code/strong/em work).
+- ASSUMPTION: a `>` inside a code fence is already protected by the step-1 placeholder (no handling needed); a `>` in a table cell is escaped inside the `<td>` markup and restored in step 4 — both are pinned in task 03's behavior checks.
+
+## Testing & Quality
+- Unit: covered by task 03's file (the source pin + the node behavior listed there) — the frontend house pattern is one unit file per feature.
+- Coverage: n/a (frontend) — the suite + the pins are the gate.
+
+## Completion Criteria
+- [ ] node repro: `renderMarkdown("> a\n> b")` → `<blockquote class="md-quote">a<br>b</blockquote>`; `renderMarkdown("> quoted")` no longer emits a literal `&gt;`
+- [ ] a non-quote input (plain paragraph, list, table, fence) renders byte-identical to the pre-task renderer
+- [ ] `uv run pytest` green (the renderer-dependent unit suites unedited); `uv run ruff check .` clean

.agents/phases/complete/138_markdown_blockquotes/02_blockquote_css.md

@@ -0,0 +1,21 @@
+# Task 02 — `.md-quote` styling (theme-safe, WCAG AA)
+
+**Phase:** `138_markdown_blockquotes` · **Source:** `TODO.md:3` — "Markdown formatted ">" quotes aren't rendering"
+**Story:** n/a
+
+## Objective
+The blockquote is visually distinct and readable in all three rendering contexts (chat bubble, thinking block, document viewer) with ONE rule set, using only the existing `:root` palette.
+
+## Work
+1. `frontend/assets/styles.css` — add the `.md-quote` rule next to the other markdown element styles (the phase-44 `.md-table` / `.md-table-wrap` block is the anchor): `border-left: 3px solid <palette var>` (a visible-but-restrained border — pick from the existing `:root` palette, the executor's contrast judgment), `padding: 0.25rem 0.75rem`, `margin: 0.5rem 0`, `color: <muted palette var>` with a ≥4.5:1 contrast comment on the bubble surface per the house convention (`--ink-soft`'s `/* 8.2:1 on --surface */` qualifies — verify against the actual bubble background and document it).
+2. `frontend/assets/styles.css` — no background fill (ASSUMPTION A2); verify the rule renders acceptably in the chat `.bubble`, the `.thinking-text` block, and the document-viewer content region — add a scoped override only if the task-03 E2E proves a clash.
+- ASSUMPTION: the built-in dark palette is the single source of truth — the `:root`-drift unit test parses built-ins from this file, so no hex literal outside `:root` and no second copy.
+
+## Testing & Quality
+- Unit: `tests/unit/test_markdown_blockquotes.py` (task 03) source-pins the `.md-quote` rule's presence and its palette-var-only references (the phase-44 CSS-pin pattern).
+- Coverage: n/a (frontend).
+
+## Completion Criteria
+- [ ] the `.md-quote` rule exists in `styles.css`, references only `:root` palette vars, and carries a ≥4.5:1 contrast comment
+- [ ] the quote is visually distinct in chat + viewer (the E2E screenshot, task 03)
+- [ ] the theme no-op (B4) is unaffected — the rule uses existing vars; no new `ui_settings` column

.agents/phases/complete/138_markdown_blockquotes/03_unit_and_e2e.md

@@ -0,0 +1,24 @@
+# Task 03 — Unit pins, node behavior, dedicated E2E
+
+**Phase:** `138_markdown_blockquotes` · **Source:** `TODO.md:3` — "Markdown formatted ">" quotes aren't rendering"
+**Story:** n/a
+
+## Objective
+Pin the renderer contract at the source level, prove the browser behavior, and ship the dedicated Playwright file, run in isolation (AGENTS.md rules 4/9).
+
+## Work
+1. `tests/unit/test_markdown_blockquotes.py` (new) — the phase-44 pattern (source pins + a `HAVE_NODE`-skipped node behavior):
+   - Source pins: the blockquote pass runs after `inline(escapeHtml(text))` and before the paragraph split; the paragraph guard includes `blockquote`; the exact `<blockquote class="md-quote">` marker string; the `.md-quote` CSS rule references palette vars only (the task-02 pin).
+   - Node behavior: single-line quote → one blockquote; a 3-line group → one blockquote with `<br>` joins; `>> nested` collapses to one level; `> <script>alert(1)</script>` renders inert (no live tag in the output); a `>` inside a ``` fence stays fence content; a table cell containing `> x` renders as table-cell text, not a blockquote; non-quote input (a paragraph + list + table) renders byte-identical to the pre-phase renderer (fixture string checked into the test, per the phase-44 shape).
+2. `tests/e2e/test_markdown_blockquotes.py` (new) — dedicated, run in isolation (`--no-cov`, DB up), mock-only, following `tests/e2e/test_markdown_tables.py`'s structure:
+   - (a) the chat: a mock flow whose answer contains `>` quotes (the phase-44 mock-flow pattern — a new user-message marker, a deterministic canned answer) → assert the DOM: the `.bubble` contains a `blockquote.md-quote` with the quote text and no literal `&gt;` text at the block's start;
+   - (b) the viewer: a KB fixture with a `.md` document containing a quote block → open the document → assert the viewer content renders the `blockquote.md-quote`;
+   - (c) the restore: save the chat (or reload `/?chat=<id>`) → the restored bubble keeps the blockquote (the restore path runs the same renderer — a cheap assertion if the suite structure allows it).
+
+## Testing & Quality
+- Unit: as above. E2E: as above. Coverage: **>90%** on `app/` (the gate runs the full suite; frontend changes add no `app/` code — the suite must stay green).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_markdown_blockquotes.py -v` green (node available → the behavior check runs)
+- [ ] `uv run pytest tests/e2e/test_markdown_blockquotes.py -v --no-cov` green in isolation
+- [ ] `uv run pytest` green, coverage TOTAL >90%, `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/139_read_range_tool_lines/00_phase.md

@@ -0,0 +1,45 @@
+# Phase 139 — The Reading tool line shows which lines are being read
+
+**Source:** `TODO.md` L4 — "The \"Reading\" tool UI output doesn't show what lines are being read, just the same file over and over which is confusing to the user"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/api/chat.py` — the SSE `tool` frame (`ChatToolEvent`) ALREADY carries `offset` / `limit` for a range `read` (phase 131 task 04 — the fields land on the frame only when well-formed via `_whole_line_number` (L307) and are omitted otherwise, so non-range frames are byte-identical); the frame is emitted at ~L928-952. `frontend/assets/app.js` — `appendToolLine(wrap, name, argument)` (L1119 — the read branch builds `📄 Reading ` + a `<code>{argument}</code>` child; the line bytes are pinned by the phase-87 emoji guard + the phase-117 disclosure pins), the live `tool` branch (L3103-3137 — reads only `ev.name` / `ev.argument`; `toolAcc.push({ name, argument })` L3116; the status label `is reading ${argument}` L3125), `toolAcc` (L2993 — the per-turn accumulator persisted as the saved chat's `tools` array at L3229 / L3310 / L3361 / L3395), the restore path (~L2030-2045 — `m.tools` → `appendToolLine(wrap, t.name, arg)` + the phase-95 truncation marker). `frontend/assets/shared.js` — `addToolLines(wrap, tools)` (~L175+ — the shared page's parity copy of `appendToolLine` with the pinned-identical line literals). `tests/integration/test_api.py` — the frontend emoji guard strips precisely the pinned emoji literals from `app.js` / `shared.js` (no new emoji may be introduced). `tests/e2e/test_read_line_ranges.py` + the phase-131 mock flow (`read the lines` marker → grep → `read(offset, limit)`) in `tests/e2e/mock_llm.py`.
+
+## Objective
+When the agent range-reads a document (`read(path, offset, limit)` — phase 131), the Reading tool line shows WHICH lines — `📄 Reading <code>source/path</code> (lines 42–71)` — so repeated reads of the same file are distinguishable, live, on restore, and on the shared page; a plain read renders byte-identical to today.
+
+## Dependencies
+- `138_markdown_blockquotes` (todo) — pipeline order only; no code overlap (139 touches the tool-line rendering, 138 the markdown renderer).
+- Code: the phase-131 wire fields (complete) — nothing new server-side.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The suffix (task 01):** one new helper in `app.js` — `readRangeSuffix(offset, limit) → string | ""` — the single source of truth for the wording (used by both the tool line and the status label): both present → ` (lines {offset}–{offset + limit - 1})` (EN-DASH; the pinned copy — ASSUMPTION A1: the range shown is the model's REQUEST; the UI does not know the document length, so a `limit` past EOF renders the requested extent); offset only → ` (from line {offset})`; limit only → ` (first {limit} lines)`; neither / malformed → `""`. The JS well-formedness guard mirrors the server's `_whole_line_number`: `Number.isInteger(x) && x >= 1`.
+- **`appendToolLine` (task 01):** the signature becomes `appendToolLine(wrap, name, argument, offset = null, limit = null)` — the read arm (`read` / `read_document`) appends, AFTER the `<code>` child, a `<span class="read-range">` with `textContent = readRangeSuffix(offset, limit)` ONLY when the suffix is non-empty (a plain read's line stays byte-identical — the phase-87/117 pins + the emoji guard stay green; no new emoji). `shared.js`'s `addToolLines` applies the identical suffix to its pinned-identical line (the parity contract — the shared page re-renders saved records that now carry the fields).
+- **The live branch (task 02):** read `ev.offset` / `ev.limit` with the same guard (absent / malformed → `null`); `toolAcc.push({ name, argument, offset, limit })` with the fields included ONLY when non-null (a non-range record keeps the exact pre-phase `{name, argument}` shape — the `bor.chat.v1` save JSONB is additive; old records without the fields restore byte-identically, no migration); pass both to `appendToolLine`; the status label becomes `${brand()} is reading ${argument}${suffix}` (same helper — ASSUMPTION A2).
+- **The restore path (task 02):** `t.offset` / `t.limit` (same guard) → `appendToolLine(wrap, t.name, arg, tOffset, tLimit)`; the phase-95 truncation note is untouched (it keys on the `<code>` argument — verify with the existing pins).
+- **E2E (task 03):** ONE new mock flow following the phase-131 pattern (user-message marker, deterministic replies, module-header docstring entry): the model range-reads the SAME document twice with different `offset`/`limit` — the owner's exact "same file over and over" scenario.
+
+## Tasks
+1. `01_tool_line_range_suffix.md` — `readRangeSuffix` + the `appendToolLine` / `addToolLines` suffix rendering.
+2. `02_live_restore_persist.md` — the live branch's `ev.offset`/`ev.limit`, the `toolAcc` persistence, the restore path, the status label.
+3. `03_unit_and_e2e.md` — unit pins + node behavior + the mock flow + the dedicated Playwright E2E.
+
+## Testing & Quality
+- Unit: `tests/unit/test_read_range_tool_lines.py` (new — the `test_frontend_tool_states.py` pattern): source pins (the suffix template literals, the `Number.isInteger` guard, the `ev.offset`/`ev.limit` read, the `toolAcc` push carrying the fields, the restore pass-through, the shared.js parity) + node behavior (`appendToolLine` with a range vs without — the plain line byte-identical; the three suffix shapes).
+- E2E: `tests/e2e/test_read_range_tool_lines.py` (new), in isolation.
+- Coverage: **>90%** on `app/` (no `app/` code changes — the suite staying green IS the gate).
+
+## Completion Criteria
+- [ ] a range read renders `📄 Reading <code>path</code> (lines N–M)` live; two range reads of the same file show DIFFERENT ranges (the owner's confusion is gone)
+- [ ] a plain read's line is byte-identical to pre-phase (the phase-87/117 pins + the emoji guard pass unedited)
+- [ ] the suffix survives save → restore (the chat page + the shared page render it from the saved record)
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run pytest tests/e2e/test_read_range_tool_lines.py -v --no-cov` green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] one `--no-gpg-sign` Conventional Commit; phase dir moved to `.agents/phases/complete/`
+
+## Locked decisions
+- **A1 — the suffix shows the model's REQUESTED range (`offset`…`offset+limit−1`); the UI cannot know the actual slice extent (owner-confirmed 2026-09-30, roadmap confirmation).**
+- **A2 — the status label carries the same suffix (`Brain is reading source/path (lines 42–71)`) (owner-confirmed 2026-09-30, roadmap confirmation).**
+
+## Commit
+```bash
+git add frontend/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(ui): show the read tool's line range in the Reading line"
+```

.agents/phases/complete/139_read_range_tool_lines/01_tool_line_range_suffix.md

@@ -0,0 +1,21 @@
+# Task 01 — The range suffix on the Reading line (chat + shared page)
+
+**Phase:** `139_read_range_tool_lines` · **Source:** `TODO.md:4` — "The \"Reading\" tool UI output doesn't show what lines are being read, just the same file over and over which is confusing to the user"
+**Story:** n/a
+
+## Objective
+`appendToolLine` (and the shared page's `addToolLines`) render the requested line range as a suffix on the Reading line whenever a well-formed `offset`/`limit` is passed — createElement + textContent only, plain reads byte-identical.
+
+## Work
+1. `frontend/assets/app.js` — add a `readRangeSuffix(offset, limit)` helper next to `appendToolLine`: the well-formedness guard `Number.isInteger(x) && x >= 1` (mirrors the server's `_whole_line_number`); both present → ` (lines ${offset}–${offset + limit - 1})` (en-dash — the pinned copy); offset only → ` (from line ${offset})`; limit only → ` (first ${limit} lines)`; otherwise → `""`.
+2. `frontend/assets/app.js` — `appendToolLine(wrap, name, argument, offset = null, limit = null)`: in the read arm (`read` / `read_document`), compute `readRangeSuffix(offset, limit)`; when non-empty, append a `<span class="read-range">` (textContent = the suffix) AFTER the `<code>` child. No other arm changes; no new emoji (the guard in `tests/integration/test_api.py` strips precisely the pinned literals).
+3. `frontend/assets/shared.js` — `addToolLines`: the same suffix on the shared page's pinned-identical Reading line (the saved record carries the fields from task 02; a record without them renders exactly as today).
+- ASSUMPTION: the span is a SIBLING of the `<code>` child — the phase-95 truncation note is the precedent (it appends a span sibling and never rewrites the line's pinned template text).
+
+## Testing & Quality
+- Unit: covered by task 03's file (source pins + node behavior).
+- Coverage: n/a (frontend).
+
+## Completion Criteria
+- [ ] node repro: `appendToolLine` with `offset=42, limit=30` → the line's text is `📄 Reading <path> (lines 42–71)`; without the arguments → byte-identical to pre-task
+- [ ] `uv run pytest` green (the phase-87/117 pins + the emoji guard unedited); `uv run ruff check .` clean

.agents/phases/complete/139_read_range_tool_lines/02_live_restore_persist.md

@@ -0,0 +1,22 @@
+# Task 02 — Wire the range through live frames, persistence, and restore
+
+**Phase:** `139_read_range_tool_lines` · **Source:** `TODO.md:4` — "The \"Reading\" tool UI output doesn't show what lines are being read, just the same file over and over which is confusing to the user"
+**Story:** n/a
+
+## Objective
+The `offset`/`limit` already on the SSE `tool` frame (phase 131) reach the Reading line live, persist in the saved chat's `tools` record (additively), and re-render on restore — chat page + shared page.
+
+## Work
+1. `frontend/assets/app.js` — the live `tool` branch (~L3103): read `ev.offset` / `ev.limit` (the `Number.isInteger(x) && x >= 1` guard → `null` when absent / malformed); `toolAcc.push({ name, argument, offset, limit })` with the fields included ONLY when non-null (a non-range record keeps the exact pre-phase `{name, argument}` shape — the `bor.chat.v1` save JSONB is additive; old rows restore unchanged, no migration); pass both values to `appendToolLine`.
+2. `frontend/assets/app.js` — the status label (~L3125): `${brand()} is reading ${argument}${readRangeSuffix(offset, limit)}` (the grep / ls labels are untouched).
+3. `frontend/assets/app.js` — the restore path (~L2030): pass `t.offset` / `t.limit` (same guard) to `appendToolLine`; the phase-95 `appendTruncatedNote` call is untouched (it keys on the `<code>` argument).
+4. `frontend/assets/app.js` — the save-payload sites (L3229 / L3310 / L3361 / L3395) need no code change (they serialize `toolAcc` as-is) — verify the phase-83 save-payload-limit tests are unaffected by the two extra fields.
+
+## Testing & Quality
+- Unit: task 03's file (source pins for the `ev.offset`/`ev.limit` read, the `toolAcc` push shape, the restore pass-through).
+- Coverage: n/a (frontend).
+
+## Completion Criteria
+- [ ] a live range read: the line shows the suffix AND the status label shows it AND `toolAcc` carries `{name, argument, offset, limit}`
+- [ ] a saved chat restored (the `/?chat=<id>` path) + the shared page re-render the suffix; a pre-phase saved record (no fields) renders byte-identical
+- [ ] `uv run pytest` green (the chat-persistence / save-payload suites unedited)

.agents/phases/complete/139_read_range_tool_lines/03_unit_and_e2e.md

@@ -0,0 +1,23 @@
+# Task 03 — Unit pins, node behavior, mock flow, dedicated E2E
+
+**Phase:** `139_read_range_tool_lines` · **Source:** `TODO.md:4` — "The \"Reading\" tool UI output doesn't show what lines are being read, just the same file over and over which is confusing to the user"
+**Story:** n/a
+
+## Objective
+Pin the suffix contract at the source level, add the owner's "same file over and over" scenario to the deterministic mock, and prove it end-to-end in a dedicated Playwright file, run in isolation.
+
+## Work
+1. `tests/unit/test_read_range_tool_lines.py` (new) — the `test_frontend_tool_states.py` pattern: source pins (the ` (lines ${offset}–${offset + limit - 1})` / ` (from line …)` / ` (first … lines)` literals; the `Number.isInteger` guard; the live branch's `ev.offset` / `ev.limit` read; the `toolAcc` push carrying the fields; the restore pass-through; the shared.js identical literals) + node behavior (the three suffix shapes; the plain-read line byte-identical to pre-phase; the shared-page parity).
+2. `tests/e2e/mock_llm.py` — ONE new scripted flow (house style — a user-message marker, deterministic replies, a module-header docstring entry): the marker `read the same file twice` → round 1: a `read` tool call `(path, offset=10, limit=20)`; round 2: a `read` tool call `(path, offset=40, limit=15)`; round 3: the answer echoing both results (the phase-131 read-echo shape).
+3. `tests/e2e/test_read_range_tool_lines.py` (new) — dedicated, run in isolation (`--no-cov`, DB up), mock-only; a KB fixture with ONE multi-hundred-line document:
+   - (a) the marker question → assert TWO Reading lines for the SAME `<code>` path carrying the distinct suffixes ` (lines 10–29)` and ` (lines 40–54)`;
+   - (b) a plain-read flow (an existing mock flow with a `read` call and no range — e.g. the phase-131 plain-read case or the phase-37 flow) → assert the Reading line has NO `.read-range` span (byte-identical shape);
+   - (c) save the chat → restore (reload `/?chat=<id>`) → assert the suffixes re-render from the saved record.
+
+## Testing & Quality
+- Unit: as above. E2E: as above. Coverage: **>90%** on `app/` (the gate; no `app/` changes).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_read_range_tool_lines.py -v` green
+- [ ] `uv run pytest tests/e2e/test_read_range_tool_lines.py -v --no-cov` green in isolation
+- [ ] `uv run pytest` green, coverage TOTAL >90%, `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/140_pictorial_pdf_pages/00_phase.md

@@ -0,0 +1,58 @@
+# Phase 140 — Pictorial PDFs: sparse pages are rendered and vision-described into the indexed content
+
+**Source:** `TODO.md` L5 — "I've added a new \"ikea_instructions.tar\" to test_sources. This is an example pdf that stil isn't working. There isn't much text, it's mostly graphical, but it doesn't have pictures. Take a screenshot of the first page or pages 8 onward, it's mostly pictographic illustrations of how to assemble a piece of furniture. We need to support this kind of pdf, and in this case showing rendered pages of the pdf is more helpful than the extracted text. We need a way to determine when that's neccesary. My suggestion is to screenshot the pdf, generate a text summary, compare it to the text extraction, and if the screenshot contains more information (you can use an LLM to judge) use the screenshot or rendered page rather in addition to the extracted text. More information is better when generating the text embeddings since that increases the chance the user's search will hit something."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** the owner's fixture `test_sources/ikea_instructions.tar` (gitignored, on disk — the phase-133 convention: tests extract to `tmp_path`, never the repo): `besta-frame-white__AA-1272068-11-100.pdf`, 24 pages, metadata title "Assembly Instructions" (Adobe InDesign) — pages 2–5 are text-heavy (multilingual warnings, 3,091–7,288 chars), the other 20 pages are sparse (4–73 chars, `Illustration N` markers) and carry **vector-drawn** pictograms (PyMuPDF `get_image_info()` → 0 embedded raster images — the phase-122/137 embedded-image pipeline sees nothing). Today the file passes the phase-133 garbage gate (`is_usable_pdf_text` — the text is usable, just thin) and is indexed as ~24 KB of page markers → a question about the assembly steps never hits. `app/rag/pdf.py` — `PAGE_SEPARATOR = "---PAGE-{page}---"` (L57), `extract_pdf_text` (L153), `extract_pdf_page_texts` (L178 — the phase-137 `dict[int, str]` helper), `is_usable_pdf_text` (L225 — the phase-133 gate), `render_pdf_pages` (L267 — all pages at 150 dpi, the zero-byte unreadable-page placeholder), `extract_pdf_images` (L300). `app/rag/importer.py` — `_index_pdf_file` (L1140 — extract → the phase-133 gate + `_fallback_page_screenshots` → digest over the FINAL content → upsert + the unchanged early-return → chunk + embed → `lite` summary → embedded images), `ImportSummary` (L212 — stats counters + the `log()` line; stats are LOG-ONLY, the sync `detail` API shape never changes). `app/rag/summarizer.py` — the marker convention (L36-95: `IMAGE_DESCRIPTION_MODE` / `DESCRIBE_PROMPT`), `describe_image` (L208 — ONE chat-model vision call, the multimodal user message, the `context` param, fail-soft `str | None`, no app-level retry). `app/config.py` — the toggle pattern (`images: bool = False` L379 — `BOR_IMAGES`; the house kill-switch: `0` disables, a negative value fails startup loudly). `tests/e2e/mock_llm.py` — the `IMAGE_DESCRIPTION_MODE` branch (L2685) + the canned reply + the phase-137 trigger pattern (a new marker branch is additive — the existing suites stay green unedited). `tests/e2e/test_pdf_support.py` — the synthetic-PDF fixture recipe (PyMuPDF build) + the module-app pattern.
+
+## Objective
+A PDF whose pages are mostly pictorial (the IKEA assembly-instruction class) indexes with high-quality content: every sparse page (deterministic gate: stripped text below a threshold) is rendered to a screenshot and vision-described, and the description is appended to that page's content block — so the embeddings carry what the text layer couldn't and search hits the illustrations (the owner's L5 rationale: "More information is better when generating the text embeddings"). NO LLM judge (owner decision 2026-09-30) and NO page cap (PLAN A21 — the LLM calls are free; a slower sync is acceptable, a lower-quality KB is not).
+
+## Dependencies
+- `139_read_range_tool_lines` (todo) — pipeline order only; no code overlap (140 is backend import + the mock; 139 is the frontend tool line).
+- Code (all complete): phase 126 (the PDF pipeline), 133 (the garbage gate + `render_pdf_pages`), 137 (`extract_pdf_page_texts` + the vision seam).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The gate (task 01):** `app/rag/pdf.py` — `pictorial_pages(page_texts: dict[int, str], *, min_chars: int) -> list[int]`: the 1-based page numbers whose `len(text.strip()) < min_chars`, ascending — pure, deterministic, NO LLM call (ASSUMPTION A1). IKEA page 1 (`BESTÅ`, 5 chars) IS a candidate — a title page; describing it is useful (the logo + product name) and never harmful.
+- **The settings (task 01):** `app/config.py` — `pdf_pictorial: bool = True` (`BOR_PDF_PICTORIAL`, the house kill-switch — `0`/`false` disables the pass entirely → content byte-identical to pre-phase; the `BOR_IMAGES` naming pattern) + `pdf_pictorial_min_chars: int = 100` (`BOR_PDF_PICTORIAL_MIN_CHARS`; validator: ≥ 0 — 0 = every page is a candidate (A21), negative fails startup loudly, the house pattern).
+- **The vision seam (task 02):** `app/rag/summarizer.py` — `PICTORIAL_PAGE_MODE = "PICTORIAL_PAGE_MODE"` + `PICTORIAL_INSTRUCTION` (locked wording: describe in detail what the page shows — the assembly steps, part names, arrows, tool icons, before/after states — ESPECIALLY the information the extracted text does not contain) + `PICTORIAL_PROMPT = f"{PICTORIAL_PAGE_MODE}: {PICTORIAL_INSTRUCTION}"`; `describe_pdf_page(llm, *, data, mime, page, page_text) -> str | None` — the same one-chat-call multimodal contract as `describe_image` (no system prompt, no tools, no app-level retry, fail-soft `None`); the message text part = `PICTORIAL_PROMPT` + `\n\nPage {page} of the PDF. Text extracted from this page:\n{page_text.strip() or "(none)"}`. `DESCRIBE_PROMPT` / `IMAGE_DESCRIPTION_MODE` stay BYTE-IDENTICAL (the phase-122/126/137 suites pass unedited).
+- **The render selector (task 02):** `app/rag/pdf.py` — `render_pdf_pages(pdf_path, *, dpi=150, pages: Sequence[int] | None = None)`: `pages` (1-based) restricts rendering to the named pages in ascending order (a 500-page PDF with 30 sparse pages renders 30 PNGs, not 500); `None` = all pages — the phase-133 caller stays byte-identical.
+- **The import pass (task 03):** `_index_pdf_file` — AFTER the phase-133 gate (the precedence is locked: an unusable text layer takes the existing full-page screenshot fallback — NO pictorial pass, no double vision), when `settings.pdf_pictorial` and the content is usable:
+  1. `page_texts = extract_pdf_page_texts(full_path)`; `candidates = pictorial_pages(page_texts, min_chars=settings.pdf_pictorial_min_chars)` — **ALL candidates, no cap (A21)**; zero candidates → skip entirely (no render, no vision call — a clean-text PDF's path is byte-identical to pre-phase).
+  2. `render_pdf_pages(full_path, pages=candidates)` — a zero-byte placeholder page (unreadable) is skipped with a warning (the phase-133 handling).
+  3. each candidate in order: `describe_pdf_page(...)` fail-soft (`None` → skip that page, a warning log, continue — one dead page never kills the pass).
+  4. content assembly: every page 1..N as its `PAGE_SEPARATOR` + the page text + (when the page has a description: `\n\n[Page {n} illustration: {description}]`). The assembly with NO descriptions is byte-identical to `extract_pdf_text`'s output (a unit pin).
+  5. the digest over the FINAL content (the phase-126/133 convention — an unchanged file + a stable vision reply re-syncs as `unchanged`; a non-deterministic re-describe is a cost, not a bug — the phase-133 docstring documents it, A21 endorses it).
+  6. counters (stats log-only): `ImportSummary.pdfs_pictorial: int = 0` (a PDF with ≥1 described page) + `pdf_pictorial_pages: int = 0` (pages described) — `log()` fields only; the sync `detail` API shape is UNTOUCHED; ONE loud log line (PLAN §9): `pdf: pictorial pass source=<s> path=<p> — N candidate pages, M described (min_chars=<threshold>)`.
+- **The viewer:** the description renders as plain text in the document viewer (A4 — PDFs are served as extracted text; the `[Page N illustration: …]` line IS content). No viewer change.
+
+## Tasks
+1. `01_settings_and_gate.md` — `BOR_PDF_PICTORIAL` + `BOR_PDF_PICTORIAL_MIN_CHARS` + `pictorial_pages` + unit tests.
+2. `02_pictorial_vision_seam.md` — `PICTORIAL_PAGE_MODE` + `describe_pdf_page` + the `render_pdf_pages` page selector + the mock branch + unit tests.
+3. `03_importer_pictorial_pass.md` — the `_index_pdf_file` pass + counters/log + the real IKEA-fixture integration repro + the unit/integration matrix.
+4. `04_e2e_pictorial_pdf.md` — the dedicated Playwright suite, run in isolation, mock-only.
+
+## Testing & Quality
+- Unit: task 01 — `pictorial_pages` (threshold boundaries `<`/`=`/`>`, a whitespace-only page → a candidate, an empty dict → `[]`, ascending order); task 02 — `describe_pdf_page`'s message shape (a capturing fake LLM: `PICTORIAL_PROMPT` first, the page block after, the data URL; `None` on an empty reply / client error; the `DESCRIBE_PROMPT` byte-identity), the `render_pdf_pages` selector (subset order + count, `None` = all); task 03 — the assembly byte-identity + the branch matrix.
+- Integration: task 03 — the real IKEA tar through the REAL importer (the canned vision fake, capturing style): every candidate page (computed IN the test from `extract_pdf_page_texts` + `pictorial_pages` — no hardcoded page list) carries a `[Page N illustration: …]` block, the text-heavy pages (2–5) do NOT, the chunks carry the description, the title is "Assembly Instructions"; a re-sync with the same fake → `unchanged` (digest stable, zero added vision calls); a `BOR_PDF_PICTORIAL=0` module app → the content is byte-identical to `extract_pdf_text`.
+- E2E: `tests/e2e/test_pictorial_pdf.py` (new, task 04) — in isolation, mock-only.
+- Coverage: **>90%** on `app/`.
+
+## Completion Criteria
+- [ ] the owner's `ikea_instructions.tar` imports with described illustration blocks on every sparse page (the integration repro green — the owner's exact file)
+- [ ] a chat question about the assembly content is grounded on the described pages (the E2E)
+- [ ] a clean-text PDF never burns a vision call (the zero-candidates no-op is pinned) and a garbage-text PDF still takes the phase-133 fallback unchanged (the precedence pin)
+- [ ] `BOR_PDF_PICTORIAL=0` → the content is byte-identical to pre-phase
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, TOTAL >90%; `uv run pytest tests/e2e/test_pictorial_pdf.py -v --no-cov` green in isolation; the pre-existing `test_pdf_support.py` / `test_garbage_pdf.py` / `test_pdf_image_context.py` suites green unedited
+- [ ] `uv run ruff check . && uv run pyright` clean
+- [ ] one atomic Conventional Commits commit, `--no-gpg-sign`; phase dir moved to `.agents/phases/complete/`
+
+## Locked decisions
+- **A1 — sparse-page detection is the deterministic per-page character threshold (default 100, `BOR_PDF_PICTORIAL_MIN_CHARS`) — no LLM call in the gate (owner-confirmed 2026-09-30, roadmap confirmation).**
+- **A2 — NO LLM judge: every described sparse page's description appends to the content (owner-selected 2026-09-30).**
+- **A3 — no page cap, no call budget (PLAN A21); `BOR_PDF_PICTORIAL` kill-switch, default ON (owner-confirmed 2026-09-30).**
+- **A4 — the description appends to the page block as `[Page N illustration: …]`; the digest is over the final content (the phase-126/133 convention) (owner-confirmed 2026-09-30).**
+
+## Commit
+```bash
+git add app/ tests/ .agents/phases/ && git commit --no-gpg-sign -m "feat(import): pictorial PDF support — sparse pages rendered + vision-described into the indexed content"
+```

.agents/phases/complete/140_pictorial_pdf_pages/01_settings_and_gate.md

@@ -0,0 +1,20 @@
+# Task 01 — The kill-switch, the threshold setting, and the sparse-page gate
+
+**Phase:** `140_pictorial_pdf_pages` · **Source:** `TODO.md:5` — "…We need a way to determine when that's neccesary. …More information is better when generating the text embeddings since that increases the chance the user's search will hit something."
+**Story:** n/a
+
+## Objective
+Two settings (the feature toggle + the sparseness threshold) and the pure, deterministic function that selects a PDF's pictorial pages — the TODO's "a way to determine when that's necessary", with no LLM call.
+
+## Work
+1. `app/config.py` — `pdf_pictorial: bool = True` (env `BOR_PDF_PICTORIAL` — the house kill-switch: `0`/`false` disables the pictorial pass entirely; the `images` toggle's naming/docstring pattern at L379) + `pdf_pictorial_min_chars: int = 100` (env `BOR_PDF_PICTORIAL_MIN_CHARS`; a `field_validator`: ≥ 0 — 0 = every page is a candidate (PLAN A21), negative raises with the named field, the house fail-loud pattern). Document both in the `Settings` docstring convention and in `.env.example` (the comment-block pattern of the neighboring settings).
+2. `app/rag/pdf.py` — `def pictorial_pages(page_texts: dict[int, str], *, min_chars: int) -> list[int]`: the 1-based page numbers whose `len(text.strip()) < min_chars`, ascending — pure; the docstring carries the contract + the IKEA example (`{"1": "BESTÅ", "2": <7 KB of warnings>, "6": "Illustration 6"}` at `min_chars=100` → `[1, 6, …]`).
+- ASSUMPTION: the threshold is STRICTLY less-than — a page with exactly `min_chars` stripped chars is NOT sparse (the boundary is pinned in the tests).
+
+## Testing & Quality
+- Unit: `tests/unit/test_pictorial_gate.py` (new) — the validators (0 ok, 100 ok, −1 raises with the named field, the defaults — toggle on, 100) and `pictorial_pages` (the `<`/`=`/`>` boundary, a whitespace-only page → a candidate, an empty dict → `[]`, ascending order, a large dict).
+- Coverage: **>90%** on the new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_pictorial_gate.py -v` green
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/140_pictorial_pdf_pages/02_pictorial_vision_seam.md

@@ -0,0 +1,22 @@
+# Task 02 — The `PICTORIAL_PAGE_MODE` vision seam + the render selector
+
+**Phase:** `140_pictorial_pdf_pages` · **Source:** `TODO.md:5` — "…Take a screenshot of the first page or pages 8 onward… My suggestion is to screenshot the pdf, generate a text summary… use the screenshot or rendered page rather in addition to the extracted text."
+**Story:** n/a
+
+## Objective
+A dedicated, deterministic, fail-soft vision call for one rendered PDF page (the page's own text as context, so the model describes what the text does NOT) — plus the ability to render only the candidate pages of a large PDF.
+
+## Work
+1. `app/rag/summarizer.py` — `PICTORIAL_PAGE_MODE = "PICTORIAL_PAGE_MODE"` + `PICTORIAL_INSTRUCTION` (the locked wording from the phase overview's design) + `PICTORIAL_PROMPT = f"{PICTORIAL_PAGE_MODE}: {PICTORIAL_INSTRUCTION}"` — the marker convention next to `IMAGE_DESCRIPTION_MODE` (L75-95).
+2. `app/rag/summarizer.py` — `async def describe_pdf_page(llm, *, data: bytes, mime: str, page: int, page_text: str | None, settings: Settings | None = None) -> str | None` — the same one-chat-call multimodal contract as `describe_image` (L208): the user message `[{type: "text", text: PICTORIAL_PROMPT + "\n\nPage {page} of the PDF. Text extracted from this page:\n" + (page_text.strip() or "(none)")}, {type: "image_url", image_url: {url: <data URL from data + mime>}}]` — no system prompt, no tools, no app-level retry; an empty reply → `None` (the house one-shot empty-content policy); a client failure → `None` (fail-soft — one dead page never stalls a sync).
+3. `app/rag/pdf.py` — `render_pdf_pages(pdf_path, *, dpi: int = 150, pages: Sequence[int] | None = None)`: the optional 1-based selector — render only the named pages, ascending, one PNG each (an unreadable named page → the zero-byte placeholder at its position, as today); `None` = all pages — the phase-133 caller stays byte-identical (its existing tests pin it).
+4. `tests/e2e/mock_llm.py` — ONE new deterministic branch (house style + a module-header docstring entry): a chat request whose text part contains `PICTORIAL_PAGE_MODE` → the fixed canned reply `PICTORIAL_PAGE_ANSWER` (a distinctive, retrieval-friendly string, e.g. "Pictorial page: the illustration shows two parts being joined with an arrow.") — additive; the `IMAGE_DESCRIPTION_MODE` branch and every existing flow are untouched.
+
+## Testing & Quality
+- Unit: `tests/unit/test_pictorial_seam.py` (new) — a capturing fake LLM: the message shape (the text part starts with `PICTORIAL_PROMPT`, then the page block; the `"(none)"` case; the image part's data URL from the bytes + mime), `None` on an empty reply and on a client exception, the `DESCRIBE_PROMPT` byte-identity (regression pin — the string is untouched); `render_pdf_pages`' selector (the subset's count + order + PNG magic bytes, `None` = all — a ≥2-page fixture PDF, the phase-126/133 recipe).
+- Coverage: **>90%** on the new/modified code.
+
+## Completion Criteria
+- [ ] `uv run pytest tests/unit/test_pictorial_seam.py -v` green
+- [ ] `uv run pytest` green (the pre-existing vision suites — `test_image_documents.py` et al. — pass unedited)
+- [ ] `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/140_pictorial_pdf_pages/03_importer_pictorial_pass.md

@@ -0,0 +1,30 @@
+# Task 03 — The `_index_pdf_file` pictorial pass + the IKEA repro
+
+**Phase:** `140_pictorial_pdf_pages` · **Source:** `TODO.md:5` — "I've added a new \"ikea_instructions.tar\" to test_sources. This is an example pdf that stil isn't working… We need to support this kind of pdf, and in this case showing rendered pages of the pdf is more helpful than the extracted text… use the screenshot or rendered page rather in addition to the extracted text."
+**Story:** n/a
+
+## Objective
+The import pass itself: after the phase-133 garbage gate, a usable-text PDF's sparse pages are rendered + vision-described + appended to the page content — and the owner's exact IKEA file is pinned as an integration regression.
+
+## Work
+1. `app/rag/importer.py` — `_index_pdf_file` (L1140): after the existing phase-133 gate block (the precedence is locked — an unusable layer takes `_fallback_page_screenshots` and the pass NEVER runs), when `settings.pdf_pictorial`: `page_texts = extract_pdf_page_texts(full_path)`; `candidates = pictorial_pages(page_texts, min_chars=settings.pdf_pictorial_min_chars)`; zero candidates → skip entirely (no render, no vision — a clean-text PDF is byte-identical to pre-phase); otherwise render (`render_pdf_pages(full_path, pages=candidates)`, the zero-byte placeholder page skipped with a warning), describe each candidate (`describe_pdf_page`, fail-soft: `None` → a warning + skip the page), and assemble the content: every page = its `PAGE_SEPARATOR` + the page text + `\n\n[Page {n} illustration: {description}]` for the described pages — the assembly with NO descriptions is byte-identical to `extract_pdf_text`'s output (a pin).
+2. `app/rag/importer.py` — the digest over the FINAL content is the existing code (the pass runs before it, exactly as the phase-133 fallback does); the unchanged early-return, the chunk + embed, and the `lite` summary pipeline are untouched downstream.
+3. `app/rag/importer.py` — `ImportSummary` (L212): `pdfs_pictorial: int = 0` + `pdf_pictorial_pages: int = 0` — `log()` fields only (the stats log-only convention; the sync `detail` API shape is untouched) + ONE loud log line (PLAN §9): `pdf: pictorial pass source=<s> path=<p> — N candidate pages, M described (min_chars=<threshold>)`.
+4. `tests/integration/test_importer.py` (extend) — the IKEA repro (the phase-133 real-fixture convention: `test_sources/` is gitignored — extract the tar to `tmp_path`, never the repo; if the tar is absent the test fails loudly with a named message, the owner's machine always has it): run the REAL `import_sources` over the extracted PDF with a fake multimodal LLM (the canned per-page reply; a capturing fake that records every `PICTORIAL_PAGE_MODE` call):
+   - the candidates are computed IN the test from `extract_pdf_page_texts` + `pictorial_pages` (no hardcoded page list — the fixture is stable but the test must not rot);
+   - every candidate page's content block carries `[Page N illustration: <canned>]`; the text-heavy pages (2–5) carry NO block;
+   - the document's chunks carry the canned description (assert the string in the joined chunk text);
+   - the title is "Assembly Instructions" (the PDF metadata);
+   - a second `import_sources` run with the same fake → the file counts `unchanged` (digest stable, ZERO added vision calls);
+   - a `BOR_PDF_PICTORIAL=0` module app → the stored content == `extract_pdf_text`'s output (byte-identical);
+   - a garbage-text PDF (the phase-133 synthetic recipe) with `pdf_pictorial` ON → the phase-133 fallback fires (the content is the full-page descriptions), the pictorial pass does NOT run (the fake records zero `PICTORIAL_PAGE_MODE` calls) — the precedence pin.
+
+## Testing & Quality
+- Unit: `tests/unit/test_pictorial_import.py` (new) — the assembly byte-identity (no descriptions) + the branch matrix (feature off, zero candidates, a fail-soft `None` page, the unreadable-page placeholder skip) with a capturing fake LLM + the synthetic-PDF recipe (the `test_pdf_support.py` pattern).
+- Integration: the step-4 matrix above.
+- Coverage: **>90%** on the new/modified code.
+
+## Completion Criteria
+- [ ] the IKEA tar imports with a description block on every sparse page + `unchanged` on the re-sync (the repro green)
+- [ ] `uv run pytest tests/unit/test_pictorial_import.py -v` green
+- [ ] `uv run pytest` green, coverage >90%; `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/140_pictorial_pdf_pages/04_e2e_pictorial_pdf.md

@@ -0,0 +1,23 @@
+# Task 04 — The dedicated E2E (synthetic pictorial PDF, mock-only, in isolation)
+
+**Phase:** `140_pictorial_pdf_pages` · **Source:** `TODO.md:5` — "…in this case showing rendered pages of the pdf is more helpful than the extracted text… More information is better when generating the text embeddings since that increases the chance the user's search will hit something."
+**Story:** n/a
+
+## Objective
+One dedicated Playwright file, run in isolation (AGENTS.md rules 4/9), proves the owner's scenario end to end: upload a pictorial PDF → sync → the indexed content carries the described page → a chat question grounded on the illustration is answered.
+
+## Work
+1. `tests/e2e/test_pictorial_pdf.py` (new) — the `test_pdf_support.py` structure (synthetic-PDF module app, the admin upload flow): build a 2-page PDF with PyMuPDF (the recipe): page 1 = a 500+ char text paragraph; page 2 = an `Illustration 2` line + a drawn vector figure (a rectangle + an arrow — the sparse page); tar it → `POST /api/git-sources/upload` (202) → the Sync button → the document appears on the Sources page:
+   - (a) the document viewer's content shows the page-1 text WITHOUT an illustration block and page 2 WITH `[Page 2 illustration: <the mock's canned PICITORIAL_PAGE_ANSWER>]` (the task-02 `PICTORIAL_PAGE_MODE` branch — deterministic);
+   - (b) a chat question that ONLY the illustration answers (the canned reply names a distinctive phrase — the question: "How are the two parts joined on page two?") → the SSE completes without deflecting (the described page's embedding retrieves — the mock's deterministic token-overlap embeddings make the phrase → description hit) → the `done` event's `sources` includes the PDF and the answer echoes the phrase;
+   - (c) the sync response's `detail` JSON keeps its pre-phase keys (no new field — the stats log-only convention) — a cheap key-set assertion.
+2. No other file changes (the mock branch shipped in task 02).
+
+## Testing & Quality
+- E2E: this file, in isolation: `uv run pytest tests/e2e/test_pictorial_pdf.py -v --no-cov` (DB up: `podman compose up -d db`).
+- Coverage: **>90%** on `app/` (the phase gate runs the full suite in the final pass).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_pictorial_pdf.py -v --no-cov` green in isolation
+- [ ] the pre-existing `test_pdf_support.py` / `test_garbage_pdf.py` / `test_pdf_image_context.py` suites green unedited
+- [ ] full gate: `uv run pytest --cov=app --cov-report=term-missing` TOTAL >90%; `uv run ruff check . && uv run pyright` clean

.agents/phases/complete/141_read_range_dedupe_fix/00_phase.md

@@ -0,0 +1,51 @@
+# Phase 141 — `read` dedupe tells the truth: only fully-covered re-reads are refused
+
+**Source:** `TODO.md` L3 — "From a chat I was having, the LLM is trying to read different ranges of a document and keeps saying: 'The system is telling me the document is already in my context, but I haven't actually seen the full text of the Hail of Thorns spell entry. The read calls keep returning "Already in your context"…' This seems like a critical bug, fix it."
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/rag/agent.py` — `AgentHolder` (L1379+: `read_docs` / `read_truncations` / `shown_images` bookkeeping), `_execute_tool`'s `read` branch (L1512+: `_read_range_args` validation ~L1523, the dedupe `known` set ~L1539, the `truncated_shown` map ~L1548, the raw-arg fast path ~L1557, the range-read dedupe check ~L1577, the `read_docs` append ~L1600, the result shapes ~L1630+), the refusal texts `ALREADY_IN_CONTEXT` (L519), `REREAD_TRUNCATED` (L600), `OFFSET_PAST_END` (L616); `tests/unit/test_agent.py` (the read-branch unit suite — the phase-131 dedupe-matrix pins); `tests/e2e/mock_llm.py` (`_READ_RESULT_PREFIX` L1412 — the first-line header contract the mock parses), `tests/e2e/test_read_line_ranges.py` (the phase-131 flow). Root cause: `known` (the `read_docs` pair set) records ANY successful read — including a RANGE read — as if the FULL document were in context; the phase-131 matrix's "range read + doc in `known` + not truncated → `ALREADY_IN_CONTEXT`" row is false whenever the earlier read was a range (only the slice reached the model), so every attempt to read a DIFFERENT range is refused with a claim that the full text is in the prompt.
+**Locked (owner-confirmed 2026-09-30, chat):** coverage-tracking dedupe — a range read proceeds unless the requested lines are FULLY covered by earlier reads; a plain re-read of a partially-covered document gets the "you have lines a–b — read the rest with `offset`/`limit`" teaching instead of the false `ALREADY_IN_CONTEXT`.
+
+## Objective
+The agent stops dead-ending on multi-range documents: the holder tracks exactly WHICH line ranges of each document are in the model's context, the dedupe matrix refuses only genuinely-covered re-reads (now with a truthful claim), and the owner's stuck scenario — grep → read range A → read range B of the same document — completes with both ranges in context.
+
+## Dependencies
+- `140_pictorial_pdf_pages` (complete) — pipeline order only; code dependencies are the completed agent surface (phases 37/70/72/95/118/131/139).
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Coverage state (task 01):** `AgentHolder` gains `read_coverage: list[tuple[str, str, int, int]]` — one `(source, path, first_line, last_line)` record per covered span, in read order, keyed by the RESOLVED pair (the phase-131 `truncated_shown` keying lesson: the raw-arg split and the resolved pair are the same pair by the `_resolve_path` first-slash contract, L1229+). Coverage recording:
+  - a plain read at-or-under-cap covers `(1, total_lines)`;
+  - a truncated plain read (char cap) covers `(1, the number of lines in content[:cap])` (counted from the actual cut, not derived from the char count);
+  - a range read covers `(first, end)` — the TRUE extent the `lines: {first}-{end} of {total}` header already reports (an overshooting `limit` is clamped); a truncated range read covers `(first, the last line inside slice[:cap])` the same way.
+  `read_docs` / `read_truncations` keep their EXACT current meaning (API-layer signal, SSE matching, per-turn log) — the coverage list is NEW state beside them, not a replacement.
+- **Dedupe matrix (task 02)** — `covered(a, b)` = the requested span is contained in the union of that document's coverage records (merge overlapping/adjacent spans first; containment is per-line, inclusive):
+  | call | coverage of the doc | result |
+  |---|---|---|
+  | plain `read(path)` | empty | full read (unchanged) |
+  | plain `read(path)` | full doc covered (1–total) | `ALREADY_IN_CONTEXT` (byte-identical line) |
+  | plain `read(path)` | partial | NEW/retargeted teaching: the covered span(s) named, "read the rest with `offset`/`limit`" (the `REREAD_TRUNCATED` role — generalized: `REREAD_TRUNCATED` is RETIRED as the partial-plain-read line, its char-based copy replaced by the line-based one) |
+  | `read(path, offset, limit)` | empty | range read (unchanged) |
+  | `read(path, offset, limit)` | requested span fully covered | `ALREADY_IN_CONTEXT` — now TRUE (the named lines ARE in the prompt) |
+  | `read(path, offset, limit)` | not fully covered | range read PROCEEDS (the owner's stuck-scenario fix — includes the phase-131 truncated-then-range row, which the coverage state now covers: a truncated first read covers only its shown lines) |
+  The `BAD_RANGE_ARGS` and `OFFSET_PAST_END` refusals keep their exact firing order (before dedupe / after resolve respectively). The raw-arg fast path (no DB lookup) survives for the rows answerable from holder state alone (full-coverage plain re-read, fully-covered range — the `total_lines` for the latter's `OFFSET_PAST_END` still needs the resolve).
+- **Prompt consistency (task 02, step 4):** `TOOLS_SECTION`'s re-read sentence ("Do not re-read a document you have already read — its full text is already in your prompt") is re-cut to the coverage-true form (read-IN-FULL docs: don't re-read; PARTIAL docs — range/truncated reads: read the other parts with `offset`/`limit`). Without this the model is still taught the pre-phase rule and would not bother trying the second range that task 02 now allows.
+- **Repro (task 03):** unit matrix (every row above, incl. truncated variants and span-merge edges) + an integration test of the owner's scenario verbatim in spirit: one document, grep → read range A → read range B → both ranges' content reach the model, then a third read of range A is refused with `ALREADY_IN_CONTEXT`.
+- **E2E (task 04):** `tests/e2e/mock_llm.py` gains ONE scripted flow (house style — user-message marker, module-header docstring entry): the marker `read two ranges` → request 1 a `read(path, offset, limit)` call, request 2 a SECOND `read` with a DIFFERENT offset on the same doc, request 3 the answer echoing a marker line from the second range (proving the second slice reached the model). `tests/e2e/test_read_range_dedupe.py` (dedicated, in isolation, mock-only): a KB fixture with ONE large doc carrying two distinct marker lines far apart; ask the marker question → assert both `read` tool frames succeeded (no refusal in the result surface) and the final answer echoes the second marker line.
+
+## Tasks
+1. `01_coverage_tracking.md` — `AgentHolder.read_coverage` + the coverage recording in the read branch.
+2. `02_dedupe_matrix_rework.md` — the new matrix, the generalized partial-read teaching, `REREAD_TRUNCATED` retirement.
+3. `03_two_range_repro.md` — the full unit matrix + the owner-scenario integration repro.
+4. `04_e2e_mock_flow.md` — the mock `read two ranges` flow + the dedicated E2E file.
+
+## Testing & Quality
+- Unit: the full 6-row matrix with truncated variants; span-merge edges (adjacent, overlapping, contained, disjoint spans); coverage recording for all four read outcomes; the refusal-text pins; the fast-path no-DB rows.
+- Integration: the two-range repro (task 03) — the owner's stuck scenario end-to-end through `run_agent`'s loop.
+- E2E: one dedicated Playwright file, run in isolation, mock-only.
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] two DIFFERENT ranges of the same document both reach the model (the owner's bug is gone); a re-read of fully-covered lines is still refused — with a claim that is now true
+- [ ] a plain re-read of a partially-covered document gets the "read the rest with `offset`/`limit`" teaching (the false full-text claim is gone in BOTH refusal directions)
+- [ ] plain-read results at-or-under-cap and the phase-131 result shapes are byte-identical (the existing pins pass unchanged)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_read_range_dedupe.py -v --no-cov` green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases (the grep/ls surfaces, the truncation notice, the `read_docs`/`read_truncations` API signals)

.agents/phases/complete/141_read_range_dedupe_fix/01_coverage_tracking.md

@@ -0,0 +1,27 @@
+# Task 01 — coverage tracking: which lines of each document are actually in the model's context
+
+**Phase:** `141_read_range_dedupe_fix` · **Source:** `TODO.md:3` — "From a chat I was having, the LLM is trying to read different ranges of a document and keeps saying: 'The system is telling me the document is already in your context, but I haven't actually seen the full text of the Hail of Thorns spell entry. The read calls keep returning "Already in your context"…' This seems like a critical bug, fix it."
+**Story:** n/a
+
+## Objective
+`AgentHolder` records, per document, exactly which line spans a successful `read` put in the model's context — the state the reworked dedupe matrix (task 02) decides on. No dedupe behavior changes in THIS task (task 02 does that); this task only adds the recording, so the suite stays green throughout.
+
+## Work
+1. `app/rag/agent.py` — `AgentHolder` (L1379+): add `read_coverage: list[tuple[str, str, int, int]]` = one `(source, path, first_line, last_line)` record per covered span, in read order, keyed by the RESOLVED pair (the `_resolve_path` first-slash contract, L1229+ — the same pair `read_docs` keys on; the phase-131 `truncated_shown` keying comment ~L1546 is the precedent for why the raw-arg split and the resolved pair agree). Document the field on the dataclass docstring (the `read_truncations` doc-block style, L1386+): spans are inclusive line numbers over `content.splitlines()`; one span per SUCCESSFUL read (a refused read records nothing — the refusal style of every refusal: counts in nothing).
+2. `app/rag/agent.py` — the read branch's four successful outcomes record their span (the `total_lines`/`end`/`first` locals already exist at the record sites, ~L1610+):
+   - plain read at-or-under-cap (~L1655): `(1, total_lines)`;
+   - truncated plain read (~L1636): `(1, len(doc.content[:cap].splitlines()))` — counted from the ACTUAL cut string (the last visible line is the one ending at or before `cap`; `splitlines()` on the cut is the truth — do not derive a line count from the char count);
+   - range read at-or-under-cap (~L1686): `(first, end)` — the TRUE extent the `lines: {first}-{end} of {total}` header reports (an overshooting `limit` is already clamped at ~L1678);
+   - truncated range read (~L1668): `(first, the last line fully inside slice[:cap])` — `len(slice_text[:cap].splitlines())` added to `first - 1`, clamped to `end` (a cut mid-line means that line is NOT fully in context — the span ends at the last COMPLETE line).
+3. `tests/unit/test_agent.py` — unit tests: each of the four outcomes records exactly its span (assert the holder list after the call); a refused call (bad range args, unknown doc, offset past end, already-covered) records NOTHING; spans are keyed by the resolved pair (a doc read through its canonical `source/path` argument); existing `read_docs` / `read_truncations` assertions pass UNCHANGED (those signals are byte-identical).
+
+- ASSUMPTION: the covered-line count for a truncated read is computed from the cut string's `splitlines()` (inclusive, whole lines only) — a trailing cut line that ends exactly at `cap` counts as covered; the char cap is never re-derived into lines arithmetically. (The TODO item left the counting rule open; whole-line containment is what makes "fully covered" checkable per line.)
+
+## Testing & Quality
+- Unit: the four record sites + the five no-record refusals + resolved-pair keying (above); every pre-existing read-branch test passes unchanged.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] every successful read shape appends exactly one coverage span with the lines documented above; refusals append nothing
+- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed work (the holder's existing fields, the result strings, the SSE frames)

.agents/phases/complete/141_read_range_dedupe_fix/02_dedupe_matrix_rework.md

@@ -0,0 +1,40 @@
+# Task 02 — the dedupe matrix rework: refuse only what is truly already in context
+
+**Phase:** `141_read_range_dedupe_fix` · **Source:** `TODO.md:3` — "From a chat I was having, the LLM is trying to read different ranges of a document and keeps saying: 'The system is telling me the document is already in my context, but I haven't actually seen the full text of the Hail of Thorns spell entry. The read calls keep returning "Already in your context"…' This seems like a critical bug, fix it."
+**Story:** n/a
+
+## Objective
+The read branch decides dedupe from the coverage state (task 01) instead of the pair set alone: a range read proceeds unless its lines are fully covered, a plain re-read of a partially-covered document is taught the "read the rest" path, and `ALREADY_IN_CONTEXT` fires only when its claim is true.
+
+## Work
+1. `app/rag/agent.py` — a small coverage helper beside `_read_range_args` (L1490+): `covered_spans(records, source, path)` → the merged span list for one doc (merge overlapping/ADJACENT spans — `(1,10)+(11,20)` → `(1,20)` — so adjacency counts as continuous coverage), and `fully_covered(spans, first, last)` → bool (the requested span inside the merged union, per-line, inclusive). Pure functions over holder state — no DB.
+2. `app/rag/agent.py` — rework the read branch's dedupe (L1539+), keeping the firing ORDER of the other refusals:
+   - the `BAD_RANGE_ARGS` check stays FIRST (before any dedupe — a bad range arg is refused regardless of context, phase-131 contract);
+   - the raw-arg fast path is RETIRED: whether a span is "full" needs the document's `total_lines`, which only the resolve knows — so EVERY dedupe row resolves the doc first (one cheap indexed lookup; the pre-phase fast path's only saving was that one query, and the owner's bug — a false refusal costs a whole stuck turn — is what forces the trade). After the resolve: `total_lines = len(doc.content.splitlines())`, then the matrix below runs against `(doc.source, doc.path, total_lines)` and the coverage state. A fully-covered PLAIN re-read — the only row the old fast path handled — still refuses with the byte-identical `ALREADY_IN_CONTEXT`; its implementation just goes through the resolve.
+   - matrix (the phase-131 table in 00_phase.md is authoritative):
+     | call | coverage | result |
+     |---|---|---|
+     | plain | empty | full read (the existing at-or-under-cap / truncated paths, untouched bytes) |
+     | plain | full doc (a merged span == `(1, total_lines)`) | `ALREADY_IN_CONTEXT` (byte-identical line, L519) |
+     | plain | partial | the NEW teaching line (below) |
+     | range | empty | range read (existing bytes) |
+     | range | requested `(first, end)` fully covered | `ALREADY_IN_CONTEXT` |
+     | range | not fully covered | range read PROCEEDS (the owner's fix) |
+   - the `OFFSET_PAST_END` refusal (L616, firing after the resolve, before the matrix's range rows) stays where it is — an offset past the end is refused regardless of coverage.
+3. `app/rag/agent.py` — the partial-plain-read teaching: RETIRE `REREAD_TRUNCATED` (L600 — its char-based `{shown}` copy is replaced) and add `REREAD_PARTIAL`: one line, same refusal contract (counts in nothing, consumes a round, no re-emit), the covered span(s) named in line form and the working workflow pointed at: "You have lines {covered} of {source}/{path} in your context ({total} lines total). To read the rest, find where your text is with grep (it reports line numbers), then call read with `offset` (1-based first line) and `limit` (number of lines)." — `{covered}` renders the merged spans as comma-joined `a–b` pairs (one span → the bare `a–b`; a single line → `a`). The phase-131 truncated-then-plain-read scenario lands on THIS line now (a truncated first read covers a partial span) — same teaching role, line-based truth.
+4. `app/rag/prompts.py` — `TOOLS_SECTION`'s re-read sentence stays consistent with the new semantics: "Do not re-read a document you have already read — its full text is already in your prompt; answer directly from it." becomes the coverage-true form: do not re-read a document you have already read IN FULL — its full text is in the prompt, answer from it — but if you have read only PART of a document (a range read, or a truncated read), read the other parts with `offset`/`limit` — the document is not complete in your context until you have read it all. The sentence stays in its current position (the `read` clause); the mock keys off the `<tools>` marker's PRESENCE, not the wording (the phase-37 contract), so the mock is untouched. The HIGH prompt's byte-identity pins that assert the OLD sentence are re-pinned to the new one (the section's other bytes are unchanged).
+5. `tests/unit/test_agent.py` — re-pin the dedupe matrix (the phase-131 pins that asserted the OLD matrix's "range + known + not truncated → ALREADY_IN_CONTEXT" row are the ones that change — every other pin, incl. byte-identical result strings for plain reads, `BAD_RANGE_ARGS`, `OFFSET_PAST_END`, `MISSING_READ_ARGS`, the no-document refusals, passes unchanged):
+   - the 6 matrix rows × {truncated, non-truncated first read} where defined;
+   - the partial-plain-read line: span rendering (one span, multiple merged spans, a single line), `{total}` from the real doc;
+   - span-merge edges: adjacent spans merge (coverage contiguous), overlapping spans merge, disjoint spans stay separate (a gap → the requested span spanning the gap is NOT fully covered → proceeds);
+   - the fast-path retirement: a plain re-read of a fully-covered doc still refuses with the byte-identical `ALREADY_IN_CONTEXT` (the row's observable contract is unchanged; its implementation now resolves first).
+
+## Testing & Quality
+- Unit: the full matrix + edges above; the refusal-text pins (`ALREADY_IN_CONTEXT` byte-identical; `REREAD_PARTIAL` exact copy); the pre-existing read-branch suite minus the re-pinned rows.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] a range read of a document earlier read ONLY as a different range proceeds (the owner's bug); a range read of fully-covered lines is refused with `ALREADY_IN_CONTEXT`
+- [ ] a plain re-read of a partially-covered document gets `REREAD_PARTIAL` with the true covered span(s); `REREAD_TRUNCATED` no longer exists
+- [ ] every byte-identical pin that is NOT re-pinned in task 02's matrix changes passes unchanged; `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed work outside the documented matrix rows

.agents/phases/complete/141_read_range_dedupe_fix/03_two_range_repro.md

@@ -0,0 +1,26 @@
+# Task 03 — the owner's stuck scenario, proven: two ranges of one document both reach the model
+
+**Phase:** `141_read_range_dedupe_fix` · **Source:** `TODO.md:3` — "From a chat I was having, the LLM is trying to read different ranges of a document and keeps saying: 'The system is telling me the document is already in my context, but I haven't actually seen the full text of the Hail of Thorns spell entry. The read calls keep returning "Already in your context"…' This seems like a critical bug, fix it."
+**Story:** n/a
+
+## Objective
+The bug the owner hit is locked as a test: an agent turn that greps, reads range A of a large document, then reads range B — both ranges' content reach the model and the answer can cite both — and a third read of range A is refused with the (now true) `ALREADY_IN_CONTEXT`.
+
+## Work
+1. `tests/integration/` (the read-branch integration home — the phase-131 handbook repro lives in the unit/integration suite per `.agents/phases/complete/131_read_line_ranges/03_handbook_repro.md`; follow that file's fixture conventions) — the two-range repro:
+   - fixture: ONE text document, ≥ 200 lines, with two distinct marker lines far apart (marker A near line ~50, marker B near line ~150) — the document's content is GENERATED in the test (no binary fixture; the handbook repro is the separate phase-131 asset, untouched);
+   - settings: `read_max_chars` high enough that the FULL document is under the cap is NOT the point — run BOTH variants: (a) doc under the cap (the pure dedupe case — the pre-phase code refused range B with `ALREADY_IN_CONTEXT`), (b) doc over the cap with a truncated first plain read (the phase-131 row, now via coverage: the range B read proceeds, the plain re-read gets `REREAD_PARTIAL`);
+   - scripted fake LLM (the `tests/unit/test_agent.py` round-shape pattern): round 1 → `read(path, offset=1, limit=40)` (range A); round 2 → `read(path, offset=<marker B's line − 10>, limit=30)` (range B); round 3 → `read(path, offset=1, limit=40)` again (the exact re-covered range A); round 4 → the answer echoing BOTH marker lines (the read-echo convention — the model can only echo what reached it).
+   - asserts: round 2's result is the range-B slice (its `lines:` header + the marker-B line present — NOT a refusal); round 3's result is `ALREADY_IN_CONTEXT`; round 4's echoed answer contains BOTH markers (the bug: pre-phase, the echo could contain only marker A).
+2. `tests/unit/test_agent.py` — the matrix unit coverage from task 02 that is scenario-shaped rather than row-shaped: the adjacent-span edge as a scenario (two reads that together cover 1–100 of a 200-line doc → a plain re-read gets `REREAD_PARTIAL` naming `1–100`, and `read(offset=101)` proceeds).
+
+## Testing & Quality
+- Integration: the two-range repro (both variants) — the owner's scenario end-to-end through the agent loop.
+- Unit: the scenario-shaped matrix edges above.
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] the two-range repro passes: range B's slice reaches the model after range A; the exact re-read of range A is refused; the final answer echoes both markers
+- [ ] the truncated-variant passes: after a truncated first plain read, the range read proceeds and the plain re-read gets `REREAD_PARTIAL`
+- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed work (the repro is additive; no existing test file is modified)

.agents/phases/complete/141_read_range_dedupe_fix/04_e2e_mock_flow.md

@@ -0,0 +1,29 @@
+# Task 04 — the mock `read two ranges` flow + the dedicated E2E
+
+**Phase:** `141_read_range_dedupe_fix` · **Source:** `TODO.md:3` — "From a chat I was having, the LLM is trying to read different ranges of a document and keeps saying: 'The system is telling me the document is already in my context, but I haven't actually seen the full text of the Hail of Thorns spell entry. The read calls keep returning "Already in your context"…' This seems like a critical bug, fix it."
+**Story:** n/a
+
+## Objective
+The browser-visible proof: the deterministic mock LLM drives a two-range turn, and the dedicated Playwright file asserts that both `read` tool frames succeed and the final answer carries content from the SECOND range — the owner's stuck scenario, end-to-end through the SSE stream.
+
+## Work
+1. `tests/e2e/mock_llm.py` — ONE scripted flow, house style (a user-message marker; a module-header docstring entry like the phase-131 `read the lines` flow):
+   - marker: the user message contains `read two ranges`;
+   - request 1: a `read` tool call `{path: <the fixture doc>, offset: 1, limit: 100}`;
+   - request 2 (a `tool`-role read result whose FIRST line starts with `_READ_RESULT_PREFIX` (L1412) and which carries a `lines: 1-100 of …` header): a SECOND `read` tool call on the SAME doc with `{offset: 101, limit: 100}` — the pre-phase server would have answered the first read fine and refused the second; the flow only works if the second proceeds;
+   - request 3 (the second read result present — assert its `lines: 101-…` header to keep the mock's own keying honest): the answer "Both parts read." + the first 80 chars of the SECOND read result (the existing read-echo shape — the marker line lives in range B, so an echo of it proves the slice reached the model).
+2. `tests/e2e/test_read_range_dedupe.py` — dedicated Playwright file, run in isolation, mock-only (the house fixture conventions of `tests/e2e/test_read_line_ranges.py` — truncate/re-import per module, `?v=` asset pins, the SSE assertion helpers):
+   - the KB fixture: ONE large text document (> 100 lines; range A lines 1–100 carry marker line `TWO_RANGES_A_LINE` near line ~50, range B lines 101+ carry marker line `TWO_RANGES_B_LINE` near line ~150);
+   - test 1: ask the `read two ranges` question → collect the SSE frames → assert exactly the two `tool` frames (both `read`, the second carrying `offset: 101`), NO refusal surface in either tool result (the results carry the `lines:` headers, not `Already in your context`), and the final `done` answer contains `TWO_RANGES_B_LINE`'s text;
+   - test 2 (the still-refused row, browser-visible): a second scripted marker flow is NOT added — instead reuse the phase-131 `read the lines` flow's existing E2E expectations (they still pass: the single-range behavior is unchanged) and add a focused integration-level assertion in `tests/unit/test_agent.py` if the mock surface can't express a refusal cleanly — the E2E's job is the HAPPY two-range path; the refusal row is unit-pinned in tasks 02/03.
+
+## Testing & Quality
+- E2E: `uv run pytest tests/e2e/test_read_range_dedupe.py -v --no-cov` — green IN ISOLATION (DB up: `podman compose up -d db`), mock-only.
+- Regression: `tests/e2e/test_read_line_ranges.py` + `tests/e2e/test_read_range_tool_lines.py` + `tests/e2e/test_read_truncation_cap.py` still pass in isolation (the phase-95/131/139 contracts).
+- Coverage: **>90%** on this task's new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] the mock flow's second range read succeeds through the real server (no refusal) and the answer echoes the second range's marker line
+- [ ] `uv run pytest tests/e2e/test_read_range_dedupe.py -v --no-cov` green in isolation; the three pre-existing read E2E files still green in isolation
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed work (the mock's pre-existing flows are byte-identical; the new flow is additive)

.agents/phases/complete/142_kb_overview_freshness/00_phase.md

@@ -0,0 +1,36 @@
+# Phase 142 — the KB overview stays fresh: newest documents survive the cap, and the model is told the outline is partial
+
+**Source:** `TODO.md` L4 — "The agent is really struggling with questions like 'Summarize the last 10 phases of brain of Reese'. When I asked that to the current deployment it said 'I'll pull the details for the last 10 phases (104–113).' when it clearly had phase 137 loaded in the RAG… 'The <knowledge_base> section in the system prompt only generated summaries up to phase 113 at import time. The phases 128–137 exist as full markdown files… but their summaries weren't included in the initial KB index. This is a KB sync/generation gap, not a retrieval logic bug.'"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `app/rag/overview.py` — `regenerate_overview` (the document-list query `order_by(Document.source, Document.path)` ~L232, best-effort change-gated per the module docstring), `build_overview_prompt` (one line per doc `source — path — title — {first summary line}`, capped at `max_chars` with the shared `TRUNCATION_MARKER`), `load_kb_overview`; `app/config.py` L216 — `overview_input_max_chars` (`BOR_OVERVIEW_INPUT_MAX_CHARS`, default 40 000); `app/rag/prompts.py` — `_KB_INTRO` (L128–132: literally says "(generated at import time)") and `build_kb_section` (L399+); `app/api/sync.py` ~L590 — the overview regeneration gate (`summary.added + summary.updated > 0` — the sync IS change-gated correctly; the staleness is inside the generation, not the trigger); `tests/e2e/test_kb_overview.py` (the mock's `KB_OVERVIEW_MODE` digest = first 8 tokens of the document list — ORDER-DEPENDENT, must be re-pinned), `tests/integration/test_import_docs_overview.py` (the import-time trigger), `app/models.py` — `Document.created_at` (L123 — the DOCUMENT's date, phase 106: git-history/mtime-derived and owner-correctable, the same date the `read` result's `date:` line shows — the "when is this document from" signal, exactly what "the last N …" means). Root cause (traced): on the owner's 1 000-doc KB the document list is ≈100k+ chars; the 40k cap cuts a LEXICOGRAPHIC prefix (`order_by (source, path)` — "113_…" sorts before "128_…", and "131_…"–"140_" sort after "13_…"), so the newest phases never reach the lite model and the stored outline confidently describes a KB that ends mid-11x; the model then anchors "the last 10 phases" on that stale image.
+**Locked (owner-confirmed 2026-09-30, chat):** recency ordering (newest documents first so they survive the cap; the cap itself is unchanged) + the honest `<knowledge_base>` intro (drops "(generated at import time)"; tells the model the outline is compact/possibly partial and to verify "latest/complete" questions with `ls`/`grep` first). No map-reduce rewrite this phase.
+
+## Objective
+"Summarize the last 10 phases" stops being a guess: the overview's input is ordered newest-first so recent documents are the ones the outline covers when the cap bites, and the `<knowledge_base>` intro stops teaching the model that a partial outline is the whole KB — it now says the outline is a possibly-partial picture and points at `ls`/`grep` for "what's the latest / the complete set" questions.
+
+## Dependencies
+- `141_read_range_dedupe_fix` (todo) — pipeline order only; no code dependency.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **Ordering (task 02):** `regenerate_overview`'s query becomes `order_by(Document.created_at.desc(), Document.source, Document.path)` — newest documents FIRST (`created_at` is the document's date per phase 106 — the same date the `date:` line in a read result shows; the owner's phase-128–137 files carry newer git dates than the 113-era files, so they lead the list and survive the cap). The (source, path) secondary keys keep the tie-break deterministic for same-date docs (the common case within one commit/import — those fall back to the old lexicographic order, so same-date fixtures stay byte-identical). The cap (`BOR_OVERVIEW_INPUT_MAX_CHARS`, default 40 000) and the cap's cut+`TRUNCATION_MARKER` behavior are UNCHANGED (house truncation convention; the env knob stays the owner's lever). Zero other call-site changes: the sync's change-gate (task-31/32 trigger) already regenerates whenever the KB changes — the staleness was purely inside the list.
+- **Intro (task 03):** `_KB_INTRO` rewritten (it is a prompt constant — PLAN §4's convention: persona/prompt text changes ship with the phase's prompt tests; the `<knowledge_base>` TAG and the section's cap behavior in `build_kb_section` stay byte-stable): the outline is a COMPACT, possibly partial picture of the KB that favors RECENT documents — and for questions about the latest state or the complete set ("the last N …", "everything about …"), verify with `ls` (drill down) / `grep` before answering from the outline. One short paragraph, same tone as `SUGGEST_INTRO` (L152).
+- **Repro (task 01):** before any fix, a failing test proves the traced root cause: `build_overview_prompt` given a doc list whose joined lines exceed `max_chars` keeps the lexicographic FIRST lines and drops the last; and (integration) a KB where the newest docs' paths sort lexicographically LAST is regenerated with the pre-fix ordering → the stored outline (the mock's 8-token digest) names the OLD docs, not the new ones. The repro is written against the CURRENT code (red), then tasks 02/03 flip it green.
+- **E2E (task 04):** dedicated file — a fixture KB whose document count × line length exceeds a FORCED small cap (`BOR_OVERVIEW_INPUT_MAX_CHARS` set low via the E2E settings fixture) → regenerate through the mock → the stored outline's digest tokens come from the NEWEST document (recency ordering visible end-to-end through the real prompt path), and the served chat prompt's `<knowledge_base>` section carries the NEW intro copy (asserted from the echo path or the direct prompt-build surface — the phase-31 E2E already exposes the section to the UI via the first-bullet echo).
+
+## Tasks
+1. `01_cap_ordering_repro.md` — the red repro tests (unit: cap keeps the lexicographic prefix; integration: newest-sorting-last docs missing from the regenerated outline).
+2. `02_recency_ordering.md` — the `created_at.desc()` ordering + the order-dependent digest re-pins.
+3. `03_honest_kb_intro.md` — the `_KB_INTRO` rewrite + the prompt tests.
+4. `04_e2e_outline_freshness.md` — the dedicated E2E (forced cap → newest doc in the outline; the new intro served).
+
+## Testing & Quality
+- Unit: `build_overview_prompt` cap behavior unchanged (the cut + marker, the pathological budget); the new ordering (regeneration with mixed `created_at` docs → newest first; same-date tie-break by (source, path)); the intro copy pin.
+- Integration: the import-time trigger still regenerates exactly on KB change (the pre-existing `tests/integration/test_import_docs_overview.py` green); the repro flipped green.
+- E2E: one dedicated Playwright file, run in isolation, mock-only; `tests/e2e/test_kb_overview.py` (phase 31) green with re-pinned digest.
+- Coverage: **>90%** on new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] with the cap forced, the regenerated outline is built from the NEWEST documents (the 1 000-doc "ends at phase 113" failure mode is gone: the newest sort-last docs are the ones represented)
+- [ ] the served `<knowledge_base>` section carries the new honest intro (no "(generated at import time)"; the verify-with-`ls`/`grep` teaching present)
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` green, `app/` coverage >90%; `uv run pytest tests/e2e/test_kb_overview_freshness.py -v --no-cov` green in isolation; `tests/e2e/test_kb_overview.py` still green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases (the cap env knob, the change-gated trigger, the `build_kb_section` cap/marker behavior, the deflect path)

.agents/phases/complete/142_kb_overview_freshness/01_cap_ordering_repro.md

@@ -0,0 +1,26 @@
+# Task 01 — the red repro: the cap keeps a lexicographic prefix, so newest docs are the ones lost
+
+**Phase:** `142_kb_overview_freshness` · **Source:** `TODO.md:4` — "The agent is really struggling with questions like 'Summarize the last 10 phases of brain of Reese'. When I asked that to the current deployment it said 'I'll pull the details for the last 10 phases (104–113).' when it clearly had phase 137 loaded in the RAG… this is a KB sync/generation gap, not a retrieval logic bug."
+**Story:** n/a
+
+## Objective
+Lock the traced root cause as failing tests BEFORE the fix: `build_overview_prompt` cuts the document list at the cap keeping the FIRST lines (which, under the current `order_by (source, path)`, are the lexicographically first — NOT the newest), and a regeneration on a KB whose newest documents sort lexicographically LAST produces an outline that names the old documents. These tests are red on the current code and turn green in tasks 02/03.
+
+## Work
+1. `tests/unit/test_overview.py` (the phase-31 unit home — if the overview units live elsewhere, e.g. inside `tests/unit/test_agent.py`'s neighbors, use the existing file for `build_overview_prompt`'s pins) — the cap-ordering repro, unit level, no LLM:
+   - build 20 fake doc rows whose `source — path` prefixes are `s — 01_old_a.md` … `s — 20_new_z.md` (a path ordering that ALSO puts the "newest" last — the owner's phase-dir shape: names like `113_…` vs `128_…` vs `131_…`), each line ~100 chars, `max_chars=500` → the prompt's user message holds ONLY the first lines (assert: `01_old_a` present, `20_new_z` ABSENT, the `TRUNCATION_MARKER` line present — the current behavior pinned as-is);
+   - the assertion this task ADDS is the one that will flip: a helper-level check that documents the INTENT — the list reaching the model should lead with the NEWEST rows — written as the expected post-fix order (fails pre-fix).
+2. `tests/integration/test_import_docs_overview.py` (or its sibling for regeneration — the file that already drives `regenerate_overview` against the mock) — the KB-shape repro, integration level:
+   - a fixture KB shaped like the owner's: one source, folders/paths whose names sort lexicographically BEHIND their content's recency (e.g. an `old/…` batch + a `zz_new/…` batch whose paths sort LAST). The batches' `created_at` (the document date — phase 106 derives it from the file's mtime for a local fixture) must differ: set the files' mtimes (`os.utime`) before import so the old batch is genuinely older, OR update the old batch's `created_at` to a past date in a raw SQL step after import — the test owns its fixture, either seam is fine,
+   - regenerate through the mock `KB_OVERVIEW_MODE` (the 8-token digest of the document list, `tests/e2e/mock_llm.py` ~L2906) with a small `BOR_OVERVIEW_INPUT_MAX_CHARS` so the cap bites,
+   - assert the CURRENT failure: the stored outline's tokens come from the lexicographically-first (oldest) documents, NOT the newest — the exact "summaries only up to phase 113" shape, reproducible in a test.
+   - Mark both tests with the outcome they expect POST-fix (newest docs win); they FAIL now — that red is the repro. (Task 02 makes them green.)
+
+## Testing & Quality
+- Unit/integration: the two repro tests above — RED on the current code (asserted by running them in this task), green after task 02 (+ task 03 for the intro).
+- Coverage: **>90%** on this task's new/modified code (tests — coverage applies to `app/` as a whole).
+
+## Completion Criteria
+- [ ] the two repro tests exist and FAIL on the pre-fix code for the documented reason (lexicographic-prefix cap; oldest docs in the outline) — the failure output names the root cause
+- [ ] no application code changed in this task (the repro is tests-only)
+- [ ] the rest of `uv run pytest` stays green (the repro tests are the only new failures)

.agents/phases/complete/142_kb_overview_freshness/02_recency_ordering.md

@@ -0,0 +1,27 @@
+# Task 02 — recency ordering: newest documents first in the overview's input
+
+**Phase:** `142_kb_overview_freshness` · **Source:** `TODO.md:4` — "The agent is really struggling with questions like 'Summarize the last 10 phases of brain of Reese'. When I asked that to the current deployment it said 'I'll pull the details for the last 10 phases (104–113).' when it clearly had phase 137 loaded in the RAG… this is a KB sync/generation gap, not a retrieval logic bug."
+**Story:** n/a
+
+## Objective
+`regenerate_overview` builds the lite model's document list newest-first, so when `BOR_OVERVIEW_INPUT_MAX_CHARS` cuts the list, the documents that fall off are the OLDEST — and the outline (the model's a-priori KB picture) always represents the recent state of the KB. Task 01's red repro turns green.
+
+## Work
+1. `app/rag/overview.py` — `regenerate_overview`'s document-list query: `order_by(Document.created_at.desc(), Document.source, Document.path)`. Update the query's inline comment + the module docstring (the "one line per document" description): the ordering is RECENT-FIRST by the DOCUMENT's date (phase 106's `created_at` — git-history/mtime-derived, owner-correctable, `created_at_manual` rows included exactly as stored: the ordering reads the column, it never re-derives dates; the (source, path) tie-break keeps same-date docs in the old lexicographic order — deterministic for the mock's digest, and byte-identical for single-date fixtures). The cap, the cap's cut + `TRUNCATION_MARKER`, the zero-docs no-op, the `LLMError` fail-soft, the upsert — ALL unchanged.
+2. `tests/unit/test_overview.py` — the unit pins:
+   - the task-01 cap test flips: with mixed `created_at` rows (the row shape `(source, path, title, summary)` is order-agnostic — the ORDER comes from the query, so the unit test for the QUERY ordering goes against the DB: a small session with 6 docs in two `created_at` batches → the SELECT returns newest batch first, (source, path) within a batch),
+   - the byte-identical pins for `build_overview_prompt` itself are UNTOUCHED (it still receives rows in whatever order the caller passes — its contract is order-preserving; only the CALLER's order changes).
+3. `tests/integration/test_import_docs_overview.py` — the integration repro flips green: the second (newer) import batch's paths now lead the digest.
+4. Re-pin the ORDER-DEPENDENT digest expectations that assumed the old order (the mock's 8 tokens are the first document line's tokens — under recency-first that is now the NEWEST doc's line):
+   - `tests/e2e/test_kb_overview.py` — `test_mock_generated_outline_is_stored_and_echoed`'s expected digest (compute it from the fixture's newest document, not the lexicographic first — the test's fixture documents and their `created_at` values decide; the test seeds its row directly for tests 1–3, so only test 4's regeneration digest is order-sensitive),
+   - any other pin asserting a specific first line of a regenerated overview (grep the suite for the digest literal — re-pin where the KB has more than one document with differing `created_at`; single-batch fixtures where every doc shares a `created_at` stay byte-identical by the (source, path) tie-break).
+
+## Testing & Quality
+- Unit/integration: the ordering tests + the flipped repro (task 01) + the re-pinned digests.
+- Regression: the phase-31 `KB_OVERVIEW_MODE` branch in `tests/e2e/mock_llm.py` is UNCHANGED (it digests whatever list the app sends — the mock is order-agnostic by construction); `tests/e2e/test_kb_overview.py` green in isolation after the re-pins.
+- Coverage: **>90%** on this task's new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] task 01's two repro tests are GREEN (the newest documents lead the capped list; the outline represents the recent KB)
+- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run pytest tests/e2e/test_kb_overview.py -v --no-cov` green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases beyond the list ORDER (the cap env knob, the trigger gate, the fail-soft, the upsert, the mock's generation branch — all byte-identical)

.agents/phases/complete/142_kb_overview_freshness/03_honest_kb_intro.md

@@ -0,0 +1,26 @@
+# Task 03 — the honest `<knowledge_base>` intro: the outline is partial, and "latest" questions verify first
+
+**Phase:** `142_kb_overview_freshness` · **Source:** `TODO.md:4` — "The agent is really struggling with questions like 'Summarize the last 10 phases of brain of Reese'. When I asked that to the current deployment it said 'I'll pull the details for the last 10 phases (104–113).' when it clearly had phase 137 loaded in the RAG…"
+**Story:** n/a
+
+## Objective
+The model stops treating the outline as the KB's full, import-time-frozen inventory: `_KB_INTRO` says what the outline actually is (a compact, possibly partial picture that favors recent documents) and gives the one behavior that fixes the owner's question class — for "latest / complete set" questions, verify with the tools (`ls` drill-down / `grep`) before answering from the outline.
+
+## Work
+1. `app/rag/prompts.py` — rewrite `_KB_INTRO` (L128–132). Current: `"The basic categories of everything in this knowledge base (generated at import time):\n"`. New copy (short — the section is char-budgeted by `build_kb_section`; keep it 1–2 lines): the outline is a COMPACT picture of the knowledge base's categories and topics that FAVORS RECENT DOCUMENTS and may omit older or lesser ones — it is a map of what exists, not a complete inventory; for questions about the LATEST state or the COMPLETE set ("the last N …", "every …", "all the …"), verify with `ls` (drill into the folders) or `grep` before answering from the outline. The "(generated at import time)" phrase is GONE (it is false — the sync regenerates the row on KB change — and it taught the model to discount/freeze the section).
+2. `app/rag/prompts.py` — leave `build_kb_section` (L399+) byte-stable: same tag, same cap loop, same pathological-budget behavior — ONLY the intro constant changes. Update the constant's doc comment (the phase-31 note) with this phase's rationale in one line.
+3. Prompt tests — the house prompt-suite pins (`tests/unit/` — the file pinning `build_kb_section` / the HIGH prompt's section order, the phase-31 pins):
+   - the new intro copy pinned verbatim (the exact string),
+   - a no-overview prompt stays byte-identical to the pre-phase text (the phase-15 convention — the existing pin passes unchanged: an empty overview omits the whole section),
+   - the section's cap/marker behavior pins pass unchanged (the intro is inside the budget loop — a one-line-longer intro changes the pathological-budget edge only if a test pinned the exact cut against the OLD intro length; re-pin any such test to the new intro length — the BEHAVIOR is unchanged),
+   - the HIGH prompt's section-order pin (`<relevance>` → `<knowledge_base>` → `<tuning>` → body) passes unchanged.
+4. The deflect path is UNTOUCHED (the LOW prompt carries no `<knowledge_base>` section — the existing byte-identity pins pass as-is).
+
+## Testing & Quality
+- Unit: the intro copy pin; the section-build pins (cap, marker, pathological budget, empty-omission); the section-order pin.
+- Coverage: **>90%** on this task's new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] `_KB_INTRO` no longer contains "(generated at import time)"; it names the recency bias and the verify-with-`ls`/`grep` behavior (pinned verbatim)
+- [ ] `uv run pytest` green; `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases (the section's tag/cap/marker, the deflect prompt's byte-identity, the section order)

.agents/phases/complete/142_kb_overview_freshness/04_e2e_outline_freshness.md

@@ -0,0 +1,28 @@
+# Task 04 — the dedicated E2E: the regenerated outline leads with the newest document, and the new intro is served
+
+**Phase:** `142_kb_overview_freshness` · **Source:** `TODO.md:4` — "The agent is really struggling with questions like 'Summarize the last 10 phases of brain of Reese'. When I asked that to the current deployment it said 'I'll pull the details for the last 10 phases (104–113).' when it clearly had phase 137 loaded in the RAG…"
+**Story:** n/a
+
+## Objective
+The browser-visible proof of the whole phase: with the cap forced to bite, a sync-path regeneration produces a stored outline whose digest comes from the NEWEST document (recency ordering, end-to-end through the real prompt path), and the served chat prompt's `<knowledge_base>` section carries the new honest intro.
+
+## Work
+1. `tests/e2e/test_kb_overview_freshness.py` — dedicated Playwright file, run in isolation, mock-only (the house conventions of `tests/e2e/test_kb_overview.py` — per-module truncate/re-import, the settings override fixture, the login helper, the SSE echo assertions):
+   - fixture: one source, TWO batches of documents whose document DATES differ (the old batch's files get past mtimes via `os.utime` before import, the new batch is current — phase 106's mtime fallback for local sources; the new batch's PATHS sort lexicographically LAST, e.g. `old/a.md`… vs `zz_new/z.md` — so the pre-fix lexicographic order and the post-fix recency order disagree about which document is first),
+   - settings: `BOR_OVERVIEW_INPUT_MAX_CHARS` set small enough (via the E2E settings override) that the document list is CUT — the cap must bite or the ordering is unobservable;
+   - test 1 (`test_regenerated_outline_leads_with_newest_doc`): import, then drive the regeneration through the mock the same way `test_kb_overview.py` test 4 does (the real `regenerate_overview` against the mock's `KB_OVERVIEW_MODE` digest) → the stored `kb_overview` row's 8 digest tokens come from the NEWEST batch's first (recency-ordered) line — assert the exact tokens (computed from the fixture in the test, not hardcoded wording);
+   - test 2 (`test_kb_section_carries_honest_intro`): the intro is a prompt constant — the deterministic surface is the section builder itself, called IN the E2E file the same way this file already calls `regenerate_overview`/`build_overview_prompt` directly against the app (the phase-31 file's own convention): `build_kb_section(<a seeded multi-line outline>)` → assert the section's lead line IS the new intro verbatim (no "generated at import time"), the tag + cap behavior intact; the UI injection path (the section reaching a rendered turn) is the phase-31 first-bullet echo, which a third lightweight test re-asserts here against the SEEDDED row so this file stands alone on the injection surface too;
+   - the pre-existing phase-31 file is NOT modified here (its re-pins landed in task 02).
+2. Run the regression set in isolation (each file its own run — the suite-isolation contract): `test_kb_overview_freshness.py` (new), `test_kb_overview.py` (phase 31, task-02 re-pins).
+
+## Testing & Quality
+- E2E: `uv run pytest tests/e2e/test_kb_overview_freshness.py -v --no-cov` — green IN ISOLATION (DB up: `podman compose up -d db`), mock-only.
+- Integration: the intro-observation fallback (if test 2 takes the `build_kb_section` surface) lives in the unit/integration suite, not the E2E.
+- Coverage: **>90%** on this task's new/modified code (`app/`).
+
+## Completion Criteria
+- [ ] with the cap biting, the regenerated outline's digest tokens come from the NEWEST document (the owner's "ends at phase 113" shape is impossible — the newest docs lead)
+- [ ] the new intro copy is pinned verbatim as the section's lead line (the `build_kb_section` surface), and the section still reaches a rendered turn (the phase-31 echo path)
+- [ ] `uv run pytest tests/e2e/test_kb_overview_freshness.py -v --no-cov` green in isolation; `tests/e2e/test_kb_overview.py` still green in isolation
+- [ ] `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases (the phase-31 injection path, the mock's generation branch)

.agents/phases/complete/143_mobile_keyboard_after_answer/00_phase.md

@@ -0,0 +1,32 @@
+# Phase 143 — the mobile keyboard stays down after an answer completes
+
+**Source:** `TODO.md` L5 — "mobile keyboard pops back up after answer is complete and that's annoying"
+**Story:** n/a (TODO-derived phase, Protocol B append).
+**Context:** `frontend/assets/app.js` — the turn's `finally` block (~L3478–3493): `// done | error | stop → idle: always settle, always focus back.` … `input.focus({ preventScroll: true })` (L3492) — EVERY turn end (done, error, stop) re-focuses the composer; on a phone, focusing the textarea pops the virtual keyboard the moment the answer completes (the owner's annoyance). The existing `matchMedia` precedent in the file (L391: `reducedMotion` for `prefers-reduced-motion` — the module-level-constant shape); `tests/unit/test_frontend_scroll.py` — `test_turn_end_focus_does_not_scroll` (L213+: the source-level pin that the finally block contains the `preventScroll` focus line — must be EXTENDED, not broken); the composer is a ≥44px tap target on mobile (PLAN §7.1).
+**Locked (owner-confirmed 2026-09-30, chat):** desktop-only refocus — the post-turn focus-back is skipped on coarse-pointer devices (`matchMedia("(pointer: coarse)")`), kept on desktop so the next question can be typed immediately.
+
+## Objective
+A phone user reads the completed answer with the keyboard DOWN: the composer is only re-focused at turn end on fine-pointer (desktop) devices; a coarse-pointer device stays unfocused (the next question starts with a tap on the ≥44px composer). Desktop behavior — including the never-scroll focus contract — is byte-identical.
+
+## Dependencies
+- `142_kb_overview_freshness` (todo) — pipeline order only; no code dependency.
+
+## Design (shared by all tasks — the executor reads this, not the chat)
+- **The gate (task 01):** a module-level constant beside the existing `reducedMotion` one (app.js ~L391): `const COARSE_POINTER = typeof matchMedia === "function" && matchMedia("(pointer: coarse)").matches;` (the L391 shape — the `typeof` guard keeps the constant safe where `matchMedia` is absent, the house style for the reduced-motion line). The finally block's focus line becomes GATED: `if (!COARSE_POINTER) input.focus({ preventScroll: true });` with a phase-143 comment explaining WHY (the keyboard pop) and the §7.1 tap-target note. The `preventScroll` argument and the never-scroll contract (phase 42 / the `test_turn_end_focus_does_not_scroll` intent) are UNCHANGED on desktop; the error/stop paths take the SAME gate (one focus line, one gate — the finally block is the single settle).
+- **The pin (task 01):** `tests/unit/test_frontend_scroll.py::test_turn_end_focus_does_not_scroll` is EXTENDED: the finally block still contains the `preventScroll` focus call (now inside the `if (!COARSE_POINTER)` guard) and the `COARSE_POINTER` constant is defined from `matchMedia("(pointer: coarse)")` — the pin asserts the GATED shape (a bare ungated `input.focus(...)` line in the block is a failure, as today).
+- **The E2E (task 02):** dedicated file, two contexts — desktop (default Chromium, no touch) and mobile (a Playwright device descriptor with `isMobile` + `hasTouch` — the descriptor's touch emulation makes Chromium report `pointer: coarse`). Each context: a mock-LLM turn to completion (the house E2E fixture — a single on-topic question, the done state, the same assertions as the chat story files), then assert `document.activeElement` — desktop: the composer's textarea (the phase-06 "always focus back" contract, preserved); mobile: NOT the composer (the keyboard stays down). A sanity assert in the mobile test: `page.evaluate(() => matchMedia("(pointer: coarse)").matches)` is true (the emulation is doing its job — if a future Playwright/Chromium change breaks the emulation, the test fails LOUDLY on the sanity line, not mysteriously on the focus line).
+
+## Tasks
+1. `01_coarse_pointer_focus_gate.md` — the constant + the gated focus line + the extended source pin.
+2. `02_e2e_mobile_focus.md` — the dedicated two-context E2E.
+
+## Testing & Quality
+- Unit: the extended source-level pin (the gated focus shape; the constant definition); every other `app.js` pin passes unchanged.
+- E2E: one dedicated Playwright file, run in isolation, mock-only (desktop + mobile contexts).
+- Coverage: **>90%** on new/modified code (this phase is frontend — the `app/` coverage gate is unaffected and must stay green).
+
+## Completion Criteria
+- [ ] desktop: after a turn ends (done, error, stop), the composer is focused with `preventScroll` — byte-identical to pre-phase
+- [ ] mobile (coarse pointer): after a turn ends, the composer is NOT focused — the keyboard stays down; the user's tap starts the next question
+- [ ] `uv run pytest` green (the extended pin passes); `uv run pytest --cov=app --cov-report=term-missing` — `app/` coverage >90%; `uv run pytest tests/e2e/test_mobile_keyboard_focus.py -v --no-cov` green in isolation; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed phases (the never-scroll focus contract on desktop, the stop path's single settle, the char counter, the send flow)

.agents/phases/complete/143_mobile_keyboard_after_answer/01_coarse_pointer_focus_gate.md

@@ -0,0 +1,38 @@
+# Task 01 — the coarse-pointer gate on the post-turn focus-back
+
+**Phase:** `143_mobile_keyboard_after_answer` · **Source:** `TODO.md:5` — "mobile keyboard pops back up after answer is complete and that's annoying"
+**Story:** n/a
+
+## Objective
+The turn's `finally` block re-focuses the composer only on fine-pointer devices: a coarse-pointer (mobile) turn end leaves the page unfocused, so the virtual keyboard does not pop back up over the completed answer.
+
+## Work
+1. `frontend/assets/app.js` — beside the existing reduced-motion constant (~L391: `const reducedMotion = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;`), add the twin constant: `const COARSE_POINTER = typeof matchMedia === "function" && matchMedia("(pointer: coarse)").matches;` — a short phase-143 comment: the coarse-pointer state of THIS device (touch phones/tablets), the keyboard-pop gate for the turn-end focus-back.
+2. `frontend/assets/app.js` — the turn's `finally` block (~L3478–3493): the last line `input.focus({ preventScroll: true });` becomes:
+   ```js
+   // Phase 143 (TODO L5): the focus-back is a DESKTOP courtesy — on a
+   // coarse pointer (a phone/tablet) focusing the composer pops the
+   // virtual keyboard over the completed answer, which is exactly what
+   // the owner found annoying. Fine pointers keep the immediate
+   // refocus (type the follow-up without moving a hand); a coarse
+   // pointer stays unfocused — the composer is a ≥44px tap target
+   // (PLAN §7.1), so the next question starts with a tap. The
+   // never-scroll contract (phase 42) and the single-settle rule are
+   // unchanged on every device — only the focus call is gated.
+   if (!COARSE_POINTER) input.focus({ preventScroll: true });
+   ```
+   The comment above the line ("Focus back for the next question, but never move the viewport…") is folded into the phase-143 comment (one comment block, no stale duplicate). The block's SETTLE lines (clearTurnTimeout / stopThinkingClock / cancelStream / setUiState / the stop status line) are UNTOUCHED — the gate wraps the focus call alone.
+3. `tests/unit/test_frontend_scroll.py` — EXTEND `test_turn_end_focus_does_not_scroll` (L213+):
+   - the finally block (located by the existing `// done | error | stop → idle: always settle, always focus back` anchor — KEEP the anchor comment in app.js verbatim or update the anchor in lockstep) now asserts the GATED shape: `if (!COARSE_POINTER) input.focus({ preventScroll: true })` is in the block, and a bare ungated `input.focus(` occurrence (the pre-phase line) is NOT,
+   - and the constant: `matchMedia("(pointer: coarse)")` appears in the file with the `COARSE_POINTER` binding (the L391-twin shape),
+   - the docstring is updated to state the phase-143 gate (the pin's job is now: focus-back exists, is preventScroll, and is coarse-gated).
+
+## Testing & Quality
+- Unit: the extended pin + every other frontend source pin green (`uv run pytest tests/unit/ -k frontend`).
+- Coverage: **>90%** on new/modified code (frontend — the `app/` gate stays green: `uv run pytest --cov=app`).
+
+## Completion Criteria
+- [ ] desktop (fine pointer): the turn end focuses the composer with `preventScroll` — the phase-06/42 contract byte-preserved
+- [ ] coarse pointer: the turn end does NOT focus the composer (the keyboard stays down)
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean
+- [ ] no behavior change in completed work (the settle lines, the error/stop paths, the char counter, the send flow — the gate wraps the focus call alone)