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

frontend/assets/app.js

@@ -1526,6 +1526,10 @@ function appendSources(wrap, sources) {
     chip.textContent = label;
     chip.title = label;
     meta.appendChild(chip);
+    // Phase 122 (task 05): a ref for an IMAGE document carries
+    // `image_url` (the frame's only new field — omitted on text refs):
+    // its chip gains the compact inline figure right after it.
+    if (s.image_url) appendSourceImageFigure(meta, s);
   }
   body.appendChild(meta);
   // Accessible full path whenever the pill visually truncates.
@@ -1575,10 +1579,82 @@ function appendRelated(wrap, related) {
     link.title = docLabel; // full path as the native tooltip (chip pattern)
     link.setAttribute("aria-label", docLabel); // the accessible name is the full path
     row.appendChild(link);
+    // Phase 122 (task 05): the related tier rides the same ref shape —
+    // an image doc's ref carries image_url and gets the same figure.
+    if (s.image_url) appendSourceImageFigure(row, s);
   }
   body.appendChild(row);
 }
 
+/* Phase 122 (task 05): the chat's sources block shows a retrieved
+ * IMAGE document "nicely" (TODO L6): the ref's chip gains a COMPACT
+ * INLINE FIGURE right after it. The chip keeps its text and its
+ * affordance — the figure is ADDITIVE, never a replacement — and the
+ * figure reuses the chip's navigation (the same documentUrl href, the
+ * /document.html escape hatch; the same left-click → same-page modal,
+ * phase 26). alt + the VISIBLE caption = the document's SUMMARY (the
+ * vision description — the WCAG alt contract): the frame carries no
+ * summary (image_url is the only new frame field), so the figure
+ * fetches the content endpoint the chip's modal already uses (the
+ * (source, path) pair is the same lookup key) and swaps the summary
+ * in; until it settles — and when it fails — the title stands in (a
+ * caption is ALWAYS visible). A FAILED IMAGE LOAD collapses the figure
+ * to the plain chip (the figure is removed — never a broken-image
+ * icon: the row's bytes route 404s when the copy was lost). */
+function appendSourceImageFigure(meta, s) {
+  const label = `${s.source}/${s.path}`;
+  const fig = document.createElement("a");
+  fig.className = "source-image";
+  fig.setAttribute("role", "listitem");
+  fig.href = documentUrl(s.source, s.path, "/"); // back → the chat page
+  fig.title = label; // full path as the native tooltip (chip pattern)
+  fig.setAttribute("aria-label", label); // the accessible name is the full path
+  fig.addEventListener("click", (e) => {
+    e.preventDefault(); // no new tab (phase 26) — the modal takes over
+    e.stopPropagation();
+    openDocumentModal(s.source, s.path, fig);
+  });
+  const img = document.createElement("img");
+  img.className = "source-image-img";
+  img.src = s.image_url;
+  img.alt = s.title || label; // the summary arrives via the fetch below
+  img.addEventListener("error", () => {
+    // The plain chip stays (it is the collapse target) — the figure,
+    // with its not-yet-resolved alt, goes.
+    fig.remove();
+  });
+  const caption = document.createElement("span");
+  caption.className = "source-image-caption";
+  caption.textContent = s.title || label; // visible caption: the title first…
+  fig.append(img, caption);
+  meta.appendChild(fig);
+  // …and the document's summary once the content fetch settles.
+  fetchContentSummary(s.source, s.path).then((summary) => {
+    if (!fig.isConnected) return; // collapsed (img error) or bubble cleared
+    if (summary && summary.trim() !== "") {
+      img.alt = summary;
+      caption.textContent = summary;
+    }
+  });
+}
+
+/* The document content endpoint the chip's modal already boots
+ * against (the (source, path) lookup key the ref carries) — phase 122
+ * (task 05) asks it ONLY for the image figure's summary (alt +
+ * caption). Any failure (404, network, bad body) resolves to null —
+ * the title fallback stands and the figure is unaffected. */
+function fetchContentSummary(source, path) {
+  const url =
+    "/api/documents/content?source=" +
+    encodeURIComponent(source) +
+    "&path=" +
+    encodeURIComponent(path);
+  return fetch(url)
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null)
+    .then((doc) => (doc && typeof doc.summary === "string" ? doc.summary : null));
+}
+
 /* "Maybe try:" chips under a deflected bubble (honesty gate, phase 04,
    shared component + one-tap submit, phase 05). The group is accessible
    (role=list + aria-label) and wraps cleanly at every width. */

