fix(web): history tab copy — every chat saves automatically, there is no Save button

meta description -> locked (A3) auto-save string (history.html L6). page-sub -> locked (A3) string, the <strong>Save</strong> emphasis retired with the button (L106-109). empty row -> locked (A3) string; colspan=6, hidden, and row id untouched (L163). h1, the anonymous gate section, and history.js are byte-identical — state language verified accurate.
feat(web): move the chat action cluster to the pinned bottom and align the button sets
2026-09-02 01:29:42 -04:00 · 2026-09-02 01:08:18 -04:00 · 2026-09-01 23:51:43 -04:00 · 2026-09-01 20:15:08 -04:00 · 2026-09-01 19:53:56 -04:00 · 2026-09-01 19:27:31 -04:00
160 changed files with 8786 additions and 609 deletions
@@ -0,0 +1,54 @@
+# Phase 63 — Unambiguous Document Listing for Agent Tools
+
+**Source:** Live troubleshooting report (2026-09-01) — the `brain-of-reese` agent at `https://brain.experimental.reeseapps.com/` cannot read documents because the `list_documents` tool output uses an ambiguous `source/path — title` format that the LLM cannot reliably parse when paths contain `/` characters.
+
+**Story:** `.agent/user_stories/agent-document-tools.md` (phase 37, extended)
+
+**Context:** The agent's grounded-turn loop uses two tools: `list_documents` (returns the catalog) and `read_document` (reads one document). The catalog output is formatted as `source/path — title` (one line per document), but when a file lives inside a subdirectory of its source, the output looks like `brain-of-reese-main/homelab/aws-route53.md — aws-route53`. The LLM cannot reliably determine where `source` ends and `path` begins because both contain `/` separators. The thinking trace shows the LLM cycling through multiple failed attempts, each time guessing a different split.
+
+The fix changes the catalog format to unambiguous `source: X | path: Y | title: Z` lines and updates the tool descriptions to tell the LLM how to parse them.
+
+## Objective
+
+The agent can always extract the correct `(source, path)` pair from the `list_documents` output, regardless of how many `/` characters the path contains.
+
+## Dependencies
+
+- `62_ui_customization` (todo, preceding — functional: no code changes in this phase touch UI or config)
+
+## Tasks
+
+1. `01_agent_list_format.md` — change `list_catalog` output from `source/path — title` to `source: X | path: Y | title: Z`; update the `read_document` tool descriptions to reference the new format.
+2. `02_mock_and_unit_tests.md` — update `tests/e2e/mock_llm.py::_catalog_docs` to parse the new format; update `tests/unit/test_agent.py` (the "No document at" refusal line is unchanged — it names the lookup failure, not the list format).
+3. `03_e2e_document_tools.md` — validate that `tests/e2e/test_agent_document_tools.py` and `tests/e2e/test_agent_unlimited_tools.py` still pass (they assert on SSE frames and UI rendering, not on the catalog text format — the tool call `argument` field `source/path` is unchanged).
+4. `04_docs.md` — update any inline documentation that references the old format.
+
+## Testing & Quality
+
+- Unit: `tests/unit/test_agent.py` — the "No document at" refusal message is unchanged (it reports the lookup failure, not the list format). The `_catalog_docs` mock parsing must produce identical `(source, path)` tuples for all existing test catalogs.
+- Integration: `tests/integration/test_agent_tools.py` — `list_catalog` ordering assertions are unchanged (the function returns `[(source, path, title), ...]` tuples; only the string formatting in `_execute_tool` changes).
+- E2E (mandatory, house rule): `tests/e2e/test_agent_document_tools.py` and `tests/e2e/test_agent_unlimited_tools.py` run in isolation — the SSE `argument` field (`source/path`) is unchanged; the mock's `_catalog_docs` parsing produces identical results; the tool lines and source chips render identically.
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+
+- [ ] `list_catalog` output uses `source: X | path: Y | title: Z` format — verifiable by a unit test that patches `list_catalog` and checks the formatted string.
+- [ ] The `read_document` tool descriptions tell the LLM to extract `source` and `path` from the `source:` / `path:` labels.
+- [ ] `tests/e2e/mock_llm.py::_catalog_docs` parses the new format and produces identical `(source, path)` tuples for all existing test catalogs.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_agent_document_tools.py tests/e2e/test_agent_unlimited_tools.py -v --no-cov` green in isolation (DB up).
+- [ ] Regression E2E suites green in isolation: `test_chat_api.py`, `test_sse_events.py`, `test_whole_document_context.py`.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/` (`.agent/` stays untracked).
+
+## Locked decisions
+
+- **Owner-locked (2026-09-01, troubleshooting report, A1):** the new format uses `source: X | path: Y | title: Z` — one line per document, pipe-delimited fields, no ambiguity even with deeply nested paths.
+- **Owner-locked (2026-09-01, troubleshooting report, A2):** the `read_document` tool descriptions are updated to reference the new format (tell the LLM how to parse `source:` and `path:` labels).
+- **Owner-locked (2026-09-01, troubleshooting report, A3):** the SSE `argument` field (`source/path`) is unchanged — it is the tool call argument, not the list output. The frontend tool-line rendering is unchanged.
+- **Owner-locked (2026-09-01, troubleshooting report, A4):** the "No document at …" refusal message is unchanged — it reports the lookup failure, not the list format.
+
+## Commit
+
+```bash
+git add app/ tests/ && git commit --no-gpg-sign -m "fix(agent): unambiguous document listing format for LLM parsing"
+```
@@ -0,0 +1,75 @@
+# Task 01 — Change `list_catalog` output format + update tool descriptions
+
+**Goal:** Make the `list_documents` catalog output unambiguous for LLM parsing, and update the `read_document` tool descriptions to tell the LLM how to extract `source` and `path`.
+
+## Changes
+
+### `app/rag/agent.py`
+
+#### 1. Change `list_catalog` output format
+
+In `_execute_tool`, the `list_documents` handler formats the catalog as:
+
+```python
+# BEFORE (ambiguous when path contains /)
+listing = f"{len(rows)} documents:\n" + "\n".join(
+    f"{source}/{path} — {title}" for source, path, title in rows
+)
+```
+
+Change to:
+
+```python
+# AFTER (unambiguous — each field is labeled)
+listing = f"{len(rows)} documents:\n" + "\n".join(
+    f"source: {source} | path: {path} | title: {title}"
+    for source, path, title in rows
+)
+```
+
+#### 2. Update `read_document` tool descriptions
+
+In `AGENT_TOOLS`, update the `source` and `path` parameter descriptions to reference the new format:
+
+```python
+# BEFORE
+"source": {
+    "description": (
+        "The document's source (a directory basename, e.g. 'Homelab')."
+    ),
+},
+"path": {
+    "description": (
+        "The document's path relative to its source directory."
+    ),
+},
+
+# AFTER
+"source": {
+    "description": (
+        "The document's source, as shown after 'source: ' in the "
+        "list_documents output (e.g. 'Homelab' from "
+        "'source: Homelab | path: homelab/aws-route53.md')."
+    ),
+},
+"path": {
+    "description": (
+        "The document's path, as shown after 'path: ' in the "
+        "list_documents output (e.g. 'homelab/aws-route53.md' from "
+        "'source: Homelab | path: homelab/aws-route53.md')."
+    ),
+},
+```
+
+### `app/rag/prompts.py`
+
+No changes needed — the prompt text references the tool names but not the output format.
+
+## Files changed
+
+- `app/rag/agent.py` — `list_catalog` formatting + `AGENT_TOOLS` descriptions
+
+## Verification
+
+- `uv run pytest tests/unit/test_agent.py -v --no-cov` — the tool shape tests (`test_agent_tools_names_and_parameters`) check the description strings, so they must be updated to match.
+- `uv run ruff check app/rag/agent.py && uv run pyright app/rag/agent.py` — lint + types clean.
@@ -0,0 +1,85 @@
+# Task 02 — Update mock parsing + unit tests for the new format
+
+**Goal:** Update `tests/e2e/mock_llm.py::_catalog_docs` to parse the new `source: X | path: Y | title: Z` format, and update `tests/unit/test_agent.py` to match the new tool descriptions.
+
+## Changes
+
+### `tests/e2e/mock_llm.py` — `_catalog_docs` function
+
+The current parsing uses `head.rpartition("/")` on the `source/path` head:
+
+```python
+# BEFORE
+def _catalog_docs(body: dict[str, Any]) -> list[tuple[str, str]]:
+    docs: list[tuple[str, str]] = []
+    for m in _messages(body):
+        if m.get("role") != "tool":
+            continue
+        content = str(m.get("content") or "")
+        if content.startswith(_READ_RESULT_PREFIX):
+            continue
+        for line in content.splitlines():
+            head = line.split(" — ", 1)[0].strip()
+            if "/" in head:
+                source, _, path = head.rpartition("/")
+                if source and path:
+                    docs.append((source, path))
+    return docs
+```
+
+Change to parse the new labeled format:
+
+```python
+# AFTER
+def _catalog_docs(body: dict[str, Any]) -> list[tuple[str, str]]:
+    docs: list[tuple[str, str]] = []
+    for m in _messages(body):
+        if m.get("role") != "tool":
+            continue
+        content = str(m.get("content") or "")
+        if content.startswith(_READ_RESULT_PREFIX):
+            continue
+        for line in content.splitlines():
+            # New format: "source: X | path: Y | title: Z"
+            if not line.startswith("source: "):
+                continue
+            parts = line.split(" | ", 2)
+            if len(parts) < 3:
+                continue
+            source = parts[0].removeprefix("source: ").strip()
+            path_part = parts[1]
+            if not path_part.startswith("path: "):
+                continue
+            path = path_part.removeprefix("path: ").strip()
+            if source and path:
+                docs.append((source, path))
+    return docs
+```
+
+### `tests/unit/test_agent.py` — tool description assertions
+
+The test `test_agent_tools_names_and_parameters` asserts the exact description strings:
+
+```python
+# BEFORE (line ~109)
+assert by_name["read_document"]["function"]["description"] == (
+    "Add the full content of one more indexed document to your context"
+)
+```
+
+This assertion is about the function description (not parameter descriptions), so it stays the same. But the test file may have inline assertions about the `source` and `path` parameter descriptions — check and update if any exist.
+
+### `tests/unit/test_agent.py` — refusal message
+
+The refusal message `"No document at S/ghost.md — check the list_documents output."` is unchanged — it reports the lookup failure, not the list format. No changes needed here.
+
+## Files changed
+
+- `tests/e2e/mock_llm.py` — `_catalog_docs` parsing
+- `tests/unit/test_agent.py` — only if inline assertions reference the old format (verify)
+
+## Verification
+
+- `uv run pytest tests/unit/test_agent.py -v --no-cov` — all agent unit tests pass.
+- `uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov` — the mock's `_catalog_docs` must produce identical `(source, path)` tuples for the test catalogs.
+- `uv run ruff check tests/ && uv run pyright tests/` — lint + types clean.
@@ -0,0 +1,44 @@
+# Task 03 — E2E document tools validation
+
+**Goal:** Run the E2E suites for agent document tools and verify they still pass with the new catalog format.
+
+## What to verify
+
+The E2E tests assert on:
+1. **SSE frames** — the `argument` field of `tool` events is `source/path` (e.g., `"Deployments/example-record-file.json"`). This is the tool call argument, NOT the list output format. **Unchanged.**
+2. **UI rendering** — tool lines show "Listing documents" and "Reading <source/path>". **Unchanged.**
+3. **Source chips** — display `${s.source}/${s.path}`. **Unchanged.**
+4. **Answer content** — the mock's deterministic answer quoting the read document. **Unchanged** (the mock reads the same `(source, path)` tuples from the catalog).
+5. **Query log** — sources field stores `"source/path, source/path"`. **Unchanged.**
+
+The only thing that changes is the **text of the catalog** that the mock parses. The mock's `_catalog_docs` function must produce identical `(source, path)` tuples for the test catalogs, which means the tool flow classification (`_tool_flow`) and the read step will work identically.
+
+## Run commands
+
+```bash
+# DB must be up: podman compose up -d db
+uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov
+uv run pytest tests/e2e/test_agent_unlimited_tools.py -v --no-cov
+```
+
+## Regression suites to run
+
+```bash
+uv run pytest tests/e2e/test_chat_api.py -v --no-cov
+uv run pytest tests/e2e/test_whole_document_context.py -v --no-cov
+uv run pytest tests/e2e/test_sse_events.py -v --no-cov
+```
+
+## Expected outcome
+
+All tests pass without modification (aside from the mock parsing change in task 02). The catalog text format is an internal detail of the agent loop — the tool call arguments, SSE frames, UI rendering, and answer content are all unchanged.
+
+## If tests fail
+
+1. Check that `_catalog_docs` produces the same `(source, path)` tuples as before for the test catalogs.
+2. Verify the mock's `_tool_flow` classification still works (it calls `_catalog_docs`).
+3. Check that the SSE `argument` field is still `source/path` (it should be — `_execute_tool` builds it from `call.arguments["source"] + "/" + call.arguments["path"]`, which is unchanged).
+
+## Files changed
+
+- None (verification only — all changes were in tasks 01 and 02)
@@ -0,0 +1,44 @@
+# Task 04 — Update documentation
+
+**Goal:** Update all documentation that references the old `source/path — title` catalog format to the new `source: X | path: Y | title: Z` format.
+
+## Files to update
+
+### `README.md` — Agent document tools section (~L168)
+
+```markdown
+# BEFORE
+* **`list_documents`** — lists every indexed document, one
+  `source/path — title` line each (the same order as the Sources page);
+
+# AFTER
+* **`list_documents`** — lists every indexed document, one
+  `source: X | path: Y | title: Z` line each (the same order as the
+  Sources page);
+```
+
+### `.agent/user_stories/agent-document-tools.md` — Acceptance criteria (~L38)
+
+```markdown
+# BEFORE
+3. `app/rag/agent.py`: the loop — budgets from
+   `BOR_AGENT_LIST_CALLS` / `BOR_AGENT_READ_CALLS` (default 1/1); the
+   `list_documents` tool returns the DB catalog
+   (`source/path — title` lines, `/api/docs` order);
+
+# AFTER
+3. `app/rag/agent.py`: the loop — budgets from
+   `BOR_AGENT_LIST_CALLS` / `BOR_AGENT_READ_CALLS` (default 1/1); the
+   `list_documents` tool returns the DB catalog
+   (`source: X | path: Y | title: Z` lines, `/api/docs` order);
+```
+
+## Verification
+
+- `grep -n "source/path — title\|source/path - title" README.md .agent/user_stories/*.md` should return no results.
+- `uv run ruff check README.md .agent/` — lint clean (markdown files are not linted by ruff, but the command should not error).
+
+## Files changed
+
+- `README.md` — Agent document tools section
+- `.agent/user_stories/agent-document-tools.md` — Acceptance criteria item 3
@@ -0,0 +1,49 @@
+# Phase 64 — Real-Time Progress for Sync + Upload, Background Upload
+
+**Source:** `TODO.md` L3 — "Need better indication of sync and upload progress. Both should show current file being processed in real time, not just 'syncing' or 'uploading'." (+ the navigate-away / toast half of the same item)
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+**Context:** `app/api/sync.py` (phase 32 — background sync + the 2 s `GET /api/sync/status` polling pattern, the template for everything here), `app/api/git_sources.py` (phase 49 — the upload route whose scan runs **synchronously in the request**: the browser `fetch` blocks until unpack + import finish, so navigating away mid-upload aborts it — the exact defect this phase removes), `app/rag/importer.py` (`import_sources` loops file-by-file with **no** progress hook — the single place both flows can be instrumented), `frontend/assets/sources.js` (the sync button's §7.4 never-stale lifecycle + load-time re-attach), `frontend/assets/git-sources.js` (the upload form's "Uploading…" lifecycle), `frontend/assets/styles.css` (`.toast` — the phase-55 share-success toast, reused verbatim for the new "successfully uploaded" toast). E2E conventions: `tests/e2e/test_archive_upload_sources.py` (archive fixture builder, mock LLM, `BOR_UPLOAD_DIR` scratch) and `tests/e2e/test_sync_button.py`.
+
+## Objective
+Both long-running KB jobs report **which file is being processed right now** (not just "Syncing…"/"Uploading…"), and the archive upload is fully **backgrounded**: `POST /api/git-sources/upload` answers 202 the moment the archive is on disk (a "successfully uploaded" toast fires — the user may navigate away), the unpack/scan continues server-side with a status endpoint, and the sync button on the RAG page (`/sources.html`) animates with the upload's current file while that scan runs.
+
+## Dependencies
+- `63_unambiguous_document_listing` (complete) — the immediately preceding phase (the todo queue was empty at authoring; this phase builds on no unfinished work).
+
+## Tasks
+1. `01_importer_progress_hook.md` — optional per-file progress callback on `import_sources` (source, rel path, done/total).
+2. `02_sync_status_current_file.md` — `SyncStatus` + `GET /api/sync/status` carry `current_file` (+ counts), wired through the hook.
+3. `03_upload_background_202.md` — `POST /upload` → 202 + background task + `GET /api/git-sources/upload/status` (phase-32 pattern, incl. `current_file`).
+4. `04_sync_button_live_file.md` — RAG-page sync button: live file label for sync runs AND for in-flight upload scans, catalog refresh + settle on upload completion, load-time re-attach.
+5. `05_upload_toast_progress.md` — Sources-page upload UI: "successfully uploaded" toast on 202, live "Processing… <file>" label via status polling, 409/load-time re-attach, failure banner.
+6. `06_e2e_sync_upload_progress.md` — the story Playwright suite + `test_archive_upload_sources.py` adaptation + regressions + commit.
+
+## Testing & Quality
+- Unit: the progress-hook contract in `tests/unit/test_importer.py`; status shapes in `tests/unit/test_sync_button.py`; the 202/background/upload-status contract in `tests/unit/test_archive_upload.py` (adapted from the synchronous expectations).
+- Frontend source pins (house pattern): a new `tests/unit/test_frontend_sync_upload.py` — label builders, the polling decision trees, toast-on-202, re-attach paths.
+- Coverage: **>90%** on `app/` (`validate.sh` gate).
+- E2E (mandatory, A16): `tests/e2e/test_sync_upload_progress.py`, run in isolation; `test_archive_upload_sources.py` updated to the 202 + toast + polling flow; regressions `test_sync_button.py`, `test_git_sources_admin.py`, `test_sync_model_down.py` in isolation.
+
+## Completion Criteria
+- [ ] `GET /api/sync/status` and `GET /api/git-sources/upload/status` both report `current_file` / `files_done` / `files_total` while their job runs (null/0 idle).
+- [ ] `POST /api/git-sources/upload` returns **202** with the safe source name once the archive is fully received; unpack + scan continue in a background task; one upload at a time (409 in flight).
+- [ ] The "Successfully uploaded — <file>" toast appears on the Sources page at 202 (before the scan finishes); navigating to `/sources.html` mid-scan shows the sync button animating with the upload's current file; on completion the button settles and the catalog shows the new documents.
+- [ ] The sync button's label shows the current file during sync runs ("Syncing… <file>") and during upload scans ("Importing <file>"); the upload area shows "Processing… <file>" during the scan.
+- [ ] `uv run pytest` green; `app/` coverage >90%.
+- [ ] `uv run pytest tests/e2e/test_sync_upload_progress.py -v --no-cov` green in isolation (DB up); `test_archive_upload_sources.py`, `test_sync_button.py`, `test_git_sources_admin.py`, `test_sync_model_down.py` green in isolation.
+- [ ] `uv run ruff check . && uv run pyright` clean.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/`.
+
+## Locked decisions
+- **Owner-locked (2026-09-01, roadmap confirmation):**
+  - **A1 — the upload goes fully background.** 202 means "archive safely on disk"; unpack → swap → row upsert → model check → import → overview run in a background task; `GET /api/git-sources/upload/status` is the single source of truth (phase-32 `SyncStatus` pattern). One upload at a time stays (409). This is the only way "navigate away before it finishes" works.
+  - **A2 — toast timing/scope.** The "successfully uploaded" toast fires on the Sources page **at 202** (file received), auto-dismisses (~5 s, phase-55 `.toast`); failures are announced by the existing `#archive-upload-error` banner, never a toast.
+  - **A3 — RAG-page sync button during an upload scan.** It enters its running animation showing the upload's current file ("Importing <file>"); on upload completion it settles to "Sync sources" and the catalog refreshes (`loadDocs()`). The upload's count line itself stays on the Sources (git-sources) page — the sync-result line never renders upload counts.
+  - **A4 — progress granularity.** Per importable file: labels show `source/relative/path` (truncated with ellipsis; the full path lives in the button `title` + the aria-live result line). The unpack phase (before any file is indexed) shows no file yet — just "Processing…"/"Syncing…".
+  - **A5 — post-202 failures.** Unpack / zero-entry / swap / model / import failures land in the upload status as `failed` with a sanitized error (the `_sanitize_error` credential mask). Pre-swap failures leave the KB, folders, and rows untouched; post-swap failures keep the folder + row so a re-upload or the next sync retries idempotently (the existing phase-49 step-7 semantics, now in the status state instead of an HTTP error).
+- **A9/A10/A16/A17 honoured** — the admin-only API surface stays stateless apart from the in-memory run state (phase 32 precedent); one story E2E suite; one atomic commit.
+
+## Commit
+```bash
+git add -A .agent/ app/ frontend/ tests/ && git commit --no-gpg-sign -m "feat(sources): real-time file progress for sync and upload — background upload with success toast"
+```
@@ -0,0 +1,30 @@
+# Task 01 — The importer progress hook
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — "Both should show current file being processed in real time, not just 'syncing' or 'uploading'."
+**Story:** n/a (TODO-derived)
+
+## Objective
+`import_sources` gains an optional per-file progress callback so both long-running jobs (admin sync, upload scan — tasks 02/03) can report the file being processed right now. Existing callers pass nothing and see zero behavior or performance change.
+
+## Work
+1. `app/rag/importer.py`:
+   - Add an optional keyword argument to `import_sources`: `progress: Callable[[str, str, int, int], None] | None = None` — signature `(source, rel_posix_path, done, total)`.
+   - **Semantics:** called once per importable file, immediately before `await _index_file(...)`, with `done` = the 1-based index of the current file **across all sources** and `total` = the total number of importable files across all `sources` roots. `rel` is the same POSIX path the doc rows use (`path.relative_to(root).as_posix()`).
+   - `total` is computed **only when `progress` is provided**: pre-walk every root with the existing `iter_importable_files` (same extension/exclusion rules — directory stats only, no file reads). When `progress is None`, no pre-walk happens: existing callers (`scripts/import_docs.py`, `app/api/sync.py` until task 02, `app/api/git_sources.py` until task 03) are byte-identical in behavior and cost.
+   - The `limit` debug path is unchanged: the callback still fires per processed file; `done` never exceeds the limit, `total` stays the full pre-walk count (an incomplete walk must not misreport the denominator).
+   - No special handling for a raising callback — the hooks in this repo (tasks 02/03) only assign dataclass fields. Keep the loop clean; no try/except around the call.
+   - Module docstring: one line noting the optional progress hook (phase 64).
+2. `tests/unit/test_importer.py` — unit tests:
+   - Multi-root, multi-file: the callback receives the exact `(source, rel, done, total)` sequence (both roots interleaved in `sources` order, `total` = combined count).
+   - `progress=None`: no callback, and a pre-walk sentinel (e.g., monkeypatch `iter_importable_files` with a call counter) proves the walk happens exactly as many times as before this change (no extra pass).
+   - Skipped/unchanged/error files still count in the sequence (the callback fires before `_index_file`, so an `EmbeddingError` file was already reported as current).
+   - `limit=`: callback fires only for processed files; `total` is still the full count.
+
+## Testing & Quality
+- Unit: as above; full suite green.
+- Coverage: **>90%** on `app/` (the hook is small; the `None` path and the pre-walk path both get dedicated tests).
+
+## Completion Criteria
+- [ ] `import_sources(..., progress=fn)` reports every importable file in order with correct `done`/`total`; `progress=None` callers are unchanged (no extra walk).
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] No behavior change in completed work (sync/upload still pass no hook yet).
@@ -0,0 +1,31 @@
+# Task 02 — Sync status reports the current file
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — "Both should show current file being processed in real time, not just 'syncing' or 'uploading'."
+**Story:** n/a (TODO-derived)
+
+## Objective
+`GET /api/sync/status` carries the file the admin sync is processing right now (`current_file` + `files_done`/`files_total`), so the RAG-page button (task 04) can render a live label instead of a bare "Syncing…".
+
+## Work
+1. `app/api/sync.py`:
+   - `SyncStatus` dataclass: add `current_file: str | None = None`, `files_done: int = 0`, `files_total: int = 0` (the four-state machine is untouched).
+   - `GET /api/sync/status` response: add the three keys — `"current_file": str | null`, `"files_done": int`, `"files_total": int` (idle: `null`/`0`/`0`). The existing keys (`state`, `started_at`, `finished_at`, `detail`, `error`) are unchanged, so the current UI and every existing consumer keep working.
+   - `_run_sync`: on start, explicitly reset the three fields (alongside the existing resets). Pass the task-01 hook to `import_sources(sources, llm, prune=True, progress=_hook)` where `_hook(source, rel, done, total)` assigns `_status.current_file = f"{source}/{rel}"`, `_status.files_done = done`, `_status.files_total = total`. The module already has its single `_status` instance — the closure captures it exactly like the existing state assignments.
+   - Terminal states: on `success` and on `failed` set `_status.current_file = None` (keep the final `files_done`/`files_total` — the run's last position is useful context and costs nothing). The clone/pull phase before the import reports no file yet (`current_file` stays `None`) — per ASSUMPTION A4 the label then shows just "Syncing…".
+   - Module docstring: the status paragraph gains one line on the progress fields (phase 64).
+2. `tests/unit/test_sync_button.py` — unit tests (extend the existing sync-API unit coverage, house fixture for the in-memory run):
+   - Idle status shape: the three new keys present with `null`/`0`/`0`.
+   - Mid-run: drive `_run_sync` with the existing mocked-import seam (the suite already stubs the pipeline) + a `progress`-shaped call injected through the real hook closure — `GET /api/sync/status` reports the assigned `current_file`/`files_done`/`files_total` while `state == "running"`.
+   - Terminal: after success and after failure, `current_file` is `null` (counts retain the final values).
+   - Backward shape: every pre-existing key in the response is unchanged (pin the full response dict on the idle state).
+
+- ASSUMPTION (owner-locked 2026-09-01): A4 — per-file granularity; `source/relative/path` form; no file shown during the clone/pull phase (bare "Syncing…").
+
+## Testing & Quality
+- Unit: as above; full suite green.
+- Coverage: **>90%** on `app/` (the `_run_sync` terminal branches already have coverage — extend, don't duplicate).
+
+## Completion Criteria
+- [ ] `GET /api/sync/status` returns `current_file`/`files_done`/`files_total` (null/0 idle), updated per file while a sync runs, `current_file` null in terminal states.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] No behavior change in completed work (the UI still shows "Syncing…" until task 04).
@@ -0,0 +1,48 @@
+# Task 03 — The upload becomes background (202 + status endpoint)
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — "Also the user can navigate away from the upload way before 'uploading' finishes." (+ "once the zipfile/tarball is on the server there should be a little 'successfully uploaded' notification toast")
+**Story:** n/a (TODO-derived)
+
+## Objective
+`POST /api/git-sources/upload` returns **202** the moment the archive is fully received (safe on disk), and unpack → swap → row upsert → model check → import → overview run in a background task behind a new `GET /api/git-sources/upload/status` (the phase-32 `SyncStatus` pattern, including task-02-style `current_file`/counts). Navigating away mid-scan no longer aborts anything.
+
+## Work
+1. `app/schemas.py` — add `UploadAccepted(BaseModel)`: `detail: str = "upload received"`, `name: str` (the safe source name). `UploadOut` is **kept** — it becomes the shape of the status `detail` on success.
+2. `app/api/git_sources.py`:
+   - **`UploadStatus` dataclass** (module level, mirrors `app.api.sync.SyncStatus`): `state: Literal["idle", "running", "success", "failed"]`, `started_at`/`finished_at`, `current_file: str | None`, `files_done: int`, `files_total: int`, `detail: dict`, `error: str | None`; one instance `_upload_status`. Keep the module-level `_upload_in_progress` **bool flag** (not a task-done check) with its existing rationale — the flag is checked and set with **no await in between, BEFORE streaming**, because the handler now awaits (the 1 MiB-chunk stream) before the background task exists: a task-done check alone would let a concurrent POST slip through during the receive and start a second run. The flag is cleared in `_run_upload`'s `finally` (at the end of the background run) and on the exception path where the task was never created (wrap stream + `create_task` in try/except, clear + re-raise).
+   - **`POST /upload` → `status_code=202`, `response_model=UploadAccepted`**; drop the `db: Session = Depends(get_db)` dependency from the signature (the handler no longer touches the DB — the upsert moves to the background). Inline (request) work, unchanged semantics: (1) name/format gate (422s as today, including `archive_source_name`'s messages), (2) 409 `an upload is already in progress` while the flag is held, (3) stream the upload in `_STREAM_CHUNK` chunks into the dotfile temp with the `upload_max_mb` cap (413 naming the cap, temp deleted). Then `asyncio.create_task(_run_upload(...))` and return `UploadAccepted(name=<safe name>)` — **the file is on disk; 202 is the "successfully uploaded" moment the UI toasts on (ASSUMPTION A2).**
+   - **`_run_upload(name, filename, total_bytes, upload_root, temp_upload, temp_unpack)`** (module function, the phase-32 `_run_sync` shape):
+     1. `_upload_status` → `running` (started_at, finished_at `None`, `current_file` `None`, counts 0, detail `{}`, error `None`).
+     2. `unpack_archive(temp_upload, temp_unpack, max_bytes)` — `ArchiveUploadError` → `failed` (sanitized via the imported `_sanitize_error`), temps deleted; the compressed temp is unlinked after unpack (phase-49 locked decision: only unpacked content is kept).
+     3. Zero entries → `failed` "the archive contains no files".
+     4. `swap_in(temp_unpack, final_dir)` — `ArchiveUploadError` → `failed` sanitized (a failure here leaves the previous folder/row/KB untouched).
+     5. Row upsert **in a short-lived `SessionLocal()`** (open/close around it, the `effective_sources`/`bump_sources_version` pattern from `app/api/sync.py` — never the request session, whose lock discipline is what the old inline `db.close()` comment guarded): by `path` (expanded `final_dir`), `kind="local"`, `url` = same path; an existing row is left as-is (`added_at` preserved); a concurrent-insert `IntegrityError` → `failed` "a local source with this path already exists: <path>" (the folder stays — the row exists, the next sync sees it).
+     6. `check_models(LLMClient())` — `ModelUnavailableError` → `failed` with the sanitized message (the phase-49 503 becomes a status state; the folder/row are committed, so the next sync/re-upload retries idempotently — ASSUMPTION A5).
+     7. `import_sources([final_dir], llm, prune=True, progress=_hook)` — `_hook(source, rel, done, total)` assigns `_upload_status.current_file = f"{source}/{rel}"` + the counts (task-01 hook).
+     8. Change-gated `regenerate_overview(llm)` (added + updated > 0 — unchanged).
+     9. The per-upload INFO log line (PLAN §9 / AGENTS.md rule 10) **moves here**, same fields as today (`upload: name=… file=… bytes_in=… files=… added=… updated=… unchanged=… pruned=… errors=… overview=… total_ms=…` — `total_ms` now the background run's duration).
+     10. `success`: finished_at, `detail` = the `UploadOut` fields as a dict (`source=name`, `files`, `added`, `updated`, `unchanged`, `pruned`, `errors`, `chunks`, `overview`).
+     - `CancelledError` is deliberately **not** caught (app shutdown cancels the task — the `_run_sync` rule). The `finally` cleans both temps (defensive, as today) and clears `_upload_in_progress`.
+   - **`GET /upload/status`** (router dependency already admin-only): response `{"state", "started_at", "finished_at", "current_file", "files_done", "files_total", "detail", "error"}` — identical key set to `GET /api/sync/status` (ISO-8601 or null, same as there).
+   - Docstrings: module docstring's upload paragraph → phase-64 contract (202 + background + status endpoint; the inline gate list stays accurate — steps 1–3 are inline, 4–10 are background); route docstring rewritten to match.
+3. `tests/unit/test_archive_upload.py` — adapt the suite to the 202 contract (keep every scenario, change the observation point from the HTTP response to the status endpoint, polling until terminal):
+   - 202 + `UploadAccepted` body (`detail` + safe `name`); the temp upload file exists on disk at that point.
+   - Inline gates unchanged: non-archive extension 422 (accepted set named), unsafe name 422, over-cap 413 (cap named, temp deleted), 409 while a run is in flight (flag still held).
+   - Success: status `success`, `detail` carries the `UploadOut` fields with correct counts, the `kind="local"` row exists (and a re-upload under the same name preserves it — the existing in-place-replace scenario, now observed via the second run's status), the folder is in place, no dotfile temps left in `upload_root`.
+   - Corrupt/traversal archive → status `failed`, sanitized error, KB + rows untouched, temps deleted.
+   - Zero-entry archive → status `failed` "the archive contains no files".
+   - Model down (stub `check_models` raising `ModelUnavailableError`) → status `failed` sanitized; folder + row exist (idempotent-retry precondition, ASSUMPTION A5).
+   - Mid-run: `current_file`/`files_done`/`files_total` reported while `running` (same hook-injection seam as task 02), `current_file` null in terminal states.
+   - Re-upload while a run is in flight → 409 (the flag, not task-done, is the gate — pin a second POST during the receive window in the existing flag test, or extend it).
+
+- ASSUMPTION (owner-locked 2026-09-01): A1 — 202 = "archive safely on disk"; the scan runs server-side afterwards; one upload at a time. A5 — post-202 failures are status states (`failed` + sanitized error), never HTTP errors; pre-swap failures leave KB/folders/rows untouched, post-swap failures keep folder + row for an idempotent retry.
+
+## Testing & Quality
+- Unit: as above (the adapted suite is this task's gate); full suite green.
+- Coverage: **>90%** on `app/` — every background branch (unpack fail, zero-entry, swap fail, IntegrityError, model down, success, cancel-cleanup) gets a dedicated test; the `_run_upload` failure branches are the new code.
+
+## Completion Criteria
+- [ ] `POST /api/git-sources/upload` answers 202 after the receive; `GET /api/git-sources/upload/status` mirrors the sync status shape (incl. `current_file`) and is admin-only (403 anonymous).
+- [ ] A scan keeps running (and completes) after the client disconnects — unit-level: the background task is created before the response and its outcome lands in `_upload_status`.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] The `test_archive_upload_sources.py` E2E suite will be adapted in task 06 (it is expected to fail until then — noted, not fixed here).
@@ -0,0 +1,38 @@
+# Task 04 — RAG-page sync button: live file, upload-scan awareness
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — "Both should show current file being processed in real time" + "Need to trigger the syncing button animation if the user clicks on sources after clicking upload"
+**Story:** n/a (TODO-derived)
+
+## Objective
+The sync button on `/sources.html` shows the current file while a **sync** runs ("Syncing… <file>") and, while an **upload scan** is in flight, enters the same running animation showing the upload's current file ("Importing <file>"); when the upload scan finishes the button settles and the catalog refreshes.
+
+## Work
+1. `frontend/assets/sources.js`:
+   - **Label builder** `fmtSyncLabel(kind, currentFile, done, total)` — `kind` is `"sync" | "upload"`: `"sync"` → `Syncing…` + (file ? ` ${file}` : "") ; `"upload"` → `Importing` + (file ? ` ${file}` : "") ; both append ` (done/total)` only when `total > 0` (A4 — no file yet during clone/pull or unpack → bare prefix). The full untruncated path is what the status endpoints report; the label shows it, truncated by CSS.
+   - **`enterSyncRunningState(kind, currentFile, done, total)`** (the existing no-arg version gains parameters): same mechanics as today (disabled, `aria-busy`, icon `is-spinning`, no `is-error`) plus: `syncBtn.title = currentFile` (removed when null — full path on hover) and `syncResult.textContent = fmtSyncLabel(...)` **without** the truncation, so the existing `role="status"` `#sync-result` announcer reads the full live path to screen readers.
+   - **Unified polling** — `startSyncPolling`'s tick now fetches **both** `GET /api/sync/status` and `GET /api/git-sources/upload/status` (both admin-only; the 403 branch on the sync fetch already hides the button — a 403 on the upload fetch is treated as "no upload", a network blip retries next tick). Decision tree, in order, per tick:
+     1. sync `running` → `enterSyncRunningState("sync", sync.current_file, sync.files_done, sync.files_total)`; reschedule.
+     2. else upload `running` → `enterSyncRunningState("upload", upload.current_file, upload.files_done, upload.files_total)`; reschedule. ← *the "clicking on sources after clicking upload" contract (A3).*
+     3. else sync `success` → `applySyncSuccess` (unchanged); stop.
+     4. else sync `failed` → `applySyncFailure` (unchanged); stop.
+     5. else upload `success` → `settleSyncButton("Sync sources")`; `syncResult.textContent = ""` (A3 — the sync-result line never renders upload counts; they live on the Sources page); `hideSyncError()`; `emitSyncStatus({ state: "idle" })`; `loadDocs()` (the KB changed — the new documents must appear); stop.
+     6. else upload `failed` → `settleSyncButton("Sync sources")`; `syncResult.textContent = ""`; `hideSyncError()`; `emitSyncStatus({ state: "idle" })`; stop (the failure UI is the Sources page's error banner — A3).
+     7. else both idle → `applySyncIdle`; stop.
+   - **`startSync` click handler**: the 202/409 branch calls `enterSyncRunningState("sync", null, 0, 0)` (the existing `emitSyncStatus({ state: "running" })` dedup via `lastSyncState` stays).
+   - **`initSyncButton` load-time re-attach**: unchanged for sync states; when the sync state is `idle`, additionally fetch the upload status — if it is `running`, `enterSyncRunningState("upload", …)` + `emitSyncStatus({ state: "running" })` + `startSyncPolling()` (a terminal upload is a no-op: the boot-time `loadDocs()` already shows the current catalog).
+   - Header comment: the sync-button block documents the phase-64 contract (live file label, the two-job decision tree, the A3 settle behavior).
+2. `frontend/assets/styles.css` — `.sync-label`: truncate long paths — `display: inline-block; max-width: min(16rem, 40vw); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; vertical-align: bottom;` (the full path stays in the button `title` + `#sync-result`).
+3. `frontend/sources.html` — no structural change; the sync-button comment block updated to the phase-64 contract.
+4. Frontend source pins — new `tests/unit/test_frontend_sync_upload.py` (the existing `tests/unit/test_frontend_feedback.py` pin style), covering: the `fmtSyncLabel` contract (both kinds, file present/absent, counts only when `total > 0`); `enterSyncRunningState` writing the full path into `title` + `#sync-result`; the tick decision tree (running-upload → "Importing" label; upload success → settle + `loadDocs` + no sync-result line; upload failed → settle, no error banner; both idle → `applySyncIdle`); the re-attach branch (sync idle + upload running → running state + polling starts).
+
+- ASSUMPTION (owner-locked 2026-09-01): A3 — during an upload scan the sync button animates with "Importing <file>"; on upload completion it settles to "Sync sources", clears the result line, and refreshes the catalog; the sync-result line never renders upload counts, and an upload failure is not surfaced on the RAG page. A4 — per-file granularity, `source/relative/path`, ellipsis truncation, bare prefix before the first file.
+
+## Testing & Quality
+- Unit: source pins as above; full suite green.
+- Coverage: **>90%** on `app/` (unchanged — frontend-only task).
+
+## Completion Criteria
+- [ ] During a sync run the button label shows `Syncing… <file> (n/m)`; during an in-flight upload scan it shows `Importing <file> (n/m)` with the spinning icon.
+- [ ] On upload completion the button settles, the catalog refreshes, and no upload counts appear in `#sync-result`; on page load with a running upload the button re-attaches to the running state.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] No behavior change in completed work (plain sync run renders as before plus the file in the label).
@@ -0,0 +1,39 @@
+# Task 05 — Upload UI: success toast on receive, live "Processing…" label
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — "once the zipfile/tarball is on the server there should be a little 'successfully uploaded' notification toast so the user knows they can navigate away"
+**Story:** n/a (TODO-derived)
+
+## Objective
+On `/git-sources.html` the upload flow follows the new 202 contract: the moment the archive is received the page shows a **"Successfully uploaded — <file>" toast** (safe to navigate away), the button switches to a live **"Processing… <file> (n/m)"** label driven by `GET /api/git-sources/upload/status` polling, and a page reload mid-scan re-attaches instead of dead-ending.
+
+## Work
+1. `frontend/assets/git-sources.js`:
+   - **`showUploadToast(message)`** — page-local, the phase-55 share-toast pattern from `frontend/assets/app.js` (lazy-created single node, class `toast`, `.is-visible` toggles the entry transition, `role="status" aria-live="polite"`, ~5 s auto-dismiss, a new toast replaces a pending one — clear the prior timer, never stack). Uses the existing `.toast` CSS as-is.
+   - **Submit handler** (the existing one, reworked):
+     - The no-file guard, the error/result clearing, and the "Uploading…" transfer label stay (the transfer is now short — 202 arrives when the receive finishes).
+     - **202** (parse the `UploadAccepted` body for `name`; body parse failure degrades to the picked file's name): `showUploadToast(\`Successfully uploaded — ${file.name}\`)`; `uploadFileInput.value = ""`; enter the **processing state** (`uploadBtn.disabled = true`, `uploadBtn.textContent = "Processing…"`, `uploadBtn.title = ""`) and `startUploadPolling()`.
+     - **409** (`an upload is already in progress`): **no error banner** — enter the processing state + `startUploadPolling()` (re-attach; never stale). The old "server detail inline" branch does NOT apply to 409 anymore.
+     - **other non-ok** (422 name/format, 413 cap, 5xx): the existing `apiDetail` error banner, file selection KEPT (the existing re-pick convention), button restored in `finally`.
+     - **network failure** (`catch`): the existing "Could not reach the server" banner, button restored.
+     - `finally` restores the button **only when no polling is active** (while `startUploadPolling` owns the button, it stays disabled/Processing — the §7.4 never-stale rule).
+   - **`startUploadPolling()`** — 2 s cadence (the `SYNC_POLL_MS` house value, local `const UPLOAD_POLL_MS = 2000`), single timer, one at a time (guard against double-start): each tick fetches `GET /api/git-sources/upload/status`:
+     - `running` → `uploadBtn.textContent = "Processing…" + (current_file ? \` ${current_file}\` : "") + (files_total > 0 ? \` (${files_done}/${files_total})\` : "")`; `uploadBtn.title = current_file || ""` (full path on hover); reschedule. (A4 — unpack phase shows bare "Processing…".)
+     - `success` → stop; `uploadResult` line = `fmtUploadResult(detail)` (the existing helper reads exactly these keys); `announce(\`Archive uploaded: ${detail.source}.\`)`; `uploadFileInput.value = ""`; restore the button (enabled, "Upload & scan", title removed); `loadSources()` (the row lands / refreshes). **No toast here** — it already fired at 202.
+     - `failed` → stop; `uploadError` banner = `status.error` (sanitized server-side); restore the button; `loadSources()` (post-swap failures keep the row — the list state may have changed; the file selection is kept for a one-click re-upload).
+     - `idle` → stop; restore the button (defensive — a started run never returns to idle).
+   - **Boot re-attach** — in the admin branch where `loadSources()` runs at boot, fetch the upload status once: `running` → processing state + `startUploadPolling()`; `success` → render the last result line only (no announce, no toast); `failed` → the error banner; `idle` → nothing.
+   - Header comment: the upload block rewritten to the phase-64 contract (202 + toast + polling + re-attach; the phase-49 synchronous paragraph marked superseded).
+2. `frontend/git-sources.html` — no structural change (the toast node is JS-created, phase-55 pattern); the phase-49 form comment updated to the phase-64 contract.
+3. Frontend source pins — extend `tests/unit/test_frontend_sync_upload.py`: the toast contract (fires on 202 with `Successfully uploaded — <name>`, `role="status"`, auto-dismiss timer, single-node reuse); the processing-label builder (file present/absent, counts only when `total > 0`, full path in `title`); 409 → processing state + polling (NOT the error banner); the polling decision tree (success → result line + `loadSources`, no toast; failed → error banner + `loadSources`; idle → restore); the `finally` never-restoring-while-polling guard; the boot re-attach branches.
+
+- ASSUMPTION (owner-locked 2026-09-01): A2 — the toast fires at 202 on this page, auto-dismisses, and is success-only (failures use the existing `#archive-upload-error` banner). A4 — bare "Processing…" during the unpack phase; `source/relative/path` granularity afterwards.
+
+## Testing & Quality
+- Unit: source pins as above; full suite green.
+- Coverage: **>90%** on `app/` (unchanged — frontend-only task).
+
+## Completion Criteria
+- [ ] Uploading an archive shows the "Successfully uploaded — <file>" toast as soon as the 202 arrives — before the scan finishes — and the button then tracks the scan with a live file label.
+- [ ] Reloading `/git-sources.html` mid-scan resumes the Processing state (no error, no second upload); a finished/failed run re-renders its result/banner.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] No behavior change in completed work (the 422/413 error paths, the re-upload flow, and the source list are untouched apart from the new async flow).
@@ -0,0 +1,40 @@
+# Task 06 — E2E suite, regressions, commit
+
+**Phase:** `64_sync_upload_progress` · **Source:** `TODO.md:3` — the whole item (the executable proof of every locked decision).
+**Story:** n/a (TODO-derived)
+
+## Objective
+The story's Playwright suite proves the full contract end-to-end (toast on receive → navigate away → sync button animating with the upload's current file → catalog refreshed; live file labels on both jobs; reload re-attach), `test_archive_upload_sources.py` is brought onto the 202 contract, the regression suites stay green in isolation, and the phase is committed.
+
+## Work
+1. `tests/e2e/test_sync_upload_progress.py` — new suite (house conventions: `tests/e2e/conftest.py` + `mock_llm.py`, the admin sign-in and fixture style of `tests/e2e/test_git_sources_admin.py`, the archive builder + `BOR_UPLOAD_DIR` scratch of `tests/e2e/test_archive_upload_sources.py`, the local-source sync fixture style of `tests/e2e/test_sync_button.py`):
+   - **Fixture note (timing):** the mock LLM indexes fast — the in-progress state is real but brief. Build the upload archive from **20+ small `.md` files** so the scan outlasts the 2 s poll, and assert the live-file label at TWO layers: the deterministic one is the status endpoint (`page.request.get("/api/git-sources/upload/status")` / `"/api/sync/status"` — `state == "running"` with non-null `current_file` observed at some tick); the UI one polls the button label for the `Importing ` / `Syncing…` / `Processing…` prefix plus a file path (generous timeout).
+   - `test_upload_toast_then_navigate_away` — on `/git-sources.html`: pick the multi-file archive, submit → the `Successfully uploaded — <archive>` toast (`.toast.is-visible`, `role="status"`) appears **while the scan is still running**; immediately navigate to `/sources.html` → the sync button is present, animating (icon `is-spinning`, `aria-busy`) with the `Importing` label; wait for the settle → button idle ("Sync sources"), no error UI, and the catalog table shows the uploaded documents (the phase-63 listing is untouched).
+   - `test_upload_progress_shows_current_file` — during the scan: the status endpoint reports a non-null `current_file` (`source/relative/path` shape) at some running tick, and the upload button label shows `Processing…` with a file path (UI layer) before the result line (`fmtUploadResult` counts) lands; the toast fired earlier in the run (not after the result).
+   - `test_sync_live_file_label` — a multi-file local source configured (the `test_sync_button.py` fixture style): on `/sources.html` click **Sync sources** → the label shows `Syncing…` with a file path while running (endpoint layer: `/api/sync/status` `current_file` non-null; UI layer: label poll), then the success settle with the counts result line (the pre-phase-64 sync UX is preserved, plus the file).
+   - `test_upload_reattach_after_reload` — start the upload, and **during the scan** reload `/git-sources.html` → the button is in the Processing state (disabled) with **no** error banner and no second upload (the status endpoint's single run is still the one from before the reload); it then settles with the result line and the list shows exactly one row for the archive (in-place identity preserved).
+2. `tests/e2e/test_archive_upload_sources.py` — adapt to the 202 contract (keep every scenario, move observation points):
+   - upload → the toast appears at 202, the button goes `Uploading…` → `Processing…` → restore; the result line + list now come from the status `success` (counts unchanged in shape).
+   - the inline 422/413 gates are unchanged (asserted exactly as today — name, format, cap, file kept).
+   - a bad-archive scenario (if present) now lands as the **error banner** via status `failed` instead of a 422 response; re-upload after it still works.
+   - the re-upload-in-place-replace scenario: the second run's status `detail` shows the prune/refresh counts; the list still has exactly ONE row for the archive name.
+   - anonymous: the gate/form stay hidden, `POST /api/git-sources/upload` 403, and `GET /api/git-sources/upload/status` 403 (new endpoint, same wall).
+3. Run in isolation (DB up, the AGENTS.md rule-9 command): `test_sync_upload_progress.py` (new), `test_archive_upload_sources.py` (updated), `test_sync_button.py`, `test_git_sources_admin.py`, `test_sync_model_down.py`.
+4. Full gate: `uv run pytest --cov=app --cov-report=term-missing` (suite green, `app/` >90%), `uv run ruff check . && uv run pyright`.
+5. Commit + hand-off:
+   ```bash
+   git add -A .agent/ app/ frontend/ tests/
+   git commit --no-gpg-sign -m "feat(sources): real-time file progress for sync and upload — background upload with success toast"
+   ```
+   then move `.agent/phases/todo/64_sync_upload_progress/` → `.agent/phases/complete/64_sync_upload_progress/` (the pipeline's `validate.sh` gate is the move's precondition).
+
+## Testing & Quality
+- E2E: the new suite + the five isolated runs above are this phase's A16 gate.
+- Coverage: **>90%** on `app/` (no new app code in this task — the gate guards against drift from tasks 01–03).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_sync_upload_progress.py -v --no-cov` green in isolation (DB up).
+- [ ] `test_archive_upload_sources.py`, `test_sync_button.py`, `test_git_sources_admin.py`, `test_sync_model_down.py` green in isolation.
+- [ ] `uv run pytest --cov=app` green with `app/` >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] One `--no-gpg-sign` Conventional Commits commit; phase dir in `.agent/phases/complete/`.
+- [ ] `TODO.md` contains only `# TODO` (cleared by the phase pipeline's conversion step — items now live here).
@@ -0,0 +1,48 @@
+# Phase 65 — Chat Action Cluster to the Pinned Bottom
+
+**Source:** `TODO.md` L3 — "Move the new chat and share button to the tune/retry/save doc cluster area so it's always at the bottom of the screen and easily accessble. Make the button clusters look better, neater, more aligned"
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+**Context:** Verified layout inventory (audited 2026-09-01, line numbers as of this writing):
+- `frontend/index.html` — the `.chat-actions` row (New chat + Share pills, ONE wrapper) sits at the **TOP** of the 46rem chat column: the comment block runs L126–148, the row div is L149, positioned between `#steering-announcer` (L129) and `<section class="messages" id="messages">` (L193). The pinned composer form follows the messages at L225. In any real conversation the row scrolls off-screen the moment the reader is at the bottom — the exact defect this phase removes.
+- `frontend/assets/styles.css` — `.chat-actions` (L433: horizontal row, `align-items: center`, `gap: 0.6rem`, intrinsic pill widths); `.new-chat-btn` (L301) / `.share-chat-btn` (L335) — solid brand pill family, `min-height: 44px`, `border-radius: 999px`; `.composer` (L1226) — `position: sticky; bottom: env(safe-area-inset-bottom, 0)`, no z-index (the phase-52 pin, owner-locked 2026-08-30); `.messages` — `flex: 1 1 auto` + `min-height: 200px` (the grow that rests the bottom at the screen on short chats); the per-answer meta cluster: `.msg-meta` (L641), `.tune-btn` (L694), `.retry-btn` (L723), `.save-as-doc-btn` (L756) — ghost pill family, `min-height: 44px`, 14px icons, `margin(-inline-start): auto` pushes Tune/Retry/Save-as-doc to the row's **right edge** ("Save as doc" is the bottom-right action of every completed brain bubble — the app's action corner). The ≤640px block (L3049) flips `.chat-actions` to a full-width vertical stack.
+- `frontend/assets/header.js` L336–339 — binds `#new-chat-btn` and dispatches the `bor:new-chat` window event; `frontend/assets/app.js` L1700 listens and resets the conversation (it owns the in-flight-turn guard); `app.js` L246/L2067 binds `#share-chat-btn` to `shareCurrentChat` (the empty-chat no-op writes `Nothing to share yet.` to `#send-status`). All bindings are id-based and **position-independent** — the move is pure HTML/CSS.
+- `frontend/assets/app.js` `copyShareLinkWithFallback` (L1424) appends the clipboard-fallback field to the **composer** (not the row) — unaffected by the move.
+- Existing suites that constrain the design: `tests/e2e/test_pinned_composer.py` (the `#composer` computed `position` must stay `sticky`; the composer box flush with the viewport bottom at EVERY scroll position inside the sticky range; settles back into flow above the footer at the document bottom; NO z-index on the composer; the empty chat must not be scrollable, `sh <= ch + 1`); `tests/e2e/test_save_share_ux.py::test_action_row_layout` (ONE `.chat-actions`, DOM order New chat → Share, horizontal row at 1280px with intrinsic pill widths, full-width stack at 390px, no horizontal overflow at 360px — all RELATIVE geometry, nothing pins the row's vertical position); `tests/e2e/test_chat_persistence.py` (`#new-chat-btn` ≥44px, click resets the conversation, `New chat started` in `#send-status`).
+- `.agent/` is tracked and committed (AGENTS.md rule 8) — the phase commit stages `.agent/` + `frontend/` + `tests/`.
+
+## Objective
+The New chat + Share pills live in the **bottom cluster** of the chat column — the same screen zone as the tune/retry/save-doc meta actions — and are **always at the bottom of the screen** (pinned with the composer, visible even while scrolled up reading a long conversation). The two button clusters read as neat, aligned sets: the bottom row hugs the column's right edge, mirroring the right-aligned "Save as doc" corner above it.
+
+## Dependencies
+- `64_sync_upload_progress` (todo, preceding — no functional dependency; ordering by number)
+
+## Tasks
+1. `01_move_chat_actions_to_bottom.md` — relocate the `.chat-actions` row (buttons + comments byte-identical) to the last child of `.chat-shell`, directly above the composer; in-flow at first.
+2. `02_pin_bottom_cluster.md` — wrap row + composer in a sticky `.chat-bottom` unit (A1): the cluster is pinned at the viewport bottom at every scroll position and settles into flow above the footer at the document bottom.
+3. `03_align_button_clusters.md` — right-align the bottom row to the column's right edge (A2); verify the five action pills share one geometry (44px targets, 999px radius, global focus-visible).
+4. `04_e2e_bottom_chat_actions.md` — the dedicated Playwright suite `tests/e2e/test_bottom_chat_actions.py` (run in isolation): pinned at every scroll position, resting at the screen bottom, settled above the footer, geometry + DOM order, mobile stack, both buttons still work.
+5. `05_regressions_and_commit.md` — regression E2E matrix, full `validate.sh`, one atomic commit.
+
+## Testing & Quality
+- E2E (mandatory, house rule — one file per phase, run in isolation): `tests/e2e/test_bottom_chat_actions.py` against the shared conftest server (DB up, mock LLM, seeded KB — the `test_pinned_composer.py` patterns for overflow conversations and scroll measurement).
+- Frontend-only phase: `app/` is untouched, so the coverage gate stays satisfied at its current level — `validate.sh` (unit + integration >90% + ruff + pyright) must still pass end to end.
+- Regression E2E (each in isolation): `test_pinned_composer.py`, `test_save_share_ux.py`, `test_chat_persistence.py`, `test_share_chat.py`, `test_chat_history.py`, `test_smoke.py`.
+
+## Completion Criteria
+- [ ] The `.chat-actions` row is the bottom cluster of `.chat-shell` — above the composer, inside the sticky `.chat-bottom` — with DOM order New chat → Share preserved and all ids/aria-labels intact.
+- [ ] Over-viewport conversation, scrolled to the top: the row is fully visible, pinned at the viewport bottom above the composer, at every scroll position inside the sticky range; at the document bottom the cluster settles into flow above the footer (no overlap).
+- [ ] Empty chat at 1280×800: the row rests at the bottom of the screen, the document is not scrollable.
+- [ ] Desktop: the row's right edge aligns with the column's right edge (A2); ≤640px: full-width vertical stack; no horizontal overflow at 360px.
+- [ ] `#new-chat-btn` click resets the conversation (`New chat started` in `#send-status`); `#share-chat-btn` on an empty chat is a no-op (`Nothing to share yet.`) — the bindings survived the move.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_bottom_chat_actions.py -v --no-cov` green in isolation (DB up); the six regression E2E suites green in isolation.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/`.
+
+## Locked decisions
+- **Owner-locked (2026-09-01, roadmap confirmation, A1):** *pinned bottom cluster* — a `.chat-bottom` wrapper (`position: sticky; bottom: env(safe-area-inset-bottom, 0)`, NO z-index) groups `.chat-actions` + `#composer` as one sticky unit, so the pills are literally always at the bottom of the screen — the rejected alternative (plain in-flow row) would scroll away while reading up a long conversation. The `#composer`'s own sticky declaration STAYS (redundant inside the wrapper — it cannot shift within its containing block — but `test_pinned_composer.py` pins the computed style `sticky`).
+- **Owner-locked (2026-09-01, roadmap confirmation, A2):** *right-aligned bottom row* — the New chat + Share row hugs the column's RIGHT edge on desktop (so the bottom-right reads as one aligned action column with the right-aligned "Save as doc" buttons above); the ≤640px stack stays full-width (alignment is moot when stretched).
+
+## Commit
+```bash
+git add .agent/ frontend/ tests/ && git commit --no-gpg-sign -m "feat(web): move the chat action cluster to the pinned bottom and align the button sets"
+```
@@ -0,0 +1,28 @@
+# Task 01 — Move the `.chat-actions` row to the bottom of the chat column
+
+**Phase:** `65_bottom_chat_actions` · **Source:** `TODO.md:3` — "Move the new chat and share button to the tune/retry/save doc cluster area so it's always at the bottom of the screen and easily accessble…"
+**Story:** n/a (TODO-derived)
+
+## Objective
+The New chat + Share row leaves the TOP of the column (where it scrolls off-screen the moment a conversation grows) and becomes the last child of `.chat-shell`, directly above the pinned composer — the same screen zone as the tune/retry/save-doc meta cluster. This task is the MOVE only (in-flow); the sticky pin lands in task 02 and the alignment in task 03.
+
+## Work
+1. `frontend/index.html`:
+   - Cut the ENTIRE `.chat-actions` block — the comment at L126–148 PLUS the `<div class="chat-actions">…</div>` at L149–187 (both buttons, every line of their comments included) — from between `#steering-announcer` (L129) and `<section class="messages" id="messages">` (L193).
+   - Paste it as the LAST child of `.chat-shell`: between the messages `</section>` (L207) and the composer comment block (L209), so each comment stays glued to its own element and the form (L225) is untouched. Indent to match the sibling elements (6 spaces); keep the blank-line separation between the four children.
+   - The two buttons stay BYTE-IDENTICAL: ids (`#new-chat-btn`, `#share-chat-btn`), classes, `aria-label`s, SVGs, the label spans, and the DOM order **New chat → Share** (pinned by `test_save_share_ux.py::test_action_row_layout`).
+   - Update the row's comment block in place (it moves with the row): keep the Phase 55/14/51 history, and APPEND a Phase 65 note — the row was relocated from the top of the column to the bottom (above the composer) per `TODO.md` L3 (owner confirmation 2026-09-01), so the cluster sits where the tune/retry/save-doc meta actions live; the top of the column is now banner → steering → announcer → messages.
+2. No CSS changes in this task: the row's styling is position-independent (`.chat-actions` at `styles.css` L433; the ≤640px stack rule at L3049). As a column child it inherits `.chat-shell`'s `gap: 1rem` above (from `.messages`) and below (to the composer) — acceptable until task 02/03 set the wrapper gap.
+3. No JS changes: every binding is id-based and position-independent — `frontend/assets/header.js` L336–339 (`#new-chat-btn` → `bor:new-chat` dispatch), `frontend/assets/app.js` L1700 (the listener), L246 + L2067 (`#share-chat-btn` → `shareCurrentChat`). The clipboard-fallback field already appends to the composer (`app.js` L1424), not the row.
+4. Leave UNTOUCHED: `#kb-banner`, `#stale-banner`, `#steering-panel`, `#steering-announcer`, `#messages`, `#composer`, and every comment except the row's own moved block.
+
+## Testing & Quality
+- `uv run pytest` green (unit + integration — no Python changed, gate stays green); coverage TOTAL **>90%**; `uv run ruff check . && uv run pyright` clean.
+- Highest-risk existing suite for this move: `uv run pytest tests/e2e/test_save_share_ux.py -v --no-cov` green in isolation (DB up) — it pins the row's geometry (single `.chat-actions`, DOM order, horizontal/stacked, intrinsic widths, 360px overflow) but nothing about its vertical position, so the move must not perturb it.
+
+## Completion Criteria
+- [ ] In `frontend/index.html`, the `.chat-actions` div appears AFTER `</section>` (the messages close, L207) and immediately before the composer form — it is the last child of `.chat-shell`; nothing remains at the old position (grep: exactly one `.chat-actions` in the file).
+- [ ] `grep -n "new-chat-btn\|share-chat-btn" frontend/index.html` shows both buttons with unchanged ids/classes/aria-labels, New chat before Share.
+- [ ] The row's comment block moved with the row and carries the Phase 65 relocation note.
+- [ ] `uv run pytest` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_save_share_ux.py -v --no-cov` green in isolation (DB up).
@@ -0,0 +1,46 @@
+# Task 02 — Pin the bottom cluster (`.chat-bottom` sticky unit)
+
+**Phase:** `65_bottom_chat_actions` · **Source:** `TODO.md:3` — "…so it's always at the bottom of the screen and easily accessble."
+**Story:** n/a (TODO-derived)
+
+## Objective
+The row + composer become ONE pinned unit (locked A1): at every scroll position inside the sticky range the bottom cluster sits flush with the viewport bottom — the pills are literally always at the bottom of the screen, even while the reader is scrolled up through a long conversation — and at the document bottom the cluster settles back into normal flow above the footer (never floating over it).
+
+## Work
+1. `frontend/index.html`:
+   - Wrap the `.chat-actions` div (task 01's position) AND the `<form class="composer">…</form>` (incl. its comment block) in a new `<div class="chat-bottom">` … `</div>` that is the single LAST child of `.chat-shell` (before the shell's closing `</div>`, currently L237). No id (nothing in JS binds it — the bindings are on the inner elements).
+   - Append a Phase 65 note to the row's comment (A1): the wrapper makes row + composer one sticky unit — `position: sticky; bottom: env(safe-area-inset-bottom, 0)`, NO z-index (the sticky header stays on top — the phase-46 stacking pinned by `test_pinned_composer.py`); the composer's OWN sticky declaration is kept (redundant inside the wrapper — its containing block is the wrapper, so it cannot shift — but `test_pinned_composer.py` asserts the computed style `sticky` on `#composer`).
+2. `frontend/assets/styles.css` — new rule directly above the `.composer` rule (L1226):
+   ```css
+   /* Phase 65 (owner-locked A1, 2026-09-01, TODO.md L3): the pinned
+      bottom cluster — the .chat-actions row + the #composer form as
+      ONE sticky unit ... (full house-style rationale: sticky range =
+      the .chat-shell containing block; the .messages flex-grow still
+      rests the unit at the screen bottom on short chats; no z-index,
+      so the phase-12 sticky header (z 20) and the phase-46 dropdown
+      always stay on top; the composer's own sticky rule stays —
+      redundant here, pinned by tests/e2e/test_pinned_composer.py). */
+   .chat-bottom {
+     display: flex;
+     flex-direction: column;
+     gap: 0.5rem;
+     position: sticky;
+     bottom: env(safe-area-inset-bottom, 0);
+   }
+   ```
+   - `gap: 0.5rem` is the row↔composer spacing INSIDE the wrapper (the wrapper is one column child, so `.chat-shell`'s 1rem gap applies only ABOVE it, from `.messages`).
+   - The `#composer` rule itself is NOT modified (its `position: sticky; bottom: env(...)` stays — see the note above).
+   - The ≤640px block needs no change: the wrapper is a column flex box, so the stacked full-width pills (the existing L3049 `.chat-actions` rule) simply make the unit taller on phones.
+3. Update the `.composer` rule's phase-52 comment minimally: the pin now belongs to `.chat-bottom`; the composer's own declaration is retained for the computed-style test pin (one line, no deletion of the phase-52 history).
+4. Leave UNTOUCHED: `.messages` (`flex: 1 1 auto` + `min-height: 200px` — the grow that absorbs free space on short chats still works: the wrapper is the last child, so the grow pushes the WHOLE unit down), every z-index in the file, and all JS.
+
+## Testing & Quality
+- `uv run pytest` green; `uv run ruff check . && uv run pyright` clean; coverage TOTAL **>90%** (gate stays green — no Python changed).
+- The load-bearing regression: `uv run pytest tests/e2e/test_pinned_composer.py -v --no-cov` green in isolation (DB up) — it re-verifies the whole pin contract WITH the wrapper: composer box flush with the viewport bottom at every scroll position, settled into flow above the footer at the document bottom, `#composer` computed `position === "sticky"` and `zIndex` in {auto, 0}, under the 64px header on a 375×812 phone, and the empty chat still not scrollable (`sh <= ch + 1` — the wrapper adds no height: the row already existed in the column, task 01).
+- `uv run pytest tests/e2e/test_save_share_ux.py -v --no-cov` green in isolation (row geometry unchanged by the wrapper).
+
+## Completion Criteria
+- [ ] `frontend/index.html`: exactly one `.chat-bottom` div, the last child of `.chat-shell`, containing exactly `.chat-actions` then `#composer` (in that order).
+- [ ] `frontend/assets/styles.css`: the `.chat-bottom` rule above `.composer` with `position: sticky; bottom: env(safe-area-inset-bottom, 0)` and NO z-index declaration; the `#composer` rule unmodified.
+- [ ] Browser check via `test_pinned_composer.py` green in isolation — in particular `test_composer_pinned_at_every_scroll_position` (flush at 0/25/50/75% of the sticky range), `test_empty_chat_composer_sits_at_the_screen_bottom` (no scrollable space), `test_pin_holds_on_mobile_under_the_header` (no header overlap, no z-index).
+- [ ] `test_save_share_ux.py` green in isolation.
@@ -0,0 +1,27 @@
+# Task 03 — Align the two button clusters (neater, more aligned)
+
+**Phase:** `65_bottom_chat_actions` · **Source:** `TODO.md:3` — "Make the button clusters look better, neater, more aligned"
+**Story:** n/a (TODO-derived)
+
+## Objective
+The bottom row and the per-answer meta cluster read as ONE tidy, aligned system (locked A2): the New chat + Share row hugs the column's RIGHT edge on desktop — mirroring the right-aligned "Save as doc" action of every brain bubble above it — so the bottom-right of the chat is a single aligned action column. The five action pills share one geometry (≥44px targets, 999px radius, the global focus-visible ring).
+
+## Work
+1. `frontend/assets/styles.css` — the `.chat-actions` rule (L433): add `justify-content: flex-end;` so the row hugs the column's right edge on desktop. The pills keep their intrinsic widths (never stretched — `align-items: center` already beats the column default, and `justify-content` only shifts the group).
+   - The ≤640px block (L3049: `.chat-actions { flex-direction: column; align-items: stretch; gap: 0.5rem; }`) is UNCHANGED — with stretched full-width pills, horizontal alignment is moot (the stacked pills already edge-to-edge the column).
+   - Update the rule's comment: the row is the bottom cluster's top member (task 01/02), right-aligned per A2, and the vertical row↔composer spacing is the `.chat-bottom` wrapper's 0.5rem gap (task 02).
+2. Five-pill geometry pass (VERIFY — fix only if a deviation exists; the expectation is "no declaration changes"):
+   - `.new-chat-btn` (L301) / `.share-chat-btn` (L335): solid brand family — `min-height: 44px`, `border-radius: 999px`, `border: 0`, 16px icons (hidden on desktop, icon-only ≤640px), `white-space: nowrap`.
+   - `.tune-btn` (L694) / `.retry-btn` (L723) / `.save-as-doc-btn` (L756): ghost family — `min-height: 44px`, `border-radius: 999px`, `padding: 0.35rem 0.8rem`, 14px icons, `margin-left/auto` right-alignment, `font-size: 0.82rem`.
+   - If any pill measures <44px tall at 360–1280px (deviation), bring it to the family's `min-height: 44px` here — do not invent new visual languages; the two families (solid = chat-level actions, ghost = per-answer actions) are intentional (phase 55 A2).
+3. No HTML changes, no JS changes, no changes to the meta-row layout (`.msg-meta` L641 stays as-is — its internal order, chips-then-actions, is pinned by the phase 49/59 comment history).
+4. No new CSS beyond the one declaration + comments.
+
+## Testing & Quality
+- `uv run pytest` green; `uv run ruff check . && uv run pyright` clean; coverage TOTAL **>90%** (gate stays green).
+- `uv run pytest tests/e2e/test_save_share_ux.py -v --no-cov` green in isolation — its desktop assertions (Share right of New chat, both pills < column/2 wide, ONE `.chat-actions`) hold for a right-aligned row; the right-EDGE alignment itself is pinned by this phase's suite in task 04.
+
+## Completion Criteria
+- [ ] `.chat-actions` rule carries `justify-content: flex-end;` with the A2 rationale in its comment; the ≤640px stack rule is byte-identical.
+- [ ] All five action pills (New chat, Share, Tune, Retry, Save as doc) report ≥44px rendered height at 360px, 390px, and 1280px widths (quick manual/Playwright measurement during the task; the standing pin lands in task 04).
+- [ ] `test_save_share_ux.py` green in isolation (DB up).
@@ -0,0 +1,43 @@
+# Task 04 — Dedicated E2E: `tests/e2e/test_bottom_chat_actions.py`
+
+**Phase:** `65_bottom_chat_actions` · **Source:** `TODO.md:3` — "…so it's always at the bottom of the screen and easily accessble. Make the button clusters look better, neater, more aligned"
+**Story:** n/a (TODO-derived)
+
+## Objective
+One dedicated Playwright suite (house rule: one file per phase, run in isolation) pins the NEW contract — the bottom cluster is always at the bottom of the screen, right-aligned, still stacked/clickable — so a future refactor cannot silently move the pills back to the top.
+
+## Work
+1. `tests/e2e/test_bottom_chat_actions.py` (NEW — self-contained, house patterns):
+   - Header docstring: Source `TODO.md` L3, run-in-isolation command `uv run pytest tests/e2e/test_bottom_chat_actions.py -v --no-cov` (DB up: `podman compose up -d db`), the owner-locked A1/A2 contracts, and the test→contract mapping (house "Playwright Mapping Rule").
+   - Fixtures/helpers: reuse the conftest `page` (1280×800), `app_url`, `mock_llm`, `db_ready`; copy the house `_reset_db` (TRUNCATE `chunks, documents, query_log, steering_notes, saved_chats`) + threaded `_import_fixtures` KB-seed pattern from `tests/e2e/test_pinned_composer.py` (13 fixture docs) into a `seeded_kb` fixture; `login` from `tests/e2e/auth_helpers.py` is NOT needed (chat is public).
+   - Test 1 `test_empty_chat_row_rests_at_screen_bottom` (no KB seed needed — static markup):
+     - fresh `/`: exactly ONE `.chat-bottom`, the row inside it; the document is NOT scrollable (`scrollHeight <= innerHeight + 1` — the wrapper must not invent scrollable space);
+     - the row's box is in the LOWER part of the viewport (row bottom ≥ 75% of the viewport height) and sits directly ABOVE the composer (row bottom ≤ composer top + 4px, no overlap);
+     - A2: the row's RIGHT edge aligns with the `.chat-shell` right edge (±2px);
+     - the composer's bottom is not clipped below the viewport.
+   - Test 2 `test_bottom_cluster_pinned_at_every_scroll_position` (`seeded_kb`, the `test_pinned_composer.py` overflow pattern — 6 short grounded turns from that file's `SHORT_QUESTIONS`):
+     - assert the overflow precondition (`scrollHeight > innerHeight + 200`);
+     - compute the sticky range from the `.chat-bottom`'s CONTAINING BLOCK (`.chat-shell` document-bottom, same math as `test_pinned_composer.py::test_composer_pinned_at_every_scroll_position`) and assert `pin_limit > 200` and `max_scroll > pin_limit`;
+     - at scroll y ∈ {0, 25%, 50%, 75%, pin_limit−1}: the `.chat-bottom` box is FULLY inside the viewport with its bottom flush with the viewport bottom (±4px) — the row AND the composer are visible at every reading position (this is the TODO's "always at the bottom");
+     - at the document bottom: the cluster settles into flow — NO overlap with `.app-footer`, the composer is no longer glued to the viewport edge (composer bottom < viewport bottom − 4px), and the row is still directly above the composer.
+   - Test 3 `test_row_geometry_and_alignment` (no conversation needed for the row; one seeded turn for `.retry-btn`):
+     - exactly one `.chat-actions` inside `.chat-bottom`; exactly one `#new-chat-btn` + one `#share-chat-btn` in it; DOM order New chat → Share (`compareDocumentPosition` — same check as `test_save_share_ux.py`);
+     - desktop 1280×800: one horizontal row (overlapping y-bands), Share right of New chat, each pill's width < column width/2 (intrinsic, never stretched), row right edge == `.chat-shell` right edge (±2px, A2);
+     - mobile 390×844: vertical stack — Share BELOW New chat, both pills the same width, each == the `.chat-bottom` content width (±2px, full-width stretch);
+     - 360×800: `document.documentElement.scrollWidth <= 360` (no horizontal overflow);
+     - touch targets: `#new-chat-btn`, `#share-chat-btn` (and, after one seeded turn, the injected `.retry-btn` on the last brain bubble) all render ≥44px tall at BOTH 1280 and 390 widths.
+   - Test 4 `test_buttons_still_work_from_the_bottom` (`seeded_kb`, one turn so a real conversation exists):
+     - `#new-chat-btn` click → `.msg` count 0, `#empty-state` visible, `localStorage["bor.chat.v1"]` null, `#send-status` contains "New chat started" (the header.js → `bor:new-chat` → app.js chain survived the move);
+     - on the now-empty chat, `#share-chat-btn` click → `#send-status` contains "Nothing to share yet.", NO `.toast`, URL unchanged (the empty-conversation no-op guard, `app.js` L1494–1497).
+   - Determinism: mock-only answers (`MOCK_ANSWER_MARKER`), settled-state assertions (`wait_settled` pattern — `#send-label` back to "Send"), no scroll calls from the app itself (the phase-42 never-auto-scroll contract — the test does all scrolling via `window.scrollTo`).
+2. No other file changes in this task.
+
+## Testing & Quality
+- `uv run pytest tests/e2e/test_bottom_chat_actions.py -v --no-cov` green in isolation (DB up) — run it after EACH of the four tests is written, not all at once.
+- `uv run pytest` green (unit + integration — no Python app changed); `uv run ruff check . && uv run pyright` clean (the new test file must pass both).
+- Coverage TOTAL **>90%** (validate.sh gate — unchanged, no `app/` code).
+
+## Completion Criteria
+- [ ] The four tests exist, are named as specified, and are green in isolation (DB up).
+- [ ] The suite asserts the A1 pin (wrapper flush at every scroll position), the A2 right-edge alignment, the mobile stack, the 360px overflow bound, the DOM order, and BOTH click-through contracts (New chat reset, Share no-op).
+- [ ] Full suite green, lint + types clean, coverage >90%.
@@ -0,0 +1,33 @@
+# Task 05 — Regression matrix, full gate, atomic commit
+
+**Phase:** `65_bottom_chat_actions` · **Source:** `TODO.md:3` — "Move the new chat and share button to the tune/retry/save doc cluster area so it's always at the bottom of the screen and easily accessble. Make the button clusters look better, neater, more aligned"
+**Story:** n/a (TODO-derived)
+
+## Objective
+Prove the move + pin + alignment broke nothing in the adjacent contracts (the composer pin, the phase-55 action row, chat persistence, sharing, history) and land ONE atomic commit.
+
+## Work
+1. Regression E2E — each in isolation, DB up (run in this order; stop and fix the FIRST failure, do not batch-patch):
+   - `uv run pytest tests/e2e/test_pinned_composer.py -v --no-cov` (the composer pin — the most entangled contract with the new wrapper);
+   - `uv run pytest tests/e2e/test_save_share_ux.py -v --no-cov` (the phase-55 row geometry + auto-save + share flows);
+   - `uv run pytest tests/e2e/test_chat_persistence.py -v --no-cov` (the New chat reset contract, incl. the ≥44px pin);
+   - `uv run pytest tests/e2e/test_share_chat.py -v --no-cov` (the full share lifecycle — the button moved under it);
+   - `uv run pytest tests/e2e/test_chat_history.py -v --no-cov` (history restore + the Share button on the chat page);
+   - `uv run pytest tests/e2e/test_smoke.py -v --no-cov` (front-door sanity).
+2. The dedicated suite one final time: `uv run pytest tests/e2e/test_bottom_chat_actions.py -v --no-cov` green in isolation.
+3. Full gate: `uv run pytest` green; coverage TOTAL **>90%**; `uv run ruff check . && uv run pyright` clean (equivalently `.agent/validate.sh` exit 0).
+4. One atomic commit (`.agent/` is tracked — AGENTS.md rule 8):
+   ```bash
+   git add .agent/ frontend/ tests/ && git commit --no-gpg-sign -m "feat(web): move the chat action cluster to the pinned bottom and align the button sets"
+   ```
+   Commit body: one line per task — the move (task 01), the sticky `.chat-bottom` unit (task 02, A1), the right-edge alignment (task 03, A2), the dedicated suite (task 04), the regression outcome (task 05).
+
+## Testing & Quality
+- The six regression suites + the dedicated suite green in isolation (DB up).
+- `uv run pytest` green; coverage TOTAL **>90%**; lint + types clean.
+
+## Completion Criteria
+- [ ] All six regression suites green in isolation; `test_bottom_chat_actions.py` green in isolation.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] Exactly one new commit on `main` staging `.agent/ frontend/ tests/` only, `--no-gpg-sign`, Conventional Commits message as specified.
+- [ ] Phase dir moved to `.agent/phases/complete/65_bottom_chat_actions/` (pipeline step — `.agent/` stays tracked and committed).
@@ -0,0 +1,30 @@
+# Task 01 — Rewrite the History-tab copy to the auto-save model
+
+**Phase:** `66_history_auto_save_copy` · **Source:** `TODO.md:4` — "Update the history tab - the text still reads like there's a save button. There isn't anymore, every chat is saved."
+**Story:** n/a (TODO-derived)
+
+## Objective
+The three offending strings in `frontend/history.html` describe how BOR used to work (a Save button the visitor pressed). They become the locked (A3) auto-save copy — accurate, same house voice, no new markup.
+
+## Work
+1. `frontend/history.html` — three exact replacements (markup otherwise byte-identical):
+   - L6 — the meta description content becomes exactly (A3):
+     `Saved chats — every conversation is saved automatically, one click back.`
+   - L106–109 — the `.page-sub` becomes exactly (A3) — the `<strong>Save</strong>` emphasis is retired with the button; keep the `<p class="page-sub">` element, the indentation, and the single paragraph:
+     `Every conversation is saved automatically — newest activity first. Click a title to return to that chat.`
+   - L163 — the `#history-empty-row` cell text becomes exactly (A3):
+     `No saved chats yet — start a conversation and it will be saved automatically.`
+     (the `colspan="6"`, the `hidden` attribute, and the row's id are untouched — `history.js` reveals this exact row on a 0-row fetch).
+2. Leave UNTOUCHED (verified accurate — "saved" as a state, not a button): the `<h1>Saved chats</h1>` (L105), the anonymous gate copy (L123–128), the table caption, every other row/cell in `history.html`, and everything in `frontend/assets/history.js` (its "saved chat" aria-labels are state language).
+3. No CSS, no JS, no other page — the TODO scopes this to the history tab; any OTHER page found to name a Save button is noted in the commit body as follow-up material, not fixed here.
+
+## Testing & Quality
+- `uv run pytest` green (unit + integration — no Python changed); `uv run ruff check . && uv run pyright` clean.
+- Coverage TOTAL **>90%** (validate.sh gate — unchanged, no `app/` code).
+- Quick manual sanity (optional, before the pins land in task 02): `grep -n "Save" frontend/history.html` — the only remaining case-sensitive "Save" hits are the retired-comment-free state strings ("Saved chats" h1, "Saved conversations are admin-only", "saved chats" table aria-label/caption).
+
+## Completion Criteria
+- [ ] `grep -c "pressed <strong>Save</strong>\|press <strong>Save</strong>\|every conversation you saved" frontend/history.html` → 0.
+- [ ] The three locked (A3) strings are present in `frontend/history.html` (meta, page-sub, empty row), each exactly once.
+- [ ] The h1, the gate section (L119–129), and `history.js` are byte-identical to before this task.
+- [ ] `uv run pytest` green; lint + types clean; coverage >90%.
@@ -0,0 +1,45 @@
+# Phase 66 — History Tab Copy: Auto-Save, No Save Button
+
+**Source:** `TODO.md` L4 — "Update the history tab - the text still reads like there's a save button. There isn't anymore, every chat is saved."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+**Context:** Verified copy inventory (audited 2026-09-01, line numbers as of this writing):
+- `frontend/history.html` L6 — `<meta name="description" content="Saved chats — every conversation you saved, one click back.">` ("you saved" implies the manual action).
+- `frontend/history.html` L106–109 — the `.page-sub`: "Every conversation you pressed <strong>Save</strong> on — newest activity first. Click a title to return to that chat." — the primary offender: it names a Save button that has not existed since phase 55 (owner-locked A2, 2026-08-31: every conversation auto-saves via `app.js` `persistConversation`; pinned by `test_save_share_ux.py::test_anonymous_auto_save`).
+- `frontend/history.html` L163 — the empty-table row (inside `#history-empty-row`, `hidden` until `frontend/assets/history.js` reveals it on a 0-row fetch): "No saved chats yet — finish a conversation and press <strong>Save</strong> in the chat."
+- STAYS AS-IS (verified accurate — "saved" as a STATE, not a button): the `<h1>Saved chats</h1>` (L105), the anonymous gate copy (L123–128: "Sign in to view your saved chats" / "Saved conversations are admin-only…"), the table caption, and the `history.js` aria-labels ("Delete saved chat: …", "Unshare saved chat: …").
+- No existing test pins any of the three offending strings (verified: "pressed Save" / "press Save" / "every conversation you saved" appear nowhere in `tests/`).
+- `.agent/` is tracked and committed (AGENTS.md rule 8) — the phase commit stages `.agent/` + `frontend/` + `tests/`.
+
+## Objective
+Every user-visible string on the History tab describes the app as it works TODAY: conversations save themselves automatically — there is no Save button to press. The exact replacement copy is locked below.
+
+## Dependencies
+- `65_bottom_chat_actions` (todo, preceding — no functional dependency; ordering by number)
+
+## Tasks
+1. `01_history_page_copy.md` — rewrite the three strings in `frontend/history.html` (meta description, page-sub, empty row) to the locked auto-save copy.
+2. `02_tests_and_commit.md` — unit text pins + dedicated E2E `tests/e2e/test_history_copy.py` (run in isolation) + regression pass + one atomic commit.
+
+## Testing & Quality
+- Unit pins (house style, `tests/unit/test_stale_ui_copy.py` pattern — read `frontend/history.html` as text): the old literals are GONE, the locked replacements are present.
+- E2E (mandatory, house rule): `tests/e2e/test_history_copy.py`, run in isolation against the shared conftest server (DB up) — an admin sees the ACTUAL page (gate hidden, table rendered): the rendered page-sub and empty-row texts match the locked copy, and no rendered page text reads like a Save button exists.
+- Coverage: **>90%** on `app/` (validate.sh gate — no `app/` change, the gate stays green at its current level).
+
+## Completion Criteria
+- [ ] `frontend/history.html` contains none of: "you pressed <strong>Save</strong>", "press <strong>Save</strong>", "every conversation you saved" — and carries the three locked (A3) strings.
+- [ ] The rendered History page (admin, empty table) shows the locked page-sub and empty-row text; the `<h1>Saved chats</h1>` and the gate copy are untouched.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_history_copy.py -v --no-cov` green in isolation (DB up).
+- [ ] Regression E2E suites green in isolation: `test_chat_history.py`, `test_stale_saved_chats.py`.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/`.
+
+## Locked decisions
+- **Owner-locked (2026-09-01, roadmap confirmation, A3):** exact replacement copy —
+  - meta description (`history.html` L6): `Saved chats — every conversation is saved automatically, one click back.`
+  - page-sub (`history.html` L106–109): `Every conversation is saved automatically — newest activity first. Click a title to return to that chat.` (the `<strong>Save</strong>` emphasis is retired with the button — no inline emphasis in the replacement)
+  - empty row (`history.html` L163): `No saved chats yet — start a conversation and it will be saved automatically.`
+
+## Commit
+```bash
+git add .agent/ frontend/ tests/ && git commit --no-gpg-sign -m "fix(web): history tab copy — every chat saves automatically, there is no Save button"
+```
@@ -0,0 +1,41 @@
+# Task 02 — Unit pins + dedicated E2E + regression pass + atomic commit
+
+**Phase:** `66_history_auto_save_copy` · **Source:** `TODO.md:4` — "Update the history tab - the text still reads like there's a save button. There isn't anymore, every chat is saved."
+**Story:** n/a (TODO-derived)
+
+## Objective
+The new auto-save copy is pinned at two layers so it can never silently regress — unit text pins (no browser, house style) and one dedicated Playwright suite asserting what a signed-in admin actually SEES on the History tab — then one atomic commit.
+
+## Work
+1. `tests/unit/test_history_copy.py` (NEW — house pattern `tests/unit/test_stale_ui_copy.py`: read `frontend/history.html` as text, assert substrings):
+   - Negative pins (GONE): `"you pressed <strong>Save</strong>"`, `"press <strong>Save</strong> in the chat"`, `"every conversation you saved"`.
+   - Positive pins (PRESENT, exactly once each): the three locked (A3) strings — `Saved chats — every conversation is saved automatically, one click back.`, `Every conversation is saved automatically — newest activity first. Click a title to return to that chat.`, `No saved chats yet — start a conversation and it will be saved automatically.`
+   - State-language survivors (PRESENT, proving no over-deletion): `<h1>Saved chats</h1>`, `Sign in to view your saved chats`, `Saved conversations are admin-only`.
+2. `tests/e2e/test_history_copy.py` (NEW — one phase, one file, run in isolation, DB up; shared conftest server, default env):
+   - Setup (house patterns from `tests/e2e/test_chat_history.py`): `_reset_db` with the TRUNCATE extended to include `saved_chats` (so the table is genuinely empty), `login(page, app_url, next="/history.html")` from `tests/e2e/auth_helpers.py`.
+   - Admin view of an empty History tab:
+     - the anonymous gate is hidden (`#history-gate` hidden — the login worked);
+     - `#history-empty-row` is revealed (visible) and its textContent == the locked (A3) empty-row string;
+     - the `.page-sub` innerText == the locked (A3) page-sub string (whitespace-normalized compare);
+     - `document.querySelector('meta[name="description"]').content` == the locked (A3) meta string;
+     - the no-button contract: `document.body.innerText` matches NEITHER `/press(ed)?\s+save/i` NOR `/save\s+button/i` — while the `<h1>` still reads "Saved chats" (asserted present, so the scan cannot pass by deleting the heading);
+     - no `#save-chat-btn` anywhere (phase 55 A2 — the control is gone from the app, not just the copy).
+   - Determinism: all assertions are settled-state (static HTML + the one 0-row fetch); Playwright `expect` retries ride out the table load.
+3. Regression E2E (each in isolation, DB up): `test_chat_history.py` (the row actions + restore flow on this page), `test_stale_saved_chats.py` (the stale pills + regenerate flow).
+4. One atomic commit (`.agent/` tracked — AGENTS.md rule 8):
+   ```bash
+   git add .agent/ frontend/ tests/ && git commit --no-gpg-sign -m "fix(web): history tab copy — every chat saves automatically, there is no Save button"
+   ```
+   Commit body: the verification read-through outcome from task 01 (the three replacements; h1/gate/history.js untouched) — one line each.
+
+## Testing & Quality
+- `uv run pytest` green (unit + integration); coverage TOTAL **>90%** (validate.sh gate — no `app/` change).
+- `uv run pytest tests/e2e/test_history_copy.py -v --no-cov` green in isolation (DB up) — run it after the unit pins pass.
+- `uv run ruff check . && uv run pyright` clean (the new test files included).
+
+## Completion Criteria
+- [ ] `tests/unit/test_history_copy.py` + `tests/e2e/test_history_copy.py` exist and are green (E2E in isolation, DB up).
+- [ ] The two regression E2E suites are green in isolation.
+- [ ] Full suite green, coverage >90%, lint + types clean.
+- [ ] Exactly one new commit on `main`, staging `.agent/ frontend/ tests/` only, `--no-gpg-sign`.
+- [ ] Phase dir moved to `.agent/phases/complete/66_history_auto_save_copy/` (`.agent/` stays tracked and committed).
@@ -0,0 +1,51 @@
+# Phase 67 — LLM Retry with Live "Trying Again" Feedback
+
+**Source:** `TODO.md` L3 — "Add a .env configurable retry in case the LLM server fails to respond. Allow 3 retries by default, with 5 seconds between each retry. Update the user interface to show 'communication interrupted, trying again' or something like that if the LLM server stops communicating."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+**Context:**
+- `app/rag/llm.py` — `LLMClient.chat_stream` is the single streaming surface (deflected turns + every agent round); `LLMError` is the typed failure the API layer already turns into an SSE `error` frame (`app/api/chat.py` — `except LLMError` around the piece loop; `EmbeddingError` around the pre-stream `llm.embed_one(request.message)`).
+- `app/rag/agent.py` — `run_agent` issues one `chat_stream` per round (plus a final `tools=None` call at the round cap); the phase-48 teardown binds each stream and closes it in a `finally`.
+- `app/config.py` — the `BOR_*` settings block (LLM section: `llm_base_url`, `llm_chat_model`, …); `agent_max_rounds` shows the house pattern for a tunable with a startup validator.
+- `app/schemas.py` — the SSE event family (`ChatThinkingEvent`, `ChatToolEvent`, `ChatDoneEvent`, `ChatErrorEvent`).
+- `frontend/assets/app.js` — `runTurn`'s `readSSE` callback is the event state machine; the `tool` branch is the house pattern for a server-driven STATUS change (`#send-status` + typing-indicator `aria-label`, no new bubble, `clearTurnTimeout()` because a frame arrived). `tests/e2e/test_agent_document_tools.py` (L236+) records every `#send-status` value during a turn for assertions.
+- `tests/e2e/mock_llm.py` — deterministic marker-driven OpenAI-compatible stand-in (chat + embeddings), run as a uvicorn subprocess by `tests/e2e/conftest.py`; the marker flow is discriminated statelessly from the request.
+- **Not in scope (owner-locked A1):** the one-shot `LLMClient.chat()` path (document summaries, KB overview) and the sync probe (`check_models`) — those are admin/import paths with their own fail-fast behavior (phase 41) and no live user to notify.
+
+## Objective
+When the aipi endpoint dies mid-turn, the app retries the LLM request automatically — `.env`-tunable, **3 retries / 5 s delay by default** — and the UI tells the user what is happening ("Communication interrupted — retrying (n of N)…") instead of the turn dead-ending in an error banner. A retry only ever restarts a request that has **not yet streamed a single output frame** to the client (locked A2), so no answer token is ever duplicated.
+
+## Dependencies
+- `66_history_auto_save_copy` (todo, preceding — no functional dependency; ordering by number)
+
+## Tasks
+1. `01_config_and_retry_primitive.md` — `BOR_LLM_RETRIES` / `BOR_LLM_RETRY_DELAY` settings + the `RetryPiece` + `chat_stream_retried()` primitive in `app/rag/llm.py`.
+2. `02_chat_endpoint_retry.md` — the `retry` SSE event, the embedding retry loop, and the deflected-stream retry in `app/api/chat.py`.
+3. `03_agent_round_retry.md` — per-round retries inside `run_agent` (loop rounds + final no-tools call).
+4. `04_frontend_retry_status.md` — the `retry` branch in `runTurn`'s SSE handler: the live "retrying (n of N)…" status.
+5. `05_e2e_and_commit.md` — `mock_llm.py` failure injection, `tests/e2e/test_llm_retry.py`, regressions, commit.
+
+## Testing & Quality
+- Unit: `tests/unit/test_config.py` (new vars, defaults, validators), `tests/unit/test_llm_client.py` (`chat_stream_retried` semantics — retry only before the first piece, `RetryPiece` ordering, exhaustion, `retries=0`), `tests/unit/test_agent.py` (per-round retry), `tests/unit/test_frontend_tool_states.py` pattern (JS pins for the `retry` branch).
+- Integration: `tests/integration/test_chat_api.py` — SSE frame ordering (embed-fail → `retry` frame → completed turn; embed-exhausted → `retry` frames + terminal `error` frame; mid-stream failure AFTER a delta → no retry, `error` frame).
+- E2E (mandatory, house rule): `tests/e2e/test_llm_retry.py`, run in isolation (mock LLM with deterministic failure injection; `BOR_LLM_RETRY_DELAY=0` on the test server so the suite stays fast).
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] `BOR_LLM_RETRIES` (default 3) and `BOR_LLM_RETRY_DELAY` (default 5 s) are honored end to end and documented in `.env.example`.
+- [ ] A dead-then-recovered endpoint: the turn completes with a normal answer and the UI showed the "retrying" status while waiting; a dead endpoint: after N attempts the existing terminal error banner appears.
+- [ ] A stream failure after the first output frame still terminates with the `error` event — no retry, no duplicated tokens.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_llm_retry.py -v --no-cov` green in isolation (DB up).
+- [ ] Regression E2E suites green in isolation: `test_chat_rag.py`, `test_agent_document_tools.py`, `test_stop_generation.py`, `test_retry_answer.py`.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/`.
+
+## Locked decisions
+- **Owner-locked (2026-09-01, roadmap confirmation, A1):** scope is the **chat turn only** — question embedding + the answer stream (deflected path and every agent round). `LLMClient.chat()` (summaries, KB overview) and `check_models` (sync probe) are untouched.
+- **Owner-locked (2026-09-01, roadmap confirmation, A2):** a retry restarts the LLM request **only if no output frame has been streamed to the client yet** for that request (no thinking/tool/delta emitted). Once tokens are flowing, the failure stays terminal (the existing `error` frame) — a partial answer is never redone.
+- **Owner-locked (2026-09-01, roadmap confirmation, A3):** env names `BOR_LLM_RETRIES` (int, default **3**) and `BOR_LLM_RETRY_DELAY` (seconds, default **5**) — a flat delay between attempts, no exponential backoff (the TODO specifies a fixed 5 s).
+- **Owner-locked (2026-09-01, roadmap confirmation, A4):** UI copy — `#send-status` reads `Communication interrupted — retrying (n of N)…` (n = current attempt, N = the configured retry count) on the existing status line; no new banner, no bubble.
+
+## Commit
+```bash
+git add -A .agent/ app/ tests/ frontend/ && git commit --no-gpg-sign -m "feat(rag): retry a failed LLM request before the first token lands — BOR_LLM_RETRIES/BOR_LLM_RETRY_DELAY with a live 'retrying' status"
+```
@@ -0,0 +1,44 @@
+# Task 01 — Retry Settings + the `chat_stream_retried` Primitive
+
+**Phase:** `67_llm_retry` · **Source:** `TODO.md:3` — "Add a .env configurable retry in case the LLM server fails to respond. Allow 3 retries by default, with 5 seconds between each retry. Update the user interface to show 'communication interrupted, trying again' or something like that if the LLM server stops communicating."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+The two `.env` knobs (`BOR_LLM_RETRIES=3`, `BOR_LLM_RETRY_DELAY=5`) and one shared streaming primitive — `chat_stream_retried()` in `app/rag/llm.py` — that the chat endpoint (task 02) and the agent loop (task 03) both build on. The primitive is the ONLY place the retry-before-first-piece rule (locked A2) lives.
+
+## Work
+1. `app/config.py` — in the `--- LLM ---` settings block (next to `llm_chat_model` / `stream_thinking`), add:
+   - `llm_retries: int = 3` — comment: retries of a failed LLM request when the endpoint stops responding (phase 67, `BOR_LLM_RETRIES`); `0` = no retries (the turn fails on the first error, pre-phase-67 behavior).
+   - `llm_retry_delay: float = 5.0` — comment: flat seconds to wait between attempts (phase 67, `BOR_LLM_RETRY_DELAY`); the TODO-locked 5 s, no backoff.
+   - Startup validators (house pattern: `agent_max_rounds` rejects negatives at startup): `llm_retries >= 0`, `llm_retry_delay >= 0`.
+2. `.env.example` — in the LLM section, add the two commented defaults next to `BOR_LLM_CHAT_MODEL`:
+   - `# BOR_LLM_RETRIES=3             # retry a dead LLM request before the first token lands (phase 67); 0 = off`
+   - `# BOR_LLM_RETRY_DELAY=5        # seconds between LLM retries (phase 67)`
+3. `app/rag/llm.py` — add, next to the other piece dataclasses:
+   - `RetryPiece` — frozen dataclass, fields `attempt: int` (1-based attempt number that is about to be tried), `max_attempts: int` (total attempts = `llm_retries + 1`). One per wait; the API layer turns it into an SSE `retry` frame.
+   - `async def chat_stream_retried(llm: LLMClient, messages: list[dict[str, str]], *, tools: list[dict[str, Any]] | None = None, retries: int = 0, delay: float = 0.0) -> AsyncGenerator[StreamPiece | ToolCallPiece | RetryPiece, None]`:
+     - Loop `attempt` over `range(1, retries + 2)` (i.e. `retries + 1` attempts).
+     - Each attempt: open `stream = llm.chat_stream(cast(...), tools=tools)`; track `emitted = False`.
+     - `async for piece in stream`: mark `emitted = True`, `yield piece`.
+     - On `LLMError`: if `emitted` → **re-raise unchanged** (terminal — locked A2: tokens already flowed, never redo a partial). Else if this was the final attempt → re-raise (exhausted). Else: `logger.warning("llm stream failed before the first piece (attempt %d/%d) — retrying in %.1fs: %s", ...)`, `yield RetryPiece(attempt, retries + 1)`, `await asyncio.sleep(delay)`, and start the next attempt with the SAME `messages`/`tools` (the request is restarted byte-identical — `chat_stream` is stateless).
+     - `finally: await stream.aclose()` per attempt (keeps phase 48's deterministic teardown for every attempt's stream, including a consumer abandon during the sleep or a mid-attempt GeneratorExit).
+     - `retries=0` → exactly one attempt, never a `RetryPiece` (the pre-phase-67 path, the kill-switch).
+     - Docstring: state the A2 rule explicitly and that `RetryPiece` always precedes its sleep (the API frame must reach the client before the wait starts).
+4. Unit tests — `tests/unit/test_llm_client.py` (append; a fake `LLMClient` whose `chat_stream` is scripted):
+   - failure on attempt 1, success on attempt 2 → pieces = `[RetryPiece(1, N), *answer pieces]`, `chat_stream` called twice, sleep awaited with the delay (monkeypatch `asyncio.sleep` and record calls).
+   - failure on every attempt with `retries=2` → `RetryPiece(1, 3)`, `RetryPiece(2, 3)` then `LLMError` raised; 3 calls total.
+   - failure AFTER the first piece → `LLMError` raised immediately, no `RetryPiece`, sleep never awaited, no second call (the A2 pin).
+   - `retries=0` → one call, error propagates, no `RetryPiece`.
+   - `delay=0` → sleep called with 0 (the e2e fast-path).
+   - a consumer abandon (close the outer generator) mid-sleep and mid-attempt → no exception leaks, inner stream `aclose()` awaited.
+5. `tests/unit/test_config.py` — defaults (`3` / `5.0`), `BOR_LLM_RETRIES=0` and `BOR_LLM_RETRY_DELAY=1.5` honored, negative values rejected at startup.
+
+## Testing & Quality
+- Unit/integration: as listed in Work (4).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] `Settings()` defaults: `llm_retries == 3`, `llm_retry_delay == 5.0`; `.env.example` documents both.
+- [ ] `chat_stream_retried` passes all unit pins, including the A2 no-retry-after-first-piece rule.
+- [ ] `uv run pytest tests/unit/test_llm_client.py tests/unit/test_config.py -v` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] no behavior change in completed work (the plain `llm.chat_stream` is untouched — the new function is additive).
@@ -0,0 +1,40 @@
+# Task 02 — The `retry` SSE Event + Endpoint-Level Retries (Embedding, Deflected Stream)
+
+**Phase:** `67_llm_retry` · **Source:** `TODO.md:3` — "…Update the user interface to show 'communication interrupted, trying again' or something like that if the LLM server stops communicating."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+`POST /api/chat` survives a dead endpoint: the pre-stream embedding and the deflected-turn stream retry (with SSE `retry` frames the UI can render live), and a `RetryPiece` from any answer stream becomes a `retry` SSE frame. Exhaustion and post-token failures keep today's terminal `error` frames.
+
+## Work
+1. `app/schemas.py` — add `ChatRetryEvent` next to `ChatErrorEvent`:
+   - `type: Literal["retry"] = "retry"`, `attempt: int` (the attempt number that just failed / the retry currently in flight — document which the endpoint sends: the attempt being tried next, 1-based), `max_attempts: int` (`llm_retries + 1`).
+   - Docstring: sibling of the other SSE events; signals "the LLM request was restarted before any token landed" (locked A2); the client shows a transient status, not an error.
+2. `app/api/chat.py` — the embedding step (currently: `try: question_vec = await llm.embed_one(...) except EmbeddingError → error frame`):
+   - Replace with an explicit attempt loop over `settings.llm_retries + 1` attempts (`attempt` 1-based):
+     - on `EmbeddingError` before the final attempt: `logger.warning("chat: question=%r embedding failed (attempt %d/%d) — retrying in %.1fs", ...)`, `yield sse_event(ChatRetryEvent(attempt=attempt + 1, max_attempts=settings.llm_retries + 1).model_dump())`, `await asyncio.sleep(settings.llm_retry_delay)`.
+     - on the final failure: the EXISTING terminal `error` frame ("I couldn't reach the embedding model — please try again.") unchanged — retries are exhausted, the copy stays (it reads correctly after N tries).
+     - `llm_retries=0` → byte-identical to today (single attempt, same frame on failure).
+     - track the turn-level retry count (`retries_used`) for the per-turn log line (step 4).
+3. `app/api/chat.py` — the answer stream:
+   - deflected path: `answer_stream = llm.chat_stream(messages)` → `chat_stream_retried(llm, messages, tools=None, retries=settings.llm_retries, delay=settings.llm_retry_delay)`.
+   - grounded path: unchanged call to `run_agent(...)` (task 03 makes IT retry internally); the shared piece loop below handles its `RetryPiece`s.
+   - piece loop: add the `RetryPiece` branch (alongside the `ToolCallPiece` branch): `yield sse_event(ChatRetryEvent(attempt=piece.attempt, max_attempts=piece.max_attempts).model_dump())` and fold the attempt into `retries_used` (count each `RetryPiece`). No other state changes (the thinking/clock/timeout handling is the client's job).
+4. `app/api/chat.py` — per-turn log line (PLAN §9): append a `retries=N` field (0 when nothing retried — the grounded/deflected/deflected-empty shapes all carry it, so the line shape is uniform; update the log-format comments and any test that pins the line shape).
+5. Integration tests — `tests/integration/test_chat_api.py` (fake LLM client injected via the existing dependency override pattern):
+   - embedding fails once then succeeds → frames: `retry` (attempt 2) then the normal `delta`/`done` sequence; the answer completes.
+   - embedding fails on every attempt (`llm_retries=2`) → `retry` frames (attempts 2, 3) then the terminal `error` frame; the detail is the existing embedding copy.
+   - deflected stream: first attempt `LLMError` before any piece, second attempt streams → `retry` frame then `delta` frames + `done`.
+   - deflected stream: `LLMError` AFTER one delta frame → no `retry` frame, the existing terminal `error` frame ("The chat model dropped the connection — try again?").
+   - `llm_retries=0` → today's behavior (one attempt, error frame, no `retry` frames).
+   - per-turn log line carries `retries=N` (assert on the captured log record).
+6. `tests/unit/test_frontend_tool_states.py` pattern — `tests/unit/test_frontend_feedback.py` (or the sibling JS-pin file the executor finds for SSE-branch ordering): pin that `ev.type === "retry"` is a first-class branch in `runTurn`'s handler (task 04 implements it; the pin lands with this task's contract so the shape is locked early). If a dedicated branch-order pin file already exists, extend it instead of creating one.
+
+## Testing & Quality
+- Unit/integration: as listed in Work (5, 6).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] A simulated dead-then-recovered endpoint returns a completed turn with a `retry` frame in between; a dead endpoint returns the existing terminal error frame after `llm_retries + 1` attempts.
+- [ ] `uv run pytest tests/integration/test_chat_api.py -v` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] no behavior change when `BOR_LLM_RETRIES=0` (pre-phase-67 wire shape, byte-identical frames).
@@ -0,0 +1,31 @@
+# Task 03 — Per-Round Retries Inside the Agent Loop
+
+**Phase:** `67_llm_retry` · **Source:** `TODO.md:3` — "Add a .env configurable retry in case the LLM server fails to respond. Allow 3 retries by default, with 5 seconds between each retry."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+A grounded turn survives a dead endpoint in the MIDDLE of the agent loop: every model request `run_agent` makes (each tool round and the forced final no-tools call) goes through `chat_stream_retried`, so a round that dies before its first piece is restarted with the same messages — while the round-cap, tool-counting, and phase-48 teardown semantics stay exactly as they are.
+
+## Work
+1. `app/rag/agent.py` — `run_agent`:
+   - loop round: `stream = llm.chat_stream(cast("list[dict[str, str]]", messages), tools=tools)` → `stream = chat_stream_retried(llm, cast(...), tools=tools, retries=settings.llm_retries, delay=settings.llm_retry_delay)`. Keep the phase-48 binding + `try/finally: await stream.aclose()` shape AROUND the new generator — closing the outer generator propagates `GeneratorExit` into `chat_stream_retried`, whose own `finally` closes the in-flight inner `chat_stream` (task 01). The inner stream's teardown therefore still happens deterministically on consumer abandon.
+   - forced final no-tools call: same substitution with `tools=None`.
+   - the `async for piece in stream` loop already yields every piece — `RetryPiece` values flow through to the API layer unchanged (no filtering); `calls` still collects only `ToolCallPiece`s.
+   - `retries=0` (or `agent_max_rounds=0`'s single `tools=None` request) → identical to today: one plain attempt.
+   - update the module docstring + the `run_agent` docstring: a failed round is retried before its first piece (phase 67, locked A2); a round that already streamed pieces fails the turn as before.
+2. Unit tests — `tests/unit/test_agent.py` (scripted fake `LLMClient.chat_stream`):
+   - round 1 dies before any piece, round 1 retry succeeds with a `list_documents` tool call → pieces include a `RetryPiece` BEFORE the tool call; the tool executes; the final answer streams; `holder.tool_calls == 1`; `tool_calls` log line still emitted once.
+   - a round dies AFTER a content piece → `LLMError` propagates out of `run_agent`, no retry (A2), the holder is untouched.
+   - the forced final no-tools call (round cap reached) dies before its first piece → retried; the answer from the retry streams.
+   - `settings.llm_retries=0` → no `RetryPiece` ever; a dead round raises immediately (pre-phase-67 behavior).
+   - consumer abandon (close `run_agent`) while a retried round is mid-sleep → no leaked exception, inner stream closed.
+   - round-cap counting is unaffected by retries: a failing-then-succeeding round consumes ONE round (retries are invisible to the cap).
+
+## Testing & Quality
+- Unit/integration: as listed in Work (2).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] A grounded turn whose agent loop's endpoint dies-then-recovers completes with the tool flow intact and a `RetryPiece` in the stream.
+- [ ] `uv run pytest tests/unit/test_agent.py -v` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] the round cap, `holder` accounting, and teardown semantics are unchanged (existing `tests/unit/test_agent.py` pins still green).
@@ -0,0 +1,39 @@
+# Task 04 — The Live "Communication interrupted — retrying" Status
+
+**Phase:** `67_llm_retry` · **Source:** `TODO.md:3` — "Update the user interface to show 'communication interrupted, trying again' or something like that if the LLM server stops communicating."
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+When a `retry` SSE frame arrives, the composer status line tells the user exactly what is happening — `Communication interrupted — retrying (n of N)…` — using the house status pattern (the `tool` frames' treatment: `#send-status` + typing-indicator `aria-label`, no new bubble, turn-timeout reset). No CSS change.
+
+## Work
+1. `frontend/assets/app.js` — `runTurn`'s `readSSE` callback, add a first-class branch (between the `tool` and `delta` branches — the branch-order unit pin from task 02 expects it):
+   ```js
+   } else if (ev.type === "retry") {
+     clearTurnTimeout(); // the stream is alive — the server is restarting the LLM request
+     const attempt = Number(ev.attempt) || 1;
+     const max = Number(ev.max_attempts) || 1;
+     const retryStatus =
+       `Communication interrupted — retrying (${attempt} of ${max})…`;
+     if (uiState === UI_STATE.thinking || uiState === UI_STATE.streaming) {
+       sendStatus.textContent = retryStatus;
+       document
+         .querySelector("#typing-indicator .bubble")
+         ?.setAttribute("aria-label", retryStatus);
+     }
+   }
+   ```
+   - The status gate covers BOTH live states: a retry arrives only before the current request's first piece (server rule A2), but the UI may already be `streaming` when a LATER agent round restarts after an earlier round emitted content (the rare content+tool-call stream).
+   - NO new bubble, NO tool line, NO banner — it is a transient status; the next `thinking`/`tool`/`delta` frame replaces it via the existing branches.
+2. `frontend/assets/app.js` — the file-header doc comment: add the `retry` frame to the SSE-event inventory (the header documents every frame type; keep the house convention).
+3. JS unit pin (task 02's contract) — the pin file from task 02 now asserts: the branch exists between `tool` and `delta`; it calls `clearTurnTimeout()`; the locked copy literal `Communication interrupted — retrying (${attempt} of ${max})…` appears; no `addMessage`/`appendToolLine` in the branch.
+4. A11y (PLAN §7 / AGENTS.md rule 5): the status line already announces through the existing `#send-status` live-region and the typing-indicator `aria-label` — verify the branch reuses both (no new DOM, no new region). Contrast/focus unaffected (no new element).
+
+## Testing & Quality
+- Unit: the JS pin (Work 3).
+- Coverage: **>90%** on `app/` (no `app/` change this task — the gate holds at its current level).
+
+## Completion Criteria
+- [ ] The branch-order + copy + no-DOM pins are green.
+- [ ] `uv run ruff check . && uv run pyright` clean (no JS check — house style: JS is E2E-gated in task 05).
+- [ ] no behavior change for existing frame types (the branch is purely additive).
@@ -0,0 +1,38 @@
+# Task 05 — Failure-Injection Mock, E2E Suite, Regressions, Commit
+
+**Phase:** `67_llm_retry` · **Source:** `TODO.md:3` — the full item (end-to-end proof: `.env` retry + the live UI feedback).
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+Prove the whole loop in a browser: a dead-then-recovered LLM endpoint shows the "retrying" status mid-turn and the answer still completes; a dead endpoint exhausts the retries and lands on the existing error banner. One dedicated Playwright suite, green in isolation, plus the regression pass and the phase commit.
+
+## Work
+1. `tests/e2e/mock_llm.py` — deterministic failure injection (module-level counters, reset per trigger phrase — the mock is single-conversation per e2e server):
+   - `RETRY_TRIGGER = "fail then answer"` — user message containing it: the first **2** streaming `chat/completions` requests respond `500` (JSON body, like a dead proxy); the 3rd streams the normal composed answer. (2 = 1 original attempt + 1 retry under the default `BOR_LLM_RETRIES=3`, so the e2e exercises a real retry without waiting for exhaustion.)
+   - `ALWAYS_FAIL_TRIGGER = "always fail"` — user message containing it: every streaming `chat/completions` request responds `500` (exhaustion path).
+   - `EMBED_FAIL_TRIGGER = "embed fail once"` — the first `embeddings` request responds `500`; the next returns the normal bag-of-words vector (covers the embedding retry loop in task 02).
+   - Document all three in the module docstring's marker list (house convention).
+2. `tests/e2e/conftest.py` (or the `app_server` env block that sets `BOR_LLM_BASE_URL`) — add `BOR_LLM_RETRY_DELAY=0` to the e2e server env so retry waits are instant (the e2e pins the MECHANISM; the 5 s default is unit-pinned via config). `BOR_LLM_RETRIES` stays at its default (3) — the exhaustion test relies on the real default.
+3. `tests/e2e/test_llm_retry.py` — the dedicated suite (reuse the `#send-status` value-recording `add_init_script` pattern from `tests/e2e/test_agent_document_tools.py` L236+):
+   - **dead-then-recovered (deflected path):** import one fixture doc; ask an unrelated question containing `fail then answer` (LOW turn → deflected stream retry): the recorded status values contain `Communication interrupted — retrying (2 of 4)…`; the turn settles with a deflected answer bubble, NO error banner.
+   - **dead-then-recovered (grounded path):** ask a KB question containing `fail then answer` (HIGH turn → agent round retries): same status assertion; the answer completes (sources present).
+   - **embedding retry:** an `embed fail once` question completes with a normal answer and a `retry` status recorded (the embedding loop is visible to the UI).
+   - **exhaustion:** an `always fail` question → the error banner (`role="alert"`) appears with the existing copy ("The chat model dropped the connection — try again?"); the last recorded status is the highest attempt (`… retrying (4 of 4)…`); the send button is re-enabled (the banner path settles the state machine).
+   - **zero-retry kill switch is unit-pinned only** (no e2e server variant needed).
+4. Regression pass (each in isolation, DB up): `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov`, `test_agent_document_tools.py`, `test_stop_generation.py`, `test_retry_answer.py` — all green (the turn state machine, tool flow, stop, and redo must be untouched).
+5. Full gate: `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), `uv run ruff check . && uv run pyright`.
+6. Commit (AGENTS.md rule 8 — one atomic phase commit; stage the phase's code + its dir move):
+   ```bash
+   git add -A .agent/ app/ tests/ frontend/ && git commit --no-gpg-sign -m "feat(rag): retry a failed LLM request before the first token lands — BOR_LLM_RETRIES/BOR_LLM_RETRY_DELAY with a live 'retrying' status"
+   ```
+   Then move the phase dir to `.agent/phases/complete/67_llm_retry/` and include the move in the SAME commit (house convention: commit first, move + amend the tree, one atomic commit — follow exactly what phase 66's commit did).
+
+## Testing & Quality
+- E2E: as listed (Work 3–4).
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_llm_retry.py -v --no-cov` green in isolation (DB up).
+- [ ] The four regression suites green in isolation.
+- [ ] `uv run pytest --cov=app` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] One `--no-gpg-sign` Conventional Commits commit; phase dir in `.agent/phases/complete/`.
@@ -0,0 +1,46 @@
+# Phase 68 — Agent Search Tool: grep the Indexed Documents
+
+**Source:** `TODO.md` L4 — "Add a search tool that allows the LLM to grep through the uploaded documents for a given string"
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+**Context:**
+- `app/rag/agent.py` — `AGENT_TOOLS` currently defines two OpenAI functions (`list_documents`, `read_document`); `_execute_tool` runs them server-side against the DB with fixed refusal strings (`ALREADY_IN_CONTEXT`, `UNKNOWN_TOOL`, `MISSING_READ_ARGS`); `AgentHolder` counts executed calls (`tool_calls`) and context additions (`read_docs`).
+- `documents` table (`app/models.py`) — `content` is the FULL document text (`Text` column), so a grep is a plain in-process scan: no new index, no migration.
+- `app/schemas.py` — `ChatToolEvent` (`{type: "tool", name, argument}`): `argument` is `"source/path"` for `read_document`, null otherwise.
+- `frontend/assets/app.js` — `runTurn`'s `tool` branch builds the status label (`${brand()} is reading …` / `… is listing documents`) and `appendToolLine` (L796) renders the per-call line (`📄 Reading <code>path</code>` / `🔎 Listing documents`); both special-case by tool name.
+- `tests/e2e/mock_llm.py` — the marker-driven deterministic tool flow (`use your tools` → list → read → answer) is the template for a search flow; `tests/e2e/test_agent_document_tools.py` is the pattern for the E2E assertions (`.tool-call` lines, `#send-status` recording).
+- Phases 37/45/63 (complete) established the tool infrastructure: native tool-calling, unlimited calls bounded by the round cap, labeled `source:/path:` catalog lines.
+
+## Objective
+A third agent tool, `search_documents`, lets the model grep every indexed document (or one named document) for an exact string and get back `path:line: text` matches — so it can LOCATE content cheaply and then `read_document` the winner, instead of reading whole documents hoping the string is in them.
+
+## Dependencies
+- `67_llm_retry` (todo, preceding — no functional dependency; ordering by number)
+
+## Tasks
+1. `01_search_tool_backend.md` — the tool definition, the `grep_document` helper, and the `_execute_tool` branch.
+2. `02_search_tool_api_ui.md` — the SSE `tool` argument mapping and the frontend status/tool-line for the search.
+3. `03_e2e_and_commit.md` — the mock search flow, the dedicated E2E suite, regressions, commit.
+
+## Testing & Quality
+- Unit: `tests/unit/test_agent.py` — match semantics (case-insensitivity, 1-based line numbers, the 20-match cap, 200-char line truncation, scoped single-doc search, no-match/missing-arg/unknown-doc refusals, `tool_calls` counting, `read_docs` untouched).
+- Integration: `tests/integration/test_agent_tools.py` — the tool appears in `AGENT_TOOLS` with the locked parameter shape; `tests/integration/test_chat_api.py` (or the SSE pin file) — a `search_documents` call streams `argument = pattern`.
+- E2E (mandatory, house rule): `tests/e2e/test_search_tool.py`, run in isolation (deterministic mock flow: the model searches, sees the match line, answers from it).
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] `search_documents` is the third entry in `AGENT_TOOLS`; a model call with `pattern` (optionally `source`+`path`) returns grep-style matches or a no-match line.
+- [ ] The UI shows `Brain is searching for '…'` in the status line and a `🔎 Searching for '<pattern>'` tool line, persisted/restored like the other tool lines.
+- [ ] `uv run pytest` green; coverage TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] `uv run pytest tests/e2e/test_search_tool.py -v --no-cov` green in isolation (DB up).
+- [ ] Regression E2E suites green in isolation: `test_agent_document_tools.py`, `test_agent_unlimited_tools.py`.
+- [ ] One `--no-gpg-sign` commit; phase dir moved to `.agent/phases/complete/`.
+
+## Locked decisions
+- **Owner-locked (2026-09-01, roadmap confirmation, A5):** the match is a **case-insensitive fixed substring** (no regex — no ReDoS surface, a simple contract for the model); output is grep-style `source/path:LINE: text` lines; **20 matches per call** maximum (global cap across documents, in catalog order), each line truncated to **200 chars**; a search does **not** add the document to the answer context (`read_document` remains the only context-adder — `holder.read_docs` is untouched by a search).
+- **Owner-locked (2026-09-01, roadmap confirmation, A6):** the tool name is `search_documents` (alongside `list_documents` / `read_document`).
+- Scope: search is offered on grounded (HIGH) turns only, exactly like the existing tools — deflected turns keep `tools=None` (A8 byte-identical deflection path), and `BOR_AGENT_MAX_ROUNDS=0` stays the no-tools kill switch (phase 45).
+
+## Commit
+```bash
+git add -A .agent/ app/ tests/ frontend/ && git commit --no-gpg-sign -m "feat(agent): search_documents tool — the model can grep the indexed documents for an exact string"
+```
@@ -0,0 +1,45 @@
+# Task 01 — `search_documents`: Tool Definition, Grep Helper, Execution Branch
+
+**Phase:** `68_search_tool` · **Source:** `TODO.md:4` — "Add a search tool that allows the LLM to grep through the uploaded documents for a given string"
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+The tool exists end to end server-side: it is in `AGENT_TOOLS` with a model-legible contract, and `_execute_tool` executes it — case-insensitive fixed-substring grep over `documents.content`, grep-style output, hard caps, and the house refusal strings.
+
+## Work
+1. `app/rag/agent.py` — module constants (next to the caps/refusals):
+   - `SEARCH_MAX_MATCHES = 20` — global per-call cap, catalog order (owner-locked A5).
+   - `SEARCH_LINE_LIMIT = 200` — per-line output truncation (owner-locked A5).
+   - `MISSING_SEARCH_ARGS = "search_documents requires a string argument 'pattern'."`
+   - `NO_MATCHES = "No matches for '{pattern}' in the knowledge base."` / scoped variant `"No matches for '{pattern}' in {source}/{path}."`
+2. `app/rag/agent.py` — `grep_document(content: str, pattern: str) -> list[tuple[int, str]]` (module-level so unit tests can use/monkeypatch it, house pattern of `list_catalog`/`find_document`):
+   - split `content` on `\n`; a line matches when `pattern.lower() in line.lower()` (case-insensitive fixed substring — owner-locked A5); return `(1-based line number, line.rstrip())` pairs.
+3. `app/rag/agent.py` — `AGENT_TOOLS`: append the third function definition:
+   - `name`: `search_documents` (owner-locked A6).
+   - `description`: "Search every indexed document for an exact string (case-insensitive) and return up to 20 matching lines as 'source/path:line: text' — use this to locate content, then read_document the winner. Optionally pass 'source' and 'path' (as shown in list_documents) to search one document only."
+   - `parameters`: `pattern` (string, **required** — "The exact text to search for (a plain substring, not a regex)"); `source` + `path` (strings, optional — the same "as shown after 'source: '/'path: ' in the list_documents output" wording `read_document` uses, phase 63 labeled fields).
+4. `app/rag/agent.py` — `_execute_tool` branch (`call.name == "search_documents"`, placed after the `read_document` branch, before the `UNKNOWN_TOOL` fallback):
+   - `pattern = call.arguments.get("pattern")`; must be a non-empty string after `.strip()` → else `MISSING_SEARCH_ARGS`.
+   - if BOTH `source` and `path` are non-empty after strip: `find_document(db, source, path)` → `None` → `"No document at {source}/{path} — check the list_documents output."` (the existing read_document refusal style); search only that document (scoped no-match message).
+   - if only ONE of `source`/`path` is given → treat it as a missing pair: `MISSING_SEARCH_ARGS` (a half-specified target is a model error, not a whole-KB search — fail loud, house style).
+   - else: iterate `list_catalog(db)` in `(source, path)` order, load each `Document.content` via `find_document` (or one bulk `select(Document)` ordered by source,path — executor's call, note which in the commit body), accumulating `f"{doc.source}/{doc.path}:{lineno}: {line[:SEARCH_LINE_LIMIT]}"` until `SEARCH_MAX_MATCHES` total; stop scanning once the cap is hit.
+   - no matches → the no-match line (pattern quoted; a pattern longer than 100 chars is truncated in the message to keep it short).
+   - success: `holder.tool_calls += 1` (an executed call, re-searches included — same counting as `list_documents`); `holder.read_docs` is **not** touched (locked A5 — the search never adds context).
+   - log line: the existing `logger.info("agent tool=%s args=%s round=%d/%d", ...)` already covers it (the `arguments` dump includes `pattern`).
+5. `app/rag/agent.py` — update the module docstring: three tools now (list/read/search); a search is a locator, not a context-adder.
+6. Unit tests — `tests/unit/test_agent.py`:
+   - case-insensitive match across multiple lines, 1-based line numbers, multi-line and repeated matches.
+   - the 20-match global cap across two documents (catalog order); line truncation at 200 chars (a 300-char line yields 200 + no crash).
+   - scoped search: found doc, missing doc (refusal), single-arg (only `source`) → `MISSING_SEARCH_ARGS`.
+   - no-match (whole KB and scoped) messages; empty/whitespace `pattern` → `MISSING_SEARCH_ARGS`; non-string `pattern` → `MISSING_SEARCH_ARGS`.
+   - `holder.tool_calls` counts a search; `holder.read_docs` unchanged after a search.
+   - `AGENT_TOOLS` shape: three tools, `search_documents` has `required: ["pattern"]` (and optional `source`/`path`).
+
+## Testing & Quality
+- Unit/integration: Work 6 + `tests/integration/test_agent_tools.py` (the new tool is offered and executed through `run_agent` with a scripted `ToolCallPiece`).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] A scripted `search_documents` call through `run_agent` returns the grep-style result text and bumps `tool_calls` without touching `read_docs`.
+- [ ] `uv run pytest tests/unit/test_agent.py tests/integration/test_agent_tools.py -v` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] no behavior change for `list_documents` / `read_document` (existing pins green).
@@ -0,0 +1,46 @@
+# Task 02 — SSE Argument Mapping + the Frontend Search Status/Tool Line
+
+**Phase:** `68_search_tool` · **Source:** `TODO.md:4` — "Add a search tool that allows the LLM to grep through the uploaded documents for a given string"
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+The search call is visible in the UI like the other two tools: the SSE `tool` frame carries the pattern as its `argument`, the status line reads `Brain is searching for 'pattern'`, and a `🔎 Searching for '<pattern>'` line lands above the answer — persisted and restored with the conversation like the existing tool lines.
+
+## Work
+1. `app/api/chat.py` — the `ToolCallPiece` branch currently computes `argument` as `f"{source}/{path}"` for `read_document`, else `None`:
+   - extend: `elif piece.name == "search_documents":` → `argument = piece.arguments.get("pattern")` (the raw string; a non-string pattern — a model error the backend refuses — yields `None`).
+2. `app/schemas.py` — `ChatToolEvent`: update the docstring + field comments — `name` is `"list_documents" | "read_document" | "search_documents"`; `argument` is `"source/path"` for `read_document`, the **search pattern** for `search_documents`, null otherwise. (No field-shape change.)
+3. `frontend/assets/app.js` — `runTurn`'s `tool` branch, the `toolStatus` computation:
+   ```js
+   const toolStatus =
+     name === "read_document" && argument
+       ? `${brand()} is reading ${argument}`
+       : name === "search_documents" && argument
+         ? `${brand()} is searching for ${argument}`
+         : `${brand()} is listing documents`;
+   ```
+4. `frontend/assets/app.js` — `appendToolLine` (L796): add the search branch BEFORE the `else` fallback:
+   ```js
+   } else if (name === "search_documents" && argument) {
+     line.textContent = "🔎 Searching for ";
+     const code = document.createElement("code");
+     code.textContent = argument; // the pattern is data, never markup
+     line.appendChild(code);
+   }
+   ```
+   (The `else` keeps `"🔎 Listing documents"` for `list_documents` and any unknown name.) The pattern goes in a `<code>` element exactly like the read path — data, never markup (the existing XSS-safe convention).
+5. Persistence/restore: the `toolAcc` record is already `{name, argument}`-generic and the restore path calls the same `appendToolLine(t.name, arg)` (L1205) — no extra work; verify the restore branch renders the search line (covered by the E2E in task 03 only if a reload happens in that suite — otherwise by the unit pin below).
+6. JS unit pins — `tests/unit/test_frontend_tool_states.py` (the phase-37 frontend contract file):
+   - the status ternary contains the locked `is searching for` branch with the correct name/argument gate;
+   - `appendToolLine` contains the `search_documents` branch with the `<code>` element (pattern-as-data pin);
+   - the persisted tool record still serializes `{name, argument}` generically (no per-tool shape).
+7. Integration pin — `tests/integration/test_chat_api.py` (or the SSE pin module): a scripted `search_documents` `ToolCallPiece` streams as `{type: "tool", name: "search_documents", argument: "<pattern>"}`.
+
+## Testing & Quality
+- Unit: Work 6 (JS pins) + Work 7 (SSE shape).
+- Coverage: **>90%** on this task's new/modified code.
+
+## Completion Criteria
+- [ ] A `search_documents` tool frame streams with `argument = pattern` and renders the locked status + tool line in the browser (E2E in task 03).
+- [ ] `uv run pytest tests/unit/test_frontend_tool_states.py tests/integration/test_chat_api.py -v` green; `uv run ruff check . && uv run pyright` clean.
+- [ ] no behavior change for the existing two tool frames (their SSE shapes + UI lines are untouched).
@@ -0,0 +1,39 @@
+# Task 03 — Mock Search Flow, E2E Suite, Regressions, Commit
+
+**Phase:** `68_search_tool` · **Source:** `TODO.md:4` — the full item (end-to-end proof: the model greps, sees the match, answers from it).
+**Story:** n/a (TODO-derived — owner roadmap confirmation 2026-09-01)
+
+## Objective
+Prove the tool in a browser with the deterministic mock: a grounded question makes the mock model call `search_documents`, the match line reaches the model, and the answer quotes the found content — with the search visible in the status line and tool lines. One dedicated Playwright suite, green in isolation, plus the regression pass and the phase commit.
+
+## Work
+1. `tests/e2e/mock_llm.py` — a new marker flow, following the `use your tools` flow's structure (stateless discrimination from the messages, streaming only):
+   - `SEARCH_TRIGGER = "search your documents"` (checked BEFORE the plain `use your tools` check — it is more specific, same convention as `think in paragraphs`):
+     - request 1 (`tools` offered, no tool results yet): stream ONLY a `tool_calls` delta — `search_documents` with `{"pattern": "<SEARCH_PATTERN>"}` (id `call_0`); `<SEARCH_PATTERN>` is a sentinel string the e2e places in a fixture document (e.g. `reese-sentinel-42` — the sentinel convention from the `show the end of your notes` marker).
+     - request 2 (a `tool`-role search result in the messages — recognizable as a search result by its `source/path:line: text` shape or the sentinel in its content): the content answer, deterministic: `Found <first matched line's content up to 80 chars>` — so the suite can assert the search result reached the model and landed in the answer.
+   - document the flow in the module docstring's marker list.
+2. `tests/e2e/test_search_tool.py` — the dedicated suite (DB up; import one fixture document containing the sentinel line, via the existing admin import fixtures in `conftest.py`/`auth_helpers.py`):
+   - **live search flow:** ask a KB question containing `search your documents` →
+     - a `.msg.brain .tool-call` line appears containing `🔎 Searching for` and the sentinel in a `<code>` (assert via `to_contain_text("Searching for")` + the code element text);
+     - the recorded `#send-status` values contain `is searching for <sentinel>` (the init-script status-recording pattern from `test_agent_document_tools.py`);
+     - the answer bubble contains the deterministic `Found …` echo (the match reached the model);
+     - NO error banner; the turn settles to idle with the send button re-enabled.
+   - **context accounting:** the search does not add a source by itself — if the mock flow searches and then answers WITHOUT a read, `done.sources` reflects only the retrieval docs (assert the sources row is unchanged by the search alone). (If the executor finds the mock flow must also read to produce a stable answer, keep the flow search-only and assert the sources row equals the retrieval baseline.)
+   - **regression-safe markers:** the existing `use your tools` questions in `test_agent_document_tools.py` / `test_agent_unlimited_tools.py` do NOT contain the new trigger (verify — the trigger phrase must not appear in any other suite's fixture text).
+3. Regression pass (each in isolation, DB up): `uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov`, `uv run pytest tests/e2e/test_agent_unlimited_tools.py -v --no-cov`, `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov` — the list/read flow, the unlimited-calls behavior, and the plain RAG turn must be untouched (the third tool changes the `tools` payload — confirm no existing suite pins an exact two-tool payload; if one does, update it to expect three and note it in the commit body).
+4. Full gate: `uv run pytest --cov=app --cov-report=term-missing` (TOTAL >90%), `uv run ruff check . && uv run pyright`.
+5. Commit (AGENTS.md rule 8 — one atomic phase commit):
+   ```bash
+   git add -A .agent/ app/ tests/ frontend/ && git commit --no-gpg-sign -m "feat(agent): search_documents tool — the model can grep the indexed documents for an exact string"
+   ```
+   Then move the phase dir to `.agent/phases/complete/68_search_tool/` and include the move in the SAME commit (house convention — mirror phase 67's commit/move pattern).
+
+## Testing & Quality
+- E2E: as listed (Work 2–3).
+- Coverage: **>90%** on `app/` (validate.sh gate).
+
+## Completion Criteria
+- [ ] `uv run pytest tests/e2e/test_search_tool.py -v --no-cov` green in isolation (DB up).
+- [ ] The three regression suites green in isolation.
+- [ ] `uv run pytest --cov=app` TOTAL >90%; `uv run ruff check . && uv run pyright` clean.
+- [ ] One `--no-gpg-sign` Conventional Commits commit; phase dir in `.agent/phases/complete/`.
@@ -0,0 +1,19 @@
+All verification passes green. Phase 61 is fully complete — final verification pass only, no code changes needed.
+
+**Phase 61 (stale_ui_copy) — final verification report**
+
+Verified (all 4 task files already in `complete/`; no work remaining, no defects found):
+- Chat page: meta description, empty-state sub, composer placeholder, and the 4 default chips in `app/config.py` match the locked (A1/A2) copy exactly
+- KB page-sub (`sources.html`) reads the locked current-source-model text (git repos + local dirs + uploaded archives, Sync pulls/re-imports); git-sources placeholder is `https://github.com/you/your-repo.git` (A3)
+- All 9 pages carry `<span class="footer-text">Powered by self-hosted models</span>` (1 each); `grep -rn "Reese's" frontend/` empty; only remaining "homelab" is the A3-exempt L176 code comment in `index.html`
+- Tests: `tests/unit/test_stale_ui_copy.py` + `tests/e2e/test_stale_ui_copy.py` exist with real pins (body-text scan, DOM assertions)
+
+Results:
+- `uv run pytest --cov=app --cov-report=term-missing`: **1201 passed**, coverage TOTAL **99%** (>90% ✓)
+- `uv run ruff check . && uv run pyright`: clean (0 errors)
+- `uv run pytest tests/e2e/test_stale_ui_copy.py -v --no-cov`: **5 passed** in isolation (DB up)
+- Regression E2E in isolation: `test_smoke` 3 ✓, `test_configurable_brand` 5 ✓, `test_header_consistency` 3 ✓, `test_dark_tech_theme` 6 ✓
+- Commit `baefcde` `--no-gpg-sign` exists, staged paths only `app/ frontend/ tests/` ✓
+
+Completion criteria: all 7 met (E2E body scan, KB page-sub, 9 footers, suite/coverage/lint, phase E2E, regression suites, single commit).
+Next pending phase: **62_ui_customization**.
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 71%]
+........................................................................ [ 77%]
+........................................................................ [ 83%]
+........................................................................ [ 89%]
+........................................................................ [ 95%]
+.................................................                        [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 101      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2458     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+**Task 01 complete — report**
+
+Implemented:
+- `frontend/index.html`: meta description, `.empty-state-sub`, and `#message-input` placeholder → locked neutral copy (A1); brand-embedding strings left untouched for the phase-39 brand layer.
+- `app/config.py`: `suggestions` default → the four locked chips (A2); `BOR_SUGGESTIONS` override path unchanged.
+- Defect fix (pre-existing — 3 `tests/integration/test_api.py` failures even on the pristine tree): the operator's local gitignored `.env` leaked into test apps via pydantic `env_file=".env"`. Made the test env hermetic — `tests/conftest.py` + `tests/e2e/conftest.py` now force `BOR_DOCS_REPO=""` and `BOR_SUGGESTIONS`=code default (derived from `Settings.model_fields` so it can't drift); `test_response_to_docs.py` "unconfigured" spawn forces empty docs repo (dotenv leak re-enabled the docs feature there too).
+
+Results:
+- `uv run pytest --cov=app` → 1193 passed; TOTAL 99% (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `bash .agent/validate.sh` → validation OK
+- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` → 3 passed (validates the modified shared E2E server)
+- Task grep criteria verified: `homelab` in `index.html` only at the L176 code comment (A3); no "deployment" text; one user-visible "Ask me anything"
+
+Decisions: conftest changes are a required defect fix (suite was red before this task on this machine); no commit made (task 04 owns it).
+
+Next pending: `02_sources_pages_copy.md` (KB page-sub + remaining page-subs + git-sources example URL).
@@ -0,0 +1,71 @@
+........................................................................ [  6%]
+........................................................................ [ 12%]
+........................................................................ [ 18%]
+........................................................................ [ 24%]
+........................................................................ [ 30%]
+........................................................................ [ 36%]
+........................................................................ [ 42%]
+........................................................................ [ 48%]
+........................................................................ [ 54%]
+........................................................................ [ 60%]
+........................................................................ [ 66%]
+........................................................................ [ 72%]
+........................................................................ [ 78%]
+........................................................................ [ 84%]
+........................................................................ [ 90%]
+........................................................................ [ 96%]
+.........................................                                [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 101      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2458     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,19 @@
+All gates green. Task 02 complete.
+
+**Implemented**
+- `frontend/sources.html` KB page-sub → locked (A1) copy: "Every file indexed from your configured sources — git repositories, local directories, and uploaded archives. Press **Sync sources** to pull the latest and re-import."
+- `frontend/git-sources.html` example placeholder → `https://github.com/you/your-repo.git` (A3)
+- `tests/unit/test_sync_button.py` — updated the stale copy-pin (it asserted the retired "clone the repos and re-import") to pin the new locked copy incl. the source-model wording
+- Verification read-through, all **no change** (accurate today): `sources.js` sync result/error strings (server-driven, incl. "no sources configured (git or local)" from `app/api/sync.py:190`); page-subs in `tuning.html`, `history.html`, `doc-edit.html`, `git-sources.html`; `#sources-gate` copy (verified `GET /api/docs` admin-only, `GET /api/documents/content` public)
+
+**Results**
+- `uv run pytest --cov=app --cov-report=term` → 1193 passed, TOTAL **99%** (>90%)
+- `uv run ruff check .` → clean; `uv run pyright` → 0 errors
+- `uv run pytest tests/e2e/test_smoke.py -v --no-cov` → 3 passed; `tests/e2e/test_header_consistency.py -v --no-cov` → 3 passed
+- `grep "Homelab\|Deployments" frontend/sources.html` and `grep "homelab" frontend/git-sources.html` both empty; only A3-exempt comments remain
+
+**Decisions**
+- One pre-existing test pinned the retired copy (defect in previously completed work) — updated to the locked replacement rather than the HTML reverted
+- No commit made: the phase's single atomic commit belongs to task 04
+
+**Next pending task:** `.agent/phases/todo/61_stale_ui_copy/03_footer_defaults.md`
@@ -0,0 +1,71 @@
+........................................................................ [  6%]
+........................................................................ [ 12%]
+........................................................................ [ 18%]
+........................................................................ [ 24%]
+........................................................................ [ 30%]
+........................................................................ [ 36%]
+........................................................................ [ 42%]
+........................................................................ [ 48%]
+........................................................................ [ 54%]
+........................................................................ [ 60%]
+........................................................................ [ 66%]
+........................................................................ [ 72%]
+........................................................................ [ 78%]
+........................................................................ [ 84%]
+........................................................................ [ 90%]
+........................................................................ [ 96%]
+.........................................                                [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 101      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2458     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,14 @@
+Task 03 is complete and green. 
+
+**Task 03 — Neutral footer default on all 9 pages (`.footer-text` hook)**
+
+- Replaced `<span>Powered by Reese's self-hosted models</span>` → `<span class="footer-text">Powered by self-hosted models</span>` on all 9 pages (`index`, `sources`, `tuning`, `document`, `git-sources`, `history`, `login`, `shared`, `doc-edit`), exactly at the audited line numbers; `.footer-version` siblings untouched
+- Verified `grep -c 'class="footer-text"' frontend/*.html` → 1 per file, 9 total; `grep -rn "Reese's" frontend/` → empty
+- No CSS/JS changes — the class is a selector-only hook for phase 62's `BOR_FOOTER_TEXT`; no test pinned the old footer text
+- Tests: `uv run pytest --cov=app` → 1193 passed (exit 0), coverage TOTAL **99%** (>90% gate); `uv run ruff check . && uv run pyright` → clean
+- Brand layer unaffected: `uv run pytest tests/unit/test_frontend_brand.py tests/e2e/test_configurable_brand.py -v --no-cov` → 15 passed (DB up, so run now rather than deferred to task 04)
+- The 9-page unit pin is deliberately deferred to task 04 per the task file; no new tests added in this task (no logic changes)
+- Not committed — the single atomic phase commit is task 04's job; working tree carries tasks 01–03 changes
+- Note: `.agent/PLAN.md` is absent from the repo; owner-locked copy was taken from the phase's `00_phase.md` locked decisions (A1)
+
+**Next pending task:** `.agent/phases/todo/61_stale_ui_copy/04_tests_and_commit.md`
@@ -0,0 +1,71 @@
+........................................................................ [  6%]
+........................................................................ [ 12%]
+........................................................................ [ 18%]
+........................................................................ [ 24%]
+........................................................................ [ 30%]
+........................................................................ [ 36%]
+........................................................................ [ 42%]
+........................................................................ [ 48%]
+........................................................................ [ 54%]
+........................................................................ [ 60%]
+........................................................................ [ 66%]
+........................................................................ [ 72%]
+........................................................................ [ 78%]
+........................................................................ [ 84%]
+........................................................................ [ 90%]
+........................................................................ [ 96%]
+.........................................                                [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 101      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2458     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Task 04 complete. Report:
+
+**Implemented**
+- `tests/unit/test_stale_ui_copy.py` (8 tests, house text-pin pattern): old homelab-era strings GONE from `index.html`/`sources.html`/`git-sources.html`; locked A1 strings present exactly once; `class="footer-text"` + neutral footer on all 9 pages; A2 chips in `app/config.py` in order; old chips absent from all of `app/` + `frontend/` (retired, not relocated).
+- `tests/e2e/test_stale_ui_copy.py` (5 tests, shared conftest server, DB up): chat placeholder/meta/footer pins, full body scan for `homelab`/`deployment`, A2 chip list in order, sources `.page-sub` (no Homelab/Deployments, has "configured sources"), git-sources `#git-source-url` placeholder (A3) — all from the rendered DOM.
+
+**Verification (all green)**
+- `uv run pytest --cov=app` → 1201 passed, coverage TOTAL **99%** (>90% gate)
+- `uv run pytest tests/e2e/test_stale_ui_copy.py -v --no-cov` → 5 passed (isolation, DB up)
+- Regression E2E in isolation: `test_smoke.py` 3 ✓, `test_configurable_brand.py` 5 ✓, `test_header_consistency.py` 3 ✓, `test_dark_tech_theme.py` 6 ✓
+- `uv run ruff check . && uv run pyright` → clean
+
+**Decisions/deviations**
+- Old git example URL also pinned (A3, "where they lived"); old-chip absence scan scoped to `app/`+`frontend/` (a repo-wide scan would hit the pin file itself).
+- Atomic commit `baefcde` on `main` — staged `frontend/ tests/ app/` only, `--no-gpg-sign`, body carries the task-02 read-through outcome (all 6 checked locations: no change needed).
+
+**Next pending task:** `62_ui_customization/01_config_settings.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 71%]
+........................................................................ [ 77%]
+........................................................................ [ 83%]
+........................................................................ [ 89%]
+........................................................................ [ 95%]
+.................................................                        [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 101      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2458     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,14 @@
+All completion criteria verified. Report:
+
+**Phase 62 — UI Customization: final verification pass (all tasks already complete, commit `c738105` present)**
+
+- Verified implementation: 3 new `Settings` fields + fail-loud `theme` validator, six-key `/api/config`, `brand.js` placeholder/footer/theme-link passes, `themes/indigo.css` + README, Containerfile L29 `cp -r ./assets/themes`, `.env.example` + README docs.
+- Live spot-checks: default `/api/config` = exactly the six keys with phase-61 defaults; `/assets/themes/indigo.css` served 200 from dev static dir; `../evil.css`, `a/b.css`, `INDIGO.CSS`, `indigo` all refused at startup, each naming the value.
+- `uv run pytest --cov=app` — all green; **coverage TOTAL 99%** (>90% gate).
+- `uv run ruff check . && uv run pyright` — clean (0 errors).
+- `uv run pytest tests/e2e/test_ui_customization.py -v --no-cov` — **5 passed** in isolation (DB up).
+- Regression E2E in isolation: `test_configurable_brand` 5✓, `test_stale_ui_copy` 5✓, `test_smoke` 3✓, `test_dark_tech_theme` 6✓.
+- Commit criterion: single `--no-gpg-sign` commit `c738105 feat(web): customizable placeholder, footer text, and color theme via BOR_* env vars` (stages only `app/ frontend/ tests/ .env.example README.md Containerfile`); `.agent/` phase files already filed under `complete/` by the harness.
+- All 9 completion criteria: **met**. No defects found; no fixes needed.
+- Note: `.agent/PLAN.md` referenced by AGENTS.md does not exist in the repo — verified against the phase overview's locked decisions (A4–A7), all honored.
+- Next pending phase: **`63_unambiguous_document_listing`**.
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,19 @@
+All green. Task complete — final verification summary:
+
+**Implemented (task 01 — Settings + `/api/config` keys + validator):**
+- `app/config.py`: `input_placeholder` / `footer_text` / `theme` (phase-61 neutral defaults) + `theme` field_validator — empty ok, bare `^[a-z0-9_-]+\.css$` only, malformed fails startup naming the value (phase-56 style)
+- `app/api/config.py`: `GET /api/config` now returns exactly the six locked keys (values verbatim, same public posture)
+- Contract tests moved to six keys: `tests/integration/test_api.py` (both key-set tests + new `test_config_serves_ui_customization_overrides` + default-value pins), `tests/e2e/test_configurable_brand.py` (both instances)
+- Unit pins: `tests/unit/test_config.py` — validator accept/reject cases (each rejection names the value), env-override + `BOR_THEME=../evil.css` startup failure
+
+**Test / lint / coverage results:**
+- `uv run pytest` → **1211 passed**
+- `uv run pytest --cov=app --cov-report=term` → **TOTAL 99%** (>90% gate)
+- `uv run ruff check .` → clean · `uv run pyright` → 0 errors
+- `bash .agent/validate.sh` → "validation OK" · e2e file collects (5 tests; run lands in task 05)
+
+**Notable decisions:**
+- Also updated `tests/unit/test_save_as_doc_button.py` L54 key-set pin (not in the task's inventory — suite would go red without it) and added the phase-61-style `.env`-leak guard for the three new vars in `tests/conftest.py`
+- No commit made — the phase's single atomic commit belongs to task 05
+
+**Next pending task:** `02_brand_layer_customization.md` (brand.js applies placeholder/footer/theme from the same boot fetch)
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 71%]
+........................................................................ [ 77%]
+........................................................................ [ 83%]
+........................................................................ [ 89%]
+........................................................................ [ 95%]
+...........................................................              [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,23 @@
+Task 02 complete. All gates green.
+
+**Implemented**
+- `frontend/assets/brand.js`: the three phase-62 keys apply from the SAME settled-config `.then` (no second fetch), placed after the app_name block and independent of it (the name passes are now wrapped in `if (name)` — behavior byte-identical to the old early-return):
+  - `input_placeholder` → `#message-input` placeholder (null-guard no-op off the chat page)
+  - `footer_text` → every `.footer-text` node via `textContent` (no markup injection)
+  - `theme` → `<link id="theme-override" href="/assets/themes/<name>">` inserted immediately after the `styles.css` link (cascade wins), idempotent via `#theme-override`, A5 degradation: `onerror` → `console.warn`, built-in theme stands
+- Header contract comment: new "Phase 62 (owner-locked 2026-09-01, TODO L3)" items 5–7 + updated no-op property (all 4 env vars unset ⇒ byte-identical)
+- `tests/unit/test_frontend_brand.py`: new pin `test_brand_js_applies_phase_62_customization_from_the_same_fetch` — single-fetch marker, all three application markers, empty-skip guards, phase-62-after-app_name ordering, app_name default literal still holds
+- Existing app_name passes 1–4 and `BOR_DOCS_REPO_CONFIGURED` logic untouched (re-indent only)
+
+**Results**
+- `uv run pytest` → 1212 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → TOTAL 99% (>90%)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+- `bash .agent/validate.sh` → validation OK
+- `node --check frontend/assets/brand.js` → syntax OK
+
+**Decisions**
+- Keyed the empty-skip guards on `typeof … === "string"` + truthiness, so a fetch failure (`cfg` null) is also a clean no-op (house style: page never breaks).
+- No defects found in prior work — baseline was green before my changes.
+
+**Next pending task:** `.agent/phases/todo/62_ui_customization/03_theme_assets.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 71%]
+........................................................................ [ 77%]
+........................................................................ [ 83%]
+........................................................................ [ 89%]
+........................................................................ [ 95%]
+............................................................             [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,21 @@
+All done and green. Final report:
+
+**Implemented (task 03 — theme assets)**
+- `frontend/assets/themes/indigo.css` — WCAG-AA dark indigo/slate theme, single `:root` block, exactly the 8 identity overrides (semantic accent/ok/err untouched)
+- `frontend/assets/themes/README.md` — authoring guide (load path, variable table w/ built-in refs, filename regex, 4.5:1 bar, never-white-on-brand trap, A7 deployment)
+- `Containerfile` — `&& cp -r ./assets/themes /out/assets/themes \` added in stage 1, after the styles.css minify (line 29)
+- `tests/unit/test_themes.py` — 6 new pins: files exist, single leading `:root` block + nothing else, exactly the 8 locked overrides, 5 identity-pair ratios ≥4.5:1 computed from the file's own hex values, Containerfile cp line (position + no esbuild), guide contract markers
+
+**Test / lint / coverage**
+- `uv run pytest --cov=app --cov-report=term -q` → rc=0, 1218 tests, TOTAL **99%** (>90%)
+- `uv run ruff check .` → All checks passed · `uv run pyright` → 0 errors
+- `uv run pytest tests/unit/test_themes.py tests/integration/test_containerfile_assets.py -v --no-cov` → 12 passed
+- Ratios (WCAG calc): ink/bg 15.84 · ink/surface 14.71 · ink-soft/surface 8.27 · bg-on-brand 6.46 · brand-ink/surface 11.99 — all ≥4.5:1
+- Dev sanity: `BOR_THEME=indigo.css` → `GET /assets/themes/indigo.css` 200, `/api/config` theme="indigo.css", served HTML has 0 theme refs; default env → theme="", built-in `--brand: #f43f5e` stands (opt-in via env var, no dir scanning)
+
+**Decisions / notes**
+- Task's comment ratios were slightly off (14.6/8.2/6.4/11.9); wrote the computed values (14.7/8.3/6.5/12.0) — no palette values changed
+- Required grep spot-check: `f43f5e|#f0e6e6|#0f0a0a` matches only the `:root` block (L9/11/14) + one comment (L1271) as expected; broader scan found decorative `rgb()` literals (bg grid, glow spots, `.send-btn` steps) — noted, not refactored per task
+- Commit deferred to task 05's atomic phase commit (per phase plan)
+
+**Next pending task:** `.agent/phases/todo/62_ui_customization/04_docs.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,12 @@
+All gates green. Task complete.
+
+**Report**
+
+- `.env.example` — added the three commented vars (`BOR_INPUT_PLACEHOLDER`, `BOR_FOOTER_TEXT`, `BOR_THEME`) in the `# --- App ---` block directly after the `BOR_APP_NAME` line, task's exact text/defaults, phase-cited.
+- `README.md` env table — three rows added immediately after the `BOR_APP_NAME` row (what it affects, default, unset ⇒ no-op contract; `BOR_THEME` row documents the startup validator regex + missing-file degradation).
+- `README.md` — new `### Customizing the look` subsection (4 sentences) placed at the end of "Configuration reference", directly **below** the env table, before "## Troubleshooting" — mirrors the house pattern of `###` feature subsections under a parent `##`; links to `frontend/assets/themes/README.md` (verified exists, link resolves) and names `indigo.css` as the example.
+- No code changes (task is docs-only, per spec).
+- Tests/lint: `uv run pytest` → 1218 passed; `uv run pytest --cov=app --cov-report=term-missing` → TOTAL **99%** (>90% gate); `uv run ruff check .` → all checks passed; `uv run pyright` → 0 errors.
+- No commit made — the phase's single atomic commit is defined in task 05 (harness/handoff per phase overview).
+
+Next pending task: `.agent/phases/todo/62_ui_customization/05_e2e_customization.md` (E2E suite + regression suites + atomic commit).
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,16 @@
+All gates green and the atomic commit landed. Final report:
+
+## Phase 62 / Task 05 — complete
+
+**Implemented**
+- `tests/e2e/test_ui_customization.py` — 5 mapped tests: `/api/config` six-key overrides + dev static serving of the theme; chat page custom placeholder/footer/`link#theme-override` + computed `--brand` `#818cf8`; multi-page footer (login, no composer); default server byte-identical (settled-fetch wait before the absence assert); malformed `BOR_THEME="../evil.css"` refuses boot via real uvicorn subprocess, stderr names the value. Own instance on `APP_PORT+2`, brand suite's env-block pattern.
+- **Defect fix (task 02 work):** the phase-33/54 cache-bust rewrite serves `styles.css?v=<token>`, so brand.js's `el.href.endsWith("styles.css")` never matched and the theme link was never inserted — now matches the raw attribute path with query/fragment stripped; unit pin added for the exact regression.
+- E2E conftest hardening: shared `app_server` pins the three new `BOR_` vars to code defaults (same leak-class fix as phase 61).
+
+**Results**
+- `uv run pytest tests/e2e/test_ui_customization.py -v --no-cov` → 5 passed (isolation, DB up)
+- Regressions in isolation: `test_configurable_brand` 5✓, `test_stale_ui_copy` 5✓, `test_smoke` 3✓, `test_dark_tech_theme` 6✓
+- `.agent/validate.sh` → unit+integration green, coverage TOTAL **99%** (>90%), ruff clean, pyright 0 errors
+- Commit `c738105` on `main`, staged exactly `app/ frontend/ tests/ .env.example README.md Containerfile`, `--no-gpg-sign`
+
+**Decisions:** `.agent/` left unstaged per task file (harness moves the phase dir). Next pending: `63_unambiguous_document_listing/01` (or the harness's queue order).
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+All verification complete. The one remaining `source/path —` match is an explanatory comment in a test describing the historical bug (introduced by this phase's own commit) — not stale.
+
+**Phase 63 — Final verification pass: ALL GREEN** (all 4 tasks already in `complete/`; no code changes needed)
+
+- Verified `app/rag/agent.py`: `_execute_tool` emits `source: X | path: Y | title: Z` lines; `AGENT_TOOLS` `read_document` param descriptions reference the `source:`/`path:` labels; "No document at …" refusal unchanged
+- Verified `tests/e2e/mock_llm.py::_catalog_docs` parses the new format via labeled-field regex; README + user story updated to new format; no stale old-format references remain
+- `uv run pytest --cov=app --cov-report=term-missing` → **1219 passed**, TOTAL coverage **99%** (>90% gate)
+- `uv run ruff check . && uv run pyright` → **All checks passed / 0 errors**
+- `uv run pytest tests/e2e/test_agent_document_tools.py tests/e2e/test_agent_unlimited_tools.py -v --no-cov` → **8 passed** (DB up)
+- Regression in isolation: `test_whole_document_context.py` **3 passed**; `tests/integration/test_chat_api.py` **17 passed**; `tests/unit/test_sse_events.py` **12 passed**; `tests/integration/test_agent_tools.py` **4 passed**
+- Commit `15a16a8 fix(agent): unambiguous document listing format for LLM parsing` already present (`--no-gpg-sign`); harness has moved task files to `complete/`
+
+Completion criteria: (1) new format + unit test — ✓ (2) tool descriptions — ✓ (3) mock parsing — ✓ (4) pytest/coverage/lint — ✓ (5) E2E document tools — ✓ (6) regression suites — ✓ (7) commit + phase move — ✓ (commit exists; `00_phase.md` move handled by harness)
+
+Deviation: `test_chat_api.py`/`test_sse_events.py` don't exist under `tests/e2e/`; ran their actual locations (integration/unit) in isolation — all green.
+
+Next pending phase: none — `todo/` holds only phase 63 itself.
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+...................................................................      [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,11 @@
+**Task 01 complete — report**
+
+- `app/rag/agent.py`: `list_documents` output now `source: X | path: Y | title: Z` (labeled, pipe-delimited — owner-locked A1); `read_document` `source`/`path` param descriptions now point the LLM at the `source:`/`path:` labels (A2, verbatim from task file); `list_documents` tool description + module docstring updated to match the new format (old wording would have misdescribed the output). "No document at …" refusal and SSE `argument` unchanged (A3/A4).
+- `tests/unit/test_agent.py`: tool-shape test now asserts the new param descriptions; all three listing-format assertions updated.
+- `tests/unit/test_mock_tool_flow.py`: `CATALOG_*` wire fixtures updated to the new format (they must stay byte-identical to `agent.py` output).
+- Deviation: `tests/e2e/mock_llm.py::_catalog_docs` (nominally task 02) was pulled into this task — the old `rsplit("/", 1)` parse would have mis-read the new lines and broken the phase's mandatory E2E gate; now regex-parses the labeled fields, producing identical `(source, path)` tuples (verified round-trip incl. the `brain-of-reese-main/homelab/aws-route53.md` case from the bug report).
+- `uv run pytest --cov=app` → 1218 passed, TOTAL coverage **99%** (>90%)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+- `uv run pytest tests/e2e/test_agent_document_tools.py tests/e2e/test_agent_unlimited_tools.py -v --no-cov` → 8 passed (DB up); regression `test_whole_document_context.py` → 3 passed. (`test_chat_api.py`/`test_sse_events.py` listed in the phase don't exist in this repo.)
+- No commit made — the phase (tasks 02–04 remaining) gets one atomic commit at phase completion per AGENTS.md rule 8.
+- Next pending task: `63_unambiguous_document_listing/02_mock_and_unit_tests.md` (its mock/unit work is already done here — expect verification only).
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 65%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+..................................................................       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,19 @@
+All gates green. Task 02 complete.
+
+**Task 02 report — mock + unit tests for the new catalog format**
+
+- **State found:** task 01's session had already applied the task-02 code (noted as a deviation in its report); this session verified it end-to-end and closed the one test gap.
+- `tests/e2e/mock_llm.py::_catalog_docs` — verified: regex-parses the labeled `source: X | path: Y | title: Z` lines; produces identical `(source, path)` tuples for all test catalogs.
+- `tests/unit/test_agent.py` — verified: `test_agent_tools_names_and_parameters` asserts the new A2 `source:`/`path:` parameter descriptions; all three listing-format assertions use the new format; "No document at S/ghost.md" refusal unchanged (A4).
+- **Added** `test_read_step_nested_path_stays_intact` in `tests/unit/test_mock_tool_flow.py` — pins the actual bug: the `brain-of-reese-main` / `homelab/aws-route53.md` nested path (multiple `/`) parses intact; the old `rpartition` parse misread it.
+
+**Gates (exact commands → outcomes)**
+- `uv run pytest tests/unit/test_agent.py -v --no-cov` → 22 passed
+- `uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov` → 4 passed (DB up)
+- `uv run pytest tests/e2e/test_agent_document_tools.py tests/e2e/test_agent_unlimited_tools.py -v --no-cov` → 8 passed in isolation
+- `uv run pytest --cov=app --cov-report=term-missing` → **1219 passed**, coverage TOTAL **99%** (>90%)
+- `uv run ruff check tests/ && uv run pyright tests/` → clean; `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Decisions/deviations:** none — mock and unit work was already in the working tree from task 01's session (its report documents the pull-in); no commit made (one atomic commit lands at phase completion per AGENTS.md rule 8).
+
+**Next pending task:** `63_unambiguous_document_listing/03_e2e_document_tools.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+...................................................................      [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,16 @@
+All gates green. Task 03 is verification-only (no code changes needed, consistent with its "Files changed: None"). Following the phase convention (one atomic commit at phase completion, per AGENTS.md rule 8), no commit is made here.
+
+**Task 03 complete — E2E document tools validation**
+
+- **Verified (no code changes):** SSE `tool` frames carry `argument` = `source/path`; UI renders "Listing documents"/"Reading …"; source chips `(source, path)` pairs; mock's deterministic answer content; query log `sources` = `"source/path, source/path"` — all asserted by the passing E2E suites against the new `source: X | path: Y | title: Z` catalog format.
+- **Gates (DB up, all in isolation):**
+  - `uv run pytest tests/e2e/test_agent_document_tools.py -v --no-cov` → 4 passed
+  - `uv run pytest tests/e2e/test_agent_unlimited_tools.py -v --no-cov` → 4 passed
+  - `uv run pytest tests/e2e/test_whole_document_context.py -v --no-cov` → 3 passed
+  - `uv run pytest tests/e2e/test_chat_rag.py -v --no-cov` → 3 passed
+  - `uv run pytest --cov=app --cov-report=term-missing` → **1219 passed**, coverage TOTAL **99%** (>90%)
+  - `uv run ruff check . && uv run pyright` → clean (0 errors)
+- **Deviations:** `test_chat_api.py` / `test_sse_events.py` named in the task never existed in this repo (verified via `git log --all`); ran `test_chat_rag.py` as the chat-API/SSE regression equivalent — same finding as task 01's report.
+- **No defects found** in prior work; no commit (phase-level commit at completion).
+
+**Next pending task:** `63_unambiguous_document_listing/04_docs.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+...................................................................      [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,18 @@
+All green. Phase 63 is now fully complete.
+
+**Task 04 — documentation update**
+
+- `README.md` — "Agent document tools" section now documents the `list_documents` output as `source: X | path: Y | title: Z` lines
+- `.agent/user_stories/agent-document-tools.md` — acceptance criterion 3 updated to the labeled format (reflowed, meaning unchanged)
+- Verified: `grep "source/path — title\|source/path - title"` over `README.md` + `.agent/user_stories/*.md` → no matches; `uv run ruff check README.md .agent/` → no error. Other `source/path` hits (SSE `argument`, source chips, `app/config.py` KB-overview note) are locked unchanged per A3 / are a different format
+- Committed phase work (tasks 01–04) as `15a16a8 fix(agent): unambiguous document listing format for LLM parsing` (`--no-gpg-sign`, staged `app/ tests/ README.md`; `.agent/` tree left for the harness, matching phases 61/62)
+
+**Test / lint / coverage results**
+- `uv run pytest --cov=app --cov-report=term-missing` → exit 0, 1231 results, 0 failures; coverage TOTAL **99%** (>90% gate)
+- `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings
+- E2E isolated (DB up): `test_agent_document_tools.py` 4 passed · `test_agent_unlimited_tools.py` 4 passed · `test_whole_document_context.py` 3 passed
+- Regression isolated: `tests/integration/test_chat_api.py` 17 passed · `tests/unit/test_sse_events.py` 12 passed (the phase's `tests/e2e/` paths for these two don't exist — actual locations used)
+
+**Deviations:** none — phase commit command's `app/ tests/` extended with `README.md` (task 04's deliverable; phase-62 precedent).
+
+**Next pending task:** none — task 04 was the last task of phase 63; `todo/` is now empty aside from this phase's harness-managed files.
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 53%]
+........................................................................ [ 59%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+...................................................................      [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           173      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2469     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,20 @@
+All verification complete — nothing to fix; the phase commit `4677d86` contains the full implementation. Final report:
+
+**Phase 64 final verification pass** (tasks 01–06 already complete; verified all criteria, no defects found)
+
+- **Test/lint/coverage**
+  - `uv run pytest --cov=app --cov-report=term -q` → 1251 passed, 0 failed; `app/` coverage **99%** (gate >90% OK)
+  - `uv run ruff check . && uv run pyright` → "All checks passed!" / "0 errors, 0 warnings, 0 informations"
+  - `uv run pytest tests/e2e/test_sync_upload_progress.py -v --no-cov` → **4 passed** (isolation, DB up)
+  - Regressions, each in isolation: `test_archive_upload_sources` **5 passed**, `test_sync_button` **3 passed**, `test_git_sources_admin` **6 passed**, `test_sync_model_down` **4 passed**
+- **Completion criteria**
+  1. `current_file`/`files_done`/`files_total` on both status endpoints — ✅ idle live-checked via running app (both return `null`/`0`/`0`); running states asserted by unit + E2E
+  2. `POST /upload` → 202 + background scan + 409 in-flight — ✅ (unit contract + E2E green)
+  3. Toast at 202, navigate-away mid-scan shows "Importing \<file\>", settle + catalog refresh — ✅ `test_upload_toast_then_navigate_away`
+  4. Live labels "Syncing… \<file\>" / "Importing \<file\>" / "Processing… \<file\>" — ✅ E2E green
+  5. Full pytest green, coverage >90% — ✅ (99%)
+  6. All 5 E2E suites green in isolation — ✅
+  7. ruff + pyright clean — ✅
+  8. Commit `4677d86` (`feat(sources): real-time file progress…`, `--no-gpg-sign`) exists; overview move to `complete/` left to the harness — ✅
+- **Decisions/deviations:** none — no code changes needed.
+- **Next pending phase:** `65_bottom_chat_actions`
@@ -0,0 +1,72 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 28%]
+........................................................................ [ 34%]
+........................................................................ [ 40%]
+........................................................................ [ 46%]
+........................................................................ [ 51%]
+........................................................................ [ 57%]
+........................................................................ [ 63%]
+........................................................................ [ 69%]
+........................................................................ [ 74%]
+........................................................................ [ 80%]
+........................................................................ [ 86%]
+........................................................................ [ 92%]
+........................................................................ [ 97%]
+...........................                                              [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        181      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py               101      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                201      0   100%
+-----------------------------------------------
+TOTAL                        2529     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,15 @@
+All green. Task complete.
+
+**Report — phase 64, task 01 (importer progress hook)**
+
+- `app/rag/importer.py`: `import_sources` gains optional kwarg `progress: Callable[[str, str, int, int], None] | None`; called once per importable file immediately before `_index_file` with `(source, rel_posix_path, done, total)` — `done` = 1-based index across all sources (`summary.files`), `total` = combined count from a pre-walk via the existing `iter_importable_files` (stats only, no file reads), done **only when `progress` is provided**; `limit` path unchanged (hook fires per processed file, `total` stays full); module docstring notes the hook (phase 64).
+- `tests/unit/test_importer.py`: 4 new tests — exact multi-root sequence (`total` = combined), no-pre-walk sentinel (monkeypatched counting wrapper: 1 walk without hook vs 2 with), unchanged + `EmbeddingError` files still reported as current, and `limit=` (2 events, `total` = 3).
+
+**Results**
+- `uv run pytest --cov=app --cov-report=term`: **1223 passed**, `app/` coverage **99%** (>90% gate)
+- `uv run ruff check . && uv run pyright`: clean (0 errors)
+- Existing callers (`scripts/import_docs.py`, `app/api/sync.py`, `app/api/git_sources.py`) untouched and byte-identical in behavior — all pre-existing tests green.
+
+**Notes:** `.agent/PLAN.md` no longer exists in the repo (removed in commit `281f355`); the phase files served as binding context — no deviations. No commit made (phase commit belongs to task 06).
+
+**Next pending task:** `64_sync_upload_progress/02_sync_status_current_file.md`
@@ -0,0 +1,71 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 47%]
+........................................................................ [ 52%]
+........................................................................ [ 58%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 94%]
+.......................................................................  [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py                89      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2476     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
@@ -0,0 +1,17 @@
+Everything is green and the diff is clean. Task complete.
+
+## Report
+
+**Implemented (task 02 — sync status reports the current file):**
+- `app/api/sync.py`: `SyncStatus` gains `current_file`/`files_done`/`files_total`; `GET /api/sync/status` returns them (null/0/0 idle, all pre-existing keys unchanged); `_run_sync` resets them at start, passes the task-01 hook to `import_sources(..., prune=True, progress=_hook)` assigning `f"{source}/{rel}"` + counts, and clears `current_file` in both terminal states while keeping final counts; module + endpoint + dataclass docstrings updated (clone/pull phase reports no file per A4).
+- `tests/unit/test_sync_button.py`: 3 new unit tests — full idle dict pinned (new keys null/0/0), mid-run status via the runner's real hook closure (worker-thread + gated clone/import, also pins A4 no-file-during-clone and success-terminal behavior), failed-terminal clears `current_file` keeping counts with sanitized error.
+- `tests/integration/test_sync_api.py` (defect fix for prior work): `FakeImportSources`/`failing_import` now accept + record the `progress` kwarg, idle-shape pin extended with the three keys, success test pins the hook wiring.
+
+**Results:**
+- `uv run pytest` → 1226 passed
+- `uv run pytest --cov=app --cov-report=term-missing` → 1226 passed, TOTAL 99% (`app/api/sync.py` 100%)
+- `uv run ruff check . && uv run pyright` → clean (0 errors)
+
+**Decisions:** unit tests drive `_run_sync` directly (no DB/HTTP; seams monkeypatched on `app.api.sync` — the house mock-import pattern), since the task named `test_sync_button.py` though the API coverage lives in the integration suite; in-memory `GitSource` needs explicit `kind="git"` (Python default applies at INSERT flush). No UI changes — "Syncing…" stays until task 04. No commit (phase commit belongs to task 06).
+
+**Next pending task:** `.agent/phases/todo/64_sync_upload_progress/03_upload_background_202.md`
@@ -0,0 +1,72 @@
+........................................................................ [  5%]
+........................................................................ [ 11%]
+........................................................................ [ 17%]
+........................................................................ [ 23%]
+........................................................................ [ 29%]
+........................................................................ [ 35%]
+........................................................................ [ 41%]
+........................................................................ [ 46%]
+........................................................................ [ 52%]
+........................................................................ [ 58%]
+........................................................................ [ 64%]
+........................................................................ [ 70%]
+........................................................................ [ 76%]
+........................................................................ [ 82%]
+........................................................................ [ 88%]
+........................................................................ [ 93%]
+........................................................................ [ 99%]
+..                                                                       [100%]
+=============================== warnings summary ===============================
+.venv/lib/python3.13/site-packages/fastapi/testclient.py:1
+  /var/home/ducoterra/Projects/Personal/brain_of_reese/.venv/lib/python3.13/site-packages/fastapi/testclient.py:1: StarletteDeprecationWarning: Using `httpx` with `starlette.testclient` is deprecated; install `httpx2` instead.
+    from starlette.testclient import TestClient as TestClient  # noqa
+
+-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
+================================ tests coverage ================================
+_______________ coverage: platform linux, python 3.13.13-final-0 _______________
+
+Name                        Stmts   Miss  Cover
+-----------------------------------------------
+app/__init__.py                 1      0   100%
+app/api/__init__.py             0      0   100%
+app/api/auth.py                22      0   100%
+app/api/chat.py               131      0   100%
+app/api/chats.py              110      0   100%
+app/api/config.py               7      0   100%
+app/api/doc_drafts.py          93      0   100%
+app/api/docs.py                50      0   100%
+app/api/git_sources.py        143      0   100%
+app/api/health.py              10      0   100%
+app/api/steering.py            42      0   100%
+app/api/suggestions.py          8      0   100%
+app/api/sync.py               101      0   100%
+app/config.py                 112      0   100%
+app/core/__init__.py            0      0   100%
+app/core/auth.py               20      0   100%
+app/core/caching.py           108      0   100%
+app/core/debugging.py          29      2    93%
+app/core/docs_push.py          39      0   100%
+app/core/logging.py            13      0   100%
+app/db.py                      21      0   100%
+app/main.py                    52      0   100%
+app/models.py                  86      0   100%
+app/rag/__init__.py             0      0   100%
+app/rag/agent.py               78      0   100%
+app/rag/archive_upload.py     128      0   100%
+app/rag/chunker.py            206      4    98%
+app/rag/git_sources.py         14      0   100%
+app/rag/importer.py           180      3    98%
+app/rag/llm.py                189      0   100%
+app/rag/overview.py            71      0   100%
+app/rag/prompts.py             65      0   100%
+app/rag/retriever.py           94      3    97%
+app/rag/sources_meta.py        16      0   100%
+app/rag/suggestions.py         27      0   100%
+app/rag/summarizer.py          24      0   100%
+app/schemas.py                198      0   100%
+-----------------------------------------------
+TOTAL                        2488     12    99%
+coverage gate: app/ 99% (>90%) OK
+All checks passed!
+0 errors, 0 warnings, 0 informations
+validation OK
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
ducoterra	f04ddbe1f8	fix(web): history tab copy — every chat saves automatically, there is no Save button Build and Push Containers / build-and-push-app (push) Successful in 1m35s Details Build and Push Containers / build-and-push-db (push) Successful in 10s Details meta description -> locked (A3) auto-save string (history.html L6). page-sub -> locked (A3) string, the <strong>Save</strong> emphasis retired with the button (L106-109). empty row -> locked (A3) string; colspan=6, hidden, and row id untouched (L163). h1, the anonymous gate section, and history.js are byte-identical — state language verified accurate.	2026-09-02 01:29:42 -04:00
ducoterra	8a1f99cb38	feat(web): move the chat action cluster to the pinned bottom and align the button sets - task 01: relocate the .chat-actions row (New chat + Share, comments byte-identical with a Phase 65 note) from the top of the column to the bottom of .chat-shell, directly above the composer - task 02 (owner-locked A1): wrap the row + #composer in ONE sticky .chat-bottom unit (position: sticky; bottom: env(safe-area-inset-bottom, 0), no z-index) — the pills stay at the bottom of the screen at every scroll position and settle into flow above the footer - task 03 (owner-locked A2): right-align the bottom row to the column's right edge (justify-content: flex-end), mirroring the right-aligned Save-as-doc corner; the five action pills share one 44px / 999px-pill geometry - task 04: dedicated Playwright suite tests/e2e/test_bottom_chat_actions.py (resting geometry, the A1 pin across the sticky range, A2 alignment + DOM order + mobile stack + 360px overflow bound + 44px touch targets, New chat / Share click-through) — green in isolation - task 05: regression matrix green in isolation (pinned_composer 4, save_share_ux 5, chat_persistence 4, share_chat 4, chat_history 5, smoke 3); full gate green — unit + integration pass, app/ coverage 99% (>90%), ruff + pyright clean	2026-09-02 01:08:18 -04:00
ducoterra	4677d86f49	feat(sources): real-time file progress for sync and upload — background upload with success toast	2026-09-01 23:51:43 -04:00
ducoterra	cddc84c7db	chore(agent): phase roadmap from TODO.md — 67_llm_retry + 68_search_tool	2026-09-01 20:15:08 -04:00
ducoterra	66419bf652	chore(agent): phase roadmap from TODO.md, 2 phases Phase 65 (TODO.md L3): move the New chat + Share cluster to the pinned bottom of the chat column (sticky .chat-bottom unit with the composer) and right-align the row to the Save-as-doc action corner. Phase 66 (TODO.md L4): History tab copy — every chat saves automatically; retire the Save-button references.	2026-09-01 19:53:56 -04:00
ducoterra	a6a1bf7143	chore(agent): phase roadmap from TODO.md, 1 phase (64_sync_upload_progress)	2026-09-01 19:27:31 -04:00