@uurtech/jdf-cli 0.2.1 → 0.2.2

package/dist/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import fs7 from 'fs';
-import path7 from 'path';
+import fs8 from 'fs';
+import path8 from 'path';
 import { fileURLToPath } from 'url';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import JSZip from 'jszip';
 import crypto, { createHash } from 'crypto';
 import { readFile } from 'fs/promises';
+import os from 'os';
 import { execFileSync, spawnSync } from 'child_process';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
@@ -23,17 +24,17 @@ var JDFX_MANIFEST_PATH = "manifest.json";
 var JDFX_ASSET_DIR = "assets";
 
 // src/commands/validate.ts
-var __dirname$1 = path7.dirname(fileURLToPath(import.meta.url));
+var __dirname$1 = path8.dirname(fileURLToPath(import.meta.url));
 function resolveSchemaPath() {
-  const bundled = path7.resolve(__dirname$1, "jdf-schema.json");
-  if (fs7.existsSync(bundled)) return bundled;
-  const dev = path7.resolve(__dirname$1, "../../../../spec/jdf-schema.json");
+  const bundled = path8.resolve(__dirname$1, "jdf-schema.json");
+  if (fs8.existsSync(bundled)) return bundled;
+  const dev = path8.resolve(__dirname$1, "../../../../spec/jdf-schema.json");
   return dev;
 }
 var SCHEMA_PATH = resolveSchemaPath();
 async function loadDocument(filePath) {
   if (filePath.toLowerCase().endsWith(".jdfx")) {
-    const zip = await JSZip.loadAsync(fs7.readFileSync(filePath));
+    const zip = await JSZip.loadAsync(fs8.readFileSync(filePath));
     const docFile = zip.file(JDFX_DOCUMENT_PATH);
     if (!docFile) {
       console.error(`\u2717 Bundle missing ${JDFX_DOCUMENT_PATH}`);
@@ -58,11 +59,11 @@ async function loadDocument(filePath) {
     }
     return { doc, bundle: { manifest, assetCount } };
   }
-  return { doc: JSON.parse(fs7.readFileSync(filePath, "utf-8")) };
+  return { doc: JSON.parse(fs8.readFileSync(filePath, "utf-8")) };
 }
 async function validate(file) {
-  const filePath = path7.resolve(file);
-  if (!fs7.existsSync(filePath)) {
+  const filePath = path8.resolve(file);
+  if (!fs8.existsSync(filePath)) {
     console.error(`File not found: ${filePath}`);
     return false;
   }
@@ -75,11 +76,11 @@ async function validate(file) {
   }
   if (!loaded) return false;
   const { doc, bundle } = loaded;
-  if (!fs7.existsSync(SCHEMA_PATH)) {
+  if (!fs8.existsSync(SCHEMA_PATH)) {
     console.error(`Schema not found at ${SCHEMA_PATH}`);
     return false;
   }
-  const schema = JSON.parse(fs7.readFileSync(SCHEMA_PATH, "utf-8"));
+  const schema = JSON.parse(fs8.readFileSync(SCHEMA_PATH, "utf-8"));
   const ajv = new Ajv({ allErrors: true, strict: false });
   addFormats(ajv);
   const validateFn = ajv.compile(schema);
@@ -88,7 +89,7 @@ async function validate(file) {
     const d = doc;
     const pageCount = Array.isArray(d.pages) ? d.pages.length : 0;
     const elCount = Array.isArray(d.pages) ? d.pages.reduce((acc, p) => acc + (Array.isArray(p?.elements) ? p.elements.length : 0), 0) : 0;
-    console.log(`\u2713 Valid: ${path7.basename(filePath)}`);
+    console.log(`\u2713 Valid: ${path8.basename(filePath)}`);
     console.log(`  Format:    ${d.$jdf}${bundle ? " (jdfx bundle)" : ""}`);
     console.log(`  Title:     ${d.meta?.title}`);
     console.log(`  Pages:     ${pageCount}`);
@@ -101,7 +102,7 @@ async function validate(file) {
     }
     return true;
   }
-  console.error(`\u2717 Invalid: ${path7.basename(filePath)}`);
+  console.error(`\u2717 Invalid: ${path8.basename(filePath)}`);
   for (const err of validateFn.errors || []) {
     const loc = err.instancePath || "(root)";
     console.error(`  ${loc} \u2014 ${err.message}`);
@@ -304,13 +305,13 @@ function stripInline(text) {
   return parseInline(text).map((r) => r.text).join("");
 }
 async function importMarkdown(inputPath, outputPath) {
-  const input = path7.resolve(inputPath);
+  const input = path8.resolve(inputPath);
   console.log(`Importing: ${input}`);
-  const content = fs7.readFileSync(input, "utf-8");
-  const doc = convertMarkdownToJdf(content, path7.basename(input, path7.extname(input)), path7.dirname(input));
+  const content = fs8.readFileSync(input, "utf-8");
+  const doc = convertMarkdownToJdf(content, path8.basename(input, path8.extname(input)), path8.dirname(input));
   let output;
   if (outputPath) {
-    output = path7.resolve(outputPath);
+    output = path8.resolve(outputPath);
   } else {
     const stem = input.replace(/\.(md|markdown)$/i, "");
     output = stem + (shouldUseJdfx(doc) ? ".jdfx" : ".jdf");
@@ -318,11 +319,11 @@ async function importMarkdown(inputPath, outputPath) {
   console.log(`Output:    ${output}`);
   if (output.toLowerCase().endsWith(".jdfx")) {
     const { bytes, manifest } = await packJdfx(doc);
-    fs7.writeFileSync(output, bytes);
+    fs8.writeFileSync(output, bytes);
     console.log(`
 Done! Created ${doc.pages.length} page(s), ${manifest.assets.length} asset(s) bundled`);
   } else {
-    fs7.writeFileSync(output, JSON.stringify(doc, null, 2));
+    fs8.writeFileSync(output, JSON.stringify(doc, null, 2));
     console.log(`
 Done! Created ${doc.pages.length} page(s)`);
   }
@@ -339,10 +340,10 @@ var MIME_BY_EXT2 = {
 };
 function resolveImageSrc(src, baseDir) {
   if (/^(https?:|data:|file:)/i.test(src)) return src;
-  const abs = path7.isAbsolute(src) ? src : path7.resolve(baseDir, src);
+  const abs = path8.isAbsolute(src) ? src : path8.resolve(baseDir, src);
   try {
-    const bytes = fs7.readFileSync(abs);
-    const ext = path7.extname(abs).slice(1).toLowerCase();
+    const bytes = fs8.readFileSync(abs);
+    const ext = path8.extname(abs).slice(1).toLowerCase();
     const mime = MIME_BY_EXT2[ext] || "application/octet-stream";
     return `data:${mime};base64,${bytes.toString("base64")}`;
   } catch {
@@ -2188,25 +2189,209 @@ async function importPdfToJdf2(source, title, options = {}) {
   };
   return importPdfToJdf(source, title, runtime, options);
 }
+var DEFAULT_OLLAMA_MODEL = "qwen2.5vl:3b";
+var DEFAULT_OPENAI_MODEL = "gpt-4o-mini";
+var OLLAMA_HOST = process.env.OLLAMA_HOST || "http://localhost:11434";
+async function loadDoc(file) {
+  if (file.toLowerCase().endsWith(".jdfx")) {
+    const zip = await JSZip.loadAsync(fs8.readFileSync(file));
+    const f = zip.file(JDFX_DOCUMENT_PATH);
+    if (!f) throw new Error(`Bundle missing ${JDFX_DOCUMENT_PATH}`);
+    const doc = JSON.parse(await f.async("string"));
+    const manifest = zip.file("manifest.json") ? JSON.parse(await zip.file("manifest.json").async("string")) : { assets: [] };
+    for (const a of manifest.assets ?? []) {
+      const af = zip.file(a.path);
+      if (!af) continue;
+      const data = (await af.async("nodebuffer")).toString("base64");
+      const res = { src: "embedded", mimeType: a.mimeType, data };
+      doc.resources ??= {};
+      if (/^video\//i.test(a.mimeType || "")) (doc.resources.videos ??= {})[a.id] = res;
+      else (doc.resources.images ??= {})[a.id] = res;
+    }
+    return { doc, bundle: true };
+  }
+  return { doc: JSON.parse(fs8.readFileSync(file, "utf-8")), bundle: false };
+}
+function findImages(doc) {
+  const out = [];
+  const walk2 = (els, page) => {
+    for (const el of els ?? []) {
+      if (el?.type === "image") out.push({ el, page, index: out.length });
+      if (el?.elements) walk2(el.elements, page);
+    }
+  };
+  doc.pages.forEach((p, i) => walk2(p.elements, i + 1));
+  return out;
+}
+async function imageBytes(doc, el, docDir) {
+  const fromData = (d, fallback) => {
+    const m = d.match(/^data:([^;,]+)?[^,]*,(.*)$/s);
+    return m ? { bytes: Buffer.from(m[2], "base64"), mime: m[1] || fallback } : { bytes: Buffer.from(d, "base64"), mime: fallback };
+  };
+  const res = el.resource ? doc.resources?.images?.[el.resource] ?? doc.resources?.[el.resource] : void 0;
+  if (res?.data) return fromData(String(res.data), res.mimeType || "image/png");
+  if (res?.path) {
+    const p = path8.resolve(docDir, res.path);
+    return fs8.existsSync(p) ? { bytes: fs8.readFileSync(p), mime: res.mimeType || "image/png" } : null;
+  }
+  const src = el.src;
+  if (!src) return null;
+  if (src.startsWith("data:")) return fromData(src, "image/png");
+  if (/^https?:\/\//i.test(src)) {
+    const r = await fetch(src);
+    if (!r.ok) throw new Error(`download failed ${r.status}: ${src}`);
+    return { bytes: Buffer.from(await r.arrayBuffer()), mime: r.headers.get("content-type") || "image/png" };
+  }
+  const local = path8.resolve(docDir, src);
+  return fs8.existsSync(local) ? { bytes: fs8.readFileSync(local), mime: "image/png" } : null;
+}
+async function ocrTesseract(bytes, lang) {
+  const { createWorker } = await import('tesseract.js');
+  const cachePath = path8.join(os.homedir(), ".cache", "jdf", "tesseract");
+  fs8.mkdirSync(cachePath, { recursive: true });
+  const worker = await createWorker(lang, 1, { cachePath, logger: () => {
+  } });
+  try {
+    const { data } = await worker.recognize(bytes, {}, { text: true, blocks: true });
+    let w = 1, h = 1;
+    try {
+      const { loadImage } = await import('@napi-rs/canvas');
+      const im = await loadImage(bytes);
+      w = im.width || 1;
+      h = im.height || 1;
+    } catch {
+    }
+    const lines = data.blocks?.flatMap((b) => b.paragraphs?.flatMap((p) => p.lines ?? []) ?? []) ?? data.lines ?? [];
+    const blocks = lines.map((ln) => ({ text: String(ln.text ?? "").replace(/\s+/g, " ").trim(), confidence: ln.confidence != null ? Math.round(ln.confidence) / 100 : void 0, bbox: ln.bbox ? { x: +(ln.bbox.x0 / w).toFixed(4), y: +(ln.bbox.y0 / h).toFixed(4), w: +((ln.bbox.x1 - ln.bbox.x0) / w).toFixed(4), h: +((ln.bbox.y1 - ln.bbox.y0) / h).toFixed(4) } : void 0 })).filter((b) => b.text.length > 0 && (b.confidence == null || b.confidence >= 0.3));
+    if (!blocks.length && String(data.text ?? "").trim()) blocks.push({ text: String(data.text).replace(/\s+/g, " ").trim() });
+    return { blocks, source: `tesseract.js:${lang}` };
+  } finally {
+    await worker.terminate();
+  }
+}
+async function openaiVision(bytes, mime, model, prompt2) {
+  const key = process.env.OPENAI_API_KEY;
+  if (!key) throw new Error("OPENAI_API_KEY is not set");
+  const base = process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
+  const r = await fetch(`${base}/chat/completions`, { method: "POST", headers: { Authorization: `Bearer ${key}`, "content-type": "application/json" }, body: JSON.stringify({ model, messages: [{ role: "user", content: [{ type: "text", text: prompt2 }, { type: "image_url", image_url: { url: `data:${mime};base64,${bytes.toString("base64")}` } }] }], max_tokens: 800 }) });
+  if (!r.ok) throw new Error(`OpenAI vision failed ${r.status}: ${(await r.text()).slice(0, 300)}`);
+  const j = await r.json();
+  return String(j.choices?.[0]?.message?.content ?? "").trim();
+}
+async function ollamaVision(bytes, model, prompt2) {
+  const r = await fetch(`${OLLAMA_HOST}/api/generate`, { method: "POST", body: JSON.stringify({ model, prompt: prompt2, images: [bytes.toString("base64")], stream: false, options: { temperature: 0 } }) });
+  if (!r.ok) throw new Error(`Ollama vision failed ${r.status}: ${(await r.text()).slice(0, 300)} \u2014 is the model pulled? (ollama pull ${model})`);
+  const j = await r.json();
+  return String(j.response ?? "").trim();
+}
+var CAPTION_PROMPT = "Describe this image for a search index in one or two factual sentences: what it shows, any chart type, axes, trends, labels, names and numbers you can read. No preamble.";
+var OCR_PROMPT = "Transcribe all text visible in this image exactly, line by line, top to bottom, left to right. Output only the text.";
+async function describeDocument(doc, docDir, opts = {}) {
+  const ocrP = opts.ocr ?? "tesseract";
+  const capP = opts.caption ?? "ollama";
+  const lang = opts.ocrLanguage ?? "eng";
+  const images = findImages(doc);
+  const targets = opts.element != null ? images.filter((im) => im.el.id === opts.element || String(im.index) === opts.element) : images;
+  if (opts.element != null && !targets.length) throw new Error(`no image element "${opts.element}" (have: ${images.map((i) => i.el.id ?? `#${i.index}`).join(", ") || "none"})`);
+  const stats = { ocr: 0, captions: 0, skipped: 0, failed: [] };
+  for (const im of targets) {
+    const el = im.el;
+    if (!el.id) el.id = `image-${im.index + 1}`;
+    const needOcr = ocrP !== "none" && (opts.force || !el.ocr?.blocks?.length);
+    const needCap = capP !== "none" && (opts.force || !el.caption);
+    if (!needOcr && !needCap) {
+      stats.skipped++;
+      continue;
+    }
+    const img = await imageBytes(doc, el, docDir);
+    if (!img) {
+      stats.failed.push(`${el.id}: image bytes not reachable`);
+      continue;
+    }
+    if (needOcr) {
+      try {
+        if (ocrP === "tesseract") {
+          const r = await ocrTesseract(img.bytes, lang);
+          el.ocr = { language: lang, source: r.source, created: (/* @__PURE__ */ new Date()).toISOString(), blocks: r.blocks };
+        } else {
+          const text = await openaiVision(img.bytes, img.mime, opts.captionModel ?? DEFAULT_OPENAI_MODEL, OCR_PROMPT);
+          el.ocr = { source: `openai:${opts.captionModel ?? DEFAULT_OPENAI_MODEL}`, created: (/* @__PURE__ */ new Date()).toISOString(), blocks: text.split(/\r?\n/).map((t) => t.trim()).filter(Boolean).map((t) => ({ text: t })) };
+        }
+        stats.ocr++;
+      } catch (e) {
+        stats.failed.push(`${el.id} ocr: ${e.message}`);
+      }
+    }
+    if (needCap) {
+      try {
+        const model = opts.captionModel ?? (capP === "ollama" ? DEFAULT_OLLAMA_MODEL : DEFAULT_OPENAI_MODEL);
+        const text = capP === "ollama" ? await ollamaVision(img.bytes, model, CAPTION_PROMPT) : await openaiVision(img.bytes, img.mime, model, CAPTION_PROMPT);
+        if (text) {
+          el.caption = text;
+          el.captionSource = `${capP}:${model}`;
+          stats.captions++;
+        }
+      } catch (e) {
+        stats.failed.push(`${el.id} caption: ${e.message}`);
+      }
+    }
+    if (!opts.quiet) console.log(`  \xB7 ${el.id} (page ${im.page}): ${needOcr ? `ocr ${el.ocr?.blocks?.length ?? 0} block(s)` : "ocr kept"}${needCap ? ` \xB7 caption ${el.caption ? `"${String(el.caption).slice(0, 70)}${String(el.caption).length > 70 ? "\u2026" : ""}"` : "\u2014"}` : ""}`);
+  }
+  return stats;
+}
+async function describeFile(inputPath, opts = {}) {
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) throw new Error(`File not found: ${input}`);
+  const { doc, bundle } = await loadDoc(input);
+  const images = findImages(doc);
+  if (!images.length) {
+    console.log(`No image elements in ${path8.basename(input)} \u2014 nothing to describe.`);
+    return;
+  }
+  console.log(`Describing: ${path8.basename(input)} \u2014 ${images.length} image(s); ocr=${opts.ocr ?? "tesseract"} caption=${opts.caption ?? "ollama"}${(opts.caption ?? "ollama") === "ollama" ? ` (${opts.captionModel ?? DEFAULT_OLLAMA_MODEL}, local)` : ""}`);
+  const stats = await describeDocument(doc, path8.dirname(input), opts);
+  const output = opts.output ? path8.resolve(opts.output) : input;
+  if (output.toLowerCase().endsWith(".jdfx") || bundle && !opts.output) fs8.writeFileSync(output, (await packJdfx(doc)).bytes);
+  else fs8.writeFileSync(output, JSON.stringify(doc, null, 2));
+  console.log(`Done: ${stats.ocr} OCR, ${stats.captions} caption(s), ${stats.skipped} already had text${stats.failed.length ? `, ${stats.failed.length} failed` : ""}.`);
+  for (const f of stats.failed) console.warn(`  ! ${f}`);
+  console.log(`Output: ${output}
+Next:   jdf chunk ${path8.basename(output)}   # image text is now part of the chunks`);
+  if (stats.failed.length && stats.ocr + stats.captions === 0) process.exitCode = 1;
+}
 
 // src/commands/import-pdf.ts
 async function importPdf(inputPath, outputPath, options = {}) {
-  const input = path7.resolve(inputPath);
-  if (!fs7.existsSync(input)) {
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) {
     console.error(`File not found: ${input}`);
     process.exit(1);
   }
   console.log(`Importing: ${input}`);
-  const title = path7.basename(input, path7.extname(input));
+  const title = path8.basename(input, path8.extname(input));
   const t0 = Date.now();
   const doc = await importPdfToJdf2(input, title, {
     password: options.password,
     invisibleText: options.dropInvisibleText ? "drop" : "keep"
   });
   console.log(`Parsed in ${((Date.now() - t0) / 1e3).toFixed(1)}s \u2014 ${doc.pages.length} page(s)`);
+  const scanned = doc.pages.filter((p) => !p.elements.some((e) => e.type === "text" || e.type === "richtext" || e.type === "table") && p.elements.some((e) => e.type === "image"));
+  if (scanned.length) {
+    if (options.ocr && options.ocr !== "none") {
+      console.log(`OCR:       ${scanned.length} scanned page(s) \u2192 ${options.ocr}`);
+      for (const p of scanned) for (const e of p.elements) if (e.type === "image" && !e.id) e.id = `scan-${doc.pages.indexOf(p) + 1}`;
+      const ids = scanned.flatMap((p) => p.elements.filter((e) => e.type === "image").map((e) => e.id));
+      for (const id of ids) {
+        const st = await describeDocument(doc, path8.dirname(input), { element: id, ocr: options.ocr, caption: "none", quiet: true });
+        if (st.failed.length) console.warn(`  ! ${st.failed.join("; ")}`);
+      }
+    } else {
+      console.warn(`! ${scanned.length} page(s) have no text layer (scanned). RAG will skip them \u2014 re-run with --ocr tesseract (local) or --ocr openai.`);
+    }
+  }
   let output;
   if (outputPath) {
-    output = path7.resolve(outputPath);
+    output = path8.resolve(outputPath);
   } else {
     const stem = input.replace(/\.pdf$/i, "");
     const wantJdfx = !options.forceJson && shouldUseJdfx(doc);
@@ -2215,11 +2400,11 @@ async function importPdf(inputPath, outputPath, options = {}) {
   console.log(`Output:    ${output}`);
   if (output.toLowerCase().endsWith(".jdfx")) {
     const { bytes, manifest } = await packJdfx(doc);
-    fs7.writeFileSync(output, bytes);
+    fs8.writeFileSync(output, bytes);
     console.log(`
 Done! Created ${doc.pages.length} page(s), ${manifest.assets.length} asset(s) bundled`);
   } else {
-    fs7.writeFileSync(output, JSON.stringify(doc, null, 2));
+    fs8.writeFileSync(output, JSON.stringify(doc, null, 2));
     console.log(`
 Done! Created ${doc.pages.length} page(s)`);
   }
@@ -2232,23 +2417,23 @@ var ImportJsonError = class extends Error {
   }
 };
 async function importJson(inputPath, outputPath, options = {}) {
-  const input = path7.resolve(inputPath);
-  if (!fs7.existsSync(input)) {
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) {
     throw new ImportJsonError(`File not found: ${input}`);
   }
   console.log(`Importing: ${input}`);
-  const raw = fs7.readFileSync(input, "utf-8");
+  const raw = fs8.readFileSync(input, "utf-8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (e) {
     throw new ImportJsonError(`Not valid JSON: ${e.message}`);
   }
-  const title = path7.basename(input, path7.extname(input));
+  const title = path8.basename(input, path8.extname(input));
   const doc = normaliseToJdf(parsed, title);
   let output;
   if (outputPath) {
-    output = path7.resolve(outputPath);
+    output = path8.resolve(outputPath);
   } else {
     const stem = input.replace(/\.json$/i, "");
     const wantJdfx = !options.forceJson && shouldUseJdfx(doc);
@@ -2257,11 +2442,11 @@ async function importJson(inputPath, outputPath, options = {}) {
   console.log(`Output:    ${output}`);
   if (output.toLowerCase().endsWith(".jdfx")) {
     const { bytes, manifest } = await packJdfx(doc);
-    fs7.writeFileSync(output, bytes);
+    fs8.writeFileSync(output, bytes);
     console.log(`
 Done! Created ${doc.pages.length} page(s), ${manifest.assets.length} asset(s) bundled`);
   } else {
-    fs7.writeFileSync(output, JSON.stringify(doc, null, 2));
+    fs8.writeFileSync(output, JSON.stringify(doc, null, 2));
     console.log(`
 Done! Created ${doc.pages.length} page(s)`);
   }
@@ -2363,8 +2548,8 @@ function transcriptChunks(el, elementId2, page, crumb, windowSec, maxTokens) {
     const body = win.map((sg) => sg.speaker ? `${sg.speaker}: ${sg.text}` : sg.text).join(" ").replace(/\s+/g, " ").trim();
     const text = `[${fmtTime(t0)}\u2013${fmtTime(t1)}] ${body}`;
     const chapter = chapterAt(t0);
-    const path9 = [...crumb, ...el.title ? [String(el.title)] : [], ...chapter ? [String(chapter.title)] : []];
-    out.push({ id: `${elementId2}@${Math.round(t0)}`, text, path: path9, page, types: ["video"], tokens: estimateTokens(text), hash: hashText(text), media: { element: elementId2, t0, t1 } });
+    const path10 = [...crumb, ...el.title ? [String(el.title)] : [], ...chapter ? [String(chapter.title)] : []];
+    out.push({ id: `${elementId2}@${Math.round(t0)}`, text, path: path10, page, types: ["video"], tokens: estimateTokens(text), hash: hashText(text), media: { element: elementId2, t0, t1 } });
     win = [];
   };
   for (const sg of segs) {
@@ -2433,8 +2618,14 @@ function serializeElement(el) {
     }
     case "checkbox":
       return `${e.checked ? "[x]" : "[ ]"} ${e.label ?? ""}`.trim();
-    case "image":
-      return e.alt ? `[image: ${e.alt}]` : "";
+    case "image": {
+      const parts = [];
+      if (e.alt) parts.push(`[image: ${e.alt}]`);
+      if (e.caption) parts.push(String(e.caption).trim());
+      const ocr = (e.ocr?.blocks || []).map((b) => String(b.text ?? "").trim()).filter(Boolean).join("\n");
+      if (ocr) parts.push(ocr);
+      return parts.join("\n");
+    }
     case "video":
       return e.title ? `[video: ${e.title}]` : "";
     case "toc":
@@ -2554,34 +2745,62 @@ function chunkDocument(doc, options = {}) {
 }
 async function loadJdf(filePath) {
   if (filePath.toLowerCase().endsWith(".jdfx")) {
-    const zip = await JSZip.loadAsync(fs7.readFileSync(filePath));
+    const zip = await JSZip.loadAsync(fs8.readFileSync(filePath));
     const docFile = zip.file(JDFX_DOCUMENT_PATH);
     if (!docFile) throw new Error(`Bundle missing ${JDFX_DOCUMENT_PATH}`);
     return JSON.parse(await docFile.async("string"));
   }
-  return JSON.parse(fs7.readFileSync(filePath, "utf-8"));
+  return JSON.parse(fs8.readFileSync(filePath, "utf-8"));
+}
+function mediaCoverage(doc) {
+  const cov = { images: { total: 0, covered: 0, missing: [] }, videos: { total: 0, covered: 0, missing: [] } };
+  const walk2 = (els, page) => {
+    for (const el of els ?? []) {
+      if (el?.type === "image") {
+        cov.images.total++;
+        const has = !!(el.caption && String(el.caption).trim()) || !!el.ocr?.blocks?.some((b) => String(b.text ?? "").trim());
+        if (has) cov.images.covered++;
+        else cov.images.missing.push({ id: el.id, page, alt: el.alt });
+      } else if (el?.type === "video") {
+        cov.videos.total++;
+        if (el.transcript?.segments?.length) cov.videos.covered++;
+        else cov.videos.missing.push({ id: el.id, page, title: el.title });
+      }
+      if (el?.elements) walk2(el.elements, page);
+    }
+  };
+  doc.pages.forEach((p, i) => walk2(p.elements, i + 1));
+  return cov;
+}
+function coverageSummary(cov) {
+  const parts = [];
+  if (cov.images.missing.length) parts.push(`${cov.images.missing.length} of ${cov.images.total} image(s) have no caption/OCR text \u2192 jdf describe`);
+  if (cov.videos.missing.length) parts.push(`${cov.videos.missing.length} of ${cov.videos.total} video(s) have no transcript \u2192 jdf transcribe`);
+  return parts.length ? parts.join("; ") : null;
 }
 async function chunkFile(inputPath, opts = {}) {
-  const input = path7.resolve(inputPath);
-  if (!fs7.existsSync(input)) throw new Error(`File not found: ${input}`);
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) throw new Error(`File not found: ${input}`);
   const doc = await loadJdf(input);
   const strategy = opts.strategy ?? "section";
   const chunks = chunkDocument(doc, { strategy, maxTokens: opts.maxTokens, transcriptWindowSec: opts.transcriptWindowSec });
+  const gap = coverageSummary(mediaCoverage(doc));
+  if (gap) console.warn(`  ! media without text (skipped by retrieval): ${gap}`);
   const format = opts.format ?? "jsonl";
   console.log(`Chunking:  ${input}`);
   console.log(`Strategy:  ${strategy}${opts.maxTokens ? ` (max ${opts.maxTokens} tokens)` : ""}`);
   if (format === "inline") {
-    const out = opts.output ? path7.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".jdf");
+    const out = opts.output ? path8.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".jdf");
     const withIndex = { ...doc, index: { chunker: `jdf-${strategy}-v1`, chunks } };
-    fs7.writeFileSync(out, JSON.stringify(withIndex, null, 2));
+    fs8.writeFileSync(out, JSON.stringify(withIndex, null, 2));
     console.log(`Output:    ${out}  (${chunks.length} chunks in "index" block)`);
   } else if (format === "json") {
-    const out = opts.output ? path7.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".chunks.json");
-    fs7.writeFileSync(out, JSON.stringify(chunks, null, 2));
+    const out = opts.output ? path8.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".chunks.json");
+    fs8.writeFileSync(out, JSON.stringify(chunks, null, 2));
     console.log(`Output:    ${out}  (${chunks.length} chunks)`);
   } else {
-    const out = opts.output ? path7.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".chunks.jsonl");
-    fs7.writeFileSync(out, chunks.map((c) => JSON.stringify(c)).join("\n") + "\n");
+    const out = opts.output ? path8.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".chunks.jsonl");
+    fs8.writeFileSync(out, chunks.map((c) => JSON.stringify(c)).join("\n") + "\n");
     console.log(`Output:    ${out}  (${chunks.length} chunks)`);
   }
   const totalTokens = chunks.reduce((a, c) => a + c.tokens, 0);
@@ -2604,11 +2823,11 @@ async function embedBatch(provider, model, inputs) {
       throw new Error(`Unknown embedding provider: ${provider}`);
   }
 }
-var OLLAMA_HOST = process.env.OLLAMA_HOST || "http://localhost:11434";
+var OLLAMA_HOST2 = process.env.OLLAMA_HOST || "http://localhost:11434";
 var OLLAMA_CONTAINER = "jdf-ollama";
 async function ollamaUp() {
   try {
-    const res = await fetch(`${OLLAMA_HOST}/api/tags`, { signal: AbortSignal.timeout(1500) });
+    const res = await fetch(`${OLLAMA_HOST2}/api/tags`, { signal: AbortSignal.timeout(1500) });
     return res.ok;
   } catch {
     return false;
@@ -2633,12 +2852,12 @@ async function ensureOllama(model, autoStart) {
       docker run -d --name ${OLLAMA_CONTAINER} -p 11434:11434 -v jdf-ollama:/root/.ollama ollama/ollama
       docker exec ${OLLAMA_CONTAINER} ollama pull ${model}`;
   if (!autoStart) {
-    throw new Error(`Ollama isn't running at ${OLLAMA_HOST} and --no-auto-start was given.
+    throw new Error(`Ollama isn't running at ${OLLAMA_HOST2} and --no-auto-start was given.
 ${manualHint}`);
   }
   if (!dockerReady()) {
     throw new Error(
-      `Ollama isn't running at ${OLLAMA_HOST}, and the Docker daemon isn't available to auto-start it.
+      `Ollama isn't running at ${OLLAMA_HOST2}, and the Docker daemon isn't available to auto-start it.
 ${manualHint}`
     );
   }
@@ -2675,7 +2894,7 @@ ${manualHint}`);
 }
 async function ollamaPull(model) {
   try {
-    const show = await fetch(`${OLLAMA_HOST}/api/show`, {
+    const show = await fetch(`${OLLAMA_HOST2}/api/show`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ name: model })
@@ -2684,7 +2903,7 @@ async function ollamaPull(model) {
   } catch {
   }
   console.log(`Pulling embedding model "${model}" into Ollama (first run only)\u2026`);
-  const res = await fetch(`${OLLAMA_HOST}/api/pull`, {
+  const res = await fetch(`${OLLAMA_HOST2}/api/pull`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ name: model, stream: false })
@@ -2695,7 +2914,7 @@ async function ollamaPull(model) {
 async function embedOllama(model, inputs) {
   const out = [];
   for (const text of inputs) {
-    const res = await fetch(`${OLLAMA_HOST}/api/embeddings`, {
+    const res = await fetch(`${OLLAMA_HOST2}/api/embeddings`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ model, prompt: text })
@@ -2753,17 +2972,17 @@ async function embedOpenAI(model, inputs) {
 }
 async function loadJdf2(filePath) {
   if (filePath.toLowerCase().endsWith(".jdfx")) {
-    const zip = await JSZip.loadAsync(fs7.readFileSync(filePath));
+    const zip = await JSZip.loadAsync(fs8.readFileSync(filePath));
     const docFile = zip.file(JDFX_DOCUMENT_PATH);
     if (!docFile) throw new Error(`Bundle missing ${JDFX_DOCUMENT_PATH}`);
     return JSON.parse(await docFile.async("string"));
   }
-  return JSON.parse(fs7.readFileSync(filePath, "utf-8"));
+  return JSON.parse(fs8.readFileSync(filePath, "utf-8"));
 }
 function loadCache(cachePath) {
   try {
-    if (!fs7.existsSync(cachePath)) return null;
-    return JSON.parse(fs7.readFileSync(cachePath, "utf-8"));
+    if (!fs8.existsSync(cachePath)) return null;
+    return JSON.parse(fs8.readFileSync(cachePath, "utf-8"));
   } catch {
     return null;
   }
@@ -2774,15 +2993,15 @@ function batched(items, size) {
   return out;
 }
 async function embedFile(inputPath, opts = {}) {
-  const input = path7.resolve(inputPath);
-  if (!fs7.existsSync(input)) throw new Error(`File not found: ${input}`);
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) throw new Error(`File not found: ${input}`);
   const provider = opts.provider ?? "ollama";
   const model = opts.model ?? DEFAULT_MODEL[provider];
   const strategy = opts.strategy ?? "section";
   const doc = await loadJdf2(input);
   const chunks = chunkDocument(doc, { strategy, maxTokens: opts.maxTokens, transcriptWindowSec: opts.transcriptWindowSec });
-  const output = opts.output ? path7.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".embeddings.json");
-  const cachePath = opts.cache ? path7.resolve(opts.cache) : output;
+  const output = opts.output ? path8.resolve(opts.output) : input.replace(/\.(jdf|jdfx)$/i, ".embeddings.json");
+  const cachePath = opts.cache ? path8.resolve(opts.cache) : output;
   console.log(`Embedding: ${input}`);
   console.log(`Provider:  ${provider} / ${model}${provider === "ollama" ? " (local \u2014 no data leaves this machine)" : " (remote API)"}`);
   console.log(`Strategy:  ${strategy} \u2192 ${chunks.length} chunks`);
@@ -2821,7 +3040,7 @@ async function embedFile(inputPath, opts = {}) {
     chunker: `jdf-${strategy}-v1`,
     vectors
   };
-  fs7.writeFileSync(output, JSON.stringify(sidecar));
+  fs8.writeFileSync(output, JSON.stringify(sidecar));
   console.log(`
 Done! ${Object.keys(vectors).length} vectors (${dims}-dim) \u2192 ${output}`);
   return sidecar;
@@ -2865,9 +3084,9 @@ function parseChapters(text) {
     return { t: toSec(m[1]), title: m[2].trim() };
   });
 }
-async function loadDoc(file) {
+async function loadDoc2(file) {
   if (file.toLowerCase().endsWith(".jdfx")) {
-    const zip = await JSZip.loadAsync(fs7.readFileSync(file));
+    const zip = await JSZip.loadAsync(fs8.readFileSync(file));
     const f = zip.file(JDFX_DOCUMENT_PATH);
     if (!f) throw new Error(`Bundle missing ${JDFX_DOCUMENT_PATH}`);
     const doc = JSON.parse(await f.async("string"));
@@ -2883,7 +3102,7 @@ async function loadDoc(file) {
     }
     return { doc, bundle: true, zip };
   }
-  return { doc: JSON.parse(fs7.readFileSync(file, "utf-8")), bundle: false };
+  return { doc: JSON.parse(fs8.readFileSync(file, "utf-8")), bundle: false };
 }
 function findVideos(doc) {
   const out = [];
@@ -2897,27 +3116,27 @@ function findVideos(doc) {
   return out;
 }
 async function clipToTempFile(doc, el, docDir) {
-  const tmp = path7.join(fs7.mkdtempSync(path7.join(__require("os").tmpdir(), "jdf-transcribe-")), "clip.mp4");
+  const tmp = path8.join(fs8.mkdtempSync(path8.join(__require("os").tmpdir(), "jdf-transcribe-")), "clip.mp4");
   const res = el.resource ? doc.resources?.videos?.[el.resource] ?? doc.resources?.images?.[el.resource] : void 0;
   if (res?.data) {
-    fs7.writeFileSync(tmp, Buffer.from(res.data.replace(/^data:[^,]*,/, ""), "base64"));
+    fs8.writeFileSync(tmp, Buffer.from(res.data.replace(/^data:[^,]*,/, ""), "base64"));
     return tmp;
   }
-  if (res?.path) return path7.resolve(docDir, res.path);
+  if (res?.path) return path8.resolve(docDir, res.path);
   const src = el.src;
   if (!src) return null;
   if (src.startsWith("data:")) {
-    fs7.writeFileSync(tmp, Buffer.from(src.replace(/^data:[^,]*,/, ""), "base64"));
+    fs8.writeFileSync(tmp, Buffer.from(src.replace(/^data:[^,]*,/, ""), "base64"));
     return tmp;
   }
   if (/^https?:\/\//i.test(src)) {
     const r = await fetch(src);
     if (!r.ok) throw new Error(`download failed ${r.status}: ${src}`);
-    fs7.writeFileSync(tmp, Buffer.from(await r.arrayBuffer()));
+    fs8.writeFileSync(tmp, Buffer.from(await r.arrayBuffer()));
     return tmp;
   }
-  const local = path7.resolve(docDir, src);
-  return fs7.existsSync(local) ? local : null;
+  const local = path8.resolve(docDir, src);
+  return fs8.existsSync(local) ? local : null;
 }
 function whisperCli(clip, model, language, prompt2) {
   const ffmpeg = spawnSync("ffmpeg", ["-version"]);
@@ -2932,7 +3151,7 @@ function whisperCli(clip, model, language, prompt2) {
   const run = spawnSync("whisper-cli", args, { encoding: "utf-8" });
   if (run.error) throw new Error("whisper-cli not found \u2014 install whisper.cpp (brew install whisper-cpp) or use --from / --provider openai");
   if (run.status !== 0) throw new Error(`whisper-cli failed: ${run.stderr.slice(-400)}`);
-  const j = JSON.parse(fs7.readFileSync(wav.replace(/\.wav$/, "") + ".json", "utf-8"));
+  const j = JSON.parse(fs8.readFileSync(wav.replace(/\.wav$/, "") + ".json", "utf-8"));
   const segs = j.transcription ?? j.segments ?? [];
   const ms = (x) => typeof x === "number" ? x / 1e3 : toSec(String(x).replace(",", "."));
   return segs.map((sg) => ({ t0: ms(sg.offsets?.from ?? sg.start), t1: ms(sg.offsets?.to ?? sg.end), text: String(sg.text ?? "").trim() })).filter((sg) => sg.text);
@@ -2942,7 +3161,7 @@ async function openaiTranscribe(clip, model, language, prompt2) {
   if (!key) throw new Error("OPENAI_API_KEY is not set");
   const base = process.env.OPENAI_BASE_URL || "https://api.openai.com/v1";
   const form = new FormData();
-  form.append("file", new Blob([fs7.readFileSync(clip)]), path7.basename(clip));
+  form.append("file", new Blob([fs8.readFileSync(clip)]), path8.basename(clip));
   form.append("model", model || "whisper-1");
   form.append("response_format", "verbose_json");
   form.append("timestamp_granularities[]", "segment");
@@ -2954,9 +3173,9 @@ async function openaiTranscribe(clip, model, language, prompt2) {
   return (j.segments ?? []).map((sg) => ({ t0: Number(sg.start), t1: Number(sg.end), text: String(sg.text).trim() })).filter((sg) => sg.text);
 }
 async function transcribeFile(inputPath, opts = {}) {
-  const input = path7.resolve(inputPath);
-  if (!fs7.existsSync(input)) throw new Error(`File not found: ${input}`);
-  const { doc, bundle } = await loadDoc(input);
+  const input = path8.resolve(inputPath);
+  if (!fs8.existsSync(input)) throw new Error(`File not found: ${input}`);
+  const { doc, bundle } = await loadDoc2(input);
   const videos = findVideos(doc);
   if (!videos.length) throw new Error("document has no video element");
   let target = videos[0];
@@ -2972,40 +3191,40 @@ async function transcribeFile(inputPath, opts = {}) {
   let segments;
   let source;
   if (opts.from) {
-    segments = parseSubtitles(fs7.readFileSync(path7.resolve(opts.from), "utf-8"), opts.from);
-    source = `${path7.extname(opts.from).slice(1).toLowerCase() || "file"}-import`;
+    segments = parseSubtitles(fs8.readFileSync(path8.resolve(opts.from), "utf-8"), opts.from);
+    source = `${path8.extname(opts.from).slice(1).toLowerCase() || "file"}-import`;
   } else {
     const provider = opts.provider ?? "whisper-cli";
-    const clip = await clipToTempFile(doc, target.el, path7.dirname(input));
+    const clip = await clipToTempFile(doc, target.el, path8.dirname(input));
     if (!clip) throw new Error("could not locate the clip bytes (no bundled asset, data URL, local path or http URL) \u2014 use --from to import subtitles instead");
     segments = provider === "openai" ? await openaiTranscribe(clip, opts.model, opts.language, opts.prompt) : whisperCli(clip, opts.model, opts.language, opts.prompt);
-    source = provider === "openai" ? `openai:${opts.model || "whisper-1"}` : `whisper-cli${opts.model ? ":" + path7.basename(opts.model) : ""}`;
+    source = provider === "openai" ? `openai:${opts.model || "whisper-1"}` : `whisper-cli${opts.model ? ":" + path8.basename(opts.model) : ""}`;
   }
   segments.sort((a, b) => a.t0 - b.t0);
   const transcript = { ...opts.language ? { language: opts.language } : {}, source, created: (/* @__PURE__ */ new Date()).toISOString(), segments };
   target.el.transcript = transcript;
-  if (opts.chapters) target.el.chapters = parseChapters(fs7.readFileSync(path7.resolve(opts.chapters), "utf-8"));
+  if (opts.chapters) target.el.chapters = parseChapters(fs8.readFileSync(path8.resolve(opts.chapters), "utf-8"));
   if (!target.el.id) target.el.id = `video-${target.index + 1}`;
-  const output = opts.output ? path7.resolve(opts.output) : input;
+  const output = opts.output ? path8.resolve(opts.output) : input;
   if (output.toLowerCase().endsWith(".jdfx") || bundle && !opts.output) {
     const { bytes } = await packJdfx(doc);
-    fs7.writeFileSync(output, bytes);
+    fs8.writeFileSync(output, bytes);
   } else {
-    fs7.writeFileSync(output, JSON.stringify(doc, null, 2));
+    fs8.writeFileSync(output, JSON.stringify(doc, null, 2));
   }
   const dur = segments.length ? segments[segments.length - 1].t1 : 0;
-  console.log(`Transcribed: ${path7.basename(input)} \u2192 element "${target.el.id}" (${segments.length} segments, ${Math.round(dur)} s, source ${source})`);
+  console.log(`Transcribed: ${path8.basename(input)} \u2192 element "${target.el.id}" (${segments.length} segments, ${Math.round(dur)} s, source ${source})`);
   if (target.el.chapters) console.log(`Chapters:    ${target.el.chapters.length}`);
   console.log(`Output:      ${output}
-Next:        jdf chunk ${path7.basename(output)}   # transcript \u2192 time-windowed chunks with media.t0/t1`);
+Next:        jdf chunk ${path8.basename(output)}   # transcript \u2192 time-windowed chunks with media.t0/t1`);
   return transcript;
 }
 var CONFIG_NAME = "jdf.rag.json";
 var OUT_DIR = ".jdf-rag";
 function walk(dir, acc = []) {
-  for (const ent of fs7.readdirSync(dir, { withFileTypes: true })) {
+  for (const ent of fs8.readdirSync(dir, { withFileTypes: true })) {
     if (ent.name === "node_modules" || ent.name === OUT_DIR || ent.name.startsWith(".")) continue;
-    const p = path7.join(dir, ent.name);
+    const p = path8.join(dir, ent.name);
     if (ent.isDirectory()) walk(p, acc);
     else if (/\.(jdf|jdfx)$/i.test(ent.name)) acc.push(p);
   }
@@ -3013,10 +3232,10 @@ function walk(dir, acc = []) {
 }
 async function readDoc(file) {
   if (file.toLowerCase().endsWith(".jdfx")) {
-    const zip = await JSZip.loadAsync(fs7.readFileSync(file));
+    const zip = await JSZip.loadAsync(fs8.readFileSync(file));
     return JSON.parse(await zip.file(JDFX_DOCUMENT_PATH).async("string"));
   }
-  return JSON.parse(fs7.readFileSync(file, "utf-8"));
+  return JSON.parse(fs8.readFileSync(file, "utf-8"));
 }
 function videosIn(doc) {
   const out = [];
@@ -3030,29 +3249,44 @@ function videosIn(doc) {
   return out;
 }
 async function ragFolder(dirPath, cli = {}) {
-  const dir = path7.resolve(dirPath);
-  if (!fs7.existsSync(dir) || !fs7.statSync(dir).isDirectory()) throw new Error(`Not a directory: ${dir}`);
-  const cfgPath = path7.join(dir, CONFIG_NAME);
-  const cfg = fs7.existsSync(cfgPath) ? JSON.parse(fs7.readFileSync(cfgPath, "utf-8")) : {};
+  const dir = path8.resolve(dirPath);
+  if (!fs8.existsSync(dir) || !fs8.statSync(dir).isDirectory()) throw new Error(`Not a directory: ${dir}`);
+  const cfgPath = path8.join(dir, CONFIG_NAME);
+  const cfg = fs8.existsSync(cfgPath) ? JSON.parse(fs8.readFileSync(cfgPath, "utf-8")) : {};
   const opts = { ...cfg, ...Object.fromEntries(Object.entries(cli).filter(([, v]) => v !== void 0)) };
   const provider = opts.provider ?? "ollama";
   const transcribe = opts.transcribe ?? "none";
-  const outDir = path7.resolve(opts.out ?? path7.join(dir, OUT_DIR));
+  const outDir = path8.resolve(opts.out ?? path8.join(dir, OUT_DIR));
+  const ocr = opts.ocr ?? "none";
+  const caption = opts.caption ?? "none";
   const files = walk(dir);
   console.log(`jdf rag: ${dir}
-  files:      ${files.length} (.jdf/.jdfx)${fs7.existsSync(cfgPath) ? `
+  files:      ${files.length} (.jdf/.jdfx)${fs8.existsSync(cfgPath) ? `
   config:     ${CONFIG_NAME}` : ""}
   embeddings: ${opts.noEmbed ? "skipped (--no-embed)" : `${provider}${opts.model ? " / " + opts.model : ""}`}
-  transcribe: ${transcribe}${opts.dryRun ? "\n  DRY RUN \u2014 nothing written" : ""}
+  transcribe: ${transcribe}   ocr: ${ocr}   caption: ${caption}${opts.dryRun ? "\n  DRY RUN \u2014 nothing written" : ""}
 `);
   if (!files.length) {
     console.log("Nothing to do.");
     return;
   }
-  const manifest = { dir, created: (/* @__PURE__ */ new Date()).toISOString(), provider: opts.noEmbed ? null : provider, model: opts.model ?? null, strategy: opts.strategy ?? "section", transcribe, files: [], totals: { files: files.length, chunks: 0, videoChunks: 0, videos: 0, transcribed: 0, untranscribed: 0 } };
+  const manifest = {
+    dir,
+    created: (/* @__PURE__ */ new Date()).toISOString(),
+    provider: opts.noEmbed ? null : provider,
+    model: opts.model ?? null,
+    strategy: opts.strategy ?? "section",
+    transcribe,
+    ocr,
+    caption,
+    files: [],
+    totals: { files: files.length, chunks: 0, videoChunks: 0, videos: 0, transcribed: 0, untranscribed: 0, images: 0, described: 0, imagesWithoutText: 0 },
+    /** Every media element that retrieval would still skip, by file — the thing to fix before shipping an index. */
+    mediaWithoutText: []
+  };
   const indexLines = [];
   for (const file of files) {
-    const rel = path7.relative(dir, file);
+    const rel = path8.relative(dir, file);
     const doc = await readDoc(file);
     const vids = videosIn(doc);
     let transcribedHere = 0;
@@ -3076,20 +3310,36 @@ async function ragFolder(dirPath, cli = {}) {
     }
     manifest.totals.videos += vids.length;
     manifest.totals.transcribed += transcribedHere;
+    const covBefore = mediaCoverage(doc);
+    let describedHere = 0;
+    if (covBefore.images.missing.length && (ocr !== "none" || caption !== "none") && !opts.dryRun) {
+      try {
+        await describeFile(file, { ocr, caption, captionModel: opts.captionModel, quiet: true });
+        describedHere = covBefore.images.missing.length;
+      } catch (e) {
+        console.warn(`  ! ${rel}: describe failed: ${e.message}`);
+      }
+    }
+    const covAfter = transcribedHere || describedHere ? mediaCoverage(await readDoc(file)) : covBefore;
+    manifest.totals.images += covAfter.images.total;
+    manifest.totals.described += describedHere;
+    manifest.totals.imagesWithoutText += covAfter.images.missing.length;
+    for (const m of covAfter.images.missing) manifest.mediaWithoutText.push({ file: rel, type: "image", ...m });
+    for (const m of covAfter.videos.missing) manifest.mediaWithoutText.push({ file: rel, type: "video", ...m });
     if (opts.dryRun) {
       manifest.files.push({ file: rel, videos: vids.length, wouldTranscribe: transcribedHere });
       continue;
     }
     const chunkOpts = { strategy: opts.strategy, maxTokens: opts.maxTokens, transcriptWindowSec: opts.transcriptWindowSec };
-    const chunkOut = path7.join(outDir, "chunks", rel.replace(/\.(jdf|jdfx)$/i, ".chunks.jsonl"));
-    fs7.mkdirSync(path7.dirname(chunkOut), { recursive: true });
+    const chunkOut = path8.join(outDir, "chunks", rel.replace(/\.(jdf|jdfx)$/i, ".chunks.jsonl"));
+    fs8.mkdirSync(path8.dirname(chunkOut), { recursive: true });
     let chunks;
     if (opts.noEmbed) {
       chunks = await chunkFile(file, { ...chunkOpts, format: "jsonl", output: chunkOut });
     } else {
       const side = await embedFile(file, { ...chunkOpts, provider, model: opts.model, incremental: true });
       chunks = await chunkFile(file, { ...chunkOpts, format: "jsonl", output: chunkOut });
-      manifest.files.push({ file: rel, chunks: chunks.length, vectors: Object.keys(side.vectors).length, sidecar: path7.relative(dir, file.replace(/\.(jdf|jdfx)$/i, ".embeddings.json")), videos: vids.length, transcribed: transcribedHere });
+      manifest.files.push({ file: rel, chunks: chunks.length, vectors: Object.keys(side.vectors).length, sidecar: path8.relative(dir, file.replace(/\.(jdf|jdfx)$/i, ".embeddings.json")), videos: vids.length, transcribed: transcribedHere });
     }
     if (opts.noEmbed) manifest.files.push({ file: rel, chunks: chunks.length, videos: vids.length, transcribed: transcribedHere });
     for (const c of chunks) {
@@ -3099,15 +3349,27 @@ async function ragFolder(dirPath, cli = {}) {
     }
   }
   if (!opts.dryRun) {
-    fs7.mkdirSync(outDir, { recursive: true });
-    fs7.writeFileSync(path7.join(outDir, "index.jsonl"), indexLines.join("\n") + (indexLines.length ? "\n" : ""));
-    fs7.writeFileSync(path7.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    fs8.mkdirSync(outDir, { recursive: true });
+    fs8.writeFileSync(path8.join(outDir, "index.jsonl"), indexLines.join("\n") + (indexLines.length ? "\n" : ""));
+    fs8.writeFileSync(path8.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
   }
   const t = manifest.totals;
   console.log(`
-Done. ${t.files} files \u2192 ${t.chunks} chunks (${t.videoChunks} from video transcripts); videos ${t.videos}, transcribed now ${t.transcribed}, still without transcript ${t.untranscribed}${t.untranscribed && transcribe === "none" ? " (pass --transcribe whisper-cli|openai, or jdf transcribe --from subs.srt)" : ""}.`);
-  if (!opts.dryRun) console.log(`Index:  ${path7.join(outDir, "index.jsonl")}
-Report: ${path7.join(outDir, "manifest.json")}${opts.noEmbed ? "" : `
+Done. ${t.files} files \u2192 ${t.chunks} chunks (${t.videoChunks} from video transcripts).`);
+  console.log(`Media coverage: videos ${t.videos - t.untranscribed}/${t.videos} with transcript (transcribed now ${t.transcribed}), images ${t.images - t.imagesWithoutText}/${t.images} with caption/OCR (described now ${t.described}).`);
+  if (manifest.mediaWithoutText.length) {
+    console.log(`
+! ${manifest.mediaWithoutText.length} media element(s) still have NO text \u2014 retrieval will skip them:`);
+    for (const m of manifest.mediaWithoutText.slice(0, 12)) console.log(`    ${m.file} \xB7 ${m.type} ${m.id ?? ""} (page ${m.page})${m.title ? ` "${m.title}"` : m.alt ? ` alt="${m.alt}"` : ""}`);
+    if (manifest.mediaWithoutText.length > 12) console.log(`    \u2026 ${manifest.mediaWithoutText.length - 12} more in manifest.json`);
+    console.log(`  fix: jdf rag <dir> --transcribe whisper-cli|openai --ocr tesseract --caption ollama   (or jdf transcribe / jdf describe per file)`);
+    if (opts.strict) {
+      console.error(`--strict: failing because media without text remains.`);
+      process.exitCode = 1;
+    }
+  }
+  if (!opts.dryRun) console.log(`Index:  ${path8.join(outDir, "index.jsonl")}
+Report: ${path8.join(outDir, "manifest.json")}${opts.noEmbed ? "" : `
 Vectors: one <file>.embeddings.json next to each document (incremental \u2014 re-run any time)`}`);
 }
 
@@ -3123,8 +3385,11 @@ The CLI exists for these workflows:
   \u2022 JDF \u2192 vectors    embed those chunks, incrementally, for a vector store.
   \u2022 video \u2192 text     attach a time-stamped transcript to a video element so
                      RAG retrieves "video at 02:13", not just "a video".
+  \u2022 image \u2192 text     OCR + a vision caption for every image so charts and
+                     scanned pages are retrievable, not skipped.
   \u2022 folder \u2192 index   one command over a directory of .jdf/.jdfx: transcribe,
-                     chunk, embed incrementally, write .jdf-rag/index.jsonl.
+                     describe, chunk, embed incrementally, write .jdf-rag/index.jsonl.
+                     Reports media coverage; --strict fails when anything has no text.
 
 Usage:
   jdf validate <file.jdf>
@@ -3132,7 +3397,8 @@ Usage:
   jdf chunk    <file.{jdf,jdfx}> [--strategy section|element|fixed] [--format jsonl|json|inline] [--max-tokens N] [-o out]
   jdf embed    <file.{jdf,jdfx}> [--provider ollama|openai] [--model NAME] [--strategy \u2026] [--incremental] [-o out]
   jdf transcribe <file.{jdf,jdfx}> [--from subs.srt|.vtt|.json] [--provider whisper-cli|openai] [--element ID] [--chapters FILE] [-o out]
-  jdf rag      <dir> [--provider ollama|openai] [--model NAME] [--transcribe none|whisper-cli|openai] [--no-embed] [--dry-run] [--out DIR]
+  jdf describe <file.{jdf,jdfx}> [--ocr tesseract|openai|none] [--caption ollama|openai|none] [--caption-model M] [--ocr-language eng] [--element ID] [--force] [-o out]
+  jdf rag      <dir> [--provider ollama|openai] [--model NAME] [--transcribe none|whisper-cli|openai] [--ocr none|tesseract|openai] [--caption none|ollama|openai] [--strict] [--no-embed] [--dry-run] [--out DIR]
   jdf --help
 
 Commands:
@@ -3141,7 +3407,8 @@ Commands:
   chunk      Split a JDF document into retrieval-ready chunks (offline, deterministic)
   embed      Compute embeddings for the chunks (local via Ollama by default)
   transcribe Store time-stamped text on a video element (import SRT/VTT/JSON, or run Whisper)
-  rag        Make a whole folder retrieval-ready (finds .jdf/.jdfx, transcribes, chunks, embeds, indexes)
+  describe   Give images text: OCR blocks (tesseract.js, local) + a caption (Ollama vision model, local)
+  rag        Make a whole folder retrieval-ready (finds .jdf/.jdfx, transcribes, describes, chunks, embeds, indexes)
 
 Flags:
   -o, --output <path>   Explicit output path
@@ -3168,6 +3435,12 @@ Flags:
       --prompt <text>   transcribe: Whisper vocabulary hint (names, acronyms) \u2014 not an instruction
       --window <sec>    chunk/embed/rag: transcript window per video chunk (default 45)
       --transcribe <p>  rag: none (default) | whisper-cli | openai \u2014 for videos that have no transcript yet
+      --ocr <p>         describe/rag/convert: tesseract (local WASM) | openai | none
+      --caption <p>     describe/rag: ollama (local vision model, default moondream) | openai | none
+      --caption-model   describe/rag: vision model name (ollama: qwen2.5vl:3b, llava\u2026; openai: gpt-4o-mini\u2026)
+      --ocr-language    describe: tesseract language(s), e.g. eng, tur, eng+tur (default eng)
+      --force           describe: redo images that already have text
+      --strict          rag: exit 1 if any image/video is still without text after the run
       --no-embed        rag: chunk + index only
       --dry-run         rag: list what would happen, write nothing
       --out <dir>       rag: index folder (default <dir>/.jdf-rag)
@@ -3187,9 +3460,11 @@ Examples:
   jdf embed report.jdf --provider openai --incremental
   jdf transcribe talk.jdfx --from talk.srt --chapters chapters.txt   # then: jdf chunk talk.jdfx
   jdf transcribe talk.jdfx --provider openai --language en --prompt "JDF, jdfx, Ollama"
-  jdf rag ./knowledge-base --transcribe openai              # whole folder \u2192 .jdf-rag/index.jsonl
+  jdf describe report.jdfx                                   # OCR (tesseract) + caption (Ollama qwen2.5vl), local
+  jdf convert scan.pdf --ocr tesseract                       # scanned pages get OCR text instead of silence
+  jdf rag ./knowledge-base --transcribe openai --ocr tesseract --caption ollama --strict
 `;
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["help", "h", "json", "verbose", "skip-validate", "incremental", "no-auto-start", "drop-invisible-text", "no-embed", "dry-run"]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["help", "h", "json", "verbose", "skip-validate", "incremental", "no-auto-start", "drop-invisible-text", "no-embed", "dry-run", "force", "strict"]);
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
@@ -3272,7 +3547,8 @@ async function main() {
           await importPdf(input, output, {
             forceJson,
             password: typeof flags.password === "string" ? flags.password : void 0,
-            dropInvisibleText: flags["drop-invisible-text"] === true
+            dropInvisibleText: flags["drop-invisible-text"] === true,
+            ocr: typeof flags.ocr === "string" ? flags.ocr : void 0
           });
           process.exit(0);
         } else if (lower.endsWith(".json")) {
@@ -3316,6 +3592,23 @@ async function main() {
         });
         process.exit(0);
       }
+      case "describe": {
+        const input = positional[0];
+        if (!input) {
+          console.error("Usage: jdf describe <file.{jdf,jdfx}> [--ocr tesseract|openai|none] [--caption ollama|openai|none] [--caption-model M] [--ocr-language eng] [--element id|n] [--force] [-o out]");
+          process.exit(1);
+        }
+        await describeFile(input, {
+          ocr: typeof flags.ocr === "string" ? flags.ocr : void 0,
+          caption: typeof flags.caption === "string" ? flags.caption : void 0,
+          captionModel: typeof flags["caption-model"] === "string" ? flags["caption-model"] : void 0,
+          ocrLanguage: typeof flags["ocr-language"] === "string" ? flags["ocr-language"] : void 0,
+          element: typeof flags.element === "string" ? flags.element : void 0,
+          force: flags.force === true,
+          output: typeof flags.output === "string" ? flags.output : void 0
+        });
+        process.exit(process.exitCode ?? 0);
+      }
       case "rag": {
         const input = positional[0];
         if (!input) {
@@ -3332,11 +3625,15 @@ async function main() {
           transcribeModel: typeof flags["transcribe-model"] === "string" ? flags["transcribe-model"] : void 0,
           language: typeof flags.language === "string" ? flags.language : void 0,
           prompt: typeof flags.prompt === "string" ? flags.prompt : void 0,
+          ocr: typeof flags.ocr === "string" ? flags.ocr : void 0,
+          caption: typeof flags.caption === "string" ? flags.caption : void 0,
+          captionModel: typeof flags["caption-model"] === "string" ? flags["caption-model"] : void 0,
+          strict: flags.strict === true,
           noEmbed: flags["no-embed"] === true,
           dryRun: flags["dry-run"] === true,
           out: typeof flags.out === "string" ? flags.out : void 0
         });
-        process.exit(0);
+        process.exit(process.exitCode ?? 0);
       }
       case "embed": {
         const input = positional[0];

package/dist/jdf-schema.json

@@ -343,7 +343,17 @@
       "anyOf": [{ "required": ["resource"] }, { "required": ["src"] }],
       "properties": {
         "type": { "const": "image" },
+        "id": { "type": "string" },
         "resource": { "type": "string" }, "src": { "type": "string" }, "alt": { "type": "string" },
+        "caption": { "type": "string" }, "captionSource": { "type": "string" },
+        "ocr": {
+          "type": "object",
+          "required": ["blocks"],
+          "properties": {
+            "language": { "type": "string" }, "source": { "type": "string" }, "created": { "type": "string" },
+            "blocks": { "type": "array", "items": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string" }, "confidence": { "type": "number" }, "bbox": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } } } } } }
+          }
+        },
         "position": { "$ref": "#/definitions/Position" },
         "width": { "type": "number" }, "height": { "type": "number" },
         "fit": { "type": "string", "enum": ["contain","cover","fill","none"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uurtech/jdf-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Command-line tool for the JDF (JSON Document Format) — validate and convert documents.",
   "license": "MIT",
   "author": "Ugur Kazdal",
@@ -52,7 +52,8 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "jszip": "^3.10.1",
-    "pdfjs-dist": "^4.10.38"
+    "pdfjs-dist": "^4.10.38",
+    "tesseract.js": "^7.0.0"
   },
   "devDependencies": {
     "@jdf/core": "workspace:*",