frontend/assets/document.js

@@ -102,6 +102,22 @@
  * call — the phase-57 split). ONE shared core — the modal and
  * /document.html both get it (document-modal.js imports
  * renderDocument from this module — no per-surface copy).
+ *
+ * Phase 122 (task 04): image documents — when doc.is_image is true,
+ * #doc-content renders the persistent bytes FIRST (the <img> block
+ * from doc.image_url — the /api/documents/{id}/image route — alt =
+ * the summary, the WCAG alt contract; a NULL summary falls back to
+ * the title), and the description (doc.content — the ONLY readable
+ * text of the doc) follows in the EXISTING plain-content slot below
+ * (the .doc-raw path; a description is prose, not markdown). The
+ * labeled Summary panel is suppressed for the verbatim-description
+ * case (summary === content — the importer invariant; the panel
+ * would duplicate the text right below the image); an admin-edited
+ * summary (different text) still renders in its panel with the
+ * phase-57 edit affordance. An <img> load failure (the route's 404 —
+ * the row exists but the copy was lost) swaps the block for a small
+ * "Image unavailable" note (role=status): the page still shows the
+ * description. ONE shared core — page + modal both get it.
  */
 
 import { bindSharedHeaderControls, fetchIsAdmin, initSharedHeader } from "./header.js";
@@ -189,12 +205,25 @@ export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
   });
 
   contentEl.replaceChildren();
+  // Phase 122 (task 04): an image document — the persistent bytes
+  // render as the <img> block FIRST; the description (= doc.content)
+  // follows in the normal content slot below (the plain-content path
+  // — the last branch in this function).
+  if (doc.is_image) {
+    contentEl.appendChild(docImageBlock(doc));
+  }
   // Phase 36: the summary panel — labeled section ABOVE the original
   // content, on BOTH surfaces (page + modal) through this one core.
   // Only a non-empty summary renders: markdown docs carry none (phase
   // 30) and the fail-soft path leaves summary NULL, so both are
-  // byte-for-byte unchanged here.
-  if (doc.summary && doc.summary.trim() !== "") {
+  // byte-for-byte unchanged here. Phase 122 (task 04): for an IMAGE
+  // doc whose summary IS the verbatim description (summary ===
+  // content — the importer invariant), the panel would duplicate the
+  // text right below the image, so it is suppressed; an admin-edited
+  // summary (different text) still renders with the phase-57 edit
+  // affordance.
+  const imageSummaryIsContent = doc.is_image && doc.summary === doc.content;
+  if (doc.summary && doc.summary.trim() !== "" && !imageSummaryIsContent) {
     const section = document.createElement("section");
     section.className = "doc-summary";
     section.setAttribute("aria-label", "Summary");
@@ -228,6 +257,40 @@ export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
   }
 }
 
