phase: 122_image_documents

**Phase 122 (image documents) — final verification pass: all green. No code changes were needed; defects found: none.**

**Verified (implementation already complete in working tree, reviewed end-to-end):**
- Toggle (`BOR_IMAGES`/`BOR_IMAGE_EXTENSIONS`/`BOR_IMAGE_DIR`, off by default) + `GET /api/config` `images` flag
- Ingest: bytes digest, `image_dir` persistent copy, `content = summary = vision description` (chat-model call; only text embedded), fail-soft skip + `images_failed` counter
- Serve/display: `/api/documents/{id}/image` route (404 matrix), viewer `<img>` + description, Sources 48px lazy thumbnails, chat inline source figure (alt = summary), agent `read` marker
- Prune guard: images-off syncs never prune `is_image` docs

**Test / lint / coverage (exact commands & outcomes):**
- `uv run pytest` → exit 0 (green; note: pytest 9.1.1 `-q` omits the final count line in output — exit code authoritative)
- `uv run pytest --cov=app --cov-report=term-missing` → **2715 passed, exit 0, TOTAL 99%** (>90% gate)
- `uv run ruff check . && uv run pyright` → "All checks passed!" / "0 errors, 0 warnings, 0 informations"
- `uv run pytest tests/e2e/test_image_documents.py -v --no-cov` → **4 passed, exit 0** (isolation)

**Completion criteria:** (1) images=true → described/embedded/displayed docs: ✅ (E2E + integration) · (2) images=false byte-identical + image docs survive sync: ✅ (E2E negative app + unit/integration) · (3) viewer + chat rendering with alt text; failed description skips + logs, sync completes: ✅ · (4) test/lint/coverage gates: ✅ · (5) commit + phase move: deferred to harness per this pass's rules (working tree left uncommitted).

**Notable deviation (pre-existing, documented in code):** image route uses `require_user` (phase-79 posture, same gate as the document content endpoint) rather than the phase text's "public" parenthetical — matches the endpoint it mirrors.

**Next pending phase:** `123_chat_image_questions`.

tests/unit/test_kb_tree_builder.py

@@ -169,14 +169,21 @@ def test_summaries_present_and_absent() -> None:
     one, two = _folder_nodes(source)
     assert one.summary == "One desc."
     assert two.summary is None
-    # File nodes carry no summary key at all (the 00_phase.md shape);
-    # since phase 106 they DO carry the creation date (``created_at``
-    # — the RAG view's ``Created`` column).
+    # File nodes carry no summary key at all on the WIRE (the
+    # 00_phase.md shape — the model_dump set check below is the wire
+    # pin); since phase 106 they DO carry the creation date
+    # (``created_at`` — the RAG view's ``Created`` column).
     file = _file_nodes(one)[0]
     assert set(file.model_dump()) == {
         "kind", "path", "title", "chunks", "created_at", "indexed_at"
     }
-    assert "summary" not in file.__class__.model_fields
+    # Phase 122 (task 04): the image-affordance fields DO exist on the
+    # class now (image file nodes set them — the wire omission for text
+    # nodes is the ``KbTreeFile`` serializer, pinned by the model_dump
+    # set check above: a text node never leaks the three keys).
+    from app.schemas import KbTreeFile
+
+    assert {"is_image", "image_url", "summary"} <= set(KbTreeFile.model_fields)
 
 
 def test_file_metadata_unchanged_in_tree() -> None:
@@ -546,3 +553,83 @@ def test_updated_at_does_not_leak_across_sources() -> None:
     a, b = build_kb_tree(["A", "B"], rows, {})
     assert a.updated_at == C0
     assert b.updated_at == C3
+
+
+# ---------------------------------------------------------------------------
+# Phase 122 (task 04) — the image-docs affordance on tree file nodes
+# ---------------------------------------------------------------------------
+
+DOC_ID = "11111111-2222-3333-4444-555555555555"
+
+
+def test_image_file_node_carries_the_affordance_and_text_node_unchanged() -> None:
+    """The ``images`` map (``{(source, path): (doc_id, summary)}``) turns
+    a file node into the image-docs node: ``is_image`` true,
+    ``image_url`` = the bytes route's path built from the mapped id,
+    ``summary`` verbatim (the RAG view's thumbnail ``alt``). A file
+    node NOT in the map keeps the pre-phase wire shape byte-identically
+    (the three image keys are OMITTED, not false/null)."""
+    rows = [
+        ("S", "one/a.md", "A", 1, T0, C0),
+        ("S", "one/pic.png", "pic", 2, T0, C0),
+    ]
+    images = {("S", "one/pic.png"): (DOC_ID, "A red square on a white background.")}
+    (source,) = build_kb_tree(["S"], rows, {}, images)
+    one = _folder_nodes(source)[0]
+    # File nodes keep the FULL source-relative path (the phase-97
+    # shape — the folder prefix rides the node).
+    files = {f.path: f for f in _file_nodes(one)}
+
+    # Text node: the pre-phase wire shape, byte-identical (no image keys).
+    assert set(files["one/a.md"].model_dump()) == {
+        "kind", "path", "title", "chunks", "created_at", "indexed_at"
+    }
+
+    # Image node: the affordance rides the node.
+    dumped = files["one/pic.png"].model_dump()
+    assert dumped["kind"] == "file"
+    assert dumped["is_image"] is True
+    assert dumped["image_url"] == f"/api/documents/{DOC_ID}/image"
+    assert dumped["summary"] == "A red square on a white background."
+    # The catalogue fields still ride verbatim.
+    assert (dumped["title"], dumped["chunks"]) == ("pic", 2)
+    assert (dumped["created_at"], dumped["indexed_at"]) == (C0, T0)
+
+
+def test_image_file_node_null_summary_and_missing_map_entry() -> None:
+    """A mapped image node with a NULL summary (the fail-soft backfill
+    corner) keeps ``summary: null`` on the wire (meaningful — the alt
+    falls back client-side). A map entry that points at a NON-existent
+    (source, path) affects nothing (the builder only reads mapped keys
+    it meets in the catalogue rows)."""
+    rows = [
+        ("S", "one/ghost.png", "ghost", 1, T0, C0),
+        ("S", "one/other.md", "Other", 1, T0, C0),
+    ]
+    images = {
+        ("S", "one/ghost.png"): (DOC_ID, None),
+        ("S", "one/absent.png"): (DOC_ID, "never matched"),
+    }
+    (source,) = build_kb_tree(["S"], rows, {}, images)
+    one = _folder_nodes(source)[0]
+    files = {f.path: f for f in _file_nodes(one)}
+    ghost = files["one/ghost.png"].model_dump()
+    assert ghost["is_image"] is True
+    assert ghost["summary"] is None  # null stays (the alt fallback corner)
+    assert ghost["image_url"] == f"/api/documents/{DOC_ID}/image"
+    assert set(files["one/other.md"].model_dump()) == {
+        "kind", "path", "title", "chunks", "created_at", "indexed_at"
+    }
+
+
+def test_image_affordance_absent_without_the_map() -> None:
+    """No map (the default) → every file node is the pre-phase shape,
+    even for ``.png`` paths: the fields are map-driven (the endpoint
+    composes the map from the ``is_image`` rows), never path-guessed —
+    a pre-phase KB serializes byte-identically."""
+    rows = [("S", "pic.png", "pic", 1, T0, C0)]
+    (source,) = build_kb_tree(["S"], rows, {})
+    (file,) = _file_nodes(source)
+    assert set(file.model_dump()) == {
+        "kind", "path", "title", "chunks", "created_at", "indexed_at"
+    }