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

app/rag/retriever.py

@@ -92,6 +92,7 @@ from sqlalchemy.orm import Session
 
 from app.config import get_settings
 from app.models import Chunk, Document
+from app.schemas import SourceRef
 
 #: Shared overflow marker (phase 15; imported by ``app.rag.prompts``)
 #: — used by the steering (<tuning>) section, the phase-118 NULL-summary
@@ -939,3 +940,27 @@ def select_related(
             continue
         out.append(doc)
     return out
+
+
+def source_ref_with_image(doc: Document) -> SourceRef:
+    """One :class:`~app.schemas.SourceRef` wire frame for *doc* — the
+    phase-122 (task 05) SHARED frame builder: the chat API's cited
+    tier (the agent's read docs) and the related tier both run through
+    it, so the per-doc ref shape has exactly one construction site.
+
+    The ref carries the chip identity (``source`` / ``path`` /
+    ``title``) and, ONLY for a standalone-image document (``is_image``),
+    the optional ``image_url`` — the image BYTES route
+    ``/api/documents/<id>/image`` (the chat's sources block renders the
+    compact inline image from it, the summary as alt + caption —
+    "shown in the chat nicely", TODO L6). For a TEXT document the field
+    stays ``None`` and is DROPPED by the model's serializer (never
+    ``null`` — the omission rule): a text-doc frame is byte-identical
+    to pre-phase. The frame's doc id rides the path — the same way the
+    document content endpoint's ``(source, path)`` lookup does (no new
+    id leak beyond what the frame already carries).
+    """
+    ref = SourceRef(source=doc.source, path=doc.path, title=doc.title)
+    if doc.is_image:
+        ref.image_url = f"/api/documents/{doc.id}/image"
+    return ref