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).

app/schemas.py

@@ -244,6 +244,75 @@ class DocList(BaseModel):
     documents: list[DocSummary]
 
 
+class KbTreeFile(BaseModel):
+    """One file node of the KB drill-down tree (phase 97, task 02).
+
+    ``kind`` is the wire discriminator (``"file"`` — the ``00_phase.md``
+    JSON shape is the contract). ``path`` is SOURCE-RELATIVE (the RAG
+    view prefixes the source in its breadcrumb); ``title`` /
+    ``chunks`` (content + ``is_summary`` chunks — the same count
+    ``GET /api/docs`` returns) / ``indexed_at`` (ISO-8601) are verbatim
+    from the catalogue row the endpoint reads.
+    """
+
+    kind: Literal["file"] = "file"
+    path: str
+    title: str
+    chunks: int = Field(ge=0)
+    indexed_at: str
+
+
+class KbTreeFolder(BaseModel):
+    """One folder node of the KB drill-down tree (phase 97, task 02).
+
+    ``path`` is the source-relative folder (never ``""`` — the SOURCE
+    node IS the root); ``documents`` is the recursive subtree count
+    (the phase-94 ``ls`` count rule: every path equal to the folder or
+    starting with ``folder + "/"`` — the file sharing a folder's name
+    counts); ``summary`` is the stored ``folder_summaries`` row (AI or
+    manual — any row) or null; ``children`` are the direct subfolders
+    (path order) followed by the direct files (catalog order) — the
+    recursive union (Pydantic v2 resolves it with
+    ``from __future__ import annotations``).
+    """
+
+    kind: Literal["folder"] = "folder"
+    path: str
+    documents: int = Field(ge=0)
+    summary: str | None = None
+    children: list[KbTreeFolder | KbTreeFile] = Field(default_factory=list)
+
+
+class KbTreeSource(BaseModel):
+    """One source node of the KB drill-down tree (phase 97, task 02).
+
+    Sources list the REGISTERED names first (registry order — each
+    always present, a registered 0-document source lists with
+    ``documents: 0`` and no children), then the indexed-only sources
+    (alphabetical) — the phase-97 superset rule. ``documents`` is the
+    source's whole recursive count; ``summary`` is the stored
+    ``(source, "")`` source-root row or null; ``children`` are the
+    source's direct subfolders + direct files (same shape as a folder
+    node's).
+    """
+
+    name: str
+    documents: int = Field(ge=0)
+    summary: str | None = None
+    children: list[KbTreeFolder | KbTreeFile] = Field(default_factory=list)
+
+
+class KbTree(BaseModel):
+    """Response of ``GET /api/docs/tree`` (phase 97, task 02).
+
+    The FULL recursive tree in ONE fetch — the RAG view (admin) drills
+    client-side, zero per-level fetches (the ``00_phase.md`` "The tree
+    endpoint" contract).
+    """
+
+    sources: list[KbTreeSource]
+
+
 class DocContent(BaseModel):
     """One indexed document's full content (feeds the viewer page, phase 10)."""
 
@@ -294,6 +363,44 @@ class SummaryResult(BaseModel):
     chunks: int
 
 
+class FolderSummaryUpdate(BaseModel):
+    """``PATCH /api/folders/summary`` body (phase 97, task 03).
+
+    ``source`` / ``folder_path`` name the folder whose stored
+    description is edited — ``folder_path = ""`` is the SOURCE ROOT
+    (the phase-94 ``folder_summaries`` convention). ``summary`` is the
+    raw new text: the API strips it before storing, and an
+    empty/whitespace-only value is the *clear* operation (row deleted
+    — the reset path, the phase-57 analog), not a 422. Unconstrained on
+    purpose: an unknown source or a folder with no indexed descendant
+    must 404 (``source not found`` / ``folder not found`` —
+    registry/row-lookup semantics), and traversal strings such as
+    ``../../etc`` are simply not prefixes of any indexed path (the
+    DB-only rule of the ``/documents/content`` lookup — no filesystem
+    access).
+    """
+
+    source: str
+    folder_path: str
+    summary: str
+
+
+class FolderSummaryResult(BaseModel):
+    """``PATCH /api/folders/summary`` response (phase 97, task 03).
+
+    ``summary`` is the stored text after the change — ``null`` after a
+    clear (the RAG view hides the level block / empties the description
+    cell on null). Every non-empty save was stored with
+    ``manually_edited = true`` (the flag itself is not echoed — the
+    response mirrors the phase-57 ``SummaryResult`` shape minus the
+    chunk count, which a folder description has no role in).
+    """
+
+    source: str
+    folder_path: str
+    summary: str | None
+
+
 class SteeringNoteIn(BaseModel):
     """``POST /api/steering`` body: one tuning instruction (phase 15).