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/integration/test_api.py

@@ -48,25 +48,30 @@ def test_health_reports_ok(client) -> None:
 
 
 def test_config_returns_default_app_metadata(client, db: Session) -> None:
-    """GET /api/config is public (anonymous) and returns exactly five
+    """GET /api/config is public (anonymous) and returns exactly six
     keys — the phase-39 app metadata, the phase-59 docs flag (inert
     false while BOR_DOCS_REPO is empty — the "Save as doc" gating),
-    and the phase-62 UI customization strings (composer placeholder,
-    footer line). Phase 91: with an empty ui_settings table the
-    effective strings are the env defaults (B1 — DB-over-env, the row
-    absent here); the retired CSS-file theming's ``theme`` key is gone
-    (task 03 — the five keys are the entire contract)."""
+    the phase-122 images flag (default false in the test env —
+    LOCKED A3: off by default), and the phase-62 UI customization
+    strings (composer placeholder, footer line). Phase 91: with an
+    empty ui_settings table the effective strings are the env defaults
+    (B1 — DB-over-env, the row absent here); the retired CSS-file
+    theming's ``theme`` key is gone (task 03 — the six keys are the
+    entire contract)."""
     _clear_ui_settings(db)
     r = client.get("/api/config")
     assert r.status_code == 200
     body = r.json()
     assert set(body) == {
         "app_name", "version", "docs_repo_configured",
-        "input_placeholder", "footer_text",
+        "images", "input_placeholder", "footer_text",
     }
     assert body["app_name"] == "Brain of Reese"
     assert body["version"] == get_settings().app_version
     assert body["docs_repo_configured"] is False
+    # Phase 122 (task 01): the images flag is the default off (the
+    # test env sets no BOR_IMAGES) — a real bool, not a truthy string.
+    assert body["images"] is False
     # Phase 62: UNSET => the phase-61 neutral copy stands (the
     # byte-identical contract).
     assert body["input_placeholder"] == "Ask me anything…"
@@ -91,7 +96,7 @@ def test_config_follows_overridden_app_name(client, db: Session) -> None:
         body = r.json()
         assert set(body) == {
             "app_name", "version", "docs_repo_configured",
-            "input_placeholder", "footer_text",
+            "images", "input_placeholder", "footer_text",
         }
         assert body["app_name"] == "Brain of Testy"
         assert body["version"] == "0.1.0"
@@ -122,7 +127,7 @@ def test_config_serves_ui_customization_overrides(client, db: Session) -> None:
         body = r.json()
         assert set(body) == {
             "app_name", "version", "docs_repo_configured",
-            "input_placeholder", "footer_text",
+            "images", "input_placeholder", "footer_text",
         }
         assert body["input_placeholder"] == "Ask the vault…"
         assert body["footer_text"] == "Powered by my own models"
@@ -153,6 +158,29 @@ def test_config_docs_flag_tracks_settings(client, db: Session) -> None:
         fastapi_app.dependency_overrides.clear()
 
 
+def test_config_images_flag_tracks_settings(client, db: Session) -> None:
+    """Phase 122 (task 01): ``images`` mirrors ``settings.images``
+    (``BOR_IMAGES``) — a real bool (never a truthy string) that flips
+    true the moment the toggle is on: that flag is the entire frontend
+    gating of the image affordances (the phase-123 attach control,
+    optionally the Sources page hint)."""
+    from app.config import Settings
+    from app.main import app as fastapi_app
+
+    _clear_ui_settings(db)
+    fastapi_app.dependency_overrides[get_settings] = lambda: Settings(
+        images=True,
+    )
+    try:
+        r = client.get("/api/config")
+        assert r.status_code == 200
+        body = r.json()
+        assert isinstance(body["images"], bool)
+        assert body["images"] is True
+    finally:
+        fastapi_app.dependency_overrides.clear()
+
+
 def test_suggestions_returns_list(client) -> None:
     # Phase 79: the chips are user-gated — sign in as the admin first
     # (the test's purpose is the list shape, not the auth contract).