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_document_viewer.py

@@ -179,6 +179,7 @@ def test_content_known_pair_maps_to_doc_content() -> None:
         title="Deep Mark",
         content="# Deep Mark\n\nbody",
         content_hash="f" * 64,
+        is_image=False,  # phase 122: the stub session never applies defaults
     )
     doc.indexed_at = datetime(2026, 8, 22, 1, 2, 3, tzinfo=UTC)
     doc.created_at = datetime(2026, 8, 20, 9, 0, 0, tzinfo=UTC)  # phase 106
@@ -190,11 +191,15 @@ def test_content_known_pair_maps_to_doc_content() -> None:
     assert r.status_code == 200
     body = r.json()
     # Wire-additive (phase 106, task 05): the pre-date keys are all
-    # still there, joined by ``created_at``.
+    # still there, joined by ``created_at`` — and (phase 122, task 04)
+    # by ``is_image`` (ALWAYS present; text docs: false) while
+    # ``image_url`` is ABSENT (never null — the omission rule).
     assert set(body) == {
         "source", "path", "title", "format", "summary", "created_at",
-        "content", "indexed_at", "chunks",
+        "content", "indexed_at", "chunks", "is_image",
     }
+    assert body["is_image"] is False
+    assert "image_url" not in body  # absent — never null (text doc)
     assert body["source"] == "Homelab"
     assert body["path"] == "notes/deep mark.md"
     assert body["title"] == "Deep Mark"

tests/unit/test_importer.py

@@ -970,12 +970,14 @@ def test_import_summary_log_line_includes_summary_counters(
     """PLAN §9 summary line: the phase-30 counters sit between
     ``embed_batches`` and ``formats``; the phase-118 backfill counter
     sits between ``summary_errors`` and ``dates_updated``; the
-    phase-106 date-refresh counter sits before ``formats``."""
+    phase-106 date-refresh counter and the phase-122 ``images_failed``
+    counter sit after ``dates_updated``, before ``formats``."""
     s = ImportSummary()
     s.files, s.added, s.chunks, s.embed_batches = 3, 3, 5, 4
     s.summaries, s.summary_errors = 2, 1
     s.summary_backfilled = 1
     s.dates_updated = 0
+    s.images_failed = 0
     s.formats = {"md": 1, "yaml": 2}
     with caplog.at_level(logging.INFO, logger="app.importer"):
         s.log()
@@ -983,7 +985,7 @@ def test_import_summary_log_line_includes_summary_counters(
     assert line == (
         "import: summary files=3 added=3 updated=0 unchanged=0 pruned=0 errors=0 "
         "chunks=5 embed_batches=4 summaries=2 summary_errors=1 summary_backfilled=1 "
-        "dates_updated=0 formats=yaml:2,md:1"
+        "dates_updated=0 images_failed=0 formats=yaml:2,md:1"
     )
 
 
@@ -1103,13 +1105,17 @@ def test_no_progress_means_no_prewalk(
         excluded: frozenset[str] = EXCLUDED_DIRS,
         ignore: tuple[str, ...] = (),
         include_hidden: bool = False,
+        image_extensions: frozenset[str] = frozenset(),
     ) -> list[Path]:
         # Phase 89: the walker gained the ``ignore`` keyword; phase 105:
-        # the ``include_hidden`` flag — the sentinel accepts (and forwards)
-        # both to stay a drop-in.
+        # the ``include_hidden`` flag; phase 122: the ``image_extensions``
+        # set — the sentinel accepts (and forwards) all three to stay a
+        # drop-in.
         nonlocal walk_calls
         walk_calls += 1
-        return real_walker(r, extensions, excluded, ignore, include_hidden)
+        return real_walker(
+            r, extensions, excluded, ignore, include_hidden, image_extensions
+        )
 
     monkeypatch.setattr(importer, "iter_importable_files", counting)
     try:

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"
+    }

tests/unit/test_save_as_doc_button.py

@@ -53,18 +53,23 @@ def test_app_config_dict_carries_the_docs_flag() -> None:
     body = app_config(s)
     # Phase 62 (task 01): the response grew to the phase-62 UI
     # customization keys; phase 91 (task 03) deleted the retired
-    # CSS-file theming's ``theme`` key — the five keys below are the
-    # entire endpoint contract.
+    # CSS-file theming's ``theme`` key; phase 122 (task 01) added the
+    # ``images`` flag — the six keys below are the entire endpoint
+    # contract.
     assert set(body) == {
         "app_name", "version", "docs_repo_configured",
-        "input_placeholder", "footer_text",
+        "images", "input_placeholder", "footer_text",
     }
     assert body["docs_repo_configured"] is s.docs_configured
     assert body["docs_repo_configured"] is False
+    assert body["images"] is False  # LOCKED A3: off by default
 
     s2 = _settings(docs_repo="/srv/docs-repo")
     assert app_config(s2)["docs_repo_configured"] is True
 
+    s3 = _settings(images=True)
+    assert app_config(s3)["images"] is True
+
 
 # ---------------------------------------------------------------------------
 # brand.js — the flag + promise are surfaced the way app_name is

tests/unit/test_wide_column_css.py

@@ -114,23 +114,25 @@ def test_no_literal_46rem_width_remains() -> None:
 # ---------- the four reading-column selectors ----------
 
 
-def test_the_four_reading_columns_use_the_token() -> None:
-    """.chat-shell, .shared-shell, .doc-md and
-    .doc-summary:has(+ .doc-md) each cap with
-    max-width: var(--chat-column) — and exactly those four rules use
-    the token for a max-width (no other selector)."""
+def test_the_reading_columns_use_the_token() -> None:
+    """.chat-shell, .shared-shell, .doc-md, .doc-image (phase 122,
+    task 04 — the viewer's image block rides the SAME reading column
+    as its .doc-md sibling) and .doc-summary:has(+ .doc-md) each cap
+    with max-width: var(--chat-column) — and exactly those five rules
+    use the token for a max-width (no other selector)."""
     css = _css()
     for selector in (
         ".chat-shell",
         ".shared-shell",
         ".doc-md",
+        ".doc-image",
         ".doc-summary:has(+ .doc-md)",
     ):
         assert "max-width: var(--chat-column)" in _rule_block(css, selector), (
             f"{selector} must cap with max-width: var(--chat-column)"
         )
-    assert css.count("max-width: var(--chat-column)") == 4, (
-        "exactly the four reading-column selectors use the token"
+    assert css.count("max-width: var(--chat-column)") == 5, (
+        "exactly the reading-column selectors use the token"
     )