phase: 97_kb_tree_catalog

All completion criteria verified — everything is green, no defects found. Final report:

## Phase 97 final verification pass — ALL GREEN

**Verified (no code changes needed):**
- `GET /api/docs/tree` (admin), `build_kb_tree` pure builder, `PATCH /api/folders/summary`, migration 0018 (`manually_edited`, head confirmed), generator skip/keep + `kept_manual` stat, RAG tree UI + edit affordance in `sources.js`/`index.html`/`styles.css`
- `tests/e2e/test_kb_tree.py`: 8 passed — top level, drill source/folder, edit round-trip, clear, manual-desc-survives-sync, reload fallback, anonymous gate
- Integration: tree shape/order/403/empty/indexed-only + PATCH update/create/root/clear/404/403/no-LLM + stat-walk equivalence (in `test_docs_api.py`); 3-field `folder_summaries=` import token preserved

**Gates (exact commands):**
- `uv run pytest --cov=app --cov-report=term-missing` → **2053 passed**, TOTAL coverage **99%** (>90% ✓)
- `uv run ruff check . && uv run pyright` → **All checks passed / 0 errors**
- `uv run pytest tests/e2e/test_kb_tree.py -v --no-cov` → **8 passed** in isolation
- 30 story/RAG-view E2E suites run **one per process**: all passed, incl. `test_ls_tree_drilldown` (agent `ls` byte-identical ✓), `test_import_documents`, `test_edit_summaries`, `test_admin_auth`, `test_kb_overview`

**Completion criteria:** tree view ✓ · edit round-trip + clear ✓ · manual persists/clear resets ✓ · `ls` unchanged ✓ · pytest/coverage/lint ✓ · E2E isolation ✓ · commit — left to harness per protocol (working tree untouched, `git add/commit` not run)

**Deviations:** none. **Next pending phase:** none — `todo/` contains only 97 (96 already committed).

tests/e2e/test_document_viewer.py

@@ -107,6 +107,16 @@ def _assert_closed(page: Page) -> None:
     expect(page.locator(".doc-modal")).not_to_be_visible()
 
 
+def _drill(page: Page, *names: str) -> None:
+    """Phase 97: the catalog is the drill-down tree the agent's `ls`
+    sees — click through the source/folder rows (exact name match,
+    one per name) to the level that holds the asserted file. The drill
+    is the only change from the flat-table era; the row itself is
+    unchanged."""
+    for name in names:
+        page.click(f'#folders-tbody a.folder-link:text-is("{name}")')
+
+
 # ---------------------------------------------------------------------------
 # 1. Chat source chip → SAME-PAGE modal (no new tab)
 # ---------------------------------------------------------------------------
@@ -172,7 +182,9 @@ def test_sources_row_opens_modal(
 ) -> None:
     _reset_db(mock_llm, seed=True)
     login(page, app_url)  # phase 16: the Sources catalog is admin-only
-
+    # Phase 97: the row lives at its folder level (docs → homelab →
+    # container_gitlab) — the drill is the only change.
+    _drill(page, "docs", "homelab", "container_gitlab")
     row = page.locator("#docs-tbody tr", has_text="gitlab-compose.yaml")
     expect(row).to_have_count(1)
     link = row.locator("td:nth-child(2) a.doc-link")
@@ -320,6 +332,9 @@ def test_modal_xss_safe(
     # The Sources table lists every indexed document — the admin entry
     # point into the modal for a doc the chat never cited.
     login(page, app_url)
+    # Phase 97: the seeded doc's row lives at the notes/ level — the
+    # drill is the only change.
+    _drill(page, "docs", "notes")
     row = page.locator("#docs-tbody tr", has_text="xss-fixture.md")
     expect(row).to_have_count(1)
     row.locator("td:nth-child(2) a.doc-link").click()