phase: 125_image_anchor_context

All completion criteria verified. The repository is left functional with all changes in the working tree (no commits made, per the harness protocol).

## Final report — phase 125 `image_anchor_context` (verification pass)

All 6 tasks were already complete; this pass verified every criterion and ran the full gates:

- **Migration 0023** `documents.image_context` (TEXT nullable, reversible) — applied (`alembic current` = 0023 head); round-trip test (4 passed) exercises real upgrade → downgrade 0022 → upgrade.
- **Criterion 1** (referenced image enriched + context line in retrieval): integration `test_markdown_referenced_image_gets_context_and_enriched_chunks` + E2E `test_sync_enriches_the_image_doc_with_markdown_context`, `test_chat_answer_quotes_the_context_line` (wire prompt pinned: `<document>` block leads with the one-line `Referenced in …: "alt"` line) — verified present and passing.
- **Criterion 2** (standalone image byte-identical): E2E `test_standalone_*` (NULL `image_context`, block body exactly the bare description, no `Referenced in` anywhere in the prompt) + unit `test_describe_image_without_context_is_byte_identical` — passing.
- **Criterion 3** (markdown-first: record stored on markdown doc, image picks up context later): integration `test_markdown_indexed_before_image_stores_record_and_image_picks_it_up` + post-index enrichment pass test (markdown file gone from disk) — passing.
- **Gates:** `uv run pytest` → 2938 passed, exit 0 · `uv run pytest --cov=app --cov-report=term-missing` → exit 0, TOTAL **99%** (>90%) · `uv run ruff check .` → All checks passed · `uv run pyright` → 0 errors, 0 warnings.
- **Phase E2E in isolation:** `uv run pytest tests/e2e/test_image_anchor_context.py -v --no-cov` → 4 passed.
- **Mock-LLM change regression check:** neighboring image E2E suites green in isolation — `test_smoke` (3), `test_image_documents` (16), `test_chat_image_questions` (17), `test_answer_images` (17).
- No defects found; no code changes needed. No live-infrastructure changes (local dev DB only). No commit made (harness commits).
- Next pending phase: check `.agents/phases/todo/` after the harness moves this phase.

app/rag/summarizer.py

@@ -211,6 +211,7 @@ async def describe_image(
     data: bytes,
     mime: str,
     settings: Settings | None = None,
+    context: str | None = None,
 ) -> str | None:
     """One-shot CHAT-model (vision) description of one image (phase 122,
     LOCKED A3) — the text that becomes the image document's ``content``
@@ -220,11 +221,22 @@ async def describe_image(
     ONE chat-model call against ``settings.llm_chat_model`` (the vision
     model — the ``lite`` summary model is NOT assumed vision-capable)
     with the multimodal user message the OpenAI-compatible API expects:
-    ``[{type: "text", text: DESCRIBE_PROMPT}, {type: "image_url",
-    image_url: {url: <data URL from *data* + *mime*>}}]`` — no system
-    prompt, no tools, no app-level retries beyond the client's own
-    (SDK-level + the house one-shot empty-content policy) — a
-    description failure must not stall a sync.
+    ``[{type: "text", text: DESCRIBE_PROMPT + context prefix},
+    {type: "image_url", image_url: {url: <data URL from *data* +
+    *mime*>}}]`` — no system prompt, no tools, no app-level retries
+    beyond the client's own (SDK-level + the house one-shot empty-
+    content policy) — a description failure must not stall a sync.
+
+    *context* (phase 125, task 03, LOCKED A3): the optional markdown
+    reference context — the alt text + surrounding paragraphs of the
+    ``![alt](path)`` references that point at THIS image (the importer's
+    same-source scan). When provided, it is appended to the text part
+    AFTER the locked :data:`DESCRIBE_PROMPT` (the marker + instruction
+    stay byte-identical — the ``IMAGE_DESCRIPTION_MODE`` mock key is
+    untouched): the vision model is told WHAT THE IMAGE IS FOR so it
+    can write a context-aware description. ``context=None`` (the
+    default — standalone images) sends the bare prompt: the message is
+    byte-identical to the pre-phase-125 shape.
 
     Returns the stripped reply cut exactly at
     ``(settings or llm.settings).summary_max_chars`` (the phase-30 cap —
@@ -236,11 +248,16 @@ async def describe_image(
     continues (LOCKED A3).
     """
     data_url = image_data_url(data, mime)
+    context_prefix = (
+        f"\n\nThis image is referenced in documentation with the following context:\n{context}"
+        if context
+        else ""
+    )
     messages: list[dict[str, Any]] = [
         {
             "role": "user",
             "content": [
-                {"type": "text", "text": DESCRIBE_PROMPT},
+                {"type": "text", "text": DESCRIBE_PROMPT + context_prefix},
                 {"type": "image_url", "image_url": {"url": data_url}},
             ],
         }