+/* ---------- image block (phase 122, task 04) ----------
+ * The viewer's image block for an ``is_image`` document: the
+ * document's PERSISTENT bytes (doc.image_url — the
+ * /api/documents/{id}/image route) as a block <img> (max-width 100%;
+ * the theme's surface treatment lives in .doc-image). alt = the
+ * summary (the vision description — the WCAG alt contract everywhere);
+ * a NULL summary (the fail-soft backfill corner) falls back to the
+ * title. On a load failure (the route's 404 — the row exists but the
+ * copy was lost) the block shows a small "Image unavailable."
+ * note (role=status) in its place; the description in the content
+ * slot below still renders (the doc is still readable). Properties
+ * only (src, alt) — every document-derived value is a text node /
+ * property, never innerHTML (the XSS contract, unchanged). */
+function docImageBlock(doc) {
+  const wrap = document.createElement("div");
+  wrap.className = "doc-image";
+  const img = document.createElement("img");
+  img.className = "doc-image-img";
+  img.src = doc.image_url;
+  img.alt =
+    typeof doc.summary === "string" && doc.summary.trim() !== ""
+      ? doc.summary
+      : doc.title;
+  img.addEventListener("error", () => {
+    const note = document.createElement("p");
+    note.className = "doc-image-unavailable";
+    note.setAttribute("role", "status");
+    note.textContent = "Image unavailable — the file is missing.";
+    wrap.replaceChildren(note);
+  });
+  wrap.appendChild(img);
+  return wrap;
+}
+
 /* ---------- summary editing (phase 57, task 02 — D4, admin-only) ----------
  * The .doc-summary panel is the ONE place the stored summary is edited
  * (page + modal through this core). Only an admin (docAdminReady) ever

frontend/assets/sources.js

@@ -285,6 +285,21 @@
  *   • the stat cards are UNTOUCHED — they keep their indexed_at
  *     "last indexed" semantics (the owner asked for the column, not
  *     the cards).
+ *
+ * Phase 122 (task 04) — the image-doc thumbnail: a file node of the
+ * tree carries the image affordance (is_image / image_url / summary —
+ * OMITTED on text nodes, the wire-additive rule) when it is an image
+ * document. makeRow's Path cell then renders a FIXED 48px thumbnail
+ * box (object-fit: cover, loading="lazy", alt = the summary — the
+ * vision description; a NULL summary falls back to the title) BEFORE
+ * the path link (the .kb-doc-path flex wrapper — the link keeps its
+ * ellipsis). Progressive enhancement: a failed fetch (or the lazy
+ * first paint) swaps in the document glyph INSIDE the same fixed box
+ * (no layout shift beyond the box, no broken-image placeholder). Text
+ * rows never get a box (the pre-phase bare-link cell, byte-identical).
+ * The glyph is static SVG (aria-hidden — the alt text is the
+ * accessible content); the box + img are properties only, never
+ * innerHTML with document-derived data (the house rule).
  */
 
 import { fetchIsAdmin } from "./header.js";
@@ -1391,12 +1406,78 @@ export async function mount(root) {
           chunks: f.chunks,
           created_at: f.created_at, // phase 106 (task 08, D8): the tree's file date
           indexed_at: f.indexed_at,
+          // Phase 122 (task 04): the image affordance — the tree's
+          // file node carries is_image / image_url / summary on an
+          // image doc (the omission rule: a TEXT node's wire shape
+          // carries none, so these stay undefined there and makeRow
+          // keeps the bare-link cell, byte-identical to pre-phase).
+          is_image: f.is_image,
+          image_url: f.image_url,
+          summary: f.summary,
         })
       );
     }
     if (tableWrap) tableWrap.hidden = files.length === 0;
   }
 
