diff --git a/README.md b/README.md
index 73c930dc..959d2b83 100644
--- a/README.md
+++ b/README.md
@@ -31,13 +31,21 @@ We believe AI citations should follow **show, don't tell**; they should prove th
 
 DeepCitation turns model citations into deterministic, inspectable proof.
 
-## Install
+## Agent Skills
+
+The fastest way to use DeepCitation — verify citations directly from your AI coding agent with the `/verify` skill. No app code, no API integration. Works with Claude Code, Cursor, Windsurf, and other agents that support skills.
+
+Install from [**DeepCitation/skills**](https://github.com/DeepCitation/skills).
+
+## Building your own integration?
+
+Install the package:
 
 ```sh
 npm install deepcitation  # or bun add / yarn add / pnpm add
 ```
 
-## Quick Start
+### Quick Start
 
 ```typescript
 import { DeepCitation, extractVisibleText, wrapCitationPrompt } from "deepcitation";
@@ -119,13 +127,6 @@ npm install && npm run dev
 - [AG-UI Chat](./examples/agui-chat) — [Live Demo](https://agui-chat-deepcitation.vercel.app/)
 - [URL Citations](./examples/url-example)
 
-
-## Agent Skills
-
-Verify citations directly from your AI coding agent with the `/verify` skill — no app code needed. Works with Claude Code, Cursor, Windsurf, and other agents that support skills.
-
-Install from [**DeepCitation/skills**](https://github.com/DeepCitation/skills).
-
 ## Development
 
 ### Running Tests
diff --git a/docs/agents/engineering-rules.md b/docs/agents/engineering-rules.md
index fa1d335b..3eb6820e 100644
--- a/docs/agents/engineering-rules.md
+++ b/docs/agents/engineering-rules.md
@@ -33,6 +33,14 @@ Do **not** flag these shared fields as "semantically document-only" in code revi
 
 > All citations are potentially verifiable against a page-indexed document. The `type` discriminator indicates the *source* of the citation, not whether page/line fields will be populated.
 
+## Test Failure Policy
+
+When tests fail, fix them. Do not investigate attribution.
+
+- **Never use `git stash` to check whether a failure is "pre-existing"** — stashing is unsafe in shared workspaces where multiple developers and agents operate on the same working tree.
+- **"I think those failures were pre-existing" is not acceptable** without an actual fix. It signals time spent on blame instead of solutions.
+- If a failing test is genuinely out of scope for your current PR, note it explicitly in the PR description and open a separate tracking issue — but do not leave the suite red.
+
 ## Testing Rules
 
 - Tests must validate implemented behavior, not aspirational behavior.
diff --git a/examples/README.md b/examples/README.md
index 76e0485e..d8bf5518 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -9,6 +9,7 @@ Complete, runnable examples demonstrating DeepCitation integration patterns.
 | [**basic-verification**](./basic-verification) | Core 3-step workflow with OpenAI/Anthropic | Learning the basics, quick integration | — |
 | [**langchain-rag-chat**](./langchain-rag-chat) | Next.js + LangChain.js RAG app with DeepCitation verification | RAG pipelines, retrieval + proof UI | [Live Demo](https://langchain-rag-chat-deepcitation.vercel.app/) |
 | [**mastra-rag-chat**](./mastra-rag-chat) | Next.js + Mastra RAG app with DeepCitation verification | Mastra framework, TypeScript-native RAG | [Live Demo](https://mastra-rag-deepcitation.vercel.app/) |
+| [**qmd-local-search**](./qmd-local-search) | CLI example using [qmd](https://github.com/tobi/qmd) as an on-device markdown index with DeepCitation verification | Local-first RAG, privacy-sensitive corpora, offline retrieval | — |
 | [**nextjs-ai-sdk**](./nextjs-ai-sdk) | Next.js chat app with Vercel AI SDK | Full-stack apps, streaming UI | [Live Demo](https://nextjs-ai-sdk-deepcitation.vercel.app/) |
 | [**agui-chat**](./agui-chat) | AG-UI protocol chat with SSE streaming | AG-UI integration, protocol-level control | [Live Demo](https://agui-chat-deepcitation.vercel.app/) |
 | [**static-html**](./static-html) | CDN popover in plain HTML, no build step | Static sites, CDN integration | — |
@@ -137,6 +138,42 @@ npm run dev
 # Open http://localhost:3000
 ```
 
+### qmd Local Search
+
+CLI example using [qmd](https://github.com/tobi/qmd) as an on-device markdown
+index. Retrieval is local (BM25 + vector + LLM rerank); DeepCitation verifies
+the resulting citations against a parallel PDF corpus keyed by filename stem.
+
+```typescript
+import { createStore } from "@tobilu/qmd";
+
+const store = await createStore({
+  dbPath: "./.qmd-index.sqlite",
+  config: { collections: { corpus: { path: "./corpus/md", pattern: "**/*.md" } } },
+});
+
+await store.update();
+await store.embed(); // first run downloads a GGUF embedding model
+
+const hits = await store.search({ query: question, collection: "corpus", limit: 6 });
+
+// Bridge: each hit.file → corpus/pdf/<stem>.pdf
+const pdfUploads = [...new Set(hits.map(h => h.file))].map(mdFile => {
+  const pdfPath = mdFileToPdfPath(mdFile);
+  return { file: readFileSync(pdfPath), filename: basename(pdfPath) };
+});
+
+const { fileDataParts, deepTextPagesByAttachmentId } = await dc.prepareAttachments(pdfUploads);
+```
+
+```bash
+# Run the qmd example
+cd qmd-local-search
+bun install          # auto-builds corpus/pdf from corpus/md
+cp .env.example .env # add DEEPCITATION_API_KEY + OPENAI_API_KEY
+bun run start        # interactive picker
+```
+
 ## More Resources
 
 - [Full Documentation](https://docs.deepcitation.com/)
diff --git a/examples/basic-verification/src/curl.ts b/examples/basic-verification/src/curl.ts
index f804e571..019d0524 100644
--- a/examples/basic-verification/src/curl.ts
+++ b/examples/basic-verification/src/curl.ts
@@ -119,7 +119,7 @@ async function prepareUrlAttachment(url: string): Promise<{
  */
 async function verifyCitations(
   attachmentId: string,
-  citations: Record<string, { fullPhrase?: string; pageNumber?: number }>,
+  citations: Record<string, { sourceContext?: string; pageNumber?: number }>,
 ): Promise<{
   verifications: Record<
     string,
@@ -275,7 +275,7 @@ provided documents accurately and cite your sources.`;
 
   console.log(`📋 Parsed ${citationCount} citation(s) from LLM output`);
   for (const [key, citation] of Object.entries(parsedCitations)) {
-    console.log(`   [${key}]: "${citation.fullPhrase?.slice(0, 50)}..."`);
+    console.log(`   [${key}]: "${citation.sourceContext?.slice(0, 50)}..."`);
   }
   console.log();
 
@@ -321,9 +321,9 @@ provided documents accurately and cite your sources.`;
       console.log(`${"─".repeat(60)}`);
 
       const originalCitation = parsedCitations[key];
-      if (originalCitation?.fullPhrase) {
+      if (originalCitation?.sourceContext) {
         console.log(
-          `  📝 Claimed: "${originalCitation.fullPhrase.slice(0, 100)}${originalCitation.fullPhrase.length > 100 ? "..." : ""}"`,
+          `  📝 Claimed: "${originalCitation.sourceContext.slice(0, 100)}${originalCitation.sourceContext.length > 100 ? "..." : ""}"`,
         );
       }
 
@@ -423,7 +423,7 @@ async function main() {
   console.log("  -d '{");
   console.log('    "data": {');
   console.log('      "attachmentId": "<ATTACHMENT_ID>",');
-  console.log('      "citations": { "1": { "fullPhrase": "...", "pageNumber": 1 } },');
+  console.log('      "citations": { "1": { "sourceContext": "...", "pageNumber": 1 } },');
   console.log('      "outputImageFormat": "avif"');
   console.log("    }");
   console.log("  }'");
diff --git a/examples/basic-verification/src/fixture-to-html.ts b/examples/basic-verification/src/fixture-to-html.ts
index dcb185ac..b29aa036 100644
--- a/examples/basic-verification/src/fixture-to-html.ts
+++ b/examples/basic-verification/src/fixture-to-html.ts
@@ -45,7 +45,7 @@ function convertFixture(provider: string) {
   // Debug: show what we got
   for (const [hash, citation] of Object.entries(parsedCitations)) {
     console.log(
-      `   [${citation.citationNumber}] hash=${hash.slice(0, 8)}… anchor="${citation.anchorText?.slice(0, 30)}"`,
+      `   [${citation.citationNumber}] hash=${hash.slice(0, 8)}… match="${citation.sourceMatch?.slice(0, 30)}"`,
     );
   }
 
@@ -56,16 +56,16 @@ function convertFixture(provider: string) {
   for (const [hash, citation] of Object.entries(parsedCitations)) {
     stubVerifications[hash] = {
       status: "found",
-      label: citation.anchorText || `Citation ${citation.citationNumber}`,
+      label: citation.sourceMatch || `Citation ${citation.citationNumber}`,
       attachmentId: citation.attachmentId || "fixture",
-      verifiedFullPhrase: citation.fullPhrase,
-      verifiedAnchorText: citation.anchorText,
-      verifiedMatchSnippet: citation.fullPhrase?.slice(0, 80),
+      verifiedSourceContext: citation.sourceContext,
+      verifiedSourceMatch: citation.sourceMatch,
+      verifiedMatchSnippet: citation.sourceContext?.slice(0, 80),
       citation: {
         pageNumber: citation.pageNumber,
         lineIds: citation.lineIds,
-        fullPhrase: citation.fullPhrase,
-        anchorText: citation.anchorText,
+        sourceContext: citation.sourceContext,
+        sourceMatch: citation.sourceMatch,
       },
       document: {
         verifiedPageNumber: citation.pageNumber,
diff --git a/examples/basic-verification/src/shared.ts b/examples/basic-verification/src/shared.ts
index ab4a210d..22ed0ec5 100644
--- a/examples/basic-verification/src/shared.ts
+++ b/examples/basic-verification/src/shared.ts
@@ -16,20 +16,17 @@ import { DeepCitation } from "deepcitation/client";
 import {
   type AttachmentAssets,
   type CitationRecord,
+  type Verification,
   extractVisibleText,
   getAllCitationsFromLlmOutput,
-  getCitationStatus,
-  getVerificationTextIndicator,
-  replaceCitationMarkers,
+  renderVerifiedHtml,
 } from "deepcitation";
 import { wrapCitationPrompt } from "deepcitation/prompts";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { basename, dirname, resolve } from "path";
 import { createInterface } from "readline";
 import { fileURLToPath } from "url";
-import { execFileSync } from "child_process";
 
-import { generateHtmlReport } from "./html-report.js";
 
 // Get current directory for loading sample files
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -132,6 +129,12 @@ export interface Step3Result {
   llmResponse: string;
 }
 
+
+export const DEFAULT_OUT_DIR = resolve(__dirname, "../../output");
+
+// ─── Step types and functions (used by step-runner.ts) ─────────────────────
+
+
 export interface Step4Result {
   parsedCitations: CitationRecord;
   visibleText: string;
@@ -139,7 +142,7 @@ export interface Step4Result {
 }
 
 export interface Step5Result {
-  verifications: Record<string, unknown>;
+  verifications: Record<string, Verification>;
   attachments?: Record<string, AttachmentAssets>;
 }
 
@@ -148,69 +151,6 @@ export interface Step6Result {
   snapshotPath: string;
 }
 
-// ─── Step functions (silent — no console output) ───────────────────────────
-
-export async function stepUpload(dc: DeepCitation, source: Source): Promise<Step1Result> {
-  const sourceLabel = source.type === "url" ? source.url : "filename" in source ? source.filename : source.label;
-
-  if (source.type === "url") {
-    const result = await dc.prepareUrl({ url: source.url });
-    return { attachmentId: result.attachmentId, deepTextPages: result.deepTextPages, sourceLabel };
-  }
-
-  const fileBuffer = readFileSync(source.path);
-  const { fileDataParts, deepTextPagesByAttachmentId } = await dc.prepareAttachments([
-    { file: fileBuffer, filename: source.filename },
-  ]);
-
-  const attachmentId = fileDataParts[0].attachmentId;
-  const deepTextPages = deepTextPagesByAttachmentId[attachmentId] ?? [];
-
-  return {
-    attachmentId,
-    deepTextPages,
-    imageBase64: source.type === "image" ? fileBuffer.toString("base64") : undefined,
-    sourceLabel,
-  };
-}
-
-export function stepWrapPrompts(
-  step1: Pick<Step1Result, "attachmentId" | "deepTextPages">,
-  opts?: { systemPrompt?: string; userPrompt?: string },
-): Step2Result {
-  const systemPrompt =
-    opts?.systemPrompt ??
-    process.env.SYSTEM_PROMPT ??
-    `You are a helpful assistant. Answer questions about the
-provided documents accurately and cite your sources.`;
-
-  const userPrompt =
-    opts?.userPrompt ??
-    process.env.USER_PROMPT ??
-    "Summarize the key information shown in this document.";
-
-  const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
-    systemPrompt,
-    userPrompt,
-    deepTextPagesByAttachmentId: { [step1.attachmentId]: step1.deepTextPages },
-  });
-
-  return { enhancedSystemPrompt, enhancedUserPrompt, systemPrompt, userPrompt };
-}
-
-export async function stepCallLlm(
-  streamLlm: StreamLlmFn,
-  prompts: Step2Result,
-  imageBase64?: string,
-): Promise<Step3Result> {
-  const llmResponse = await streamLlm({
-    enhancedSystemPrompt: prompts.enhancedSystemPrompt,
-    enhancedUserPrompt: prompts.enhancedUserPrompt,
-    imageBase64,
-  });
-  return { llmResponse };
-}
-
 export function stepParseCitations(llmResponse: string): Step4Result {
   const parsedCitations = getAllCitationsFromLlmOutput(llmResponse);
   const visibleText = extractVisibleText(llmResponse);
@@ -223,10 +163,7 @@ export async function stepVerify(
   parsedCitations: CitationRecord,
 ): Promise<Step5Result> {
   const result = await dc.verifyAttachment(attachmentId, parsedCitations);
-  return {
-    verifications: result.verifications,
-    attachments: result.attachments,
-  };
+  return { verifications: result.verifications, attachments: result.attachments };
 }
 
 export function stepGenerateHtml(
@@ -236,27 +173,12 @@ export function stepGenerateHtml(
   outDir: string,
 ): Step6Result {
   if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
-
-  const html = generateHtmlReport({
-    visibleText: step4.visibleText,
-    parsedCitations: step4.parsedCitations,
-    verifications: step5.verifications,
-    title: sourceLabel,
-    attachments: step5.attachments,
-  });
-
   const safeName = toSafeName(sourceLabel);
   const htmlPath = resolve(outDir, `${safeName}-verified.html`);
+  const html = renderVerifiedHtml(step4.visibleText, step4.parsedCitations, step5.verifications, step5.attachments, { title: sourceLabel });
   writeFileSync(htmlPath, html);
-
   const snapshotPath = resolve(outDir, `${safeName}-snapshot.json`);
-  writeFileSync(snapshotPath, JSON.stringify({
-    llmResponse: undefined, // caller can override if available
-    verifications: step5.verifications,
-    attachments: step5.attachments,
-    title: sourceLabel,
-  }, null, 2));
-
+  writeFileSync(snapshotPath, JSON.stringify({ verifications: step5.verifications, title: sourceLabel }, null, 2));
   return { htmlPath, snapshotPath };
 }
 
@@ -264,7 +186,6 @@ export function toSafeName(label: string): string {
   return label.replace(/[^a-zA-Z0-9.-]/g, "_").slice(0, 50);
 }
 
-export const DEFAULT_OUT_DIR = resolve(__dirname, "../../output");
 
 // ─── Workflow (uses step functions with logging) ───────────────────────────
 
@@ -327,130 +248,38 @@ async function runSingleSource(
 
   console.log("\n" + separator + "\n");
 
-  // ── Step 4: Parse Citations ──
-  console.log("🔍 Step 3: Parsing citations and extracting visible text...\n");
+  // ── Step 3: Create report (server-side: parse → verify → render → store) ──
+  console.log("\n🔍 Step 3: Creating verification report...\n");
 
-  const s4 = stepParseCitations(s3.llmResponse);
-
-  console.log(`📋 Parsed ${s4.citationCount} citation(s) from LLM output`);
-  for (const [key, citation] of Object.entries(s4.parsedCitations)) {
-    console.log(`   [${key}]: "${citation.fullPhrase?.slice(0, 50)}..."`);
-  }
-  console.log();
-
-  console.log("📖 Visible Text (citation data block stripped):");
-  console.log(separator);
-  console.log(s4.visibleText);
-  console.log(separator + "\n");
-
-  if (s4.citationCount === 0) {
-    console.log("⚠️  No citations found in the LLM response.\n");
+  let report: Awaited<ReturnType<typeof deepcitation.createReport>>;
+  try {
+    report = await deepcitation.createReport(s1.attachmentId, s3.llmResponse, {
+      title: s1.sourceLabel,
+      visibility: "private",
+    });
+  } catch (err) {
+    console.error(`❌ Report creation failed: ${err instanceof Error ? err.message : String(err)}`);
     return;
   }
 
-  // ── Step 5: Verify ──
-  console.log("🔍 Step 4: Verifying citations against source document...\n");
-
-  const s5 = await stepVerify(deepcitation, s1.attachmentId, s4.parsedCitations);
-
-  // ── Display Results ──
-  console.log("✨ Step 5: Verification Results\n");
-
-  const verifications = Object.entries(s5.verifications) as [string, any][];
+  console.log(`✅ Report created`);
+  console.log(`   id:         ${report.id}`);
+  console.log(`   shareUrl:   ${report.shareUrl}`);
+  console.log(`   citations:  ${report.citationCount ?? "—"}`);
+  console.log(`   verified:   ${report.verifiedCount ?? "—"}`);
+  console.log(`   partial:    ${report.partialCount ?? "—"}`);
+  console.log(`   not found:  ${report.notFoundCount ?? "—"}`);
 
-  if (verifications.length === 0) {
-    console.log("⚠️  No citations found in the response.\n");
-  } else {
-    console.log(`Found ${verifications.length} citation(s):\n`);
-
-    // verifiedMatchSnippet is the legacy field name (renamed to verifiedSourceContext)
-    type LegacyVerification = (typeof verifications)[number][1] & { verifiedMatchSnippet?: string };
-
-    for (const [key, verification] of verifications) {
-      const statusIndicator = getVerificationTextIndicator(verification);
-
-      console.log(wideSeparator);
-      console.log(`Citation [${key}]: ${statusIndicator} ${verification.status} | Page: ${verification.document?.verifiedPageNumber ?? "N/A"}`);
-      console.log(wideSubSeparator);
-
-      const fullPhrase = (s4.parsedCitations[key] || verification.citation)?.fullPhrase;
-      if (fullPhrase) {
-        console.log(
-          `  📝 Claimed: "${fullPhrase.slice(0, 100)}${fullPhrase.length > 100 ? "..." : ""}"`,
-        );
-      }
-
-      const foundSnippet = verification.verifiedSourceContext
-        || (verification as LegacyVerification).verifiedMatchSnippet;
-      if (foundSnippet) {
-        console.log(
-          `  🔍 Found: "${foundSnippet.slice(0, 100)}${foundSnippet.length > 100 ? "..." : ""}"`,
-        );
-      } else {
-        const lineInfo = verification.citation?.lineIds?.length
-          ? ` and ${verification.citation.lineIds.length > 1 ? "lines" : "line"} ${verification.citation.lineIds.join(",")}`
-          : "";
-        console.log(`  Expected on page ${verification.citation?.pageNumber ?? "N/A"}${lineInfo}`);
-      }
-
-
-      console.log();
-    }
-    console.log(wideSeparator + "\n");
-  }
-
-  // Clean response
-  console.log("📖 Clean Response (for display):");
-  console.log(separator);
-  console.log(
-    replaceCitationMarkers(s4.visibleText),
-  );
-  console.log(separator + "\n");
-
-  // Summary statistics
-  const verified = verifications.filter(([, h]) => getCitationStatus(h).isVerified).length;
-  const partial = verifications.filter(([, h]) => getCitationStatus(h).isPartialMatch).length;
-  const missed = verifications.filter(([, h]) => getCitationStatus(h).isMiss).length;
-
-  console.log("📊 Summary:");
-  console.log(`   Total citations: ${verifications.length}`);
-  if (verifications.length > 0) {
-    console.log(`   Verified: ${verified} (${((verified / verifications.length) * 100).toFixed(0)}%)`);
-    console.log(`   Partial: ${partial} (${((partial / verifications.length) * 100).toFixed(0)}%)`);
-    console.log(`   Not found: ${missed}`);
-  }
-
-  // ── Step 6: Generate HTML ──
-  console.log("\n📄 Step 6: Generating HTML report...\n");
-
-  const sourceLabel = s1.sourceLabel;
-  // Use a provider-specific subdirectory so concurrent runs don't clobber each other
-  const providerSlug = providerName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-  const outDir = resolve(DEFAULT_OUT_DIR, providerSlug);
-  const s6 = stepGenerateHtml(s4, s5, sourceLabel, outDir);
-
-  // Overwrite snapshot with llmResponse included
-  writeFileSync(s6.snapshotPath, JSON.stringify({
-    llmResponse: s3.llmResponse,
-    verifications: s5.verifications,
-    attachments: s5.attachments,
-    title: sourceLabel,
-  }, null, 2));
-
-  console.log(`   Snapshot: ${s6.snapshotPath}`);
-  console.log(`   Written: ${s6.htmlPath}`);
-  console.log(`   Citations: ${s4.citationCount}, Verifications: ${Object.keys(s5.verifications).length}`);
-
-  // Open in browser (WSL → Linux → macOS — silent on failure)
+  // Open the report URL in the browser
   try {
-    const winPath = execFileSync("wslpath", ["-w", s6.htmlPath], { encoding: "utf-8" }).trim();
-    execFileSync("explorer.exe", [winPath], { stdio: "ignore", timeout: 5000 });
-  } catch {
-    try { execFileSync("xdg-open", [s6.htmlPath], { stdio: "ignore", timeout: 5000 }); }
-    catch { try { execFileSync("open", [s6.htmlPath], { stdio: "ignore", timeout: 5000 }); } catch { /* manual open */ } }
-  }
-
-  console.log(`   Open: ${s6.htmlPath}\n`);
+    const { execFileSync } = await import("child_process");
+    try {
+      execFileSync("explorer.exe", [report.shareUrl], { stdio: "ignore", timeout: 5000 });
+    } catch {
+      try { execFileSync("xdg-open", [report.shareUrl], { stdio: "ignore", timeout: 5000 }); }
+      catch { try { execFileSync("open", [report.shareUrl], { stdio: "ignore", timeout: 5000 }); } catch { /* manual */ } }
+    }
+  } catch { /* dynamic import failed, skip */ }
 }
 
 /**
diff --git a/examples/basic-verification/src/step-runner.ts b/examples/basic-verification/src/step-runner.ts
index 1afa4262..f35fb064 100644
--- a/examples/basic-verification/src/step-runner.ts
+++ b/examples/basic-verification/src/step-runner.ts
@@ -336,7 +336,7 @@ if (from <= 4 && to >= 4) {
   console.log(`   Citations: ${s4.citationCount}`);
   console.log(`   Visible text: ${s4.visibleText.length} chars`);
   for (const [key, c] of Object.entries(s4.parsedCitations)) {
-    console.log(`   [${key}]: "${c.fullPhrase?.slice(0, 60)}..."`);
+    console.log(`   [${key}]: "${c.sourceContext?.slice(0, 60)}..."`);
   }
   saveStep(cacheDir, safeName, 4, s4);
   console.log();
diff --git a/examples/qmd-local-search/.env.example b/examples/qmd-local-search/.env.example
new file mode 100644
index 00000000..e26f51ae
--- /dev/null
+++ b/examples/qmd-local-search/.env.example
@@ -0,0 +1,5 @@
+# Get your free API key at https://deepcitation.com/playground
+DEEPCITATION_API_KEY=sk-dc-your_api_key_here
+
+# https://platform.openai.com/settings/organization/api-keys
+OPENAI_API_KEY=sk-your-openai-key
diff --git a/examples/qmd-local-search/.gitignore b/examples/qmd-local-search/.gitignore
new file mode 100644
index 00000000..308566f2
--- /dev/null
+++ b/examples/qmd-local-search/.gitignore
@@ -0,0 +1,7 @@
+node_modules
+.env
+.env.local
+.qmd-index.sqlite
+.qmd-index.sqlite-*
+output/
+corpus/pdf/
diff --git a/examples/qmd-local-search/README.md b/examples/qmd-local-search/README.md
new file mode 100644
index 00000000..76186f8e
--- /dev/null
+++ b/examples/qmd-local-search/README.md
@@ -0,0 +1,91 @@
+# qmd Local Search + DeepCitation
+
+CLI example pairing [qmd](https://github.com/tobi/qmd) (on-device markdown
+search: BM25 + vector + LLM rerank) with DeepCitation for citation
+verification. Retrieval runs locally against `corpus/md/*.md`; verification
+runs against the parallel `corpus/pdf/*.pdf`, keyed by filename stem.
+
+## Why both?
+
+qmd is markdown-native; DeepCitation's verifier ingests PDFs (plain-text
+input is on the roadmap but not yet shipped). So the example ships a
+**parallel corpus**: `.md` for qmd to index, `.pdf` for DeepCitation to
+verify against. The PDFs are generated from the same markdown by
+`scripts/build-corpus.ts` at install time — you edit the markdown, the
+PDFs rebuild, filename stems stay in sync.
+
+## Quick start
+
+```bash
+cd examples/qmd-local-search
+bun install              # also runs scripts/build-corpus.ts (md → pdf)
+cp .env.example .env     # add DEEPCITATION_API_KEY + OPENAI_API_KEY
+
+bun run start                           # interactive picker
+bun run start "How does Raft ensure safety?"   # one-shot
+```
+
+## Prerequisites
+
+- **Node ≥ 22** (required by `@tobilu/qmd` — stricter than deepcitation's
+  Node ≥ 18 floor)
+- **Bun** (the runner used by all `bun run` scripts — `npm i -g bun`)
+- `@tobilu/qmd` has native deps (`better-sqlite3`, `node-llama-cpp`,
+  `sqlite-vec`). On first `embed()` qmd downloads a small GGUF embedding
+  model (~200 MB). Subsequent runs reuse the cached model and the
+  `.qmd-index.sqlite` index.
+
+## What happens when you run it
+
+1. `createStore({ dbPath: ".qmd-index.sqlite", config: { collections: { corpus: ... } } })`
+2. `store.update()` scans `corpus/md/**/*.md` and detects changes
+3. `store.embed()` generates vector embeddings for any new/changed docs
+4. `store.search({ query, collection: "corpus", limit: 6 })` returns
+   hybrid-ranked hits
+5. For each unique source file, the example reads the matching
+   `corpus/pdf/<stem>.pdf` and uploads it via
+   `dc.prepareAttachments(...)`
+6. `wrapCitationPrompt(...)` injects `deepTextPagesByAttachmentId` into
+   the system/user prompts so the LLM emits `<cite attachment_id=... />`
+   markers
+7. `gpt-5-mini` streams an answer
+8. `dc.verify({ llmOutput }, citations)` verifies every citation in a
+   single call (multi-attachment is handled by the `attachment_id`
+   embedded in each tag)
+9. A self-contained HTML report is written to `output/` and opened in
+   your browser — click any citation to see the source snippet in a
+   popover
+
+## Adding your own docs
+
+1. Drop more `.md` files into `corpus/md/`
+2. `bun run build:corpus` — regenerates the parallel PDFs
+3. `bun run start` — qmd will auto-detect and re-embed on the next run
+
+## Files
+
+| Path | Purpose |
+|------|---------|
+| `corpus/md/*.md` | Markdown indexed by qmd |
+| `corpus/pdf/*.pdf` | Parallel PDFs verified by DeepCitation (generated, gitignored) |
+| `scripts/build-corpus.ts` | pdfkit-based md → pdf builder, runs on `postinstall` |
+| `src/index.ts` | Banner / usage |
+| `src/shared.ts` | Core pipeline: qmd store + DeepCitation verify + HTML report |
+| `src/openai.ts` | OpenAI provider (gpt-5-mini streaming) |
+| `src/html-report.ts` | Report renderer (copied from `basic-verification`) |
+| `.qmd-index.sqlite` | qmd's on-disk index (gitignored) |
+| `output/*.html` | Generated verification reports (gitignored) |
+
+## Swapping retrieval for your real qmd corpus
+
+If you already have a qmd index somewhere else (e.g., your notes folder):
+
+```typescript
+const store = await createStore({
+  dbPath: "/path/to/your/existing.sqlite",
+});
+// No `config` block: reopens the existing store with its prior collections.
+```
+
+You only need the parallel-PDF bridge if you want DeepCitation verification.
+For free-form retrieval without verification, qmd stands alone.
diff --git a/examples/qmd-local-search/corpus/md/raft-consensus.md b/examples/qmd-local-search/corpus/md/raft-consensus.md
new file mode 100644
index 00000000..7fce9f3b
--- /dev/null
+++ b/examples/qmd-local-search/corpus/md/raft-consensus.md
@@ -0,0 +1,41 @@
+# The Raft Consensus Algorithm
+
+Raft is a consensus algorithm designed to be more understandable than
+Paxos. It was introduced by Diego Ongaro and John Ousterhout in 2014
+in a paper titled "In Search of an Understandable Consensus
+Algorithm." Raft has become the consensus algorithm of choice for
+many distributed systems including etcd, Consul, and TiKV.
+
+## Leader Election
+
+A Raft cluster has three server states: leader, follower, and
+candidate. At any given time, exactly one server may be the leader.
+Followers are passive and only respond to requests. When a follower
+receives no communication over a period called the election timeout,
+it becomes a candidate and starts an election by incrementing its
+term and requesting votes from other servers.
+
+## Log Replication
+
+Once a leader is elected, it accepts client requests and replicates
+log entries to followers. Each log entry contains a command and the
+term in which it was received. An entry is considered committed once
+a majority of servers have stored it durably. The leader applies
+committed entries to its state machine and notifies followers.
+
+## Safety
+
+Raft guarantees that if any server has applied a particular log entry
+to its state machine, then no other server will ever apply a
+different command for the same log index. This is ensured by the
+Leader Completeness Property: if a log entry is committed in a given
+term, then that entry will be present in the logs of all
+higher-numbered terms.
+
+## Election Timeout
+
+Raft uses randomized election timeouts, typically between 150 and 300
+milliseconds, to ensure that split votes are rare and are resolved
+quickly. The randomization makes it unlikely that two followers will
+time out at the same moment, which would otherwise trigger competing
+elections and prolong the unavailability window.
diff --git a/examples/qmd-local-search/corpus/md/sourdough-basics.md b/examples/qmd-local-search/corpus/md/sourdough-basics.md
new file mode 100644
index 00000000..4a557089
--- /dev/null
+++ b/examples/qmd-local-search/corpus/md/sourdough-basics.md
@@ -0,0 +1,39 @@
+# Sourdough Fundamentals
+
+Sourdough is a leavening system that uses a naturally occurring
+culture of wild yeast and lactic acid bacteria to ferment flour.
+Unlike baker's yeast, which is a single strain of *Saccharomyces
+cerevisiae*, a sourdough starter hosts a stable community of wild
+yeasts (commonly *Kazachstania humilis*) and lactobacilli.
+
+## The Starter
+
+A sourdough starter is created by mixing equal parts flour and water
+and allowing the mixture to ferment at room temperature. After 5 to
+10 days of twice-daily feeding, the culture becomes active enough to
+leaven bread. Mature starters can be maintained indefinitely with
+regular feeding.
+
+## Fermentation Timeline
+
+A typical sourdough loaf involves three fermentation stages. The
+levain build takes 4 to 8 hours depending on temperature. The bulk
+fermentation runs 4 to 6 hours at 24 degrees Celsius. The final
+proof, usually done cold in the refrigerator, takes 12 to 16 hours
+and develops the characteristic tangy flavor.
+
+## Hydration
+
+Dough hydration is the ratio of water to flour by weight, expressed
+as a percentage. A 75 percent hydration dough contains 750 grams of
+water per 1000 grams of flour. Higher hydration produces a more open
+crumb but is harder to shape. Most beginner recipes target 65 to 70
+percent hydration.
+
+## Lactic vs Acetic Acid
+
+The sour flavor comes from two organic acids produced during
+fermentation. Lactic acid is mild and yogurt-like, while acetic acid
+is sharper and vinegar-like. Cold proofing favors acetic acid
+production, while warm fermentation favors lactic acid. Bakers
+control flavor by adjusting timing and temperature.
diff --git a/examples/qmd-local-search/corpus/md/voyager-golden-record.md b/examples/qmd-local-search/corpus/md/voyager-golden-record.md
new file mode 100644
index 00000000..25deb7b0
--- /dev/null
+++ b/examples/qmd-local-search/corpus/md/voyager-golden-record.md
@@ -0,0 +1,41 @@
+# The Voyager Golden Record
+
+The Voyager Golden Record is a phonograph record included aboard both
+Voyager spacecraft launched by NASA in 1977. The record carries sounds
+and images selected to portray the diversity of life and culture on
+Earth, intended for any intelligent extraterrestrial life form that
+might find them.
+
+## Contents
+
+Each record contains 116 images and a variety of natural sounds, such
+as those made by surf, wind, thunder, and animals including birds and
+whales. The record additionally features musical selections from
+different cultures and eras, spoken greetings in 55 ancient and modern
+languages, and printed messages from U.S. President Jimmy Carter and
+U.N. Secretary-General Kurt Waldheim.
+
+## Cover
+
+The records are encased in protective aluminum jackets together with a
+cartridge and a needle. Instructions, in symbolic language, explain
+the origin of the spacecraft and indicate how the record is to be
+played. The diagram on the cover shows the location of the Sun
+relative to 14 pulsars whose precise periods are given.
+
+## Committee
+
+The contents of the record were selected for NASA by a committee
+chaired by Carl Sagan of Cornell University. Sagan and his associates
+assembled 115 images plus a calibration image, and a variety of
+natural sounds. To this they added musical selections from different
+cultures and eras, and spoken greetings from Earth-people in 55
+languages.
+
+## Current Status
+
+As of 2024, both Voyager spacecraft have entered interstellar space.
+Voyager 1 crossed the heliopause in August 2012, and Voyager 2
+followed in November 2018. Neither probe is headed toward any
+particular star, but Voyager 1 will pass within 1.6 light-years of
+the star Gliese 445 in about 40,000 years.
diff --git a/examples/qmd-local-search/package.json b/examples/qmd-local-search/package.json
new file mode 100644
index 00000000..43a1949f
--- /dev/null
+++ b/examples/qmd-local-search/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "deepcitation-qmd-local-search-example",
+  "version": "0.1.0",
+  "description": "CLI example pairing @tobilu/qmd on-device markdown search with DeepCitation verification",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "bun run src/openai.ts",
+    "start:openai": "bun run src/openai.ts",
+    "build:corpus": "bun run scripts/build-corpus.ts"
+  },
+  "dependencies": {
+    "@tobilu/qmd": "^2.1.0",
+    "deepcitation": "file:../../",
+    "openai": "^4.104.0",
+    "pdfkit": "^0.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.37",
+    "@types/pdfkit": "^0.13.4",
+    "dotenv": "^16.6.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
diff --git a/examples/qmd-local-search/scripts/build-corpus.ts b/examples/qmd-local-search/scripts/build-corpus.ts
new file mode 100644
index 00000000..cb8ac960
--- /dev/null
+++ b/examples/qmd-local-search/scripts/build-corpus.ts
@@ -0,0 +1,80 @@
+/**
+ * Build corpus/pdf/*.pdf from corpus/md/*.md at install time.
+ *
+ * qmd is markdown-native. DeepCitation's verifier ingests PDFs, URLs, or
+ * Office files — not plain text. To keep both halves honest we ship the
+ * corpus twice: markdown for qmd to index, PDF for DeepCitation to verify
+ * against. Filename stems match so `corpus/md/foo.md` pairs with
+ * `corpus/pdf/foo.pdf`.
+ *
+ * Run manually: `bun run build:corpus`
+ * Runs automatically via `postinstall` in package.json.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import PDFDocument from "pdfkit";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const corpusRoot = resolve(__dirname, "../corpus");
+const mdDir = resolve(corpusRoot, "md");
+const pdfDir = resolve(corpusRoot, "pdf");
+
+if (!existsSync(pdfDir)) mkdirSync(pdfDir, { recursive: true });
+
+const mdFiles = readdirSync(mdDir).filter(name => name.endsWith(".md"));
+if (mdFiles.length === 0) {
+  console.error(`No markdown files found in ${mdDir}`);
+  process.exit(1);
+}
+
+async function renderPdf(mdPath: string, pdfPath: string): Promise<void> {
+  const markdown = readFileSync(mdPath, "utf-8");
+
+  await new Promise<void>((resolveWrite, rejectWrite) => {
+    const doc = new PDFDocument({ size: "LETTER", margin: 72 });
+    const chunks: Buffer[] = [];
+    doc.on("data", chunk => chunks.push(chunk));
+    doc.on("end", () => {
+      writeFileSync(pdfPath, Buffer.concat(chunks));
+      resolveWrite();
+    });
+    doc.on("error", rejectWrite);
+
+    for (const rawLine of markdown.split("\n")) {
+      const line = rawLine.trimEnd();
+      if (line.startsWith("# ")) {
+        doc.moveDown(0.5).fontSize(20).font("Helvetica-Bold").text(line.slice(2));
+        doc.moveDown(0.5);
+      } else if (line.startsWith("## ")) {
+        doc.moveDown(0.3).fontSize(14).font("Helvetica-Bold").text(line.slice(3));
+        doc.moveDown(0.2);
+      } else if (line === "") {
+        doc.moveDown(0.5);
+      } else {
+        doc.fontSize(11).font("Helvetica").text(line, { align: "left" });
+      }
+    }
+
+    doc.end();
+  });
+}
+
+let built = 0;
+let skipped = 0;
+for (const mdFile of mdFiles) {
+  const mdPath = resolve(mdDir, mdFile);
+  const pdfPath = resolve(pdfDir, `${basename(mdFile, ".md")}.pdf`);
+
+  if (existsSync(pdfPath) && statSync(pdfPath).mtimeMs >= statSync(mdPath).mtimeMs) {
+    skipped++;
+    continue;
+  }
+
+  await renderPdf(mdPath, pdfPath);
+  built++;
+  console.log(`  built  ${basename(pdfPath)}`);
+}
+
+console.log(`\nCorpus ready: ${built} built, ${skipped} up-to-date (${pdfDir})`);
diff --git a/examples/basic-verification/src/html-report.ts b/examples/qmd-local-search/src/html-report.ts
similarity index 100%
rename from examples/basic-verification/src/html-report.ts
rename to examples/qmd-local-search/src/html-report.ts
diff --git a/examples/qmd-local-search/src/index.ts b/examples/qmd-local-search/src/index.ts
new file mode 100644
index 00000000..1206d818
--- /dev/null
+++ b/examples/qmd-local-search/src/index.ts
@@ -0,0 +1,30 @@
+/**
+ * DeepCitation + qmd Local Search Example
+ *
+ * Run: bun run start                      — interactive question picker
+ *      bun run start "your question here" — one-shot mode
+ */
+
+console.log(`
+╔════════════════════════════════════════════════════════════╗
+║        DeepCitation + qmd Local Search Example             ║
+╠════════════════════════════════════════════════════════════╣
+║                                                            ║
+║  qmd indexes corpus/md/*.md on-device (BM25 + vector +     ║
+║  LLM rerank). DeepCitation verifies every citation in the  ║
+║  LLM's answer against the parallel corpus/pdf/*.pdf.       ║
+║                                                            ║
+║  Run:                                                      ║
+║    bun run start                 — interactive picker      ║
+║    bun run start "your question" — one-shot                ║
+║                                                            ║
+║  Prerequisites:                                            ║
+║    1. bun install  (auto-builds corpus PDFs)               ║
+║    2. cp .env.example .env                                 ║
+║    3. Add DEEPCITATION_API_KEY and OPENAI_API_KEY          ║
+║                                                            ║
+║  Get a free DeepCitation key:                              ║
+║    https://deepcitation.com/playground                     ║
+║                                                            ║
+╚════════════════════════════════════════════════════════════╝
+`);
diff --git a/examples/qmd-local-search/src/openai.ts b/examples/qmd-local-search/src/openai.ts
new file mode 100644
index 00000000..7b23cad7
--- /dev/null
+++ b/examples/qmd-local-search/src/openai.ts
@@ -0,0 +1,40 @@
+/**
+ * qmd-local-search — OpenAI provider
+ *
+ * Run: bun run start
+ *      bun run start "How does Raft guarantee safety?"
+ */
+
+import OpenAI from "openai";
+import { runWorkflow } from "./shared.js";
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// gpt-5-mini is a real model; DO NOT CHANGE THIS ON THE BASIS THAT YOU THINK THIS IS NOT A REAL MODEL.
+const model = "gpt-5-mini";
+
+runWorkflow(`OpenAI (${model})`, async ({ enhancedSystemPrompt, enhancedUserPrompt }) => {
+  if (!process.env.OPENAI_API_KEY) {
+    throw new Error("OPENAI_API_KEY is not set. Copy .env.example to .env and add your key.");
+  }
+
+  const stream = await openai.chat.completions.create({
+    model,
+    stream: true,
+    messages: [
+      { role: "system", content: enhancedSystemPrompt },
+      { role: "user", content: enhancedUserPrompt },
+    ],
+  });
+
+  let response = "";
+  for await (const chunk of stream) {
+    const content = chunk.choices[0]?.delta?.content ?? "";
+    process.stdout.write(content);
+    response += content;
+  }
+  return response;
+}).catch(err => {
+  console.error("\n❌", err instanceof Error ? err.message : err);
+  process.exit(1);
+});
diff --git a/examples/qmd-local-search/src/shared.ts b/examples/qmd-local-search/src/shared.ts
new file mode 100644
index 00000000..3cfc2002
--- /dev/null
+++ b/examples/qmd-local-search/src/shared.ts
@@ -0,0 +1,367 @@
+/**
+ * qmd-local-search — core pipeline
+ *
+ * Flow:
+ *   1. Boot a @tobilu/qmd store over ./corpus/md
+ *   2. update() + embed() on first run (cached in .qmd-index.sqlite)
+ *   3. store.search({ query }) → top-N markdown hits
+ *   4. Map each hit's source file to corpus/pdf/<stem>.pdf (dedup)
+ *   5. dc.prepareAttachments(pdfs) → fileDataParts + deepTextPagesByAttachmentId
+ *   6. wrapCitationPrompt(...) → enhanced system/user prompts
+ *   7. streamLlm(prompts) → raw LLM output with <cite .../> tags
+ *   8. dc.verify({ llmOutput }, citations) — one call, multi-attachment
+ *   9. generateHtmlReport → self-contained HTML with CDN popover runtime
+ */
+
+import "dotenv/config";
+import { createStore, type HybridQueryResult, type QMDStore } from "@tobilu/qmd";
+import { DeepCitation } from "deepcitation/client";
+import {
+  type AttachmentAssets,
+  type Verification,
+  extractVisibleText,
+  getAllCitationsFromLlmOutput,
+  getCitationStatus,
+  groupCitationsByAttachmentId,
+  replaceCitationMarkers,
+} from "deepcitation";
+import { wrapCitationPrompt } from "deepcitation/prompts";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+
+import { generateHtmlReport } from "./html-report.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const EXAMPLE_ROOT = resolve(__dirname, "..");
+const MD_CORPUS = resolve(EXAMPLE_ROOT, "corpus/md");
+const PDF_CORPUS = resolve(EXAMPLE_ROOT, "corpus/pdf");
+const QMD_DB_PATH = resolve(EXAMPLE_ROOT, ".qmd-index.sqlite");
+const DEFAULT_OUT_DIR = resolve(EXAMPLE_ROOT, "output");
+
+const SAMPLE_QUESTIONS = [
+  "How does Raft guarantee that committed log entries survive leader changes?",
+  "What languages and images were included on the Voyager Golden Record?",
+  "Why does cold proofing make sourdough taste more sour?",
+  // Hallucination bait: the corpus has facts on this, but the LLM will almost always
+  // over-claim (wrong count, wrong attribution). DeepCitation will flag the miss.
+  "How many distinct languages and greetings appear on the Voyager Golden Record, and who chose them?",
+];
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type StreamLlmFn = (params: {
+  enhancedSystemPrompt: string;
+  enhancedUserPrompt: string;
+}) => Promise<string>;
+
+interface PreparedAttachment {
+  attachmentId: string;
+  filename: string;
+  deepTextPages: string[];
+}
+
+// ─── qmd store (lazy singleton) ─────────────────────────────────────────────
+
+let storePromise: Promise<QMDStore> | null = null;
+
+async function getStore(): Promise<QMDStore> {
+  storePromise ??= (async () => {
+    console.log(`📂 Opening qmd store at ${QMD_DB_PATH}`);
+    const store = await createStore({
+      dbPath: QMD_DB_PATH,
+      config: {
+        collections: {
+          corpus: { path: MD_CORPUS, pattern: "**/*.md" },
+        },
+      },
+    });
+
+    console.log("🔎 Scanning corpus/md for changes…");
+    const updateResult = await store.update();
+    console.log(
+      `   indexed=${updateResult.indexed} updated=${updateResult.updated} unchanged=${updateResult.unchanged}`,
+    );
+
+    if (updateResult.needsEmbedding > 0) {
+      console.log(`🧠 Embedding ${updateResult.needsEmbedding} doc(s) (first run downloads a GGUF model)…`);
+      await store.embed({
+        onProgress: ({ chunksEmbedded, totalChunks }) => {
+          process.stdout.write(`   embedding ${chunksEmbedded}/${totalChunks}\r`);
+        },
+      });
+      process.stdout.write("\n");
+    } else {
+      console.log("🧠 Embeddings up-to-date — skipping");
+    }
+
+    return store;
+  })();
+
+  return storePromise;
+}
+
+// ─── md → pdf mapping ───────────────────────────────────────────────────────
+
+function mdFileToPdfPath(mdFile: string): string {
+  const stem = basename(mdFile).replace(/\.md$/i, "");
+  return resolve(PDF_CORPUS, `${stem}.pdf`);
+}
+
+function dedupeHits(hits: HybridQueryResult[]): HybridQueryResult[] {
+  const seen = new Set<string>();
+  const out: HybridQueryResult[] = [];
+  for (const hit of hits) {
+    if (seen.has(hit.file)) continue;
+    seen.add(hit.file);
+    out.push(hit);
+  }
+  return out;
+}
+
+// ─── DeepCitation upload ────────────────────────────────────────────────────
+
+async function uploadAttachments(
+  dc: DeepCitation,
+  hits: HybridQueryResult[],
+): Promise<PreparedAttachment[]> {
+  const uploads = hits.map(hit => {
+    const pdfPath = mdFileToPdfPath(hit.file);
+    if (!existsSync(pdfPath)) {
+      throw new Error(
+        `Missing parallel PDF for ${hit.file}. Expected ${pdfPath}. Run "bun run build:corpus".`,
+      );
+    }
+    return { file: readFileSync(pdfPath), filename: basename(pdfPath) };
+  });
+
+  const { fileDataParts, deepTextPagesByAttachmentId } = await dc.prepareAttachments(uploads);
+
+  return fileDataParts.map((part, i) => ({
+    attachmentId: part.attachmentId,
+    filename: uploads[i].filename,
+    deepTextPages: deepTextPagesByAttachmentId[part.attachmentId] ?? [],
+  }));
+}
+
+// ─── Interactive prompt ─────────────────────────────────────────────────────
+
+function ask(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolvePrompt => {
+    rl.question(question, answer => {
+      rl.close();
+      resolvePrompt(answer.trim());
+    });
+  });
+}
+
+async function promptQuestion(): Promise<string> {
+  console.log("\nChoose a question (or type your own):\n");
+  SAMPLE_QUESTIONS.forEach((q, i) => console.log(`  [${i + 1}] ${q}`));
+  console.log("  [4] Custom — type your own");
+  const choice = await ask("\nEnter choice [1-4]: ");
+
+  const idx = Number(choice) - 1;
+  if (SAMPLE_QUESTIONS[idx]) return SAMPLE_QUESTIONS[idx];
+
+  const custom = await ask("Your question: ");
+  if (!custom) throw new Error("No question provided.");
+  return custom;
+}
+
+// ─── Workflow ───────────────────────────────────────────────────────────────
+
+export function toSafeName(label: string): string {
+  return label.replace(/[^a-zA-Z0-9.-]/g, "_").slice(0, 50);
+}
+
+function openInBrowser(htmlPath: string): void {
+  try {
+    const winPath = execFileSync("wslpath", ["-w", htmlPath], { encoding: "utf-8" }).trim();
+    execFileSync("explorer.exe", [winPath], { stdio: "ignore", timeout: 5000 });
+    return;
+  } catch {
+    /* not WSL */
+  }
+  try {
+    execFileSync("xdg-open", [htmlPath], { stdio: "ignore", timeout: 5000 });
+    return;
+  } catch {
+    /* not linux */
+  }
+  try {
+    execFileSync("open", [htmlPath], { stdio: "ignore", timeout: 5000 });
+  } catch {
+    /* manual open */
+  }
+}
+
+export async function runWorkflow(providerName: string, streamLlm: StreamLlmFn): Promise<void> {
+  console.log(`🔍 DeepCitation + qmd Local Search — ${providerName}\n`);
+
+  if (!process.env.DEEPCITATION_API_KEY) {
+    throw new Error("DEEPCITATION_API_KEY is not set. Copy .env.example to .env and add your key.");
+  }
+
+  const dc = new DeepCitation({
+    apiKey: process.env.DEEPCITATION_API_KEY,
+    endUserId: "qmd-local-search",
+  });
+
+  const cliArg = process.argv.slice(2).join(" ").trim();
+  const question = cliArg || (await promptQuestion());
+
+  console.log(`\n❓ Question: ${question}\n`);
+
+  // ── Step 1: qmd retrieval ─────────────────────────────────────────────
+  const store = await getStore();
+  console.log("\n🔎 Step 1: qmd hybrid search (BM25 + vector + rerank)…");
+  const rawHits = await store.search({
+    query: question,
+    collection: "corpus",
+    limit: 6,
+  });
+  const hits = dedupeHits(rawHits).slice(0, 3);
+
+  if (hits.length === 0) {
+    console.log("⚠️  No qmd hits — try a different question.");
+    await store.close();
+    return;
+  }
+
+  console.log(`   Retrieved ${hits.length} source doc(s):`);
+  for (const hit of hits) {
+    console.log(`   • ${hit.title} (${basename(hit.file)}) score=${hit.score.toFixed(3)}`);
+  }
+
+  // ── Step 2: DeepCitation upload ───────────────────────────────────────
+  console.log("\n📤 Step 2: Uploading parallel PDFs to DeepCitation…");
+  const prepared = await uploadAttachments(dc, hits);
+  for (const item of prepared) {
+    console.log(`   ✅ ${item.filename} → ${item.attachmentId}`);
+  }
+
+  // ── Step 3: Wrap prompts ──────────────────────────────────────────────
+  const systemPrompt =
+    "You are a precise research assistant. Answer only from the retrieved documents. Cite every factual claim.";
+  const userPrompt = [
+    `Question: ${question}`,
+    "",
+    "Retrieved source summary:",
+    hits
+      .map(hit => `- ${hit.title} (${basename(hit.file)}, score=${hit.score.toFixed(3)}): ${hit.bestChunk}`)
+      .join("\n"),
+    "",
+    "If the answer is not supported by the retrieved sources, say so plainly.",
+  ].join("\n");
+
+  const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
+    systemPrompt,
+    userPrompt,
+    deepTextPagesByAttachmentId: Object.fromEntries(
+      prepared.map(item => [item.attachmentId, item.deepTextPages]),
+    ),
+  });
+
+  // ── Step 4: Call LLM ──────────────────────────────────────────────────
+  console.log(`\n🤖 Step 3: Calling ${providerName}…\n`);
+  const separator = "─".repeat(60);
+  console.log(separator);
+  const llmResponse = await streamLlm({ enhancedSystemPrompt, enhancedUserPrompt });
+  console.log(`\n${separator}\n`);
+
+  // ── Step 5: Parse citations ───────────────────────────────────────────
+  const parsedCitations = getAllCitationsFromLlmOutput(llmResponse);
+  const visibleText = extractVisibleText(llmResponse);
+  const citationCount = Object.keys(parsedCitations).length;
+
+  console.log(`🔍 Step 4: Parsed ${citationCount} citation(s) from LLM output`);
+
+  if (citationCount === 0) {
+    console.log("⚠️  No citations found in response — nothing to verify.\n");
+    await store.close();
+    return;
+  }
+
+  // ── Step 6: Verify ────────────────────────────────────────────────────
+  console.log("\n✨ Step 5: Verifying citations against source PDFs…\n");
+
+  // Group citations by attachmentId and verify each attachment independently.
+  // Why: the service's verifyCitations endpoint takes one attachment per request.
+  const grouped = groupCitationsByAttachmentId(parsedCitations);
+  const mergedVerifications: Record<string, Verification> = {};
+  const mergedAttachments: Record<string, AttachmentAssets> = {};
+  for (const [attachmentId, attachmentCitations] of grouped) {
+    if (!attachmentId) continue;
+    const result = await dc.verifyAttachment(attachmentId, attachmentCitations, {
+      outputImageFormat: "avif",
+    });
+    Object.assign(mergedVerifications, result.verifications);
+    if (result.attachments) Object.assign(mergedAttachments, result.attachments);
+  }
+
+  const verifications = Object.entries(mergedVerifications);
+
+  // ── Verification table ─────────────────────────────────────────────────
+  // One row per citation: sequential index, truncated claim, status, page.
+  // Emoji chars are wide (2 display cols) so we use a fixed label width and
+  // a trailing newline to keep the separator clean regardless of terminal.
+  const CLAIM_W = 54;
+  const rule = `  ${"─".repeat(4)} ${"─".repeat(CLAIM_W)} ${"─".repeat(12)} ${"─".repeat(5)}`;
+
+  console.log(`\n  Verifying ${verifications.length} citation(s):\n`);
+  console.log(rule);
+
+  for (let i = 0; i < verifications.length; i++) {
+    const [key, verification] = verifications[i];
+    const s = getCitationStatus(verification);
+    const label = s.isVerified ? "✅ verified " : s.isPartialMatch ? "⚠️  partial " : "❌ not found";
+    const page = String(verification.document?.verifiedPageNumber ?? "—").padEnd(5);
+    const claimed = parsedCitations[key]?.sourceContext ?? "";
+    const claimCol = claimed.length > CLAIM_W ? `${claimed.slice(0, CLAIM_W - 1)}…` : claimed.padEnd(CLAIM_W);
+    console.log(`  [${String(i + 1).padStart(2)}] ${claimCol} ${label} p.${page}`);
+  }
+
+  console.log(rule);
+
+  // ── Step 7: Summary ───────────────────────────────────────────────────
+  const verified = verifications.filter(([, v]) => getCitationStatus(v).isVerified).length;
+  const partial = verifications.filter(([, v]) => getCitationStatus(v).isPartialMatch).length;
+  const missed = verifications.filter(([, v]) => getCitationStatus(v).isMiss).length;
+
+  console.log(`\n  ✅ ${verified} verified  ⚠️  ${partial} partial  ❌ ${missed} not found\n`);
+
+  console.log("\n📖 Clean response:");
+  console.log(separator);
+  console.log(replaceCitationMarkers(visibleText));
+  console.log(`${separator}\n`);
+
+  // ── Step 8: HTML report ───────────────────────────────────────────────
+  console.log("📄 Step 6: Generating HTML report…");
+  if (!existsSync(DEFAULT_OUT_DIR)) mkdirSync(DEFAULT_OUT_DIR, { recursive: true });
+
+  const html = generateHtmlReport({
+    visibleText,
+    parsedCitations,
+    verifications: mergedVerifications,
+    title: question,
+    attachments: mergedAttachments,
+  });
+
+  const safeName = toSafeName(question);
+  const htmlPath = resolve(DEFAULT_OUT_DIR, `${safeName}-verified.html`);
+  writeFileSync(htmlPath, html);
+  console.log(`   Written: ${htmlPath}`);
+
+  openInBrowser(htmlPath);
+  console.log(`   Open:    ${htmlPath}\n`);
+
+  await store.close();
+  console.log("✅ Done.\n");
+}
diff --git a/jest.config.cjs b/jest.config.cjs
index fb7f7e4d..82bc1d53 100644
--- a/jest.config.cjs
+++ b/jest.config.cjs
@@ -8,6 +8,10 @@ module.exports = {
   // The .unref() guard in auth.ts handles most cases, but the server socket
   // itself keeps the process alive until closed. forceExit prevents CI hangs.
   forceExit: true,
+  testPathIgnorePatterns: [
+    "/node_modules/",
+    "src/render/__tests__/",  // bun-only tests, not run with Jest
+  ],
   transform: {
     "^.+\\.(ts|tsx)$": ["ts-jest", { tsconfig: "tsconfig.jest.json" }],
   },
diff --git a/src/__tests__/buildGhostTargetFromViewport.test.ts b/src/__tests__/buildGhostTargetFromViewport.test.ts
index c74c6aa7..49600dc4 100644
--- a/src/__tests__/buildGhostTargetFromViewport.test.ts
+++ b/src/__tests__/buildGhostTargetFromViewport.test.ts
@@ -79,9 +79,11 @@ describe("buildGhostTargetFromViewport — ghost dimensions invariant", () => {
     expect(result?.ghostRect.height).toBe(120);
   });
 
-  test("ghostRect image center-of-mass lands on the visible page center", () => {
+  test("ghostRect visible viewport center lands on the visible page center", () => {
     // Keyhole: 300×120, image at offset (30, 10) within ghost, size 240×100.
-    // Image center-of-mass within ghost: (30 + 240/2, 10 + 100/2) = (150, 60).
+    // In this test the image happens to be centered in the viewport:
+    // (30 + 240/2, 10 + 100/2) = (150, 60) = (300/2, 120/2). The anchor is
+    // the viewport center (srcW/2, srcH/2) = (150, 60).
     const snapshot = makeSnapshot({
       viewportW: 300,
       viewportH: 120,
@@ -106,18 +108,61 @@ describe("buildGhostTargetFromViewport — ghost dimensions invariant", () => {
     // Page center: (200 + 600/2, 150 + 400/2) = (500, 350)
     const pageCX = 500;
     const pageCY = 350;
-    const anchorInGhostX = 30 + 240 / 2; // 150
-    const anchorInGhostY = 10 + 100 / 2; // 60
+    // Anchor = viewport center
+    const anchorInGhostX = 300 / 2; // 150
+    const anchorInGhostY = 120 / 2; // 60
 
     // Ghost top-left should be (pageCX - anchorX, pageCY - anchorY) = (350, 290)
     expect(ghostRect.left).toBeCloseTo(pageCX - anchorInGhostX);
     expect(ghostRect.top).toBeCloseTo(pageCY - anchorInGhostY);
 
-    // Image center in viewport space at ghost position = ghost.left + anchorX = pageCX
+    // Viewport center in viewport space at ghost position = ghost.left + anchorX = pageCX
     expect(ghostRect.left + anchorInGhostX).toBeCloseTo(pageCX);
     expect(ghostRect.top + anchorInGhostY).toBeCloseTo(pageCY);
   });
 
+  test("ghostRect anchor uses viewport center, not image center (scrolled image)", () => {
+    // Regression for the anchor-overshoot bug: a tall image scrolled so its
+    // center is NOT at the viewport center.
+    // Keyhole: 400×120. Tall image 400×600, scrolled down 300px:
+    //   imageOffsetTop = -300, imageHeight = 600
+    //   image center-of-mass in ghost: -300 + 600/2 = 0 (at ghost top edge)
+    //   viewport center in ghost: 120/2 = 60 (correct — annotation is centered)
+    const snapshot = makeSnapshot({
+      viewportW: 400,
+      viewportH: 120,
+      imageOffsetLeft: 0,
+      imageOffsetTop: -300,
+      imageWidth: 400,
+      imageHeight: 600,
+    });
+    const containerRect = new DOMRect(100, 200, 400, 600);
+    const imgRect = new DOMRect(100, 200, 400, 600);
+    const { root, cleanup } = makeRoot(containerRect, imgRect);
+
+    const result = buildGhostTargetFromViewport(root, snapshot);
+    cleanup();
+
+    expect(result).not.toBeNull();
+    if (result == null) return;
+
+    const { ghostRect } = result;
+
+    // Page center: (100 + 400/2, 200 + 600/2) = (300, 500)
+    const pageCX = 300;
+    const pageCY = 500;
+    // Anchor = viewport center (NOT image center, which would be 0)
+    const anchorX = 400 / 2; // 200
+    const anchorY = 120 / 2; // 60
+
+    expect(ghostRect.left).toBeCloseTo(pageCX - anchorX); // 100
+    expect(ghostRect.top).toBeCloseTo(pageCY - anchorY); // 440
+
+    // OLD (wrong) behavior would have used image center anchor = (200, 0),
+    // giving ghostRect.top = pageCY - 0 = 500. Assert it's NOT that.
+    expect(ghostRect.top).not.toBeCloseTo(500);
+  });
+
   test("markerRect is the visible intersection of container and img", () => {
     // Container partially off-screen; img fully inside container.
     const snapshot = makeSnapshot({ viewportW: 200, viewportH: 80 });
diff --git a/src/__tests__/cdnPopover.test.tsx b/src/__tests__/cdnPopover.test.tsx
index 706c5aa5..c9a567bd 100644
--- a/src/__tests__/cdnPopover.test.tsx
+++ b/src/__tests__/cdnPopover.test.tsx
@@ -232,6 +232,11 @@ describe("cdn.ts source invariants", () => {
     expect(cdnSource).toContain("viewState.current");
     expect(cdnSource).toContain("viewState.transition");
   });
+  it("defers CDN repositioning during evidence view transitions", () => {
+    expect(cdnSource).toContain('from "../../react/viewTransition.js"');
+    expect(cdnSource).toContain("isViewTransitioning()");
+    expect(cdnSource).toMatch(/if\s*\(\s*isViewTransitioning\(\).*\)\s*{\s*deferReposition\(/s);
+  });
   it("imports from cdn-mappers", () => {
     expect(cdnSource).toContain('from "./cdn-mappers.js"');
   });
diff --git a/src/__tests__/cliIntegration.test.ts b/src/__tests__/cliIntegration.test.ts
index e9e759a8..802a40be 100644
--- a/src/__tests__/cliIntegration.test.ts
+++ b/src/__tests__/cliIntegration.test.ts
@@ -313,16 +313,6 @@ describe("verify command", () => {
     expect(r.stderr).toContain("--style");
   });
 
-  it("verify --markdown errors with invalid --audience", () => {
-    const mdFile = join(TEST_DIR, "audience-test.md");
-    writeFileSync(mdFile, "test\n<<<CITATION_DATA>>>\n[]\n<<<END_CITATION_DATA>>>");
-    const r = run(["verify", "--markdown", mdFile, "--audience", "casual"], {
-      env: { DEEPCITATION_API_KEY: "sk-dc-test12345678901234" },
-    });
-    expect(r.exitCode).toBe(1);
-    expect(r.stderr).toContain("--audience");
-  });
-
   it("verify --html errors on nonexistent file", () => {
     const r = run(["verify", "--html", "/nonexistent.html"], {
       env: { DEEPCITATION_API_KEY: "sk-dc-test12345678901234" },
@@ -874,20 +864,4 @@ describe("verify --markdown output naming", () => {
     // Should parse the citation before failing at API
     expect(r.stderr).toContain("1 citation");
   });
-
-  it("--style and --audience are forwarded through markdown pipeline", () => {
-    const mdDir = join(TEST_DIR, "md-style-fwd");
-    mkdirSync(mdDir, { recursive: true });
-    const mdFile = join(mdDir, "styled.md");
-    writeFileSync(
-      mdFile,
-      `Claim [1].\n\n<<<CITATION_DATA>>>\n[{"n":1,"a":"att-1","r":"t","f":"claim","k":"Claim","p":"page_number_1_index_0","l":[1]}]\n<<<END_CITATION_DATA>>>`,
-    );
-
-    // plain style + executive audience should not error at parse stage
-    const r = run(["verify", "--markdown", mdFile, "--style", "plain", "--audience", "executive"], {
-      env: { DEEPCITATION_API_KEY: "sk-dc-test12345678901234" },
-    });
-    expect(r.stderr).toContain("1 citation");
-  });
 });
diff --git a/src/__tests__/cliPublish.test.ts b/src/__tests__/cliPublish.test.ts
deleted file mode 100644
index 73a82577..00000000
--- a/src/__tests__/cliPublish.test.ts
+++ /dev/null
@@ -1,215 +0,0 @@
-/**
- * Tests for `deepcitation publish` — the opt-in hosted-reports upload path.
- *
- * Covers:
- *   - --dry-run path never hits the network and emits a structured payload
- *   - Missing --html / --vr → non-zero exit with help text
- *   - sk-dc- leak in HTML → hard fail before POST
- *   - Payload size cap enforced before POST
- *   - Invalid JSON in verify-response.json → non-zero exit
- *   - --lint pre-check: bad HTML fails before POST
- *   - --vis validates against {private, unlisted, public}
- *
- * These tests only exercise the dry-run path. The actual network call is
- * covered by the server route tests in `packages/deepcitation-functions`.
- */
-
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
-import { publish } from "../cli/publish.js";
-import { CITATION_DATA_END_DELIMITER, CITATION_DATA_START_DELIMITER } from "../prompts/citationPrompts.js";
-
-function htmlWithCitationBlock(body: string, jsonBody: string): string {
-  return `<html><body>${body}\n\n${CITATION_DATA_START_DELIMITER}\n${jsonBody}\n${CITATION_DATA_END_DELIMITER}\n</body></html>`;
-}
-
-const VALID_CITATION_JSON = JSON.stringify({
-  doc1: [{ n: 1, k: "45%", p: "1_0", l: [5], f: "Revenue grew 45% year over year in Q4." }],
-});
-
-const VALID_HTML = htmlWithCitationBlock(
-  '<p>Revenue grew <strong>45%</strong> <cite data-cite="1">[1]</cite>.</p>',
-  VALID_CITATION_JSON,
-);
-
-const VALID_VERIFY_RESPONSE = JSON.stringify({
-  verifications: {
-    abc123: { status: "found", citationKey: "abc123" },
-  },
-});
-
-describe("publish", () => {
-  let tmp: string;
-  let mockExit: jest.SpiedFunction<typeof process.exit>;
-  let mockError: jest.SpiedFunction<typeof console.error>;
-  let mockLog: jest.SpiedFunction<typeof console.log>;
-  const errorLines: string[] = [];
-  const logLines: string[] = [];
-
-  beforeEach(() => {
-    tmp = join(tmpdir(), `dc-publish-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
-    mkdirSync(tmp, { recursive: true });
-    errorLines.length = 0;
-    logLines.length = 0;
-    mockExit = jest.spyOn(process, "exit").mockImplementation(((code?: number) => {
-      throw new Error(`process.exit(${code ?? 0})`);
-    }) as never);
-    mockError = jest.spyOn(console, "error").mockImplementation(((...args: unknown[]) => {
-      errorLines.push(args.map(String).join(" "));
-    }) as never);
-    mockLog = jest.spyOn(console, "log").mockImplementation(((...args: unknown[]) => {
-      logLines.push(args.map(String).join(" "));
-    }) as never);
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-    mockExit.mockRestore();
-    mockError.mockRestore();
-    mockLog.mockRestore();
-  });
-
-  function write(name: string, content: string): string {
-    const path = join(tmp, name);
-    writeFileSync(path, content);
-    return path;
-  }
-
-  async function publishAndCatchExit(args: string[]): Promise<number> {
-    try {
-      await publish(args);
-      return 0;
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      const m = msg.match(/^process\.exit\((\d+)\)$/);
-      if (m) return parseInt(m[1], 10);
-      throw err;
-    }
-  }
-
-  it("--dry-run writes a structured payload and does not require auth", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--dry-run"]);
-
-    expect(code).toBe(0);
-    // Structured dry-run payload goes to stdout
-    const combined = logLines.join("\n");
-    const parsed = JSON.parse(combined);
-    expect(parsed.dryRun).toBe(true);
-    expect(parsed.htmlPath).toBe(htmlPath);
-    expect(parsed.verifyResponsePath).toBe(jsonPath);
-    expect(parsed.visibility).toBe("private");
-    expect(parsed.htmlBytes).toBeGreaterThan(0);
-    expect(parsed.jsonBytes).toBeGreaterThan(0);
-  });
-
-  it("--dry-run with --vis public carries the visibility", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-
-    const code = await publishAndCatchExit([
-      "--html",
-      htmlPath,
-      "--vr",
-      jsonPath,
-      "--vis",
-      "public",
-      "--title",
-      "Q2 report",
-      "--dry-run",
-    ]);
-
-    expect(code).toBe(0);
-    const parsed = JSON.parse(logLines.join("\n"));
-    expect(parsed.visibility).toBe("public");
-    expect(parsed.title).toBe("Q2 report");
-  });
-
-  it("rejects missing --html with exit 1", async () => {
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-    const code = await publishAndCatchExit(["--vr", jsonPath, "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/--html is required/);
-  });
-
-  it("rejects missing --vr with exit 1", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const code = await publishAndCatchExit(["--html", htmlPath, "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/--vr.*is required/);
-  });
-
-  it("rejects missing HTML file with exit 1", async () => {
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-    const code = await publishAndCatchExit(["--html", join(tmp, "does-not-exist.html"), "--vr", jsonPath, "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/HTML file not found/);
-  });
-
-  it("rejects HTML containing a DeepCitation API key (fail-closed)", async () => {
-    const htmlPath = write("leaky.html", `<html><body>oops: sk-dc-abcdef1234567890\n${VALID_HTML}</body></html>`);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/contains a DeepCitation API key/);
-  });
-
-  it("rejects invalid JSON in verify-response.json", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", "{ not valid json");
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/is not valid JSON/);
-  });
-
-  it("rejects invalid --vis value", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--vis", "everyone", "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/Invalid --vis/);
-  });
-
-  it("--lint fails when HTML has a citation-syntax error", async () => {
-    // Code-fenced CITATION_DATA block triggers the lint rule-8 error.
-    const badHtml = [
-      "<html><body>",
-      '<p>Some text <cite data-cite="1">[1]</cite>.</p>',
-      "```json",
-      CITATION_DATA_START_DELIMITER,
-      VALID_CITATION_JSON,
-      CITATION_DATA_END_DELIMITER,
-      "```",
-      "</body></html>",
-    ].join("\n");
-    const htmlPath = write("bad.html", badHtml);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--lint", "--dry-run"]);
-    expect(code).toBe(1);
-    expect(errorLines.join("\n")).toMatch(/lint ERR|code-fence|refusing to publish/);
-  });
-
-  it("--lint passes when HTML is clean", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "--lint", "--dry-run"]);
-
-    expect(code).toBe(0);
-    expect(errorLines.join("\n")).toMatch(/lint: clean|warning/);
-  });
-
-  it("-d short-alias is equivalent to --dry-run", async () => {
-    const htmlPath = write("r.html", VALID_HTML);
-    const jsonPath = write("r.json", VALID_VERIFY_RESPONSE);
-    const code = await publishAndCatchExit(["--html", htmlPath, "--vr", jsonPath, "-d"]);
-    expect(code).toBe(0);
-    const parsed = JSON.parse(logLines.join("\n"));
-    expect(parsed.dryRun).toBe(true);
-  });
-});
diff --git a/src/__tests__/cliVerifyPub.test.ts b/src/__tests__/cliVerifyPub.test.ts
deleted file mode 100644
index 6468cd22..00000000
--- a/src/__tests__/cliVerifyPub.test.ts
+++ /dev/null
@@ -1,115 +0,0 @@
-/**
- * Tests for `verify`'s auto-publish path.
- *
- * Successful `verify` runs hand their freshly-verified HTML +
- * verify-response.json straight to `publishInMemory`, the shared helper
- * also used by the standalone `publish` subcommand. Most of the upload
- * semantics are covered by cliPublish.test.ts via the disk path. This
- * file focuses on:
- *
- *   1. VERIFY_HELP documents the auto-publish defaults + escape hatch
- *      so agents can discover them.
- *   2. The shared guards (size cap, API-key leak scan, JSON validate)
- *      reject bad payloads **before** any network call — i.e. the same
- *      fail-closed posture used by `publish`, but reached via the
- *      in-memory entry point.
- *
- * We never exercise the full verifyHtml pipeline here: it needs live
- * auth and a live API. The thin wiring inside verifyHtml is:
- *
- *     if (publishAfter) { await publishInMemory(...); }
- *
- * — where `publishAfter` is true unless --no-publish is passed.
- */
-
-import { describe, expect, it } from "@jest/globals";
-import { normalizeShortFlags } from "../cli/cliUtils.js";
-import { VERIFY_HELP } from "../cli/commands.js";
-import { API_KEY_LEAK_RE, MAX_HTML_BYTES, MAX_JSON_BYTES, publishInMemory, resolveVisibility } from "../cli/publish.js";
-
-describe("verify auto-publish help surface", () => {
-  it("VERIFY_HELP documents the --no-publish opt-out", () => {
-    expect(VERIFY_HELP).toContain("--no-publish");
-  });
-
-  it("VERIFY_HELP lists --vis for the publish visibility knob", () => {
-    expect(VERIFY_HELP).toContain("--vis");
-    expect(VERIFY_HELP).toContain("--visibility");
-  });
-
-  it("VERIFY_HELP advertises private as the default visibility", () => {
-    expect(VERIFY_HELP).toMatch(/default: private/);
-  });
-
-  it("VERIFY_HELP shows a --no-publish example so agents can copy it", () => {
-    expect(VERIFY_HELP).toMatch(/verify --md .*--no-publish/);
-  });
-});
-
-describe("publishInMemory fail-closed guards (shared by verify --pub and publish)", () => {
-  const MINIMAL_JSON = JSON.stringify({ verifications: { abc: { status: "found" } } });
-
-  it("rejects HTML containing a DeepCitation API key", async () => {
-    const html = "<html><body>leaked sk-dc-abcdefghijklmn01 in page</body></html>";
-    await expect(
-      publishInMemory({
-        html,
-        verifyResponseJson: MINIMAL_JSON,
-        visibility: "unlisted",
-      }),
-    ).rejects.toThrow(/API key/);
-  });
-
-  it("rejects HTML larger than the MAX_HTML_BYTES cap", async () => {
-    // Build a string just over the cap without allocating a 10MB regex target.
-    const html = "x".repeat(MAX_HTML_BYTES + 1);
-    await expect(
-      publishInMemory({
-        html,
-        verifyResponseJson: MINIMAL_JSON,
-        visibility: "unlisted",
-      }),
-    ).rejects.toThrow(/HTML exceeds/);
-  });
-
-  it("rejects verify-response.json larger than the MAX_JSON_BYTES cap", async () => {
-    const json = "x".repeat(MAX_JSON_BYTES + 1);
-    await expect(
-      publishInMemory({
-        html: "<html><body>ok</body></html>",
-        verifyResponseJson: json,
-        visibility: "unlisted",
-      }),
-    ).rejects.toThrow(/verify-response\.json exceeds/);
-  });
-
-  it("rejects invalid JSON bodies", async () => {
-    await expect(
-      publishInMemory({
-        html: "<html><body>ok</body></html>",
-        verifyResponseJson: "not json at all",
-        visibility: "unlisted",
-      }),
-    ).rejects.toThrow(/not valid JSON/);
-  });
-});
-
-describe("verify backward compat: --pub / --publish are no-op aliases", () => {
-  it("normalizeShortFlags still maps --pub → --publish (alias preserved)", () => {
-    expect(normalizeShortFlags(["--pub"])).toEqual(["--publish"]);
-  });
-
-  it("resolveVisibility with no value returns private (auto-publish default)", () => {
-    expect(resolveVisibility(undefined, VERIFY_HELP)).toBe("private");
-  });
-});
-
-describe("API_KEY_LEAK_RE regression guard", () => {
-  it("matches production-length DeepCitation keys", () => {
-    expect(API_KEY_LEAK_RE.test("sk-dc-abcdefghijklmn01")).toBe(true);
-  });
-
-  it("does not flag shorter lookalikes (avoid over-eager strips)", () => {
-    expect(API_KEY_LEAK_RE.test("sk-dc-short")).toBe(false);
-  });
-});
diff --git a/src/__tests__/markdownToHtml.test.ts b/src/__tests__/markdownToHtml.test.ts
index 40e74dff..12c913f8 100644
--- a/src/__tests__/markdownToHtml.test.ts
+++ b/src/__tests__/markdownToHtml.test.ts
@@ -1,10 +1,5 @@
 import { describe, expect, it } from "@jest/globals";
-import {
-  AUDIENCE_PRESETS,
-  buildCdnComparisonShowcaseHtml,
-  markdownToHtml,
-  wrapCitationMarkers,
-} from "../cli/markdownToHtml.js";
+import { buildCdnComparisonShowcaseHtml, markdownToHtml, wrapCitationMarkers } from "../cli/markdownToHtml.js";
 
 // ── wrapCitationMarkers ───────────────────────────────────────────
 
@@ -301,36 +296,6 @@ describe("buildCdnComparisonShowcaseHtml", () => {
   });
 });
 
-// ── markdownToHtml — audience presets ─────────────────────────────
-
-describe("markdownToHtml audience presets", () => {
-  it("exports all five audience presets", () => {
-    expect(AUDIENCE_PRESETS).toEqual(["general", "executive", "technical", "legal", "medical"]);
-  });
-
-  it("uses narrower width for executive audience", () => {
-    const md = "# Report\n\n## Section\n\nContent.";
-    const executive = markdownToHtml(md, { style: "report", audience: "executive" });
-    const general = markdownToHtml(md, { style: "report", audience: "general" });
-    expect(executive).toContain("720px");
-    expect(general).toContain("960px");
-  });
-
-  it("collapses details for executive audience", () => {
-    const md = "# Report\n\n## Key Findings\n\nImportant.\n\n## Details\n\nMore.";
-    const executive = markdownToHtml(md, { style: "report", audience: "executive" });
-    // executive tier2Open is false, so no "open" attribute
-    expect(executive).toContain("<details>");
-    expect(executive).not.toContain("<details open>");
-  });
-
-  it("expands details for general audience", () => {
-    const md = "# Report\n\n## Key Findings\n\nImportant.\n\n## Details\n\nMore.";
-    const general = markdownToHtml(md, { style: "report", audience: "general" });
-    expect(general).toContain("<details open>");
-  });
-});
-
 // ── markdownToHtml — report body structure ────────────────────────
 
 describe("markdownToHtml report body (progressive disclosure)", () => {
@@ -511,3 +476,83 @@ describe("markdownToHtml — §7 extraction-script structure regressions", () =>
     expect(result).not.toMatch(/<strong>interest rate<\/strong>\s*<span data-cite="1">/);
   });
 });
+
+// ── Header claim + model ──────────────────────────────────────────
+
+describe("markdownToHtml header — claim & model", () => {
+  it("renders a claim card when claim is provided", () => {
+    const result = markdownToHtml("# T\nbody", { claim: "Did revenue exceed $4B?" });
+    expect(result).toContain('class="dc-claim"');
+    expect(result).toContain(">CLAIM<");
+    expect(result).toContain("Did revenue exceed $4B?");
+  });
+
+  it("omits the claim card when claim is absent", () => {
+    const result = markdownToHtml("# T\nbody", {});
+    expect(result).not.toContain('<div class="dc-claim"');
+    expect(result).not.toContain(">CLAIM<");
+  });
+
+  it("suppresses a whitespace-only claim", () => {
+    const result = markdownToHtml("# T\nbody", { claim: "   " });
+    expect(result).not.toContain('<div class="dc-claim"');
+    expect(result).not.toContain(">CLAIM<");
+  });
+
+  it("escapes HTML in the claim", () => {
+    const result = markdownToHtml("# T\nbody", { claim: "<script>x</script>" });
+    expect(result).toContain("&lt;script&gt;");
+    expect(result).not.toContain("<script>x");
+  });
+
+  it("honors inline markdown in the claim", () => {
+    const result = markdownToHtml("# T\nbody", { claim: "Did **Acme** beat *Q1*?" });
+    const claimMatch = result.match(/<blockquote class="dc-claim-text">([\s\S]*?)<\/blockquote>/);
+    expect(claimMatch).not.toBeNull();
+    const claimInner = claimMatch?.[1] ?? "";
+    expect(claimInner).toContain("<strong>Acme</strong>");
+    expect(claimInner).toContain("<em>Q1</em>");
+  });
+
+  it("renders MODEL in the meta strip when provided", () => {
+    const result = markdownToHtml("# T\nbody", { model: "Claude Haiku 4.5", citationCount: 5 });
+    expect(result).toContain(">MODEL<");
+    expect(result).toContain("Claude Haiku 4.5");
+    // Order: ANALYZED → MODEL → CITATIONS
+    expect(result).toMatch(/ANALYZED[\s\S]*MODEL[\s\S]*CITATIONS/);
+  });
+
+  it("omits the MODEL meta item when model is absent", () => {
+    const result = markdownToHtml("# T\nbody", { citationCount: 3 });
+    expect(result).not.toContain(">MODEL<");
+  });
+
+  it("renders claim card + MODEL + cowork notice together in source order", () => {
+    const result = markdownToHtml("# T\nbody", {
+      claim: "Is X true?",
+      model: "Claude Haiku 4.5",
+      cowork: true,
+      citationCount: 2,
+    });
+    // Claim card appears before meta strip; meta strip appears before cowork notice.
+    // Anchor on element markup (not class names) so the <style> block doesn't pollute indexOf.
+    const claimIdx = result.indexOf('<div class="dc-claim"');
+    const metaIdx = result.indexOf('<div class="dc-meta"');
+    const coworkIdx = result.indexOf('<div class="dc-cowork-notice"');
+    expect(claimIdx).toBeGreaterThan(-1);
+    expect(metaIdx).toBeGreaterThan(-1);
+    expect(coworkIdx).toBeGreaterThan(-1);
+    expect(claimIdx).toBeLessThan(metaIdx);
+    expect(metaIdx).toBeLessThan(coworkIdx);
+    expect(result).toContain("Is X true?");
+    expect(result).toContain("Claude Haiku 4.5");
+  });
+
+  it("renders a long claim intact without truncation", () => {
+    const longClaim = `${"A".repeat(20)}${"m".repeat(760)}${"Z".repeat(20)}`;
+    expect(longClaim.length).toBe(800);
+    const result = markdownToHtml("# T\nbody", { claim: longClaim });
+    expect(result).toContain("A".repeat(20));
+    expect(result).toContain("Z".repeat(20));
+  });
+});
diff --git a/src/__tests__/useViewportBoundaryGuard.test.ts b/src/__tests__/useViewportBoundaryGuard.test.ts
new file mode 100644
index 00000000..5b63ec06
--- /dev/null
+++ b/src/__tests__/useViewportBoundaryGuard.test.ts
@@ -0,0 +1,179 @@
+/**
+ * Tests for useViewportBoundaryGuard — specifically the isViewStateTransitionRef
+ * flag that controls whether the safety timer skips vertical correction.
+ *
+ * Key regression: when transitioning out of expanded-page (CDN), sideOffset
+ * changes from N → undefined in a second layout-effect run within the same
+ * flushSync batch. The old code set isViewStateTransitionRef.current = isViewStateChange
+ * which overwrote true→false on the second run, causing the safety timer to apply
+ * full vertical correction mid-animation (skipVertical=false instead of true).
+ *
+ * Observable proxy: make the popover element overflow BOTH horizontally (left=-10)
+ * and vertically (top=-20). With VIEWPORT_MARGIN_PX=16 and topInset=0:
+ *   guardClamp → dx=26, dy=20
+ *   skipVertical=true  → translate "26px"      (horizontal only)
+ *   skipVertical=false → translate "26px 20px"  (both)
+ *
+ * After advanceTimersByTime(200), the last write to style.translate comes from
+ * the safety timer (fires at SETTLE_MS≈136ms), which is what we're asserting.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { act, cleanup, renderHook } from "@testing-library/react";
+import type React from "react";
+import type { PopoverViewState } from "../react/DefaultPopoverContent";
+import { useViewportBoundaryGuard } from "../react/hooks/useViewportBoundaryGuard";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a div whose getBoundingClientRect overflows both left and top so
+ * guardClamp produces a visible dy when skipVertical=false.
+ *
+ * With clientWidth=1024, innerHeight=768, VIEWPORT_MARGIN_PX=16:
+ *   dx = 16 − (−10) = 26   (left overflow)
+ *   dy = 0  − (−20) = 20   (top overflow, only when skipVertical=false)
+ */
+function makeOutOfBoundsEl(): HTMLElement {
+  const el = document.createElement("div");
+  jest.spyOn(el, "getBoundingClientRect").mockReturnValue({
+    left: -10,
+    top: -20,
+    right: 290,
+    bottom: 380,
+    width: 300,
+    height: 400,
+    x: -10,
+    y: -20,
+    toJSON: () => ({}),
+  } as DOMRect);
+  return el;
+}
+
+function makeRefs(el: HTMLElement): {
+  popoverContentRef: React.RefObject<HTMLElement | null>;
+  triggerRef: React.RefObject<HTMLSpanElement | null>;
+} {
+  return {
+    popoverContentRef: { current: el },
+    triggerRef: { current: document.createElement("span") },
+  };
+}
+
+// skipVertical=true  → only dx applied
+const HORIZONTAL_ONLY = "26px";
+// skipVertical=false → dx and dy applied
+const HORIZONTAL_AND_VERTICAL = "26px 20px";
+
+type HookProps = { popoverViewState: PopoverViewState; sideOffset: number | undefined };
+
+function renderGuard(el: HTMLElement, initialProps: HookProps) {
+  const { popoverContentRef, triggerRef } = makeRefs(el);
+  return renderHook(
+    ({ popoverViewState, sideOffset }: HookProps) =>
+      useViewportBoundaryGuard(true, popoverViewState, popoverContentRef, triggerRef, sideOffset),
+    { initialProps },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  // Provide realistic viewport dimensions for predictable guardClamp output.
+  Object.defineProperty(document.documentElement, "clientWidth", {
+    value: 1024,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(window, "innerHeight", {
+    value: 768,
+    writable: true,
+    configurable: true,
+  });
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+  cleanup();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useViewportBoundaryGuard — safety-timer skipVertical flag", () => {
+  it("skips vertical correction in safety timer on a plain view-state transition", () => {
+    const el = makeOutOfBoundsEl();
+    const { rerender } = renderGuard(el, { popoverViewState: "expanded-page", sideOffset: -184 });
+
+    // Transition: expanded-page → summary in one re-render
+    act(() => rerender({ popoverViewState: "summary", sideOffset: undefined }));
+
+    // Advance past SETTLE_MS (≈136ms) so the safety timer fires
+    act(() => jest.advanceTimersByTime(200));
+
+    // isViewStateChange=true → isViewStateTransitionRef set to true →
+    // safety timer uses skipVertical=true → horizontal correction only
+    expect(el.style.translate).toBe(HORIZONTAL_ONLY);
+  });
+
+  it("still skips vertical when sideOffset changes in the same batch as the view-state change (CDN scenario)", () => {
+    const el = makeOutOfBoundsEl();
+    const { rerender } = renderGuard(el, { popoverViewState: "expanded-page", sideOffset: -184 });
+
+    // Simulate the CDN flushSync double-render:
+    //   render 1 → viewState changes to "summary" (layout effect: isViewStateChange=true → flag=true)
+    //   render 2 → sideOffset clears to undefined  (layout effect: isViewStateChange=false → must NOT overwrite flag)
+    // Both within one act() so passive effects (useEffect) flush only after both commits.
+    act(() => {
+      rerender({ popoverViewState: "summary", sideOffset: -184 }); // render 1
+      rerender({ popoverViewState: "summary", sideOffset: undefined }); // render 2
+    });
+
+    act(() => jest.advanceTimersByTime(200));
+
+    // The sideOffset-change layout-effect run must not have clobbered the flag.
+    // Safety timer must still use skipVertical=true.
+    expect(el.style.translate).toBe(HORIZONTAL_ONLY);
+  });
+
+  it("applies full (vertical+horizontal) correction for initial open — no transition", () => {
+    const el = makeOutOfBoundsEl();
+    // Render directly in summary state with no prior transition; flag starts false.
+    renderGuard(el, { popoverViewState: "summary", sideOffset: undefined });
+
+    act(() => jest.advanceTimersByTime(200));
+
+    // No view-state transition → isViewStateTransitionRef stays false →
+    // safety timer uses skipVertical=false → both dx and dy applied
+    expect(el.style.translate).toBe(HORIZONTAL_AND_VERTICAL);
+  });
+
+  it("resets the flag so subsequent non-transition renders use full correction", () => {
+    const el = makeOutOfBoundsEl();
+    const { rerender } = renderGuard(el, { popoverViewState: "expanded-page", sideOffset: -184 });
+
+    // First transition: expanded-page → summary (flag set to true, consumed & reset by useEffect)
+    act(() => {
+      rerender({ popoverViewState: "summary", sideOffset: -184 });
+      rerender({ popoverViewState: "summary", sideOffset: undefined });
+    });
+    act(() => jest.advanceTimersByTime(200)); // fires safety timer, resets flag to false
+
+    // Simulate sideOffset changing again with NO view-state change (e.g. window resize).
+    // Flag is now false. The useEffect does NOT re-run (popoverViewState unchanged).
+    // The layout effect for sideOffset runs clamp(skipVertical=false) directly —
+    // no safety timer involved. Clear the style first so the layout-effect write is observable.
+    el.style.translate = "";
+    act(() => rerender({ popoverViewState: "summary", sideOffset: 8 }));
+
+    // The sideOffset-only layout effect calls clamp(skipVertical=false) directly —
+    // no safety timer involved here. Assert both dx and dy are applied:
+    expect(el.style.translate).toBe(HORIZONTAL_AND_VERTICAL);
+  });
+});
diff --git a/src/cli.ts b/src/cli.ts
index a454de9a..4c98f94f 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -29,7 +29,7 @@ import {
   merge,
   openBillingDashboard,
   prepare,
-  publish,
+  report,
   resolveBaseUrl,
   slice,
   status,
@@ -111,8 +111,8 @@ switch (command) {
   case "text":
     text(rest);
     break;
-  case "publish":
-    publish(rest).catch(err => {
+  case "report":
+    report(rest, fmtNetErr).catch(err => {
       console.error(`Error: ${fmtNetErr(err)}`);
       process.exit(1);
     });
diff --git a/src/cli/commands.ts b/src/cli/commands.ts
index 736375ec..7d2519a2 100644
--- a/src/cli/commands.ts
+++ b/src/cli/commands.ts
@@ -57,15 +57,8 @@ import {
 import { extractMarkersFromBody, findAnchorWithFallback, getAllLines, toCompactPageId } from "./cite.js";
 import { die, extractApiKey, isValidApiKeyFormat, normalizeShortFlags, parseArgs } from "./cliUtils.js";
 import { findSummaryForMarkdown, hydrateCitations, parseSummaryToLineMap } from "./hydrate.js";
-import {
-  AUDIENCE_PRESETS,
-  type AudiencePreset,
-  generateReviewVariants,
-  markdownToHtml,
-  type ReportStyle,
-} from "./markdownToHtml.js";
+import { generateReviewVariants, markdownToHtml, type ReportStyle } from "./markdownToHtml.js";
 import { createCoworkFetch, createProxyFetch } from "./proxy.js";
-import { publishInMemory, resolveVisibility } from "./publish.js";
 import type { TextFormat } from "./textRender.js";
 import { applyLineIds, parseFormatMode, parseLineIdsMode, renderTextStream, resolvePageSpec } from "./textRender.js";
 
@@ -73,7 +66,6 @@ import { applyLineIds, parseFormatMode, parseLineIdsMode, renderTextStream, reso
 export { HYDRATE_HELP, hydrate } from "./hydrate.js";
 export { LINT_HELP, lint } from "./lint.js";
 export { MERGE_HELP, merge } from "./merge.js";
-export { PUBLISH_HELP, publish } from "./publish.js";
 export { SLICE_HELP, slice } from "./slice.js";
 export { TEXT_HELP, text } from "./text.js";
 export type { LineIdsMode, TextFormat } from "./textRender.js";
@@ -186,8 +178,9 @@ Options:
   --html <file>             Path to HTML file with citations
   --citations <file>        Path to citations JSON (citations-only mode)
   --style <plain|report>    HTML output style (default: "report", --markdown only)
-  --audience <preset>       Audience preset: general, executive, technical, legal, medical (default: "general")
   --title <text>            Report title (default: first H1 in markdown, or "Verification Report")
+  --claim <text>            Claim or question being verified (rendered in header card)
+  --model <name>            Model that performed verification (e.g. "Claude Haiku 4.5")
   --summary <file>          Summary file for auto-hydrating compact citations (--markdown only)
   --out <file>              Output path (default: {stem}-verified.html in CWD)
   --output-dir <dir>        Save HTML and verify-response.json to this directory with stable names
@@ -202,8 +195,8 @@ Options:
 
 Examples:
   deepcitation verify --md .deepcitation/draft-report.md          # auto-publishes as private
+  deepcitation verify --md report.md --claim "Did Q1 revenue exceed $4B?" --model "Claude Haiku 4.5"
   deepcitation verify --md report.md --style plain
-  deepcitation verify --md report.md --audience executive --theme dark
   deepcitation verify --md report.md --vis unlisted               # shareable by link
   deepcitation verify --md report.md --vis public                 # (Portal session only)
   deepcitation verify --md report.md --no-publish                 # local-only, don't upload
@@ -833,10 +826,6 @@ export async function verifyMarkdown(argv: string[], fmtNetErr: (err: unknown) =
   const style = (args.style ?? "report") as ReportStyle;
   if (!["plain", "report"].includes(style)) die('--style must be "plain" or "report"', VERIFY_HELP);
 
-  const audience = (args.audience ?? "general") as AudiencePreset;
-  if (!AUDIENCE_PRESETS.includes(audience))
-    die(`--audience must be one of: ${AUDIENCE_PRESETS.join(", ")}`, VERIFY_HELP);
-
   // --citations: load citation data from a separate JSON file.
   // Assemble a combined string and parse through existing parseCitationData
   // so all downstream logic (compact key expansion, hydration, validation) works unchanged.
@@ -1028,6 +1017,8 @@ export async function verifyMarkdown(argv: string[], fmtNetErr: (err: unknown) =
   }
 
   const title = args.title as string | undefined;
+  const claim = args.claim as string | undefined;
+  const model = args.model as string | undefined;
 
   // Resolve source URL from prepare JSONs (URL-sourced documents only)
   const urlSourceMap = loadUrlSourceMap();
@@ -1038,8 +1029,9 @@ export async function verifyMarkdown(argv: string[], fmtNetErr: (err: unknown) =
 
   const html = markdownToHtml(parsed.visibleText, {
     style,
-    audience,
     title,
+    claim,
+    model,
     sourceMatchMap,
     citationCount: parsed.citations.length,
     cowork: IS_COWORK,
@@ -1053,7 +1045,7 @@ export async function verifyMarkdown(argv: string[], fmtNetErr: (err: unknown) =
   // Forward to verifyHtml with pre-loaded content — no temp file needed.
   // Note: --title is NOT stripped so verifyHtml can forward it to publishInMemory
   // on auto-publish. The HTML shell already baked in the title above.
-  const stripFlags = new Set(["--markdown", "--style", "--audience", "--citations", "--summary"]);
+  const stripFlags = new Set(["--markdown", "--style", "--citations", "--summary", "--claim", "--model"]);
   const forwardArgs: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     if (stripFlags.has(argv[i])) {
@@ -1083,8 +1075,7 @@ export async function verifyHtml(argv: string[], _fmtNetErr: (err: unknown) => s
   // --publish / --pub are no-op opt-ins kept for backwards-compat: auto-publish
   // is now the default and only needs to be suppressed with --no-publish.
   const keepJson = normalized.includes("--json") || normalized.includes("--keep-json");
-  const publishAfter = !normalized.includes("--no-publish");
-  const booleanFlags = new Set(["--json", "--keep-json", "--publish", "--no-publish"]);
+  const booleanFlags = new Set(["--json", "--keep-json"]);
   const filteredArgv = normalized.filter(a => !booleanFlags.has(a));
   const args = parseArgs(filteredArgv, VERIFY_HELP);
   const htmlPath = args.html;
@@ -1418,34 +1409,6 @@ export async function verifyHtml(argv: string[], _fmtNetErr: (err: unknown) => s
     ),
   );
   console.error(`Run metadata → ${metaPath}`);
-
-  // Auto-publish the freshly verified HTML + JSON to the hosted reports
-  // endpoint so it shows up on the user's "My Verifications" page. Default
-  // visibility is `private` (owner-only); `--no-publish` suppresses the
-  // upload for local-only runs. The HTML body `output` and JSON body
-  // `verifyOutput` are already in memory, so the upload is a single POST.
-  //
-  // A publish failure is NOT fatal — the verified artifact already exists
-  // on disk, so we emit a warning and continue instead of exiting non-zero.
-  if (publishAfter) {
-    const visibility = resolveVisibility(args.visibility, VERIFY_HELP);
-    console.error(`Publishing to My Verifications (${visibility})...`);
-    try {
-      await publishInMemory({
-        html: output,
-        verifyResponseJson: JSON.stringify(verifyOutput),
-        visibility,
-        title: args.title,
-        attachmentId: args["attachment-id"],
-        htmlSourcePath: outPath,
-      });
-    } catch (err) {
-      const msg = sanitizeForLog(err instanceof Error ? err.message : String(err));
-      console.error(`Warning: publish failed — report saved locally only. ${msg}`);
-      console.error(`  Local artifact: ${outPath}`);
-      console.error(`  Retry manually: deepcitation publish --html <file> --vr <file>`);
-    }
-  }
 }
 
 export const AUTH_HELP = `Usage: deepcitation auth [subcommand] [options]
@@ -1749,3 +1712,56 @@ export async function getAttachment(argv: string[]) {
     process.stdout.write(json + "\n");
   }
 }
+
+export const REPORT_HELP = `Usage: deepcitation report --attachment-id <id> [options]
+
+Submit raw LLM output (piped from stdin or --input) to generate a hosted
+verification report. The server parses citations, verifies them, renders
+HTML, and returns the report URL.
+
+Options:
+  --attachment-id <id>      attachmentId from the prepare step (required)
+  --input <file>            Path to a file containing the LLM output
+                            (reads from stdin if omitted)
+  --vis, --visibility <v>   private | unlisted | public (default: private)
+  --title <text>            Optional human-readable title
+  -h, --help                Show this help message
+`;
+
+export async function report(argv: string[], fmtNetErr: (err: unknown) => string): Promise<void> {
+  const normalized = normalizeShortFlags(argv);
+  const args = parseArgs(normalized, REPORT_HELP);
+
+  const attachmentId = args["attachment-id"];
+  if (!attachmentId) die("--attachment-id is required", REPORT_HELP);
+
+  let llmOutput: string;
+  if (args.input) {
+    const inputPath = resolve(args.input);
+    if (!existsSync(inputPath)) die(`Input file not found: ${sanitizeForLog(args.input)}`, REPORT_HELP);
+    llmOutput = readFileSync(inputPath, "utf-8");
+  } else {
+    // Read from stdin
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+    llmOutput = Buffer.concat(chunks).toString("utf-8");
+  }
+
+  if (!llmOutput.trim()) die("No LLM output provided (empty stdin or file)", REPORT_HELP);
+
+  const { apiKey } = await requireAuth();
+  const dc = await createClient(apiKey);
+
+  const visibility = args.visibility as import("../client/types.js").CreateReportOptions["visibility"] | undefined;
+  const title = args.title;
+
+  console.error("Submitting to DeepCitation...");
+  try {
+    const result = await dc.createReport(attachmentId, llmOutput, { visibility, title });
+    console.error(`  id:       ${result.id}`);
+    console.error(`  shareUrl: ${result.shareUrl}`);
+    console.log(result.shareUrl);
+  } catch (err) {
+    die(fmtNetErr(err), REPORT_HELP);
+  }
+}
diff --git a/src/cli/markdownToHtml.ts b/src/cli/markdownToHtml.ts
index f47a96d9..7207fb36 100644
--- a/src/cli/markdownToHtml.ts
+++ b/src/cli/markdownToHtml.ts
@@ -19,14 +19,9 @@ import type { VerificationData } from "../vanilla/runtime/types.js";
 
 export type ReportStyle = "plain" | "report";
 
-export const AUDIENCE_PRESETS = ["general", "executive", "technical", "legal", "medical"] as const;
-export type AudiencePreset = (typeof AUDIENCE_PRESETS)[number];
-
 export interface MarkdownToHtmlOptions {
   /** Output style: "plain" (simple HTML) or "report" (progressive disclosure) */
   style?: ReportStyle;
-  /** Audience preset — affects width, tier visibility, tone tokens */
-  audience?: AudiencePreset;
   /** Optional title override (extracted from first H1 if not provided) */
   title?: string;
   /** Human-readable source label (document name, filename, etc.) */
@@ -45,6 +40,14 @@ export interface MarkdownToHtmlOptions {
   /** When true, adds an info banner noting that interactive features require
    *  opening the file in a local browser (CDN blocked in Cowork sandbox). */
   cowork?: boolean;
+  /** The claim or question being verified. Rendered as a quoted card
+   *  between the H1 and the meta strip. Supports inline markdown
+   *  (bold/italic/code). Whitespace-only values are ignored. */
+  claim?: string;
+  /** Human-readable name of the model that performed the verification
+   *  (e.g. "Claude Haiku 4.5"). Surfaced as a MODEL item in the meta
+   *  strip, ordered between ANALYZED and CITATIONS. */
+  model?: string;
 }
 
 // ── Inline formatting ──────────────────────────────────────────────
@@ -370,39 +373,55 @@ const BRAND_LOGO_SVG = `<svg width="14" height="14" viewBox="0 0 24 24" fill="no
 
 const FAVICON_DATA_URI = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-linecap="square" stroke-linejoin="miter" shape-rendering="crispEdges" width="24" height="24"><path d="M4 1 L1 1 L1 23 L4 23" stroke="#A1A1AA" stroke-width="1"/><path d="M20 1 L23 1 L23 23 L20 23" stroke="#A1A1AA" stroke-width="1"/><path d="M5.5 12 L18.5 12" stroke="#3B82F6" stroke-width="1.8"/><path d="M12 5.5 L12 18.5" stroke="#3B82F6" stroke-width="1.8"/><path d="M6.5 6.5 L17.5 17.5 M17.5 6.5 L6.5 17.5" stroke="#3B82F6" stroke-width="2.35"/></svg>')}`;
 
-const AUDIENCE_CONFIG: Record<AudiencePreset, { width: string; tier2Open: boolean }> = {
-  general: { width: "960px", tier2Open: true },
-  executive: { width: "720px", tier2Open: false },
-  technical: { width: "960px", tier2Open: true },
-  legal: { width: "840px", tier2Open: true },
-  medical: { width: "840px", tier2Open: true },
-};
-
 const MONO_FONT = `"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace`;
 const SANS_FONT = `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`;
 
+// CSS custom-property defaults injected into every <style> block.
+// Generated HTML is self-contained; hosts can override via :root {}.
+const DC_ROOT_TOKENS = `  :root {
+    --dc-background: #ffffff;
+    --dc-muted: #f4f4f5;
+    --dc-foreground: #18181b;
+    --dc-muted-foreground: #71717a;
+    --dc-subtle-foreground: #a1a1aa;
+    --dc-border: #e4e4e7;
+    --dc-primary: #3b82f6;
+    --dc-primary-foreground: #ffffff;
+    --dc-verified: #10b981;
+    --dc-partial: #f59e0b;
+    --dc-destructive: #ef4444;
+    --dc-verified-bg: #f0fdf4;
+    --dc-partial-bg: #fffbeb;
+    --dc-destructive-bg: #fef2f2;
+    --dc-radius-sm: 0.25rem;
+    --dc-radius-md: 0.375rem;
+    --dc-radius-lg: 0.5rem;
+    --dc-font-family: ${SANS_FONT};
+    --dc-font-family-mono: ${MONO_FONT};
+  }`;
+
 const BASE_CSS = `  * { margin: 0; padding: 0; box-sizing: border-box; }
   h1 { font-size: 24px; font-weight: 600; }
-  h2 { font-size: 18px; font-weight: 600; margin: 2rem 0 0.75rem; border-bottom: 1px solid #E4E4E7; padding-bottom: 0.4rem; }
+  h2 { font-size: 18px; font-weight: 600; margin: 2rem 0 0.75rem; border-bottom: 1px solid var(--dc-border); padding-bottom: 0.4rem; }
   h3 { font-size: 16px; font-weight: 600; margin: 1.5rem 0 0.5rem; }
   p { margin: 0.5rem 0; }
   [data-cite] strong { font-weight: 600; }
-  a { color: #0284C7; }
+  a { color: var(--dc-primary); }
   table { width: 100%; border-collapse: collapse; margin: 0.75rem 0; font-size: 14px; }
-  th, td { padding: 0.5rem 0.75rem; text-align: left; border-bottom: 1px solid #E4E4E7; }
-  th { font-weight: 600; background: #F4F4F5; }
+  th, td { padding: 0.5rem 0.75rem; text-align: left; border-bottom: 1px solid var(--dc-border); }
+  th { font-weight: 600; background: var(--dc-muted); }
   ul, ol { margin: 0.5rem 0 0.5rem 1.5rem; }
   li { margin: 0.25rem 0; }
-  pre { background: #18181B; color: #E4E4E7; padding: 1rem; overflow-x: auto; margin: 0.75rem 0; font-size: 13px; }
-  code { font-family: ${MONO_FONT}; font-size: 0.9em; background: #F4F4F5; padding: 1px 4px; }
+  pre { background: var(--dc-foreground); color: var(--dc-border); padding: 1rem; overflow-x: auto; margin: 0.75rem 0; font-size: 13px; }
+  code { font-family: var(--dc-font-family-mono); font-size: 0.9em; background: var(--dc-muted); padding: 1px 4px; }
   pre code { background: none; padding: 0; }
-  hr { border: none; border-top: 1px solid #E4E4E7; margin: 1.5rem 0; }
-  .meta { color: #52525B; font-size: 14px; margin-bottom: 1.5rem; }
+  hr { border: none; border-top: 1px solid var(--dc-border); margin: 1.5rem 0; }
+  .meta { color: var(--dc-muted-foreground); font-size: 14px; margin-bottom: 1.5rem; }
   .dc-cowork-notice {
     display: flex; align-items: flex-start; gap: 0.6rem;
     padding: 0.65rem 0.9rem; margin-bottom: 1rem;
-    background: #EFF6FF; border: 1px solid #BFDBFE; border-radius: 6px;
-    font-size: 13px; line-height: 1.5; color: #1E40AF;
+    background: var(--dc-muted); border: 1px solid var(--dc-border); border-radius: var(--dc-radius-lg);
+    font-size: 13px; line-height: 1.5; color: var(--dc-foreground);
   }
   .dc-cowork-notice svg { flex-shrink: 0; margin-top: 2px; }`;
 
@@ -421,8 +440,9 @@ function plainShell(title: string, bodyHtml: string, options?: { cowork?: boolea
 <link rel="icon" type="image/svg+xml" href="${FAVICON_DATA_URI}">
 <title>${escapeHtml(title)}</title>
 <style>
+${DC_ROOT_TOKENS}
 ${BASE_CSS}
-  body { font-family: ${SANS_FONT}; max-width: 860px; margin: 0 auto; padding: 2rem 1.5rem; line-height: 1.6; color: #18181B; background: #fff; }
+  body { font-family: var(--dc-font-family); max-width: 860px; margin: 0 auto; padding: 2rem 1.5rem; line-height: 1.6; color: var(--dc-foreground); background: var(--dc-background); }
   h1 { margin-bottom: 0.5rem; }
 </style>
 </head>
@@ -448,7 +468,7 @@ function formatSourceUrl(url: string): string {
 }
 
 /**
- * Build the header meta strip: SOURCE · ANALYZED · AUDIENCE · CITATIONS · PAGES.
+ * Build the header meta strip: SOURCE · ANALYZED · CITATIONS · PAGES.
  * Only renders items that have data. Date always renders (defaults to today).
  */
 function buildMetaStrip(opts: {
@@ -457,7 +477,7 @@ function buildMetaStrip(opts: {
   reportDate?: string;
   citationCount?: number;
   pageCount?: number;
-  audience: AudiencePreset;
+  model?: string;
 }): string {
   const items: string[] = [];
 
@@ -479,11 +499,10 @@ function buildMetaStrip(opts: {
     `<span class="dc-meta-item"><span class="dc-meta-key">ANALYZED</span><span class="dc-meta-val">${escapeHtml(date)}</span></span>`,
   );
 
-  // AUDIENCE — only shown when non-default
-  if (opts.audience !== "general") {
-    const label = opts.audience.charAt(0).toUpperCase() + opts.audience.slice(1);
+  // MODEL — only shown when provided
+  if (opts.model) {
     items.push(
-      `<span class="dc-meta-item"><span class="dc-meta-key">AUDIENCE</span><span class="dc-meta-val">${escapeHtml(label)}</span></span>`,
+      `<span class="dc-meta-item"><span class="dc-meta-key">MODEL</span><span class="dc-meta-val">${escapeHtml(opts.model)}</span></span>`,
     );
   }
 
@@ -505,14 +524,17 @@ function buildMetaStrip(opts: {
   return `<div class="dc-meta">${items.join(sep)}</div>`;
 }
 
-function reportShell(
-  title: string,
-  bodyHtml: string,
-  audience: AudiencePreset,
-  options: MarkdownToHtmlOptions,
-): string {
-  const cfg = AUDIENCE_CONFIG[audience];
-  const metaStrip = buildMetaStrip({ ...options, audience });
+function reportShell(title: string, bodyHtml: string, options: MarkdownToHtmlOptions): string {
+  const cfg = { width: "960px", tier2Open: true };
+  const metaStrip = buildMetaStrip(options);
+
+  const claimText = options.claim?.trim();
+  const claimCard = claimText
+    ? `<div class="dc-claim" role="note" aria-label="Claim under verification">
+<span class="dc-claim-label">CLAIM</span>
+<blockquote class="dc-claim-text">${inlineFormat(claimText)}</blockquote>
+</div>`
+    : "";
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -522,15 +544,16 @@ function reportShell(
 <link rel="icon" type="image/svg+xml" href="${FAVICON_DATA_URI}">
 <title>${escapeHtml(title)}</title>
 <style>
+${DC_ROOT_TOKENS}
 ${BASE_CSS}
   body {
-    font-family: ${SANS_FONT};
+    font-family: var(--dc-font-family);
     max-width: ${cfg.width};
     margin: 0 auto;
     padding: 2rem 1.5rem 4rem;
     line-height: 1.6;
-    color: #18181B;
-    background: #F8FAFC;
+    color: var(--dc-foreground);
+    background: var(--dc-muted);
     font-size: 16px;
   }
   h1 { margin-bottom: 0.25rem; }
@@ -541,30 +564,30 @@ ${BASE_CSS}
   .dc-meta {
     display: flex; flex-wrap: wrap; align-items: center; gap: 0.1rem 0;
     margin: 0.5rem 0 1.5rem;
-    font-family: ${MONO_FONT}; font-size: 12px; color: #52525B;
+    font-family: var(--dc-font-family-mono); font-size: 12px; color: var(--dc-muted-foreground);
   }
   .dc-meta-item { display: inline-flex; align-items: center; gap: 0.5rem; }
-  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.06em; color: #94A3B8; font-size: 11px; }
-  .dc-meta-val { color: #334155; }
-  .dc-meta-link { color: #0284C7; text-decoration: none; }
+  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.06em; color: var(--dc-subtle-foreground); font-size: 11px; }
+  .dc-meta-val { color: var(--dc-foreground); }
+  .dc-meta-link { color: var(--dc-primary); text-decoration: none; }
   .dc-meta-link:hover { text-decoration: underline; }
-  .dc-meta-sep { color: #CBD5E1; margin: 0 0.4rem; }
+  .dc-meta-sep { color: var(--dc-border); margin: 0 0.4rem; }
 
   /* Verdict banner */
   .dc-verdict {
     display: flex; gap: 1.5rem; padding: 1rem 0;
-    border-top: 1px solid #E4E4E7; border-bottom: 1px solid #E4E4E7;
-    font-family: ${MONO_FONT}; font-size: 14px;
+    border-top: 1px solid var(--dc-border); border-bottom: 1px solid var(--dc-border);
+    font-family: var(--dc-font-family-mono); font-size: 14px;
     margin-bottom: 1.5rem;
   }
-  .dc-verdict .v-found  { color: #10B981; }
-  .dc-verdict .v-partial { color: #D97706; }
-  .dc-verdict .v-miss   { color: #EF4444; }
+  .dc-verdict .v-found  { color: var(--dc-verified); }
+  .dc-verdict .v-partial { color: var(--dc-partial); }
+  .dc-verdict .v-miss   { color: var(--dc-destructive); }
 
   /* Table overrides — §6.1 Anti-Grid: no header fill, heavier separators, blue row hover */
-  th, td { border-bottom: 1px solid #94A3B8; }
-  th { font-size: 12px; font-weight: 500; background: none; color: #52525B; text-transform: uppercase; letter-spacing: 0.04em; border-bottom: 2px solid #94A3B8; }
-  tbody tr:hover { background: #EFF6FF; }
+  th, td { border-bottom: 1px solid var(--dc-subtle-foreground); }
+  th { font-size: 12px; font-weight: 500; background: none; color: var(--dc-muted-foreground); text-transform: uppercase; letter-spacing: 0.04em; border-bottom: 2px solid var(--dc-subtle-foreground); }
+  tbody tr:hover { background: var(--dc-muted); }
 
   /* Code overrides */
   pre { line-height: 1.7; }
@@ -573,26 +596,26 @@ ${BASE_CSS}
   /* Progressive disclosure */
   details { margin: 0.75rem 0; }
   summary {
-    cursor: pointer; font-weight: 500; font-size: 14px; color: #52525B;
+    cursor: pointer; font-weight: 500; font-size: 14px; color: var(--dc-muted-foreground);
     padding: 0.5rem 0; user-select: none;
   }
-  summary:hover { color: #18181B; }
+  summary:hover { color: var(--dc-foreground); }
 
   /* Cards */
-  .dc-section { background: #fff; border: 1px solid #E4E4E7; padding: 1.25rem; margin: 1rem 0; }
+  .dc-section { background: var(--dc-background); border: 1px solid var(--dc-border); padding: 1.25rem; margin: 1rem 0; }
 
   /* Mono metrics */
-  .mono { font-family: ${MONO_FONT}; font-size: 14px; font-weight: 500; }
+  .mono { font-family: var(--dc-font-family-mono); font-size: 14px; font-weight: 500; }
 
   /* Branding footer */
   .dc-footer {
     margin-top: 3rem; padding-top: 1rem;
-    border-top: 1px solid #E4E4E7;
-    font-size: 12px; color: #A1A1AA;
+    border-top: 1px solid var(--dc-border);
+    font-size: 12px; color: var(--dc-subtle-foreground);
     display: flex; align-items: center; gap: 0.5rem;
   }
-  .dc-footer a { color: #A1A1AA; text-decoration: none; }
-  .dc-footer a:hover { color: #52525B; text-decoration: underline; }
+  .dc-footer a { color: var(--dc-subtle-foreground); text-decoration: none; }
+  .dc-footer a:hover { color: var(--dc-muted-foreground); text-decoration: underline; }
   .dc-footer svg { flex-shrink: 0; }
 
   /* Cowork environment notice */
@@ -600,15 +623,52 @@ ${BASE_CSS}
     display: flex; align-items: flex-start; gap: 0.6rem;
     padding: 0.65rem 0.9rem;
     margin-bottom: 1rem;
-    background: #EFF6FF; border: 1px solid #BFDBFE; border-radius: 6px;
-    font-size: 13px; line-height: 1.5; color: #1E40AF;
+    background: var(--dc-muted); border: 1px solid var(--dc-border); border-radius: var(--dc-radius-lg);
+    font-size: 13px; line-height: 1.5; color: var(--dc-foreground);
   }
   .dc-cowork-notice svg { flex-shrink: 0; margin-top: 2px; }
+
+  /* Claim card — eyebrow label + quoted thesis */
+  .dc-claim {
+    margin: 0.75rem 0 1rem;
+    padding: 0.9rem 1.1rem;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
+    border-left: 3px solid var(--dc-primary);
+    border-radius: var(--dc-radius-lg);
+  }
+  .dc-claim-label {
+    display: block;
+    font-family: var(--dc-font-family-mono);
+    font-size: 11px;
+    font-weight: 500;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--dc-primary);
+    margin-bottom: 0.35rem;
+  }
+  .dc-claim-text {
+    margin: 0;
+    padding: 0;
+    border: none;
+    font-family: inherit;
+    font-size: 17px;
+    line-height: 1.55;
+    color: var(--dc-foreground);
+    font-weight: 450;
+    max-width: 65ch;
+  }
+  .dc-claim-text strong { font-weight: 600; }
+  .dc-claim-text em { font-style: italic; }
+  @media print {
+    .dc-claim { background: var(--dc-background); border-color: var(--dc-border); border-left-color: var(--dc-primary); }
+  }
 </style>
 </head>
 <body>
 <header>
   <h1>${escapeHtml(title)}</h1>
+  ${claimCard}
   ${metaStrip}
 </header>
 ${
@@ -647,8 +707,7 @@ ${bodyHtml}
 //   briefing-card    → SHAREABILITY (screenshot/PDF/social: self-contained hero)
 //   marginalia       → MEMORABILITY (distinctive bracket + spine motif)
 //
-// All four restrict themselves to Inter + Source Code Pro and the
-// zinc/blue palette from deepcitation-web/BRANDING.md.
+// All four use the --dc-* token system and system font stack per SDK BRANDING.md.
 
 interface ReviewVariant {
   slug: string;
@@ -657,39 +716,35 @@ interface ReviewVariant {
   css: string;
 }
 
-const REVIEW_FONT_LINKS = `<link rel="preconnect" href="https://fonts.googleapis.com">
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Source+Code+Pro:wght@400;500;600&display=swap" rel="stylesheet">`;
-
 // Structural defaults shared by every variant: reset, citation rule, table
 // primitives, code, horizontal rules, details/summary, verdict colors, and
 // the cowork notice SVG positioning. Each variant appends its own layout-
 // specific rules after this block, so the cascade lets variants override
 // anything they need without repeating the basics.
 const REVIEW_SHARED_BASE_CSS = `  * { margin: 0; padding: 0; box-sizing: border-box; }
-  h1, h2, h3 { color: #09090B; }
+  h1, h2, h3 { color: var(--dc-foreground); }
   p { margin: 0.65rem 0; }
-  a { color: #005595; text-decoration: underline; text-decoration-color: rgba(0,85,149,0.35); text-underline-offset: 2px; }
-  a:hover { text-decoration-color: #005595; }
-  [data-cite] strong { font-weight: 500; color: #005595; }
+  a { color: var(--dc-primary); text-decoration: underline; text-decoration-color: color-mix(in srgb, var(--dc-primary) 35%, transparent); text-underline-offset: 2px; }
+  a:hover { text-decoration-color: var(--dc-primary); }
+  [data-cite] strong { font-weight: 500; color: var(--dc-primary); }
   ul, ol { margin: 0.6rem 0 0.6rem 1.5rem; }
   li { margin: 0.3rem 0; }
-  pre { background: #F4F4F5; color: #18181B; padding: 1rem 1.15rem; overflow-x: auto; margin: 1rem 0; font-size: 13px; line-height: 1.7; border: 1px solid #E4E4E7; border-left: 3px solid #09090B; font-family: 'Source Code Pro', monospace; }
-  code { font-family: 'Source Code Pro', monospace; font-size: 0.88em; background: #F4F4F5; color: #09090B; padding: 1px 5px; border: 1px solid #E4E4E7; border-radius: 0; }
+  pre { background: var(--dc-muted); color: var(--dc-foreground); padding: 1rem 1.15rem; overflow-x: auto; margin: 1rem 0; font-size: 13px; line-height: 1.7; border: 1px solid var(--dc-border); border-left: 3px solid var(--dc-foreground); font-family: var(--dc-font-family-mono); }
+  code { font-family: var(--dc-font-family-mono); font-size: 0.88em; background: var(--dc-muted); color: var(--dc-foreground); padding: 1px 5px; border: 1px solid var(--dc-border); border-radius: 0; }
   pre code { background: none; border: none; padding: 0; }
-  hr { border: none; border-top: 1px solid #E4E4E7; margin: 2rem 0; }
+  hr { border: none; border-top: 1px solid var(--dc-border); margin: 2rem 0; }
   table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 14px; }
-  th, td { padding: 0.55rem 0.75rem; text-align: left; border-bottom: 1px solid #E4E4E7; }
-  th { font-family: 'Source Code Pro', monospace; font-weight: 500; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #71717A; background: transparent; border-bottom: 2px solid #09090B; }
-  tbody tr:hover { background: #F9FAFB; }
+  th, td { padding: 0.55rem 0.75rem; text-align: left; border-bottom: 1px solid var(--dc-border); }
+  th { font-family: var(--dc-font-family-mono); font-weight: 500; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--dc-muted-foreground); background: transparent; border-bottom: 2px solid var(--dc-foreground); }
+  tbody tr:hover { background: var(--dc-muted); }
   details { margin: 0.75rem 0; }
-  summary { cursor: pointer; font-weight: 500; font-size: 13px; color: #52525B; padding: 0.5rem 0; user-select: none; font-family: 'Source Code Pro', monospace; text-transform: uppercase; letter-spacing: 0.05em; }
-  summary:hover { color: #09090B; }
-  .dc-section { background: #FFFFFF; border: 1px solid #E4E4E7; padding: 1.25rem 1.5rem; margin: 1rem 0; }
-  .mono { font-family: 'Source Code Pro', monospace; font-size: 14px; font-weight: 500; }
-  .dc-verdict .v-found  { color: #10B981; }
-  .dc-verdict .v-partial { color: #D97706; }
-  .dc-verdict .v-miss   { color: #EF4444; }
+  summary { cursor: pointer; font-weight: 500; font-size: 13px; color: var(--dc-muted-foreground); padding: 0.5rem 0; user-select: none; font-family: var(--dc-font-family-mono); text-transform: uppercase; letter-spacing: 0.05em; }
+  summary:hover { color: var(--dc-foreground); }
+  .dc-section { background: var(--dc-background); border: 1px solid var(--dc-border); padding: 1.25rem 1.5rem; margin: 1rem 0; }
+  .mono { font-family: var(--dc-font-family-mono); font-size: 14px; font-weight: 500; }
+  .dc-verdict .v-found  { color: var(--dc-verified); }
+  .dc-verdict .v-partial { color: var(--dc-partial); }
+  .dc-verdict .v-miss   { color: var(--dc-destructive); }
   .dc-meta-sep { display: none; }
   .dc-cowork-notice svg { flex-shrink: 0; margin-top: 2px; }`;
 
@@ -700,9 +755,9 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     description:
       "Single column with a 5rem left gutter holding CSS-counter section numbers (01, 01.1, 01.2) aligned to each H2 and H3. Reviewers can reference sections by number, and the gutter gives an at-a-glance sense of structural depth while scrolling.",
     css: `  body {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-    color: #18181B;
-    background: #FFFFFF;
+    font-family: var(--dc-font-family);
+    color: var(--dc-foreground);
+    background: var(--dc-background);
     font-size: 16px;
     line-height: 1.65;
     -webkit-font-smoothing: antialiased;
@@ -717,10 +772,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.4rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
     font-weight: 500;
-    color: #CBD5E1;
+    color: var(--dc-border);
     letter-spacing: 0.05em;
   }
   body > header h1 {
@@ -734,27 +789,27 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     display: flex;
     flex-wrap: wrap;
     gap: 0.25rem 1.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
-    color: #71717A;
+    color: var(--dc-muted-foreground);
     margin: 0.75rem 0 0;
     padding-top: 0.85rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
   }
   .dc-meta-item { display: inline-flex; align-items: baseline; gap: 0.4rem; }
-  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.08em; color: #A1A1AA; font-size: 10px; font-weight: 500; }
-  .dc-meta-val { color: #09090B; font-weight: 500; }
-  .dc-meta-link { color: #005595; text-decoration: none; font-weight: 500; }
+  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.08em; color: var(--dc-subtle-foreground); font-size: 10px; font-weight: 500; }
+  .dc-meta-val { color: var(--dc-foreground); font-weight: 500; }
+  .dc-meta-link { color: var(--dc-primary); text-decoration: none; font-weight: 500; }
   .dc-meta-link:hover { text-decoration: underline; }
   .dc-verdict {
     display: flex;
     gap: 1.5rem;
     padding: 0.85rem 1rem;
     margin-bottom: 2.25rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
-    border: 1px solid #E4E4E7;
-    background: #FAFAFA;
+    border: 1px solid var(--dc-border);
+    background: var(--dc-muted);
   }
   h1 { font-size: 30px; font-weight: 600; letter-spacing: -0.02em; }
   h2 {
@@ -764,7 +819,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     font-weight: 600;
     margin: 2.75rem 0 0.85rem;
     padding-bottom: 0.5rem;
-    border-bottom: 1px solid #E4E4E7;
+    border-bottom: 1px solid var(--dc-border);
     letter-spacing: -0.01em;
     position: relative;
   }
@@ -773,10 +828,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.35rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
     font-weight: 500;
-    color: #005595;
+    color: var(--dc-primary);
     letter-spacing: 0.05em;
   }
   h3 {
@@ -791,36 +846,36 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.2rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     font-weight: 500;
-    color: #94A3B8;
+    color: var(--dc-subtle-foreground);
   }
   .dc-footer {
     margin: 3.5rem 0 0 -5rem;
     padding: 1.25rem 0 0 5rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
     font-size: 11px;
-    color: #A1A1AA;
+    color: var(--dc-subtle-foreground);
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     text-transform: uppercase;
     letter-spacing: 0.06em;
   }
-  .dc-footer a { color: #A1A1AA; text-decoration: none; }
-  .dc-footer a:hover { color: #52525B; text-decoration: underline; }
+  .dc-footer a { color: var(--dc-subtle-foreground); text-decoration: none; }
+  .dc-footer a:hover { color: var(--dc-muted-foreground); text-decoration: underline; }
   .dc-cowork-notice {
     display: flex;
     align-items: flex-start;
     gap: 0.6rem;
     padding: 0.65rem 0.9rem;
-    background: #F0F9FF;
-    border: 1px solid #BAE6FD;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     font-size: 13px;
     line-height: 1.5;
-    color: #005595;
+    color: var(--dc-foreground);
     margin-bottom: 1.5rem;
   }
   @media (max-width: 720px) {
@@ -835,9 +890,9 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     description:
       "Numbered-outline gutter plus a sticky verdict console that pins FOUND / PARTIAL / MISS counts to the viewport while the reviewer scrolls. Citation triggers are larger and more obviously interactive; jumping to a section via anchor scrolls it under the verdict bar with a soft :target highlight. Optimized for the active review moment — every affordance speeds the cite-by-cite walkthrough.",
     css: `  body {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-    color: #18181B;
-    background: #FFFFFF;
+    font-family: var(--dc-font-family);
+    color: var(--dc-foreground);
+    background: var(--dc-background);
     font-size: 16px;
     line-height: 1.65;
     -webkit-font-smoothing: antialiased;
@@ -853,10 +908,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.65rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     font-weight: 500;
-    color: #CBD5E1;
+    color: var(--dc-border);
     letter-spacing: 0.05em;
   }
   body > header h1 {
@@ -870,17 +925,17 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     display: flex;
     flex-wrap: wrap;
     gap: 0.25rem 1.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
-    color: #71717A;
+    color: var(--dc-muted-foreground);
     margin: 0;
     padding-top: 0.85rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
   }
   .dc-meta-item { display: inline-flex; align-items: baseline; gap: 0.4rem; }
-  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.08em; color: #A1A1AA; font-size: 10px; font-weight: 500; }
-  .dc-meta-val { color: #09090B; font-weight: 500; }
-  .dc-meta-link { color: #005595; text-decoration: none; font-weight: 500; }
+  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.08em; color: var(--dc-subtle-foreground); font-size: 10px; font-weight: 500; }
+  .dc-meta-val { color: var(--dc-foreground); font-weight: 500; }
+  .dc-meta-link { color: var(--dc-primary); text-decoration: none; font-weight: 500; }
   .dc-meta-link:hover { text-decoration: underline; }
   .dc-verdict {
     position: sticky;
@@ -890,12 +945,12 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     gap: 1.25rem;
     padding: 0.7rem 1.5rem 0.7rem 6.5rem;
     margin: 0 -1.5rem 2.25rem -6.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
     background: rgba(255, 255, 255, 0.96);
     -webkit-backdrop-filter: blur(8px);
     backdrop-filter: blur(8px);
-    border-bottom: 1px solid #E4E4E7;
+    border-bottom: 1px solid var(--dc-border);
   }
   .dc-verdict:empty { display: none; }
   .dc-verdict .v-found,
@@ -923,7 +978,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     font-weight: 600;
     margin: 2.75rem 0 0.85rem;
     padding-bottom: 0.5rem;
-    border-bottom: 1px solid #E4E4E7;
+    border-bottom: 1px solid var(--dc-border);
     letter-spacing: -0.01em;
     position: relative;
     scroll-margin-top: 5rem;
@@ -933,10 +988,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.35rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
     font-weight: 500;
-    color: #005595;
+    color: var(--dc-primary);
     letter-spacing: 0.05em;
   }
   h3 {
@@ -952,13 +1007,13 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.2rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     font-weight: 500;
-    color: #94A3B8;
+    color: var(--dc-subtle-foreground);
   }
   h2:target, h3:target {
-    background: linear-gradient(to right, rgba(0,85,149,0.07), transparent 60%);
+    background: linear-gradient(to right, color-mix(in srgb, var(--dc-primary) 7%, transparent), transparent 60%);
     padding-left: 0.5rem;
     margin-left: -0.5rem;
     transition: background-color 0.3s ease;
@@ -967,46 +1022,46 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     cursor: pointer;
     padding: 1px 4px;
     margin: 0 -1px;
-    border-bottom: 1px dotted rgba(0,85,149,0.4);
+    border-bottom: 1px dotted color-mix(in srgb, var(--dc-primary) 40%, transparent);
     transition: background-color 0.12s ease, border-color 0.12s ease;
   }
   [data-cite]:hover strong {
-    background: rgba(0,85,149,0.08);
-    border-bottom-color: #005595;
+    background: color-mix(in srgb, var(--dc-primary) 8%, transparent);
+    border-bottom-color: var(--dc-primary);
   }
   .dc-section {
-    background: #FFFFFF;
-    border: 1px solid #E4E4E7;
+    background: var(--dc-background);
+    border: 1px solid var(--dc-border);
     padding: 1.25rem 1.5rem;
     margin: 1rem 0;
     transition: border-color 0.12s ease;
   }
-  .dc-section:hover { border-color: #94A3B8; }
+  .dc-section:hover { border-color: var(--dc-subtle-foreground); }
   .dc-footer {
     margin: 3.5rem 0 0 -5rem;
     padding: 1.25rem 0 0 5rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
     font-size: 11px;
-    color: #A1A1AA;
+    color: var(--dc-subtle-foreground);
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     text-transform: uppercase;
     letter-spacing: 0.06em;
   }
-  .dc-footer a { color: #A1A1AA; text-decoration: none; }
-  .dc-footer a:hover { color: #52525B; text-decoration: underline; }
+  .dc-footer a { color: var(--dc-subtle-foreground); text-decoration: none; }
+  .dc-footer a:hover { color: var(--dc-muted-foreground); text-decoration: underline; }
   .dc-cowork-notice {
     display: flex;
     align-items: flex-start;
     gap: 0.6rem;
     padding: 0.65rem 0.9rem;
-    background: #F0F9FF;
-    border: 1px solid #BAE6FD;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     font-size: 13px;
     line-height: 1.5;
-    color: #005595;
+    color: var(--dc-foreground);
     margin-bottom: 1.5rem;
   }
   @media (max-width: 720px) {
@@ -1022,9 +1077,9 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     description:
       "A self-contained hero panel (title + meta + verdict) sits in the first viewport so a screenshot of the top of the report conveys the entire status at a glance. Verdict counts render as full-width tinted chips for thumbnail legibility. Title is framed with FileLasso's bracket motif. A print stylesheet keeps headings and tables intact when exported to PDF. Optimized for the handoff moment — the report has to survive being cropped, screenshotted, and pasted into Slack.",
     css: `  body {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-    color: #18181B;
-    background: #FFFFFF;
+    font-family: var(--dc-font-family);
+    color: var(--dc-foreground);
+    background: var(--dc-background);
     font-size: 15px;
     line-height: 1.65;
     -webkit-font-smoothing: antialiased;
@@ -1037,8 +1092,8 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: relative;
     padding: 1.85rem 2rem 1.5rem;
     margin-bottom: 0;
-    background: #FAFAFA;
-    border: 1px solid #E4E4E7;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     border-bottom: none;
   }
   body > header::before,
@@ -1047,7 +1102,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     width: 18px;
     height: 18px;
-    border: 2px solid #005595;
+    border: 2px solid var(--dc-primary);
     pointer-events: none;
   }
   body > header::before {
@@ -1068,32 +1123,32 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     letter-spacing: -0.02em;
     line-height: 1.18;
     margin-bottom: 1rem;
-    color: #09090B;
+    color: var(--dc-foreground);
   }
   body > header .dc-meta {
     display: flex;
     flex-wrap: wrap;
     gap: 0.4rem 1.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     margin: 0;
     padding-top: 0.85rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
   }
   .dc-meta-item { display: inline-flex; align-items: baseline; gap: 0.4rem; }
-  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.1em; color: #A1A1AA; font-size: 10px; font-weight: 500; }
-  .dc-meta-val { color: #09090B; font-weight: 600; }
-  .dc-meta-link { color: #005595; text-decoration: none; font-weight: 600; }
+  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.1em; color: var(--dc-subtle-foreground); font-size: 10px; font-weight: 500; }
+  .dc-meta-val { color: var(--dc-foreground); font-weight: 600; }
+  .dc-meta-link { color: var(--dc-primary); text-decoration: none; font-weight: 600; }
   .dc-meta-link:hover { text-decoration: underline; }
   .dc-verdict {
     display: flex;
     gap: 0;
     padding: 0;
     margin: 0 0 2.25rem;
-    background: #FFFFFF;
-    border: 1px solid #E4E4E7;
+    background: var(--dc-background);
+    border: 1px solid var(--dc-border);
     border-top: none;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     position: relative;
   }
   .dc-verdict::after {
@@ -1103,7 +1158,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     right: -1px;
     width: 18px;
     height: 18px;
-    border: 2px solid #005595;
+    border: 2px solid var(--dc-primary);
     border-left: none;
     border-top: none;
     pointer-events: none;
@@ -1121,12 +1176,12 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     text-transform: uppercase;
     letter-spacing: 0.08em;
     font-weight: 600;
-    border-right: 1px solid #E4E4E7;
+    border-right: 1px solid var(--dc-border);
   }
   .dc-verdict .v-miss { border-right: none; }
-  .dc-verdict .v-found  { color: #047857; background: #F0FDF4; }
-  .dc-verdict .v-partial { color: #B45309; background: #FFFBEB; }
-  .dc-verdict .v-miss   { color: #B91C1C; background: #FEF2F2; }
+  .dc-verdict .v-found  { color: var(--dc-verified); background: var(--dc-verified-bg); }
+  .dc-verdict .v-partial { color: var(--dc-partial); background: var(--dc-partial-bg); }
+  .dc-verdict .v-miss   { color: var(--dc-destructive); background: var(--dc-destructive-bg); }
   h1 { font-size: 26px; font-weight: 600; letter-spacing: -0.02em; margin: 2rem 0 0.5rem; }
   h2 {
     counter-increment: h2section;
@@ -1135,17 +1190,17 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     font-weight: 600;
     margin: 2.5rem 0 0.75rem;
     padding-bottom: 0.5rem;
-    border-bottom: 1px solid #E4E4E7;
+    border-bottom: 1px solid var(--dc-border);
     letter-spacing: -0.01em;
     page-break-after: avoid;
     break-after: avoid-page;
   }
   h2::before {
     content: counter(h2section, decimal-leading-zero) "  ";
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     font-weight: 500;
-    color: #005595;
+    color: var(--dc-primary);
     letter-spacing: 0.06em;
     margin-right: 0.5rem;
     vertical-align: 0.18em;
@@ -1157,31 +1212,31 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     gap: 0.6rem;
     padding: 0.65rem 0.9rem;
     margin: -0.5rem 0 1.5rem;
-    background: #F0F9FF;
-    border: 1px solid #BAE6FD;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     font-size: 13px;
     line-height: 1.5;
-    color: #005595;
+    color: var(--dc-foreground);
   }
   .dc-footer {
     margin: 3.5rem 0 0;
     padding: 1.25rem 0 0;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
     font-size: 11px;
-    color: #A1A1AA;
+    color: var(--dc-subtle-foreground);
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     text-transform: uppercase;
     letter-spacing: 0.06em;
   }
-  .dc-footer a { color: #A1A1AA; text-decoration: none; }
-  .dc-footer a:hover { color: #52525B; text-decoration: underline; }
+  .dc-footer a { color: var(--dc-subtle-foreground); text-decoration: none; }
+  .dc-footer a:hover { color: var(--dc-muted-foreground); text-decoration: underline; }
   @media print {
     body { max-width: none; padding: 0.5in; font-size: 11pt; }
     body > header { background: transparent; }
-    body > header::before, body > header::after, .dc-verdict::after { border-color: #09090B; }
+    body > header::before, body > header::after, .dc-verdict::after { border-color: var(--dc-foreground); }
     .dc-verdict .v-found,
     .dc-verdict .v-partial,
     .dc-verdict .v-miss {
@@ -1199,9 +1254,9 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     description:
       "Bracket-framed title, a §-marginalia gutter for every section, and a thin two-tone spine running the full document height along the left edge. Custom selection color in brand blue, corner brackets on the verdict box, and a bracketed footer. The signature element is the spine: any screenshot taken from inside the document will carry FileLasso's blue ledger line. Optimized for the months-later recognition moment — when a colleague spots a thumbnail and instantly knows what tool produced it.",
     css: `  body {
-    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-    color: #18181B;
-    background: #FFFFFF;
+    font-family: var(--dc-font-family);
+    color: var(--dc-foreground);
+    background: var(--dc-background);
     font-size: 16px;
     line-height: 1.7;
     -webkit-font-smoothing: antialiased;
@@ -1218,7 +1273,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     top: 3.25rem;
     bottom: 4rem;
     width: 2px;
-    background: #005595;
+    background: var(--dc-primary);
     pointer-events: none;
   }
   body::after {
@@ -1228,20 +1283,20 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     top: 3.25rem;
     bottom: 4rem;
     width: 1px;
-    background: #E4E4E7;
+    background: var(--dc-border);
     pointer-events: none;
   }
-  ::selection { background: rgba(0,85,149,0.18); color: #09090B; }
+  ::selection { background: color-mix(in srgb, var(--dc-primary) 18%, transparent); color: var(--dc-foreground); }
   body > header { margin-bottom: 2.5rem; position: relative; }
   body > header::before {
     content: "\\00a7";
     position: absolute;
     left: -5.15rem;
     top: 0.45rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 18px;
     font-weight: 500;
-    color: #005595;
+    color: var(--dc-primary);
     line-height: 1;
   }
   body > header h1 {
@@ -1249,12 +1304,12 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     font-weight: 600;
     letter-spacing: -0.025em;
     line-height: 1.12;
-    color: #09090B;
+    color: var(--dc-foreground);
   }
   body > header h1::before {
     content: "[";
-    font-family: 'Source Code Pro', monospace;
-    color: #005595;
+    font-family: var(--dc-font-family-mono);
+    color: var(--dc-primary);
     font-weight: 400;
     margin-right: 0.55rem;
     font-size: 0.85em;
@@ -1262,8 +1317,8 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
   }
   body > header h1::after {
     content: "]";
-    font-family: 'Source Code Pro', monospace;
-    color: #005595;
+    font-family: var(--dc-font-family-mono);
+    color: var(--dc-primary);
     font-weight: 400;
     margin-left: 0.55rem;
     font-size: 0.85em;
@@ -1273,27 +1328,27 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     display: flex;
     flex-wrap: wrap;
     gap: 0.35rem 1.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
-    color: #71717A;
+    color: var(--dc-muted-foreground);
     margin: 1.25rem 0 0;
     padding-top: 1rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
   }
   .dc-meta-item { display: inline-flex; align-items: baseline; gap: 0.45rem; }
-  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.1em; color: #A1A1AA; font-size: 10px; font-weight: 500; }
-  .dc-meta-val { color: #09090B; font-weight: 500; }
-  .dc-meta-link { color: #005595; text-decoration: none; font-weight: 500; }
+  .dc-meta-key { text-transform: uppercase; letter-spacing: 0.1em; color: var(--dc-subtle-foreground); font-size: 10px; font-weight: 500; }
+  .dc-meta-val { color: var(--dc-foreground); font-weight: 500; }
+  .dc-meta-link { color: var(--dc-primary); text-decoration: none; font-weight: 500; }
   .dc-meta-link:hover { text-decoration: underline; }
   .dc-verdict {
     display: flex;
     gap: 1.5rem;
     padding: 1rem 1.25rem;
     margin: 0 0 2.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 12px;
-    background: #FAFAFA;
-    border: 1px solid #E4E4E7;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     position: relative;
   }
   .dc-verdict:empty { display: none; }
@@ -1303,7 +1358,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     width: 12px;
     height: 12px;
-    border: 1.5px solid #005595;
+    border: 1.5px solid var(--dc-primary);
     pointer-events: none;
   }
   .dc-verdict::before {
@@ -1326,7 +1381,7 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     font-weight: 600;
     margin: 3rem 0 1rem;
     padding-bottom: 0.5rem;
-    border-bottom: 1px solid #E4E4E7;
+    border-bottom: 1px solid var(--dc-border);
     letter-spacing: -0.015em;
     position: relative;
   }
@@ -1335,10 +1390,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5.5rem;
     top: 0.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 11px;
     font-weight: 500;
-    color: #005595;
+    color: var(--dc-primary);
     letter-spacing: 0.06em;
     font-variant-numeric: tabular-nums;
   }
@@ -1354,10 +1409,10 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     position: absolute;
     left: -5rem;
     top: 0.25rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     font-size: 10px;
     font-weight: 500;
-    color: #94A3B8;
+    color: var(--dc-subtle-foreground);
     font-variant-numeric: tabular-nums;
   }
   .dc-cowork-notice {
@@ -1365,30 +1420,30 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
     align-items: flex-start;
     gap: 0.6rem;
     padding: 0.7rem 0.95rem;
-    background: #F0F9FF;
-    border: 1px solid #BAE6FD;
+    background: var(--dc-muted);
+    border: 1px solid var(--dc-border);
     font-size: 13px;
     line-height: 1.5;
-    color: #005595;
+    color: var(--dc-foreground);
     margin-bottom: 1.5rem;
   }
   .dc-footer {
     margin: 4rem 0 0 -5rem;
     padding: 1.5rem 0 0 5rem;
-    border-top: 1px solid #E4E4E7;
+    border-top: 1px solid var(--dc-border);
     font-size: 11px;
-    color: #A1A1AA;
+    color: var(--dc-subtle-foreground);
     display: flex;
     align-items: center;
     gap: 0.5rem;
-    font-family: 'Source Code Pro', monospace;
+    font-family: var(--dc-font-family-mono);
     text-transform: uppercase;
     letter-spacing: 0.08em;
   }
-  .dc-footer::before { content: "[\\00a0"; color: #CBD5E1; }
-  .dc-footer::after { content: "\\00a0]"; color: #CBD5E1; }
-  .dc-footer a { color: #A1A1AA; text-decoration: none; }
-  .dc-footer a:hover { color: #52525B; text-decoration: underline; }
+  .dc-footer::before { content: "[\\00a0"; color: var(--dc-border); }
+  .dc-footer::after { content: "\\00a0]"; color: var(--dc-border); }
+  .dc-footer a { color: var(--dc-subtle-foreground); text-decoration: none; }
+  .dc-footer a:hover { color: var(--dc-muted-foreground); text-decoration: underline; }
   @media (max-width: 720px) {
     body { padding: 2.25rem 1.25rem 3rem; }
     body::before, body::after { display: none; }
@@ -1402,10 +1457,9 @@ const REVIEW_VARIANTS: ReviewVariant[] = [
  * Produce design-review variants of an already-rendered report HTML.
  *
  * Each variant is the same body markup — same meta strip, same verdict
- * banner, same citation spans — with a fully replaced `<style>` block and
- * the shared font `<link>` tags injected into `<head>`. The CDN runtime
- * script and `<<<CITATION_DATA>>>` block are left intact, so popovers still
- * function for design review.
+ * banner, same citation spans — with a fully replaced `<style>` block.
+ * The CDN runtime script and `<<<CITATION_DATA>>>` block are left intact,
+ * so popovers still function for design review.
  *
  * Callers typically run this AFTER `verifyHtml` has written the main file,
  * so variants get the same runtime injection and verification payload.
@@ -1414,9 +1468,8 @@ export function generateReviewVariants(
   mainHtml: string,
 ): Array<{ slug: string; label: string; description: string; html: string }> {
   return REVIEW_VARIANTS.map(v => {
-    const fullCss = `${REVIEW_SHARED_BASE_CSS}\n${v.css}`;
-    let html = mainHtml.replace(/<style>[\s\S]*?<\/style>/, `<style>\n${fullCss}\n</style>`);
-    html = html.replace(/<\/head>/, `${REVIEW_FONT_LINKS}\n</head>`);
+    const fullCss = `${DC_ROOT_TOKENS}\n${REVIEW_SHARED_BASE_CSS}\n${v.css}`;
+    const html = mainHtml.replace(/<style>[\s\S]*?<\/style>/, `<style>\n${fullCss}\n</style>`);
     return { slug: v.slug, label: v.label, description: v.description, html };
   });
 }
@@ -1428,7 +1481,7 @@ export function generateReviewVariants(
  * Returns a full HTML document with the chosen style shell.
  */
 export function markdownToHtml(markdown: string, options: MarkdownToHtmlOptions = {}): string {
-  const { style = "report", audience = "general" } = options;
+  const { style = "report" } = options;
 
   const blocks = parseBlocks(markdown);
 
@@ -1440,7 +1493,7 @@ export function markdownToHtml(markdown: string, options: MarkdownToHtmlOptions
   let bodyParts: string[];
 
   if (style === "report") {
-    bodyParts = buildReportBody(blocks, audience);
+    bodyParts = buildReportBody(blocks);
   } else {
     bodyParts = blocks.map(renderBlock);
   }
@@ -1453,15 +1506,15 @@ export function markdownToHtml(markdown: string, options: MarkdownToHtmlOptions
   bodyHtml = wrapCitationMarkers(bodyHtml, options.sourceMatchMap);
 
   if (style === "report") {
-    return reportShell(title, bodyHtml, audience, options);
+    return reportShell(title, bodyHtml, options);
   }
   return plainShell(title, bodyHtml, { cowork: options.cowork });
 }
 
 // ── Report body builder (progressive disclosure) ───────────────────
 
-function buildReportBody(blocks: Block[], audience: AudiencePreset): string[] {
-  const cfg = AUDIENCE_CONFIG[audience];
+function buildReportBody(blocks: Block[]): string[] {
+  const cfg = { tier2Open: true };
   const parts: string[] = [];
 
   // Split blocks into sections by H2
diff --git a/src/cli/publish.ts b/src/cli/publish.ts
deleted file mode 100644
index 366c00b0..00000000
--- a/src/cli/publish.ts
+++ /dev/null
@@ -1,291 +0,0 @@
-/**
- * `deepcitation publish` — upload a verified HTML + `verify-response.json`
- * pair to the DeepCitation hosted reports endpoint.
- *
- * Two entry points share the guards in `publishInMemory`:
- *   - The standalone `publish` subcommand (this file's default export),
- *     which reads the two files from disk.
- *   - The `verify` auto-publish path in `commands.ts`, which hands the
- *     freshly verified HTML + JSON straight from memory.
- *
- * Default visibility is `private` (owner-only — shows up on My
- * Verifications but has no shareable link). Callers opt into `unlisted`
- * (shareable by link) or `public` (listed, Portal-only) explicitly.
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
-import type {
-  PublishVerificationReportOptions,
-  VerificationReport,
-  VerificationReportVisibility,
-} from "../client/types.js";
-import { sanitizeForLog } from "../utils/logSafety.js";
-import { die, normalizeShortFlags, parseArgs } from "./cliUtils.js";
-import { createClient, requireAuth } from "./commands.js";
-import { runCitationLintChecks } from "./lint.js";
-
-export const PUBLISH_HELP = `Usage: deepcitation publish --html <file> --vr <file> [options]
-
-Upload an already-verified HTML report and its companion verify-response.json
-to the DeepCitation hosted reports endpoint. Returns a share URL.
-
-Default visibility is "private" — the report shows up on My Verifications
-but has no shareable link. Pass "--vis unlisted" for a share-by-link URL,
-or "--vis public" to list it (Portal session required for public).
-
-Options:
-  --html <file>             Path to the verified HTML produced by \`verify\`
-  --vr, --verify-response <file>
-                            Path to verify-response.json (sibling of the HTML)
-  --vis, --visibility <v>   private | unlisted | public (default: private)
-  --title <text>            Optional human-readable title
-  --attachment-id <id>      Optional source attachmentId to link back
-  --lint                    Run citation-syntax lint on the HTML before upload
-  -d, --dry-run             Do not POST; print what would be uploaded and exit
-  -h, --help                Show this help message
-
-Size limits (enforced locally to avoid a server round-trip):
-  HTML  ≤ 5 MB
-  JSON  ≤ 2 MB
-
-Examples:
-  deepcitation publish --html report-verified.html --vr report-verify-response.json
-  deepcitation publish --html r.html --vr r.json --vis public --title "Q2 report"
-  deepcitation publish --html r.html --vr r.json --lint
-  deepcitation publish --html r.html --vr r.json --dry-run
-`;
-
-export const MAX_HTML_BYTES = 5 * 1024 * 1024;
-export const MAX_JSON_BYTES = 2 * 1024 * 1024;
-
-export const ALLOWED_VISIBILITIES: readonly VerificationReportVisibility[] = ["private", "unlisted", "public"];
-
-/**
- * Reject HTML that contains a literal DeepCitation API key. Uploading a
- * key — even to an unlisted share URL — is a one-way leak: anyone who
- * guesses the ID can pull the key out. Fail closed before the POST.
- *
- * Minimum: 6-char prefix ("sk-dc-") + 14 alphanum chars = 20 chars total.
- * Keep in sync with VALID_API_KEY_RE in cliUtils.ts which anchors the same
- * minimum for format validation.
- */
-export const API_KEY_LEAK_RE = /sk-dc-[a-zA-Z0-9]{14,}/;
-
-/**
- * Publish an in-memory HTML + verify-response.json pair. Shared by the
- * standalone `publish` subcommand and the one-shot `verify --pub` flag.
- *
- * Enforces the same fail-closed guards regardless of entry point:
- * size caps, API-key leak scan, JSON parse check. Writes a publish
- * receipt into `.deepcitation/publish-<id>.json` on success.
- */
-export async function publishInMemory(params: {
-  html: string;
-  verifyResponseJson: string;
-  visibility: VerificationReportVisibility;
-  title?: string;
-  attachmentId?: string;
-  /**
-   * Optional path of the HTML file the caller wrote to disk alongside
-   * this publish. Recorded in the receipt so audit/re-publish tooling
-   * can find the original artifact.
-   */
-  htmlSourcePath?: string;
-}): Promise<VerificationReport> {
-  const htmlBytes = Buffer.byteLength(params.html, "utf-8");
-  const jsonBytes = Buffer.byteLength(params.verifyResponseJson, "utf-8");
-  if (htmlBytes > MAX_HTML_BYTES) {
-    throw new Error(`HTML exceeds ${MAX_HTML_BYTES} bytes (got ${htmlBytes}). Cannot publish.`);
-  }
-  if (jsonBytes > MAX_JSON_BYTES) {
-    throw new Error(`verify-response.json exceeds ${MAX_JSON_BYTES} bytes (got ${jsonBytes}). Cannot publish.`);
-  }
-  if (API_KEY_LEAK_RE.test(params.html)) {
-    throw new Error(
-      "HTML contains a DeepCitation API key (sk-dc-...). Refusing to publish — " +
-        "remove the key from the report first. This rule is fail-closed and cannot be bypassed.",
-    );
-  }
-  try {
-    JSON.parse(params.verifyResponseJson);
-  } catch (err) {
-    throw new Error(`verify-response.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-  }
-
-  const { apiKey } = await requireAuth();
-  const dc = await createClient(apiKey);
-
-  const options: PublishVerificationReportOptions = {
-    visibility: params.visibility,
-    ...(params.title ? { title: params.title } : {}),
-    ...(params.attachmentId ? { attachmentId: params.attachmentId } : {}),
-  };
-
-  const report = await dc.publishVerificationReport(params.html, params.verifyResponseJson, options);
-
-  console.error(`  id:        ${report.id}`);
-  console.error(`  shareUrl:  ${report.shareUrl}`);
-
-  // Write a local receipt for audit / re-publish tooling. The upload already
-  // succeeded at this point, so a disk error here must not surface as a
-  // publish failure — emit a warning and continue.
-  try {
-    const receiptDir = resolve(".deepcitation");
-    if (!existsSync(receiptDir)) mkdirSync(receiptDir, { recursive: true });
-    const receiptPath = resolve(receiptDir, `publish-${report.id}.json`);
-    writeFileSync(
-      receiptPath,
-      JSON.stringify(
-        {
-          id: report.id,
-          shareUrl: report.shareUrl,
-          htmlUrl: report.htmlUrl,
-          jsonUrl: report.jsonUrl,
-          visibility: report.visibility,
-          title: report.title,
-          createdAt: report.createdAt,
-          sources: params.htmlSourcePath
-            ? { html: params.htmlSourcePath, htmlName: basename(params.htmlSourcePath) }
-            : undefined,
-        },
-        null,
-        2,
-      ),
-    );
-    console.error(`  receipt:   ${receiptPath}`);
-  } catch {
-    console.error("  Warning: could not write publish receipt to .deepcitation/ — report was uploaded successfully.");
-  }
-  return report;
-}
-
-export function resolveVisibility(value: string | undefined, helpText: string): VerificationReportVisibility {
-  if (!value) return "private";
-  if (!ALLOWED_VISIBILITIES.includes(value as VerificationReportVisibility)) {
-    die(`Invalid --vis "${sanitizeForLog(value)}". Allowed: ${ALLOWED_VISIBILITIES.join(", ")}`, helpText);
-  }
-  return value as VerificationReportVisibility;
-}
-
-export async function publish(argv: string[]): Promise<void> {
-  const normalized = normalizeShortFlags(argv);
-
-  // Boolean flags — strip before parseArgs so they don't consume the next token.
-  const dryRun = normalized.includes("--dry-run");
-  const lintFirst = normalized.includes("--lint");
-  const booleans = new Set(["--dry-run", "--lint"]);
-  const filteredArgv = normalized.filter(a => !booleans.has(a));
-
-  const args = parseArgs(filteredArgv, PUBLISH_HELP);
-
-  const htmlPath = args.html;
-  const jsonPath = args["verify-response"];
-  if (!htmlPath) die("--html is required", PUBLISH_HELP);
-  if (!jsonPath) die("--vr (--verify-response) is required", PUBLISH_HELP);
-
-  const htmlResolved = resolve(htmlPath);
-  const jsonResolved = resolve(jsonPath);
-  if (!existsSync(htmlResolved)) die(`HTML file not found: ${sanitizeForLog(htmlPath)}`, PUBLISH_HELP);
-  if (!existsSync(jsonResolved)) die(`verify-response.json not found: ${sanitizeForLog(jsonPath)}`, PUBLISH_HELP);
-
-  // Read into buffers first so the size check uses the same bytes that will
-  // be uploaded — no TOCTOU window between stat and read.
-  const htmlBuf = readFileSync(htmlResolved);
-  const jsonBuf = readFileSync(jsonResolved);
-  if (htmlBuf.byteLength > MAX_HTML_BYTES) {
-    die(`HTML exceeds ${MAX_HTML_BYTES} bytes (got ${htmlBuf.byteLength}). Cannot publish.`, PUBLISH_HELP);
-  }
-  if (jsonBuf.byteLength > MAX_JSON_BYTES) {
-    die(
-      `verify-response.json exceeds ${MAX_JSON_BYTES} bytes (got ${jsonBuf.byteLength}). Cannot publish.`,
-      PUBLISH_HELP,
-    );
-  }
-
-  const html = htmlBuf.toString("utf-8");
-  const verifyResponseJson = jsonBuf.toString("utf-8");
-
-  // Fail-closed: never upload an HTML body that has an API key in it.
-  if (API_KEY_LEAK_RE.test(html)) {
-    die(
-      `HTML file contains a DeepCitation API key (sk-dc-...). Refusing to publish — ` +
-        `remove the key from the file first. This rule is fail-closed and cannot be bypassed.`,
-      PUBLISH_HELP,
-    );
-  }
-
-  // JSON shape guard — local parse now saves a 400 round-trip later.
-  try {
-    JSON.parse(verifyResponseJson);
-  } catch (err) {
-    die(`verify-response.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`, PUBLISH_HELP);
-  }
-
-  // Optional citation-syntax pre-check on the HTML body. Uses the same
-  // ruleset as `deepcitation lint`, so an agent that passes lint on the
-  // draft markdown will pass it on the verified HTML.
-  if (lintFirst) {
-    const findings = runCitationLintChecks(html);
-    const errs = findings.filter(f => f.severity === "ERR");
-    if (errs.length > 0) {
-      for (const f of errs) {
-        const id = f.citationId !== undefined ? ` [${f.citationId}]` : "";
-        console.error(`  lint ERR ${f.rule}${id}: ${f.message}`);
-      }
-      die(`--lint found ${errs.length} citation-syntax error(s); refusing to publish`, PUBLISH_HELP);
-    }
-    const warns = findings.filter(f => f.severity === "WARN");
-    if (warns.length > 0) {
-      console.error(`  lint: ${warns.length} warning(s) (not blocking)`);
-    } else {
-      console.error(`  lint: clean`);
-    }
-  }
-
-  const visibility = resolveVisibility(args.visibility, PUBLISH_HELP);
-  const title = args.title;
-  const attachmentId = args["attachment-id"];
-
-  if (dryRun) {
-    console.error(`Dry run — not uploading.`);
-    console.error(`  html:       ${htmlResolved} (${htmlBuf.byteLength} bytes)`);
-    console.error(`  vr:         ${jsonResolved} (${jsonBuf.byteLength} bytes)`);
-    console.error(`  visibility: ${visibility}`);
-    if (title) console.error(`  title:      ${title}`);
-    if (attachmentId) console.error(`  attachment: ${attachmentId}`);
-    // Structured dry-run payload on stdout so test and agent callers can parse it.
-    console.log(
-      JSON.stringify(
-        {
-          dryRun: true,
-          htmlPath: htmlResolved,
-          verifyResponsePath: jsonResolved,
-          htmlBytes: htmlBuf.byteLength,
-          jsonBytes: jsonBuf.byteLength,
-          visibility,
-          title,
-          attachmentId,
-        },
-        null,
-        2,
-      ),
-    );
-    return;
-  }
-
-  console.error(`Publishing verification report (${visibility})...`);
-  try {
-    const report = await publishInMemory({
-      html,
-      verifyResponseJson,
-      visibility,
-      title,
-      attachmentId,
-      htmlSourcePath: htmlResolved,
-    });
-    console.log(report.shareUrl);
-  } catch (err) {
-    die(err instanceof Error ? err.message : String(err), PUBLISH_HELP);
-  }
-}
diff --git a/src/client/DeepCitation.ts b/src/client/DeepCitation.ts
index da9a8bb4..2ed1998f 100644
--- a/src/client/DeepCitation.ts
+++ b/src/client/DeepCitation.ts
@@ -20,6 +20,7 @@ import type {
   ConvertedPdfDownloadPolicy,
   ConvertFileInput,
   ConvertFileResponse,
+  CreateReportOptions,
   DeepCitationConfig,
   DeepCitationLogger,
   DeleteAttachmentResponse,
@@ -31,7 +32,6 @@ import type {
   PrepareAttachmentsResult,
   PrepareConvertedFileOptions,
   PrepareUrlOptions,
-  PublishVerificationReportOptions,
   UploadFileOptions,
   UploadFileResponse,
   VerificationReport,
@@ -1328,89 +1328,55 @@ export class DeepCitation {
   }
 
   /**
-   * Publish a verified HTML report and its companion `verify-response.json`
-   * to the DeepCitation hosted reports endpoint. HTML and JSON are stored
-   * as independent artifacts under a single report ID so consumers can
-   * fetch each half on its own (e.g. browsers pull HTML, third-party
-   * verifiers pull JSON).
+   * Submit raw LLM output to the DeepCitation server, which parses citations,
+   * verifies them against the source attachment, renders a self-contained HTML
+   * report, and stores it. Returns the hosted `VerificationReport` immediately.
    *
-   * The `deepcitation verify` CLI calls this automatically for every
-   * successful run so reports show up on "My Verifications". Default
-   * server-side visibility is `"private"` (owner-only); callers opt
-   * into `"unlisted"` (shareable by link) or `"public"` (listed,
-   * Firebase-session only) explicitly.
-   *
-   * @param html - The merged verified HTML produced by `deepcitation verify`
-   * @param verifyResponseJson - The `verify-response.json` string produced by the same run
-   * @param options - Visibility, title, and optional source attachment link
+   * @param attachmentId - The attachment ID returned by `prepareAttachments` or `prepareUrl`
+   * @param llmOutput - Raw LLM response string including the `<<<CITATION_DATA>>>` block
+   * @param options - Visibility and optional title
    * @returns The hosted `VerificationReport` with `shareUrl`, `htmlUrl`, `jsonUrl`
    *
    * @example
    * ```typescript
-   * const html = readFileSync("report-verified.html", "utf-8");
-   * const json = readFileSync("report-verify-response.json", "utf-8");
-   * const report = await deepcitation.publishVerificationReport(html, json, {
+   * const report = await deepcitation.createReport(attachmentId, llmOutput, {
    *   visibility: "unlisted",
    *   title: "Q2 verification summary",
    * });
    * console.log(report.shareUrl);
    * ```
    */
-  async publishVerificationReport(
-    html: string,
-    verifyResponseJson: string,
-    options?: PublishVerificationReportOptions,
+  async createReport(
+    attachmentId: string,
+    llmOutput: string,
+    options?: CreateReportOptions,
   ): Promise<VerificationReport> {
-    if (typeof html !== "string" || html.length === 0) {
-      throw new ValidationError("html must be a non-empty string");
+    if (!attachmentId || typeof attachmentId !== "string") {
+      throw new ValidationError("attachmentId must be a non-empty string");
     }
-    if (typeof verifyResponseJson !== "string" || verifyResponseJson.length === 0) {
-      throw new ValidationError("verifyResponseJson must be a non-empty string");
-    }
-    // Parse guard — fail fast on the client instead of forcing a 400 round-trip.
-    try {
-      JSON.parse(verifyResponseJson);
-    } catch (err) {
-      throw new ValidationError(
-        `verifyResponseJson is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
-      );
+    if (!llmOutput || typeof llmOutput !== "string") {
+      throw new ValidationError("llmOutput must be a non-empty string");
     }
 
-    const formData = new FormData();
-    formData.append("html", new Blob([html], { type: "text/html" }), "verified.html");
-    formData.append(
-      "verify_response_json",
-      new Blob([verifyResponseJson], { type: "application/json" }),
-      "verify-response.json",
-    );
-    if (options?.visibility) formData.append("visibility", options.visibility);
-    if (options?.title) formData.append("title", options.title);
-    if (options?.attachmentId) formData.append("attachmentId", options.attachmentId);
-
-    this.logger.info?.("Publishing verification report", {
-      visibility: options?.visibility ?? "private",
-      htmlBytes: html.length,
-      jsonBytes: verifyResponseJson.length,
-    });
+    const body: Record<string, string> = { attachmentId, llmOutput };
+    if (options?.visibility) body.visibility = options.visibility;
+    if (options?.title) body.title = options.title;
 
-    const response = await this._fetch(`${this.apiUrl}/v1/verification-reports`, {
+    const response = await this._fetch(`${this.apiUrl}/v1/reports`, {
       method: "POST",
-      headers: { ...this.baseHeaders() },
-      body: formData,
+      headers: { ...this.baseHeaders(), "Content-Type": "application/json" },
+      body: JSON.stringify(body),
     });
     this.checkLatestVersion(response);
     this.checkUsageWarning(response);
 
     if (!response.ok) {
-      this.logger.error?.("Publish verification report failed", { status: response.status });
-      throw await createApiError(response, "Publish verification report");
+      this.logger.error?.("Create report failed", { attachmentId, status: response.status });
+      throw await createApiError(response, "Create report");
     }
 
     const result = (await response.json()) as VerificationReport;
-    this.logger.info?.("Publish verification report complete", {
-      id: result.id,
-      shareUrl: result.shareUrl,
-    });
+    this.logger.info?.("Create report complete", { id: result.id, shareUrl: result.shareUrl });
     return result;
   }
 }
diff --git a/src/client/index.ts b/src/client/index.ts
index be1766d0..ec99bf67 100644
--- a/src/client/index.ts
+++ b/src/client/index.ts
@@ -14,6 +14,7 @@ export type {
   ConvertedPdfDownloadPolicy,
   ConvertFileInput,
   ConvertFileResponse,
+  CreateReportOptions,
   DeepCitationConfig,
   DeepCitationLogger,
   DeleteAttachmentResponse,
@@ -26,7 +27,6 @@ export type {
   PrepareConvertedFileOptions,
   PreparedAttachment,
   PrepareUrlOptions,
-  PublishVerificationReportOptions,
   UploadFileOptions,
   UploadFileResponse,
   UrlCacheInfo,
diff --git a/src/client/types.ts b/src/client/types.ts
index 6c90eba7..7ca90a24 100644
--- a/src/client/types.ts
+++ b/src/client/types.ts
@@ -532,16 +532,13 @@ export interface AttachmentResponse {
 export type VerificationReportVisibility = "private" | "unlisted" | "public";
 
 /**
- * Options when publishing a verification report via
- * `DeepCitation.publishVerificationReport`.
+ * Options for `DeepCitation.createReport`.
  */
-export interface PublishVerificationReportOptions {
-  /** Visibility of the hosted report. Defaults to `"unlisted"` server-side. */
+export interface CreateReportOptions {
+  /** Visibility of the report. Defaults to `"private"` (owner-only). */
   visibility?: VerificationReportVisibility;
-  /** Optional human-readable title to surface in lists and metadata. */
+  /** Optional human-readable title shown in the My Reports list. */
   title?: string;
-  /** Optional link back to the source attachment. */
-  attachmentId?: string;
 }
 
 /**
diff --git a/src/index.ts b/src/index.ts
index b17f0e41..8f887a26 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -112,6 +112,8 @@ export {
   CITATION_Y_PADDING,
   generateCitationInstanceId,
 } from "./react/utils.js";
+export type { RenderVerifiedHtmlOptions } from "./render/renderVerifiedHtml.js";
+export { renderVerifiedHtml } from "./render/renderVerifiedHtml.js";
 // Rendering port (prepare-once, render-many pattern)
 export {
   type CitationAdapter,
@@ -120,7 +122,6 @@ export {
   prepareCitations,
   type ResolvedCitation,
 } from "./rendering/prepareCitations.js";
-
 // Types
 export type { DeepTextItem, ScreenBox } from "./types/boxes.js";
 export type {
@@ -169,7 +170,6 @@ export type {
   UrlVerificationResult,
   Verification,
 } from "./types/verification.js";
-
 // Utilities
 export { getCitationKey, getVerificationKey } from "./utils/citationKey.js";
 export {
diff --git a/src/react/ZoomToolbar.tsx b/src/react/ZoomToolbar.tsx
index e076c822..433b5e47 100644
--- a/src/react/ZoomToolbar.tsx
+++ b/src/react/ZoomToolbar.tsx
@@ -55,7 +55,7 @@ export interface ZoomToolbarProps {
   locatePulseKey?: number;
 }
 
-type LocatePulseStage = "idle" | "grow" | "settle";
+type LocatePulseStage = "idle" | "flash" | "settle";
 
 /** Shared card style for both the zoom card and the standalone locate card. */
 const CARD_CLASSES = "rounded-dc-lg border border-dc-border bg-dc-background shadow-md text-dc-foreground";
@@ -98,7 +98,7 @@ export function ZoomToolbar({
     let settleTimer: ReturnType<typeof setTimeout> | null = null;
     let idleTimer: ReturnType<typeof setTimeout> | null = null;
     const startFrame = requestAnimationFrame(() => {
-      setLocatePulseStage("grow");
+      setLocatePulseStage("flash");
       settleTimer = setTimeout(() => {
         setLocatePulseStage("settle");
       }, LOCATE_ICON_PULSE_GROW_MS);
@@ -125,7 +125,7 @@ export function ZoomToolbar({
   }, []);
 
   const locateIconStyle: React.CSSProperties =
-    locatePulseStage === "grow"
+    locatePulseStage === "flash"
       ? {
           transform: `scale(${LOCATE_ICON_PULSE_SCALE})`,
           color: LOCATE_ICON_PULSE_COLOR,
@@ -169,9 +169,10 @@ export function ZoomToolbar({
               "w-10 h-10 flex items-center justify-center transition-all duration-180",
               locateDirty ? "text-dc-primary opacity-90 hover:bg-dc-muted" : "opacity-45 hover:opacity-65",
             )}
+            style={locateIconStyle}
             aria-label={locateDirty ? t("zoom.reCenter") : t("zoom.centered")}
           >
-            <span className="size-4 transform-gpu" style={locateIconStyle}>
+            <span className="size-4 transform-gpu">
               <LocateIcon />
             </span>
           </button>
diff --git a/src/react/constants.ts b/src/react/constants.ts
index 84ada16e..56255d48 100644
--- a/src/react/constants.ts
+++ b/src/react/constants.ts
@@ -831,13 +831,15 @@ export const GHOST_BLUR_COLLAPSE_LATE_PX = 2;
 export const EASE_CONTENT_REVEAL = "ease-in";
 
 /** Locate icon pulse grow duration (ms) after annotation overlay dismiss. */
-export const LOCATE_ICON_PULSE_GROW_MS = 70;
+export const LOCATE_ICON_PULSE_GROW_MS = 120;
 /** Locate icon pulse settle duration (ms) after grow stage completes. */
-export const LOCATE_ICON_PULSE_SETTLE_MS = 50;
+export const LOCATE_ICON_PULSE_SETTLE_MS = 80;
 /** Locate icon pulse peak scale (1 = baseline size). */
-export const LOCATE_ICON_PULSE_SCALE = 1.18;
-/** Locate icon pulse accent color used during temporary highlight. */
-export const LOCATE_ICON_PULSE_COLOR = "rgb(56 189 248)";
+export const LOCATE_ICON_PULSE_SCALE = 1.12;
+/** Locate icon pulse accent color used during temporary highlight.
+ *  Uses the muted-foreground design token (neutral zinc) so the cue reads
+ *  as the same quiet grey as the dismiss button that triggered it. */
+export const LOCATE_ICON_PULSE_COLOR = "var(--dc-muted-foreground)";
 
 /** Stagger delay before expanded-page content animates in. Container morph starts first.
  * 30ms is tight enough to avoid an empty-container flash while still letting the shell
diff --git a/src/react/evidence/EvidenceKeyhole.tsx b/src/react/evidence/EvidenceKeyhole.tsx
index 045883ed..85037437 100644
--- a/src/react/evidence/EvidenceKeyhole.tsx
+++ b/src/react/evidence/EvidenceKeyhole.tsx
@@ -19,7 +19,7 @@ import { computeAnnotationScrollTarget } from "../overlayGeometry.js";
 import { cn, isImageSource } from "../utils.js";
 import { DC_EVIDENCE_VT_NAME } from "../viewTransition.js";
 import { animateScrollLeft } from "./animateScrollLeft.js";
-import { IDENTITY_RENDER_SCALE } from "./resolvers.js";
+import { IDENTITY_RENDER_SCALE, resolveEvidenceSourceAnchorRatio } from "./resolvers.js";
 
 /**
  * Displays a verification image as a "keyhole" strip — a fixed-height horizontal
@@ -70,6 +70,10 @@ export function EvidenceKeyhole({
     const phraseItem = verification.document?.sourceContextDeepItem;
     return { anchorItem, renderScale, viewBoxOriginY, phraseItem };
   }, [verification]);
+  // Annotation anchor ratio in image space (0–1 on each axis), used by the
+  // page-expand ghost animation to align the ghost over the annotation on the
+  // expanded page. Mirrors InlineExpandedImage's sourceAnchorRatio logic.
+  const sourceAnchorRatio = useMemo(() => resolveEvidenceSourceAnchorRatio(verification), [verification]);
   // Drag-to-pan hook for mouse interaction (xy enables vertical pan for width-fit tall images;
   // when no vertical overflow exists, scrollTop stays 0 — no visible effect on normal crops).
   const { containerRef, isDragging, handlers, scrollState, wasDraggingRef } = useDragToPan({ direction: "xy" });
@@ -324,6 +328,10 @@ export function EvidenceKeyhole({
             data-dc-keyhole=""
             data-dc-page-expand-source=""
             data-dc-page-expand-source-kind="summary-keyhole"
+            {...(sourceAnchorRatio && {
+              "data-dc-source-anchor-x": sourceAnchorRatio.x.toFixed(4),
+              "data-dc-source-anchor-y": sourceAnchorRatio.y.toFixed(4),
+            })}
             className={cn(DOCUMENT_CANVAS_BG_CLASSES, "overflow-x-auto overflow-y-hidden")}
             style={{
               viewTransitionName: DC_EVIDENCE_VT_NAME,
diff --git a/src/react/hooks/useViewportBoundaryGuard.ts b/src/react/hooks/useViewportBoundaryGuard.ts
index 33ac253f..e00ce7d7 100644
--- a/src/react/hooks/useViewportBoundaryGuard.ts
+++ b/src/react/hooks/useViewportBoundaryGuard.ts
@@ -74,10 +74,13 @@ export function useViewportBoundaryGuard(
     const isInitialOpen = prevViewStateRef.current === null;
     const isViewStateChange = !isInitialOpen && prevViewStateRef.current !== popoverViewState;
     prevViewStateRef.current = popoverViewState;
-    // Signal to the sibling useEffect (which runs after this) whether this cycle
-    // is a view-state transition. useEffect cannot compute this itself because
-    // prevViewStateRef has already been updated by this point.
-    isViewStateTransitionRef.current = isViewStateChange;
+    // Signal to the sibling useEffect whether this cycle is a view-state transition.
+    // Only set to true — never reset here. The useEffect consumes and resets the flag
+    // after reading so the next transition starts clean. This prevents a subsequent
+    // layout-effect run (e.g. triggered by sideOffset changing in the same flushSync
+    // batch when leaving expanded-page) from overwriting true with false before the
+    // useEffect has had a chance to read it.
+    if (isViewStateChange) isViewStateTransitionRef.current = true;
 
     if (isViewStateChange) {
       // Apply full vertical clamping immediately on view-state change. The
@@ -128,6 +131,7 @@ export function useViewportBoundaryGuard(
     // isViewStateTransitionRef is written by the sibling useLayoutEffect on the same deps
     // and is readable here because layout effects flush before passive effects.
     const skipVerticalInTimer = isViewStateTransitionRef.current;
+    isViewStateTransitionRef.current = false; // consumed; reset for next transition
     const safetyTimer = setTimeout(() => {
       const current = popoverContentRef.current;
       if (current) clamp(current, skipVerticalInTimer, containerTopRef.current);
diff --git a/src/react/viewTransition.ts b/src/react/viewTransition.ts
index 2012d738..adb78903 100644
--- a/src/react/viewTransition.ts
+++ b/src/react/viewTransition.ts
@@ -296,18 +296,28 @@ function buildGhostTarget(
   // like a key into a keyhole. No scale = no squash/stretch.
   //
   // The keyhole viewport may be scrolled so only part of the evidence crop is
-  // visible (e.g. right half when the match is on the right). We find the
-  // annotation center WITHIN the ghost (imageOffset + imageSize/2) and align
-  // that point with the annotation center on the expanded page. This ensures
-  // content alignment regardless of keyhole scroll position.
+  // visible (e.g. right half when the match is on the right). We align the
+  // annotation center WITHIN the ghost with the annotation center on the
+  // expanded page.
   const srcW = snapshot.viewportRect.width;
   const srcH = snapshot.viewportRect.height;
 
-  // Annotation center within the ghost element: the evidence crop image is
-  // centered on the annotation, so the image center ≈ annotation center.
-  // imageOffset accounts for keyhole scroll position.
-  const anchorInGhostX = snapshot.imageOffsetLeft + snapshot.imageWidth / 2;
-  const anchorInGhostY = snapshot.imageOffsetTop + snapshot.imageHeight / 2;
+  // Annotation center within the ghost element.
+  // Formula: imageOffsetLeft + sourceAnchorX × imageWidth = annotation X in ghost-local coords.
+  //
+  // Why this works in both cases:
+  //   Scrolled (non-clamped): imageOffsetLeft = −scrollLeft = srcW/2 − annX·zoom,
+  //     so imageOffsetLeft + annX·zoom = srcW/2.  The annotation ends up at the
+  //     viewport center because EvidenceKeyhole's centering scroll placed it there.
+  //   Width-filling (scrollLeft=0): imageOffsetLeft = 0, so anchor = annX·zoom =
+  //     sourceAnchorX × imageWidth — the annotation's actual pixel position in
+  //     the displayed image.  Using srcW/2 here is wrong when annX ≠ imageW/2.
+  //
+  // sourceAnchorX/Y is set by EvidenceKeyhole (summary-keyhole) and
+  // InlineExpandedImage (expanded-keyhole) via data-dc-source-anchor-x/y.
+  // Falls back to 0.5 when no attribute is set (legacy or non-annotated sources).
+  const anchorInGhostX = snapshot.imageOffsetLeft + snapshot.sourceAnchorX * snapshot.imageWidth;
+  const anchorInGhostY = snapshot.imageOffsetTop + snapshot.sourceAnchorY * snapshot.imageHeight;
 
   // Annotation center on the expanded page — use spotlight center (annotation
   // center with symmetric padding) or marker center.
@@ -359,12 +369,17 @@ export function buildGhostTargetFromViewport(root: ParentNode, snapshot: GhostSn
     if (right <= left || bottom <= top) continue;
     const visibleRect = new DOMRect(left, top, right - left, bottom - top);
     // Keep ghost at source keyhole dimensions — no scale-up for miss/not_found.
-    // Mirror buildGhostTarget: align the image center-of-mass in the ghost to
-    // the center of the visible page area, so the ghost slides without scaling.
+    // Anchor = visible viewport center (srcW/2, srcH/2).
+    // Unlike buildGhostTarget, we use the viewport center here rather than
+    // the annotation position, because miss/not_found has no annotation:
+    //   • No scroll applied → imageOffsetLeft/Top = 0
+    //   • sourceAnchorX/Y defaults to 0.5, but imageWidth may exceed srcW
+    //     (tall image, width-fill zoom), making imageHeight/2 >> srcH
+    // Using srcW/2, srcH/2 keeps the visible center of the ghost on the target.
     const srcW = snapshot.viewportRect.width;
     const srcH = snapshot.viewportRect.height;
-    const anchorInGhostX = snapshot.imageOffsetLeft + snapshot.imageWidth / 2;
-    const anchorInGhostY = snapshot.imageOffsetTop + snapshot.imageHeight / 2;
+    const anchorInGhostX = srcW / 2;
+    const anchorInGhostY = srcH / 2;
     const pageCX = visibleRect.left + visibleRect.width / 2;
     const pageCY = visibleRect.top + visibleRect.height / 2;
     const ghostRect = new DOMRect(pageCX - anchorInGhostX, pageCY - anchorInGhostY, srcW, srcH);
@@ -409,7 +424,10 @@ function createPageExpandGhost(snapshot: GhostSnapshot): HTMLDivElement | null {
   ghost.style.zIndex = "2147483646";
   ghost.style.borderRadius = snapshot.borderRadius;
   ghost.style.transformOrigin = "0 0";
-  ghost.style.willChange = "transform, opacity";
+  // Include filter in will-change: blur() animation needs a compositor layer
+  // hint; without it the GPU can't promote the element ahead of time and the
+  // first blur frame causes a synchronous paint that produces a visible stutter.
+  ghost.style.willChange = "transform, opacity, filter";
   const debugPhase = getPageExpandDebugPhase();
   if (debugPhase && debugPhase !== "both") {
     ghost.style.outline =
@@ -431,6 +449,9 @@ function createPageExpandGhost(snapshot: GhostSnapshot): HTMLDivElement | null {
   img.style.maxWidth = "none";
   img.style.userSelect = "none";
   img.style.pointerEvents = "none";
+  // Promote the image to its own compositor layer so the parent's overflow clip
+  // and border-radius don't trigger repaints each frame.
+  img.style.willChange = "transform";
   ghost.appendChild(img);
   document.body.appendChild(ghost);
   return ghost;
@@ -1047,6 +1068,7 @@ function runPageCollapseGhostAnimation(
   snapshot: GhostSnapshot,
   keyholeRect: DOMRect,
   popoverRoot: HTMLElement | null,
+  onDone: () => void,
 ): void {
   const src = snapshot.viewportRect;
 
@@ -1102,6 +1124,12 @@ function runPageCollapseGhostAnimation(
     fill: "both",
   });
 
+  let pendingAnimations = popoverRoot ? 2 : 1;
+  const markAnimationDone = () => {
+    pendingAnimations -= 1;
+    if (pendingAnimations === 0) onDone();
+  };
+
   // Content reveal: holds at floor through GHOST_OFFSET_COLLAPSE_MID (0.65) while
   // the ghost covers vertical travel, then ramps 0.03→0.35 by GHOST_OFFSET_COLLAPSE_PEAK
   // (0.88) as the ghost fades to GHOST_OPACITY_COLLAPSE_PEAK (0.3), then finishes 0.35→1.0
@@ -1123,6 +1151,7 @@ function runPageCollapseGhostAnimation(
       .finally(() => {
         contentAnim.cancel();
         cleanupPageExpandScrim(popoverRoot);
+        markAnimationDone();
       });
   }
 
@@ -1130,6 +1159,7 @@ function runPageCollapseGhostAnimation(
     .catch(() => {})
     .finally(() => {
       ghost.remove();
+      markAnimationDone();
     });
 }
 
@@ -1211,13 +1241,15 @@ export function startEvidencePageCollapseTransition(
     }
 
     waitForPageCollapseTarget(root, keyholeRect => {
-      _transitionDepth = Math.max(0, _transitionDepth - 1);
       if (!keyholeRect) {
         ghost.remove();
         cleanupPageExpandScrim(rootEl);
+        _transitionDepth = Math.max(0, _transitionDepth - 1);
         return;
       }
-      runPageCollapseGhostAnimation(ghost, snapshot, keyholeRect, rootEl);
+      runPageCollapseGhostAnimation(ghost, snapshot, keyholeRect, rootEl, () => {
+        _transitionDepth = Math.max(0, _transitionDepth - 1);
+      });
     });
   };
 
diff --git a/src/render/__tests__/renderVerifiedHtml.test.ts b/src/render/__tests__/renderVerifiedHtml.test.ts
new file mode 100644
index 00000000..91abaa57
--- /dev/null
+++ b/src/render/__tests__/renderVerifiedHtml.test.ts
@@ -0,0 +1,50 @@
+// packages/deepcitation/src/render/__tests__/renderVerifiedHtml.test.ts
+import { describe, expect, it } from "bun:test";
+import { renderVerifiedHtml } from "../renderVerifiedHtml.js";
+
+const fakeCitations = {
+  abc123: {
+    sourceMatch: "blood pressure",
+    sourceContext: "The patient's blood pressure was 120/80.",
+    pageNumber: 1,
+    attachmentId: "att_001",
+  },
+};
+
+const fakeVerifications = {
+  abc123: {
+    status: "found" as const,
+    verifiedPageNumber: 1,
+    verifiedSourceContext: "blood pressure was 120/80",
+    attachmentId: "att_001",
+  },
+};
+
+describe("renderVerifiedHtml", () => {
+  it("returns a non-empty HTML string", () => {
+    const html = renderVerifiedHtml("The blood pressure [1] was normal.", fakeCitations, fakeVerifications);
+    expect(typeof html).toBe("string");
+    expect(html.length).toBeGreaterThan(100);
+  });
+
+  it("embeds dc-data script tag with verification data", () => {
+    const html = renderVerifiedHtml("The blood pressure [1] was normal.", fakeCitations, fakeVerifications);
+    expect(html).toContain("dc-data");
+    expect(html).toContain("abc123");
+  });
+
+  it("returns valid HTML with a body tag", () => {
+    const html = renderVerifiedHtml("Hello [1].", fakeCitations, fakeVerifications);
+    expect(html).toContain("<html");
+    expect(html).toContain("</html>");
+  });
+
+  it("accepts empty attachments without throwing", () => {
+    expect(() => renderVerifiedHtml("Hello [1].", fakeCitations, fakeVerifications, {})).not.toThrow();
+  });
+
+  it("uses the title option in the HTML output", () => {
+    const html = renderVerifiedHtml("Hello.", {}, {}, {}, { title: "My Report" });
+    expect(html).toContain("My Report");
+  });
+});
diff --git a/src/render/renderVerifiedHtml.ts b/src/render/renderVerifiedHtml.ts
new file mode 100644
index 00000000..3fda8a27
--- /dev/null
+++ b/src/render/renderVerifiedHtml.ts
@@ -0,0 +1,54 @@
+// packages/deepcitation/src/render/renderVerifiedHtml.ts
+/**
+ * Shared HTML render pipeline: markdown visible text + citation data
+ * + verification results → self-contained HTML with CDN runtime injected.
+ *
+ * Used by the Functions `createReport` handler (server-side) and
+ * available for any other consumer that needs to render a verified report.
+ */
+
+import { markdownToHtml } from "../cli/markdownToHtml.js";
+import type { CitationRecord } from "../types/citation.js";
+import type { AttachmentAssets, Verification } from "../types/verification.js";
+import {
+  buildCitationMaps,
+  injectCdnRuntime,
+  normalizeNumericMarkers,
+  reattachPageImages,
+  replaceCitationMarkers,
+} from "../vanilla/reportUtils.js";
+
+export interface RenderVerifiedHtmlOptions {
+  title?: string;
+  theme?: "light" | "dark" | "auto";
+  indicatorVariant?: "icon" | "dot" | "none";
+}
+
+/**
+ * Render a self-contained verified HTML report from in-memory data.
+ *
+ * @param visibleText - Markdown from the LLM with CITATION_DATA already stripped
+ * @param parsedCitations - CitationRecord keyed by citation hash
+ * @param verifications - Verification results keyed by citation hash
+ * @param attachments - Optional attachment assets (for page image re-attachment)
+ * @param options - Title, theme, indicator variant
+ * @returns Complete HTML string ready to store or serve
+ */
+export function renderVerifiedHtml(
+  visibleText: string,
+  parsedCitations: CitationRecord,
+  verifications: Record<string, Verification>,
+  attachments?: Record<string, AttachmentAssets>,
+  options?: RenderVerifiedHtmlOptions,
+): string {
+  const { title = "", theme = "auto", indicatorVariant = "icon" } = options ?? {};
+  const citationCount = Object.keys(parsedCitations).length;
+  const { sourceMatchMap, keyMap } = buildCitationMaps(parsedCitations);
+  const normalizedText = normalizeNumericMarkers(visibleText, sourceMatchMap);
+  let html = markdownToHtml(normalizedText, { style: "report", title, citationCount, sourceMatchMap });
+  html = replaceCitationMarkers(html, parsedCitations);
+  const cdnVerifications = { ...verifications };
+  reattachPageImages(cdnVerifications, attachments);
+  const { html: injected } = injectCdnRuntime(html, cdnVerifications, keyMap, { theme, indicatorVariant });
+  return injected;
+}
diff --git a/src/vanilla/reportUtils.ts b/src/vanilla/reportUtils.ts
index d09af694..232a0025 100644
--- a/src/vanilla/reportUtils.ts
+++ b/src/vanilla/reportUtils.ts
@@ -56,31 +56,67 @@ export function stripExistingInjection(html: string): { html: string; hadExistin
   let result = html;
   let hadExisting = false;
 
-  const patterns = [
-    // dc-data and dc-key-map JSON blocks
-    /<script[^>]*id="dc-data"[^>]*>[\s\S]*?<\/script>\s*/g,
-    /<script[^>]*id="dc-key-map"[^>]*>[\s\S]*?<\/script>\s*/g,
-    // Init call
-    /<script>\s*window\.DeepCitationPopover\s*&&[\s\S]*?<\/script>\s*/g,
-  ];
-
-  for (const pattern of patterns) {
-    if (pattern.test(result)) {
+  // Strip <script> blocks by ID using string search to avoid ReDoS.
+  // Regex with multiple [^>]* groups on uncontrolled input is polynomial.
+  for (const id of ["dc-data", "dc-key-map"]) {
+    const idMarker = `id="${id}"`;
+    while (true) {
+      const idIdx = result.indexOf(idMarker);
+      if (idIdx === -1) break;
+      const tagStart = result.lastIndexOf("<script", idIdx);
+      if (tagStart === -1) break;
+      const closeIdx = result.indexOf("</script>", idIdx);
+      if (closeIdx === -1) break;
+      const end = closeIdx + "</script>".length;
+      // Consume trailing whitespace
+      let ws = end;
+      while (
+        ws < result.length &&
+        (result[ws] === " " || result[ws] === "\t" || result[ws] === "\n" || result[ws] === "\r")
+      )
+        ws++;
+      result = result.slice(0, tagStart) + result.slice(ws);
       hadExisting = true;
-      // Reset lastIndex since we tested before replacing
-      pattern.lastIndex = 0;
-      result = result.replace(pattern, "");
     }
   }
 
+  // Strip plain <script> blocks (no attributes) that are DeepCitation-owned.
+  // Uses indexOf to scan structurally — regex on full HTML is polynomial here.
   // CDN bundle: large script without id that *defines* DeepCitationPopover.
   // Requires assignment (`window.DeepCitationPopover=` or `window.DeepCitationPopover =`)
   // to avoid stripping user scripts that merely reference the API.
-  const cdnBundlePattern = /<script>(?:(?!<\/script>)[\s\S])*?window\.DeepCitationPopover\s*=[\s\S]*?<\/script>\s*/g;
-  if (cdnBundlePattern.test(result)) {
-    hadExisting = true;
-    cdnBundlePattern.lastIndex = 0;
-    result = result.replace(cdnBundlePattern, "");
+  let pos = 0;
+  while (true) {
+    const scriptStart = result.indexOf("<script>", pos);
+    if (scriptStart === -1) break;
+    const contentStart = scriptStart + "<script>".length;
+    const closeIdx = result.indexOf("</script>", contentStart);
+    if (closeIdx === -1) break;
+    const content = result.slice(contentStart, closeIdx);
+
+    // Init call: bounded check on first 80 chars (trimStart + literal prefix)
+    const trimmed = content.trimStart();
+    const isInitCall =
+      trimmed.startsWith("window.DeepCitationPopover") &&
+      /^window\.DeepCitationPopover\s*&&/.test(trimmed.slice(0, 80));
+    // CDN bundle: linear regex applied only to bounded content string
+    const isCdnBundle =
+      content.includes("window.DeepCitationPopover") && /window\.DeepCitationPopover\s*=/.test(content);
+
+    if (isInitCall || isCdnBundle) {
+      hadExisting = true;
+      const end = closeIdx + "</script>".length;
+      let ws = end;
+      while (
+        ws < result.length &&
+        (result[ws] === " " || result[ws] === "\t" || result[ws] === "\n" || result[ws] === "\r")
+      )
+        ws++;
+      result = result.slice(0, scriptStart) + result.slice(ws);
+      // Don't advance pos — content was removed at this position
+    } else {
+      pos = contentStart;
+    }
   }
 
   return { html: result, hadExisting };
@@ -223,18 +259,79 @@ export function autoFixDisplayLabels(
   verifications: Record<string, unknown>,
 ): { html: string; log: string[] } {
   const log: string[] = [];
-  const elementRe = /<([a-zA-Z][a-zA-Z0-9]*)[^>]*\sdata-citation-key="([^"]+)"([^>]*)>([\s\S]*?)<\/\1>/g;
-  const fixedHtml = html.replace(elementRe, (fullMatch, _tag, hashedKey, rest, content) => {
-    // Skip if data-dc-display-label is already set on this element
-    if (/data-dc-display-label=/.test(rest) || /data-dc-display-label=/.test(fullMatch)) return fullMatch;
+  // Use string scanning instead of regex on the full HTML to avoid ReDoS.
+  // The pattern [^>]*\s...[^>]* applied to uncontrolled input is polynomial.
+  const attrMarker = ' data-citation-key="';
+  const parts: string[] = [];
+  let lastEnd = 0;
+  let searchPos = 0;
+
+  while (true) {
+    const attrIdx = html.indexOf(attrMarker, searchPos);
+    if (attrIdx === -1) break;
+
+    // Find the enclosing tag's opening < (must not be a closing tag)
+    const tagStart = html.lastIndexOf("<", attrIdx);
+    if (tagStart === -1 || tagStart < lastEnd || html[tagStart + 1] === "/") {
+      searchPos = attrIdx + 1;
+      continue;
+    }
+
+    // Find the end of the opening tag
+    const tagClose = html.indexOf(">", attrIdx);
+    if (tagClose === -1) {
+      searchPos = attrIdx + 1;
+      continue;
+    }
+
+    // Extract tag name from between < and first whitespace or >
+    const afterAngle = tagStart + 1;
+    const tagHeaderSlice = html.slice(afterAngle, tagClose);
+    const tagNameEnd = tagHeaderSlice.search(/[\s/>]/);
+    const tagName = tagNameEnd >= 0 ? tagHeaderSlice.slice(0, tagNameEnd) : tagHeaderSlice;
+    if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(tagName)) {
+      searchPos = tagClose + 1;
+      continue;
+    }
+
+    // Extract citation key (bounded between the attribute marker and the next quote)
+    const keyStart = attrIdx + attrMarker.length;
+    const keyEnd = html.indexOf('"', keyStart);
+    if (keyEnd === -1) {
+      searchPos = attrIdx + 1;
+      continue;
+    }
+    const hashedKey = html.slice(keyStart, keyEnd);
+
+    // Skip if opening tag already has data-dc-display-label
+    const openingTag = html.slice(tagStart, tagClose + 1);
+    if (openingTag.includes("data-dc-display-label=")) {
+      searchPos = tagClose + 1;
+      continue;
+    }
 
     const sourceMatch = (verifications[hashedKey] as { citation?: { sourceMatch?: string } } | undefined)?.citation
       ?.sourceMatch;
-    if (!sourceMatch) return fullMatch;
+    if (!sourceMatch) {
+      searchPos = tagClose + 1;
+      continue;
+    }
+
+    // Find closing tag (uses first occurrence — same behaviour as the original lazy regex)
+    const closeTag = `</${tagName}>`;
+    const contentStart = tagClose + 1;
+    const closeIdx = html.indexOf(closeTag, contentStart);
+    if (closeIdx === -1) {
+      searchPos = tagClose + 1;
+      continue;
+    }
+
+    const content = html.slice(contentStart, closeIdx);
 
     // Strip inner HTML tags to get approximate visible text.
     // Loop until stable to handle nested fragments like <scr<script>ipt>.
-    let visibleText = content as string;
+    // Applied to bounded content string — no ReDoS risk.
+    let visibleText = content;
     let prev: string;
     do {
       prev = visibleText;
@@ -242,19 +339,34 @@ export function autoFixDisplayLabels(
     } while (visibleText !== prev);
     visibleText = visibleText.replace(/\s+/g, " ").trim();
 
-    if (!visibleText || visibleText.length > 80) return fullMatch;
-    if (sourceMatch.toLowerCase().includes(visibleText.toLowerCase())) return fullMatch;
+    const matchEnd = closeIdx + closeTag.length;
+
+    if (!visibleText || visibleText.length > 80 || sourceMatch.toLowerCase().includes(visibleText.toLowerCase())) {
+      searchPos = tagClose + 1;
+      continue;
+    }
 
     const escaped = visibleText.replace(/"/g, "&quot;");
     log.push(
       `  [${hashedKey.slice(0, 8)}…] claimText="${visibleText}" sourceMatch="${sourceMatch.slice(0, 60)}${sourceMatch.length > 60 ? "…" : ""}"`,
     );
-    return fullMatch.replace(
-      `data-citation-key="${hashedKey}"`,
-      `data-citation-key="${hashedKey}" data-dc-display-label="${escaped}"`,
+
+    // Emit unchanged HTML up to this element, then the patched element
+    parts.push(html.slice(lastEnd, tagStart));
+    const fullMatch = html.slice(tagStart, matchEnd);
+    parts.push(
+      fullMatch.replace(
+        `data-citation-key="${hashedKey}"`,
+        `data-citation-key="${hashedKey}" data-dc-display-label="${escaped}"`,
+      ),
     );
-  });
-  return { html: fixedHtml, log };
+    lastEnd = matchEnd;
+    searchPos = matchEnd;
+  }
+
+  if (parts.length === 0) return { html, log };
+  parts.push(html.slice(lastEnd));
+  return { html: parts.join(""), log };
 }
 
 /** Options for {@link injectCdnRuntime}. */
diff --git a/src/vanilla/runtime/cdn.ts b/src/vanilla/runtime/cdn.ts
index 329b85d7..b0d5dab0 100644
--- a/src/vanilla/runtime/cdn.ts
+++ b/src/vanilla/runtime/cdn.ts
@@ -9,6 +9,7 @@ import { DefaultPopoverContent } from "../../react/DefaultPopoverContent.js";
 import { usePopoverViewState } from "../../react/hooks/usePopoverViewState.js";
 import { usePrefersReducedMotion } from "../../react/hooks/usePrefersReducedMotion.js";
 import { sanitizeUrl } from "../../react/urlUtils.js";
+import { isViewTransitioning } from "../../react/viewTransition.js";
 import { canChildScrollVertically, findPageScrollEl } from "../../shared/scroll.js";
 import type { Citation } from "../../types/citation.js";
 import type { PageImage, Verification } from "../../types/verification.js";
@@ -84,6 +85,7 @@ let activeSelector = "[data-citation-key]";
 let activeIndicatorVariant: CdnIndicatorVariant = "icon";
 let dismissController: AbortController | null = null;
 let positionRafId = 0;
+let repositionGen = 0;
 let resizeObserver: ResizeObserver | null = null;
 let lastCoords = { x: NaN, y: NaN };
 let scrollPassthroughController: AbortController | null = null;
@@ -283,9 +285,20 @@ function reposition(): void {
     contentEl.style.translate = `${dx}px ${dy}px`;
   }
 }
+function deferReposition(retriesLeft: number, gen: number): void {
+  positionRafId = requestAnimationFrame(() => {
+    if (gen !== repositionGen) return; // stale chain — a newer scheduleReposition fired
+    if (isViewTransitioning() && retriesLeft > 0) {
+      deferReposition(retriesLeft - 1, gen);
+      return;
+    }
+    reposition();
+  });
+}
 function scheduleReposition(): void {
+  repositionGen++;
   cancelAnimationFrame(positionRafId);
-  positionRafId = requestAnimationFrame(reposition);
+  deferReposition(30, repositionGen);
 }
 function startPositionTracking(): void {
   stopPositionTracking();
diff --git a/teardown-v14.png b/teardown-v14.png
deleted file mode 100644
index f38c2703..00000000
Binary files a/teardown-v14.png and /dev/null differ
diff --git a/tests/playwright/specs/annotationOverlay.spec.tsx b/tests/playwright/specs/annotationOverlay.spec.tsx
index 4b4b7692..e57115e2 100644
--- a/tests/playwright/specs/annotationOverlay.spec.tsx
+++ b/tests/playwright/specs/annotationOverlay.spec.tsx
@@ -220,7 +220,7 @@ test.describe("Annotation Overlay — dismiss", () => {
     await overlayDismiss.click();
     await expect(popover.locator("[data-dc-annotation-overlay]").filter({ visible: true })).toHaveCount(0);
 
-    await expect.poll(async () => scrollToBtn.getAttribute("data-dc-locate-pulse-stage")).toMatch(/grow|settle/);
+    await expect.poll(async () => scrollToBtn.getAttribute("data-dc-locate-pulse-stage")).toMatch(/flash|settle/);
     await expect.poll(async () => scrollToBtn.getAttribute("data-dc-locate-pulse-stage")).toBeNull();
   });
 
@@ -248,7 +248,7 @@ test.describe("Annotation Overlay — dismiss", () => {
 
     await popover.locator("[data-dc-overlay-dismiss]").filter({ visible: true }).click();
     await expect(overlay).toHaveCount(0);
-    await expect.poll(async () => scrollToBtn.getAttribute("data-dc-locate-pulse-stage")).toMatch(/grow|settle/);
+    await expect.poll(async () => scrollToBtn.getAttribute("data-dc-locate-pulse-stage")).toMatch(/flash|settle/);
   });
 });
 
diff --git a/tsconfig.json b/tsconfig.json
index 316e531e..1d74aa86 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -14,11 +14,27 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "jsx": "react-jsx",
-    "types": ["node", "react", "react-dom", "jest", "@testing-library/jest-dom"],
+    "types": [
+      "node",
+      "react",
+      "react-dom",
+      "jest",
+      "@testing-library/jest-dom"
+    ],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": [
+        "./src/*"
+      ]
     }
   },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "lib", "src/__tests__", "src/react/testing", "tests"]
-}
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "lib",
+    "src/**/__tests__",
+    "src/react/testing",
+    "tests"
+  ]
+}
\ No newline at end of file