+  /* Phase 122 (task 04): the document glyph — the fallback INSIDE the
+   * fixed thumbnail box (a failed fetch, or a node with no servable
+   * image_url). Static SVG, aria-hidden (the img's alt is the
+   * accessible content; this is decoration for the box). Built with
+   * createElementNS — the module keeps its ONE innerHTML (the static
+   * sync-modal skeleton, the test_kb_tree_ui pin). */
+  function docThumbGlyph() {
+    const span = document.createElement("span");
+    span.className = "kb-doc-thumb-glyph";
+    span.setAttribute("aria-hidden", "true");
+    const NS = "http://www.w3.org/2000/svg";
+    const svg = document.createElementNS(NS, "svg");
+    svg.setAttribute("viewBox", "0 0 48 48");
+    svg.setAttribute("fill", "none");
+    svg.setAttribute("stroke", "currentColor");
+    svg.setAttribute("stroke-width", "2.4");
+    svg.setAttribute("stroke-linecap", "round");
+    svg.setAttribute("stroke-linejoin", "round");
+    const sheet = document.createElementNS(NS, "path");
+    sheet.setAttribute(
+      "d",
+      "M12 4h16l8 8v28a4 4 0 0 1-4 4H12a4 4 0 0 1-4-4V8a4 4 0 0 1 4-4Z"
+    );
+    const fold = document.createElementNS(NS, "path");
+    fold.setAttribute("d", "M28 4v8h8");
+    svg.append(sheet, fold);
+    span.appendChild(svg);
+    return span;
+  }
+
+  /* Phase 122 (task 04): the image-doc thumbnail — the FIXED 48px box
+   * (object-fit: cover via CSS, loading="lazy", alt = the summary —
+   * the vision description; a NULL/blank summary falls back to the
+   * title, then the path). A failed fetch swaps in the document
+   * glyph in the SAME box (progressive enhancement — no layout shift
+   * beyond the fixed box, no broken-image placeholder). Called only
+   * for image rows (makeRow gates on d.is_image). */
+  function docThumb(d) {
+    const box = document.createElement("span");
+    box.className = "kb-doc-thumb";
+    const alt =
+      typeof d.summary === "string" && d.summary.trim() !== ""
+        ? d.summary
+        : d.title || d.path;
+    if (d.image_url) {
+      const img = document.createElement("img");
+      img.className = "kb-doc-thumb-img";
+      img.loading = "lazy";
+      img.src = d.image_url;
+      img.alt = alt;
+      img.addEventListener("error", () => box.replaceChildren(docThumbGlyph()));
+      box.appendChild(img);
+    } else {
+      box.appendChild(docThumbGlyph());
+    }
+    return box;
+  }
+
   /* The no-data state (phase 97): zero sources (nothing registered,
    * nothing indexed) OR a failed tree fetch (the former showEmpty
    * failure behavior, unchanged in kind) — every catalog surface
@@ -1440,7 +1521,18 @@ export async function mount(root) {
     });
     link.title = d.path; // full path as the link's hover/accessible name
     link.textContent = d.path;
-    pathTd.appendChild(link);
+    // Phase 122 (task 04): an image row gets the FIXED 48px thumbnail
+    // box before the path link (the .kb-doc-path flex wrapper — the
+    // link keeps its ellipsis). Text rows keep the bare-link cell,
+    // byte-identical to pre-phase (no box at all).
+    if (d.is_image) {
+      const pathWrap = document.createElement("div");
+      pathWrap.className = "kb-doc-path";
+      pathWrap.append(docThumb(d), link);
+      pathTd.appendChild(pathWrap);
+    } else {
+      pathTd.appendChild(link);
+    }
     tr.appendChild(pathTd);
 
     // Phase 106 (task 08, D8): the cell order is [title, chunks,

frontend/assets/styles.css

@@ -737,6 +737,47 @@ details.thinking .thinking-text ul { margin: 0 0 0.5rem; }
 }
 .source-chip:hover { background: var(--brand-soft); text-decoration: underline; }
 
+/* Phase 122 (task 05): the sources block's COMPACT INLINE IMAGE for a
+   retrieved IMAGE document ("shown in the chat nicely", TODO L6) — the
+   .source-image figure sits beside its chip in the .msg-meta flex row
+   (additive: the chip's text and affordance stay). A capped (96px,
+   contain) img on the theme's surface, the document's summary as the
+   visible caption in the AA-safe muted ink (8.6:1 on --bg — the
+   row's page background). A failed image load removes the whole
+   figure in JS (the plain chip stays — never a broken-image icon). */
+.source-image {
+  display: inline-flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.15rem;
+  max-width: 100%;
+  min-width: 0;
+  text-decoration: none;
+}
+.source-image-img {
+  display: block;
+  max-height: 96px;
+  max-width: 100%;
+  width: auto;
+  height: auto;
+  object-fit: contain;
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+}
+.source-image-caption {
+  max-width: 14rem;
+  color: var(--ink-soft); /* 8.6:1 on --bg (AA) — the row's page background */
+  font-size: 0.7rem;
+  line-height: 1.25;
+  text-align: center;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+.source-image:hover { text-decoration: underline; } /* flat — the caption underlines, the chip pattern */
+
 /* Phase 113 (task 02): the related-docs row — the SECONDARY tier of
    scored docs (phase 113 task 01's usefulness bar demotes the
    sub-floor hits out of the citation surface; on a deflected turn the
@@ -2246,6 +2287,61 @@ details.thinking .thinking-text ul { margin: 0 0 0.5rem; }
   text-decoration: underline;
 }
 
+/* Image-document rows (phase 122, task 04): the file table's Path cell
+   carries a FIXED 48px thumbnail box before the path link (image rows
+   only — text rows keep the pre-phase bare-link cell, no box). The
+   .kb-doc-path flex wrapper gives the link its own ellipsis budget
+   (min-width: 0 — the .sync-label pattern) now that the box shares
+   the cell; object-fit: cover keeps every aspect ratio inside the
+   square (CSS on .kb-doc-thumb-img). The glyph fallback (a failed
+   fetch, or a node without a servable image_url) swaps INSIDE the
+   same fixed box — no layout shift beyond the box, no broken-image
+   placeholder. The img's alt (the vision description) carries the
+   accessibility; the glyph is aria-hidden. Phase-08 tokens only. */
+.kb-doc-path {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+  max-width: 100%;
+}
+.kb-doc-path .doc-link {
+  flex: 1 1 auto;
+  min-width: 0; /* lets the link shrink — what engages the ellipsis */
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.kb-doc-thumb {
+  flex: 0 0 auto;
+  display: block;
+  width: 48px;
+  height: 48px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+  background: var(--bg);
+  color: var(--ink-soft); /* the glyph's stroke color (decorative) */
+  overflow: hidden;
+}
+.kb-doc-thumb-img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.kb-doc-thumb-glyph {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  padding: 9px;
+  box-sizing: border-box;
+}
+.kb-doc-thumb-glyph svg {
+  width: 100%;
+  height: 100%;
+}
+
 /* ---------- KB folder-description editor (phase 97, task 05) ----------
    The phase-57 edit affordance on the RAG view's folder descriptions
    (the .kb-summary-* family, mirroring the viewer's .doc-summary-*):
@@ -4267,6 +4363,44 @@ details.thinking .thinking-text ul { margin: 0 0 0.5rem; }
   line-height: 1.5;
 }
 
+/* Image documents (phase 122, task 04): the viewer's image block —
+   the document's persistent bytes (the /api/documents/{id}/image
+   route) above its description (the .doc-raw content slot below). The
+   theme's surface card treatment (the .doc-md language): the image
+   sits on --surface with the line border + radius; max-width 100% +
+   max-height 70vh keep any aspect ratio inside the page (height: auto
+   keeps the ratio). Static content — no animation; the alt text (the
+   vision description) carries the accessibility (WCAG). Phase-08
+   tokens only (no new hue — the monochrome invariant). */
+.doc-image {
+  width: 100%;
+  max-width: var(--chat-column);
+  margin: 0 auto 1rem;
+  display: flex;
+  justify-content: center;
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  padding: 0.5rem;
+}
+.doc-image-img {
+  display: block;
+  max-width: 100%;
+  max-height: 70vh;
+  height: auto;
+  border-radius: var(--radius-sm);
+  background: var(--bg);
+}
+/* The onerror fallback (the route's 404 — the row exists but the
+   copy was lost): a muted note in the card's place-of-image; the
+   description below still renders, so the doc stays readable. */
+.doc-image-unavailable {
+  margin: 1.25rem 1rem;
+  color: var(--ink-soft); /* 5.1:1 on --surface (AA) */
+  font-size: 0.9rem;
+}
+
 /* Designed not-found state (no emoji — plain SVG mark, phase 08 rule). */
 .doc-not-found {
   width: 100%;