@hevmind/ask 0.1.0

package/src/components/markdown.ts

@@ -0,0 +1,107 @@
+// Minimal, dependency-free, streaming-safe Markdown renderer for the AI answer.
+//
+// The renderer is fed the *whole* accumulated answer on every token, so partial
+// syntax (an unterminated `[label](`) simply fails to match and renders as
+// literal text until the closing token arrives — never a broken DOM. Model
+// output is untrusted: the source text is HTML-escaped first, then our own
+// trusted tags are injected. Links are validated against the grounding source
+// set so a hallucinated URL degrades to plain text — and, when the source
+// carries distinctive `terms`, a link whose surrounding text shares none of
+// them (a misattributed citation) also degrades to plain text.
+
+export interface Source {
+  title: string;
+  heading?: string;
+  url: string;
+  group?: string;
+  /** Distinctive tokens of the cited section, for the link-support check. */
+  terms?: string[];
+}
+
+const LINK_RE = /\[([^\]]+)\]\(([^)\s]+)\)/g;
+const CODE_RE = /`([^`]+)`/g;
+const BOLD_RE = /\*\*([^*]+)\*\*/g;
+const LIST_ITEM_RE = /^\s*(?:[-*]|\d+\.)\s+/;
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/** Breadcrumb for a source, e.g. "Concepts › Kubernetes autoscaling". */
+export function sourceBreadcrumb(source: Source): string {
+  return [source.group, source.heading ?? source.title].filter(Boolean).join(' › ');
+}
+
+function tokenSet(text: string): Set<string> {
+  // Strip link *targets* (keep labels) so a URL/anchor slug can't leak its own
+  // terms into the support check — otherwise a link to #autoscaling would always
+  // "support" itself via the word "autoscaling" in its href.
+  const withoutUrls = text.replace(LINK_RE, (_m, label: string) => label);
+  return new Set(withoutUrls.toLowerCase().match(/[a-z0-9]+/g) ?? []);
+}
+
+/**
+ * A cited link survives only if the text around it shares a distinctive term
+ * with the cited section. Lenient by design: a source with no `terms` (e.g. a
+ * legacy/degraded digest) is never degraded on this basis.
+ */
+function supportsClaim(unitTokens: Set<string>, source: Source): boolean {
+  if (!source.terms || source.terms.length === 0) return true;
+  for (const term of source.terms) if (unitTokens.has(term)) return true;
+  return false;
+}
+
+export function renderMarkdown(md: string, sources: Source[] = []): string {
+  const urlMap = new Map(sources.map((source) => [source.url, source]));
+  // Split into blocks on blank lines; render each as a list or a paragraph.
+  return md
+    .split(/\n{2,}/)
+    .map((block) => renderBlock(block.trim(), urlMap))
+    .filter(Boolean)
+    .join('');
+}
+
+function renderBlock(block: string, urlMap: Map<string, Source>): string {
+  if (!block) return '';
+  // Horizontal rules and headings don't belong in a compact popover; the model
+  // is told not to use them, but degrade them gracefully if it does.
+  if (/^(-{3,}|\*{3,}|_{3,})$/.test(block)) return '';
+  const heading = block.match(/^#{1,6}\s+(.+)$/);
+  if (heading && !block.includes('\n')) {
+    return `<p><strong>${renderInline(escapeHtml(heading[1]), urlMap, tokenSet(heading[1]))}</strong></p>`;
+  }
+  const lines = block.split('\n');
+  if (lines.every((line) => !line.trim() || LIST_ITEM_RE.test(line))) {
+    const items = lines.filter((line) => line.trim());
+    const ordered = /^\s*\d+\./.test(items[0] ?? '');
+    const tag = ordered ? 'ol' : 'ul';
+    const body = items
+      .map((line) => {
+        const text = line.replace(LIST_ITEM_RE, '');
+        return `<li>${renderInline(escapeHtml(text), urlMap, tokenSet(text))}</li>`;
+      })
+      .join('');
+    return `<${tag}>${body}</${tag}>`;
+  }
+  const text = block.replace(/\n/g, ' ');
+  return `<p>${renderInline(escapeHtml(text), urlMap, tokenSet(text))}</p>`;
+}
+
+function renderInline(escaped: string, urlMap: Map<string, Source>, unitTokens: Set<string>): string {
+  // Order: code, then bold, then links. The source text is already escaped, so
+  // injected tags are the only markup in the string.
+  let out = escaped.replace(CODE_RE, (_m, code: string) => `<code>${code}</code>`);
+  out = out.replace(BOLD_RE, (_m, inner: string) => `<strong>${inner}</strong>`);
+  out = out.replace(LINK_RE, (whole, label: string, url: string) => {
+    const source = urlMap.get(url);
+    if (!source) return label; // hallucinated / off-corpus link → plain text
+    if (!supportsClaim(unitTokens, source)) return label; // misattributed citation → plain text
+    const title = escapeHtml(sourceBreadcrumb(source));
+    return `<a class="as-answer-link" href="${escapeHtml(url)}" title="${title}">${label}</a>`;
+  });
+  return out;
+}

package/src/digest/build.ts

@@ -0,0 +1,432 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { callClaude, type AnthropicTool } from '../llm.ts';
+import { chunkDocument, hashableChunkText, type Chunk, type SourceDocument } from '../search/chunk.ts';
+import { classifyMode, distinctiveTokens, extractFacts } from './facts.ts';
+import { parseFrontmatter } from './frontmatter.ts';
+import { normalizeDigest, type Digest, type DigestNode } from './schema.ts';
+
+export interface DigestBuildOptions {
+  siteRoot: string;
+  collections: string[] | null;
+  basePath: string;
+  digestPath: string;
+  digestContentGlobs?: string[];
+  chunkHeadingDepth: number;
+  digestModel: string;
+  apiKey?: string;
+}
+
+export interface CorpusBuild {
+  documents: SourceDocument[];
+  chunks: Chunk[];
+  contentHash: string;
+}
+
+export interface DigestBuildResult {
+  status: 'built' | 'skipped';
+  path: string;
+  contentHash: string;
+  chunks: number;
+}
+
+const DIGEST_TOOL: AnthropicTool = {
+  name: 'emit_digest',
+  description:
+    'Emit a documentation digest: a compact orientation, a glossary, and one distilled summary per section.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      context: {
+        type: 'string',
+        description:
+          'Compact markdown orientation explaining the product, core concepts, feature areas, and how users talk about them.',
+      },
+      glossary: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            term: { type: 'string' },
+            aliases: { type: 'array', items: { type: 'string' } },
+            definition: { type: 'string' },
+          },
+          required: ['term', 'aliases', 'definition'],
+        },
+      },
+      summaries: {
+        type: 'array',
+        description:
+          'One entry per section id in the corpus. The summary is the agent-facing distillation of that section.',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'The exact section id from the corpus.' },
+            summary: {
+              type: 'string',
+              description:
+                'A tight 1-3 sentence distillation of the section a search agent can answer from. Paraphrase prose; do NOT restate code, flags, or exact identifiers (those are preserved separately).',
+            },
+          },
+          required: ['id', 'summary'],
+        },
+      },
+      suggestions: {
+        type: 'array',
+        description:
+          '3-5 natural questions a real reader might ask that these docs genuinely answer. Phrase them the way a user would type them, not as headings.',
+        items: { type: 'string' },
+      },
+    },
+    required: ['context', 'glossary', 'summaries', 'suggestions'],
+  },
+};
+
+export interface EmittedDistillation {
+  context: string;
+  glossary: Digest['glossary'];
+  summaries: Array<{ id: string; summary: string }>;
+  suggestions: string[];
+}
+
+/** The exact model-input payload the skill (or `build`) distils from. */
+export interface DigestInput {
+  contentHash: string;
+  digestPath: string;
+  /** True when the committed digest.json already matches this corpus — no rebuild needed. */
+  upToDate: boolean;
+  sections: Array<{ id: string; url: string; title: string; text: string }>;
+}
+
+/** Sections handed to the model: one entry per heading chunk. */
+export function corpusSections(corpus: CorpusBuild): DigestInput['sections'] {
+  return corpus.chunks.map((chunk) => ({
+    id: chunk.id,
+    url: chunk.url,
+    title: chunk.heading ? `${chunk.docTitle} > ${chunk.heading}` : chunk.docTitle,
+    text: chunk.text,
+  }));
+}
+
+/**
+ * Assembles the committed digest from a model distillation. Everything but the
+ * distilled fields (`summary`, `glossary`, `context`, `suggestions`) is derived
+ * here deterministically, so it is identical whether the distillation came from
+ * the API or a Claude Code skill.
+ */
+export function assembleDigest(emitted: EmittedDistillation, corpus: CorpusBuild): Digest {
+  const summaryById = new Map(emitted.summaries.map((entry) => [entry.id, entry.summary]));
+  return {
+    version: 2,
+    generatedAt: new Date().toISOString(),
+    contentHash: corpus.contentHash,
+    context: emitted.context,
+    glossary: emitted.glossary,
+    overview: buildOverview(corpus.chunks),
+    suggestions: emitted.suggestions,
+    nodes: buildNodes(corpus.chunks, summaryById),
+    edges: [],
+  };
+}
+
+export async function buildDigest(options: DigestBuildOptions): Promise<DigestBuildResult> {
+  const corpus = await buildCorpus(options);
+  const outPath = path.resolve(options.siteRoot, options.digestPath);
+  const existing = await readExistingDigest(outPath);
+  // Skip only when the committed artifact is already a current-version digest with
+  // nodes built from this exact corpus. A v1 (node-less) artifact always rebuilds.
+  if (existing && existing.version === 2 && existing.contentHash === corpus.contentHash && existing.nodes.length > 0) {
+    return { status: 'skipped', path: outPath, contentHash: corpus.contentHash, chunks: corpus.chunks.length };
+  }
+
+  const apiKey = options.apiKey ?? process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) throw new Error('ANTHROPIC_API_KEY is required to build a fresh digest.');
+
+  const corpusText = corpusSections(corpus)
+    .map((section) => `id: ${section.id}\nurl: ${section.url}\ntitle: ${section.title}\n\n${section.text}`)
+    .join('\n\n---\n\n');
+
+  const response = await callClaude({
+    apiKey,
+    model: options.digestModel,
+    maxTokens: 8192,
+    system: [
+      {
+        type: 'text',
+        text: DIGEST_SYSTEM_PROMPT,
+      },
+      {
+        type: 'text',
+        text: `<corpus>\n${corpusText}\n</corpus>`,
+        cache_control: { type: 'ephemeral' },
+      },
+    ],
+    messages: [
+      {
+        role: 'user',
+        content:
+          'Emit the context, glossary, one summary per section id, and 3-5 suggested questions. Every id in the corpus must get a summary.',
+      },
+    ],
+    tools: [DIGEST_TOOL],
+    toolChoice: { type: 'tool', name: 'emit_digest' },
+  });
+
+  const toolUse = response.content.find((block) => block.type === 'tool_use' && block.name === 'emit_digest');
+  const emitted = parseEmittedDigest(toolUse?.type === 'tool_use' ? toolUse.input : null);
+  const digest = assembleDigest(emitted, corpus);
+
+  await writeGraph(outPath, digest);
+  return { status: 'built', path: outPath, contentHash: corpus.contentHash, chunks: corpus.chunks.length };
+}
+
+/** Shared instruction for the model step, whether it runs via API or a skill. */
+export const DIGEST_SYSTEM_PROMPT =
+  'You build documentation digests for an AI search agent. Return only the forced tool call. Write a compact orientation, a glossary with aliases real users would type, one tight summary for every section id in the corpus, and 3-5 natural questions a reader might ask that these docs answer. Summaries are what the agent reasons from, so make them faithful and self-contained; paraphrase prose but never restate code, flags, or exact identifiers.';
+
+/** Reads the forced tool call (or a skill's distillation file) into the emit shape. */
+export function parseEmittedDigest(input: unknown): EmittedDistillation {
+  const base = normalizeDigest(input);
+  const raw = (input ?? {}) as { summaries?: unknown };
+  const summaries = Array.isArray(raw.summaries)
+    ? raw.summaries
+        .map((entry) => {
+          if (!entry || typeof entry !== 'object') return null;
+          const maybe = entry as { id?: unknown; summary?: unknown };
+          if (typeof maybe.id !== 'string' || typeof maybe.summary !== 'string') return null;
+          return { id: maybe.id, summary: maybe.summary.trim() };
+        })
+        .filter((entry): entry is { id: string; summary: string } => entry !== null)
+    : [];
+  return { context: base.context, glossary: base.glossary, summaries, suggestions: base.suggestions };
+}
+
+async function writeGraph(outPath: string, digest: Digest): Promise<void> {
+  await mkdir(path.dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(digest, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * `corpus` command: chunk the content and write the model-input payload (plus a
+ * freshness flag) for a Claude Code skill to distil. Fully deterministic, keyless.
+ */
+export async function writeCorpusInput(options: {
+  siteRoot: string;
+  collections: string[] | null;
+  basePath: string;
+  digestPath: string;
+  outPath: string;
+  digestContentGlobs?: string[];
+  chunkHeadingDepth: number;
+}): Promise<{ path: string; upToDate: boolean; sections: number }> {
+  const corpus = await buildCorpus(options);
+  const committed = await readExistingDigest(path.resolve(options.siteRoot, options.digestPath));
+  const upToDate = Boolean(
+    committed && committed.version === 2 && committed.contentHash === corpus.contentHash && committed.nodes.length > 0,
+  );
+  const payload: DigestInput = {
+    contentHash: corpus.contentHash,
+    digestPath: options.digestPath,
+    upToDate,
+    sections: corpusSections(corpus),
+  };
+  const outPath = path.resolve(options.siteRoot, options.outPath);
+  await mkdir(path.dirname(outPath), { recursive: true });
+  await writeFile(outPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  return { path: outPath, upToDate, sections: payload.sections.length };
+}
+
+/**
+ * `assemble` command: read a skill-produced distillation, re-chunk the content
+ * from disk, and write the committed digest with the deterministic parts computed
+ * in code. Keyless — the model never runs here.
+ */
+export async function assembleFromDistillation(options: {
+  siteRoot: string;
+  collections: string[] | null;
+  basePath: string;
+  digestPath: string;
+  inputPath: string;
+  digestContentGlobs?: string[];
+  chunkHeadingDepth: number;
+}): Promise<DigestBuildResult> {
+  const inputPath = path.resolve(options.siteRoot, options.inputPath);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await readFile(inputPath, 'utf8'));
+  } catch {
+    throw new Error(`Could not read distillation JSON at ${options.inputPath}. Run \`ask digest corpus\` first.`);
+  }
+  const corpus = await buildCorpus(options);
+  const digest = assembleDigest(parseEmittedDigest(raw), corpus);
+  const outPath = path.resolve(options.siteRoot, options.digestPath);
+  await writeGraph(outPath, digest);
+  return { status: 'built', path: outPath, contentHash: corpus.contentHash, chunks: corpus.chunks.length };
+}
+
+/** Assembles section nodes. Everything but `summary` is derived deterministically. */
+export function buildNodes(chunks: Chunk[], summaryById: Map<string, string>): DigestNode[] {
+  return chunks
+    .map((chunk): DigestNode => {
+      const facts = extractFacts(chunk.id, chunk.raw);
+      const summary = summaryById.get(chunk.id)?.trim() || excerpt(chunk.text);
+      const terms = distinctiveTokens(
+        [chunk.heading ?? '', summary, facts.map((fact) => fact.literal).join(' '), chunk.text].join(' '),
+      );
+      return {
+        id: chunk.id,
+        kind: 'section',
+        title: chunk.docTitle,
+        heading: chunk.heading ?? null,
+        group: chunk.group ?? null,
+        url: chunk.url,
+        summary,
+        facts,
+        sources: [{ chunkId: chunk.id, url: chunk.url, anchor: chunk.anchorId ?? null }],
+        mode: classifyMode(chunk.group),
+        terms,
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Deterministic grouped table of contents — the agent's cheap high-level map. */
+export function buildOverview(chunks: Chunk[]): string {
+  const byGroup = new Map<string, Chunk[]>();
+  for (const chunk of chunks) {
+    const group = chunk.group ?? 'Docs';
+    (byGroup.get(group) ?? byGroup.set(group, []).get(group)!).push(chunk);
+  }
+  const lines: string[] = [];
+  for (const [group, items] of [...byGroup.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    lines.push(`## ${group}`);
+    for (const chunk of items) {
+      lines.push(`- ${chunk.heading ?? chunk.docTitle} — \`${chunk.id}\``);
+    }
+  }
+  return lines.join('\n');
+}
+
+function excerpt(text: string, max = 220): string {
+  const trimmed = text.replace(/\s+/g, ' ').trim();
+  return trimmed.length > max ? trimmed.slice(0, max).trimEnd() + '…' : trimmed;
+}
+
+export async function buildCorpus(options: {
+  siteRoot: string;
+  collections: string[] | null;
+  basePath: string;
+  digestContentGlobs?: string[];
+  chunkHeadingDepth: number;
+}): Promise<CorpusBuild> {
+  const files = await resolveContentFiles(options.siteRoot, options.collections, options.digestContentGlobs);
+  const documents = await Promise.all(
+    files.map(async (file) => {
+      const raw = await readFile(file, 'utf8');
+      const { data, body } = parseFrontmatter(raw);
+      const slug = slugFromFile(options.siteRoot, file, options.collections);
+      return {
+        slug,
+        title: typeof data.title === 'string' ? data.title : slug,
+        group: typeof data.group === 'string' ? data.group : undefined,
+        description: typeof data.description === 'string' ? data.description : undefined,
+        body,
+      } satisfies SourceDocument;
+    }),
+  );
+
+  const chunks = documents
+    .sort((a, b) => a.slug.localeCompare(b.slug))
+    .flatMap((doc) => chunkDocument(doc, options.basePath, options.chunkHeadingDepth))
+    .sort((a, b) => a.id.localeCompare(b.id));
+  const contentHash = sha256(hashableChunkText(chunks));
+  return { documents, chunks, contentHash };
+}
+
+export function sha256(text: string): string {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+async function readExistingDigest(file: string): Promise<Digest | null> {
+  try {
+    return normalizeDigest(JSON.parse(await readFile(file, 'utf8')));
+  } catch {
+    return null;
+  }
+}
+
+async function resolveContentFiles(
+  siteRoot: string,
+  collections: string[] | null,
+  digestContentGlobs: string[] | undefined,
+): Promise<string[]> {
+  const collectionsForDefault = collections?.length ? collections : ['docs'];
+  const globs =
+    digestContentGlobs?.length
+      ? digestContentGlobs
+      : collectionsForDefault.map((collection) => `src/content/${collection}/**/*.{md,mdx}`);
+  const files = new Set<string>();
+
+  for (const glob of globs) {
+    for (const file of await filesForGlob(siteRoot, glob)) files.add(file);
+  }
+
+  return [...files].sort((a, b) => a.localeCompare(b));
+}
+
+async function filesForGlob(siteRoot: string, glob: string): Promise<string[]> {
+  const normalized = glob.replace(/\\/g, '/');
+  const rootPart = globRoot(normalized);
+  const root = path.resolve(siteRoot, rootPart);
+  const all = await walk(root).catch(() => []);
+  const re = globToRegex(normalized);
+  return all.filter((file) => re.test(path.relative(siteRoot, file).replace(/\\/g, '/')));
+}
+
+function globRoot(glob: string): string {
+  const wildcard = glob.search(/[*{]/);
+  if (wildcard === -1) return path.dirname(glob);
+  const before = glob.slice(0, wildcard);
+  return before.replace(/[/\\][^/\\]*$/, '') || '.';
+}
+
+function globToRegex(glob: string): RegExp {
+  let pattern = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  pattern = pattern.replace(/\\\{([^}]+)\\\}/g, (_, inner: string) => `(${inner.split(',').map(escapeRegex).join('|')})`);
+  pattern = pattern.replace(/\*\*\/?/g, '::GLOBSTAR::');
+  pattern = pattern.replace(/\*/g, '[^/]*');
+  pattern = pattern.replace(/::GLOBSTAR::/g, '(?:.*/)?');
+  return new RegExp(`^${pattern}$`);
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function walk(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const file = path.join(dir, entry.name);
+      return entry.isDirectory() ? walk(file) : [file];
+    }),
+  );
+  return files.flat();
+}
+
+function slugFromFile(siteRoot: string, file: string, collections: string[] | null): string {
+  const normalizedFile = path.resolve(file);
+  const collectionNames = collections?.length ? collections : ['docs'];
+  for (const collection of collectionNames) {
+    const root = path.resolve(siteRoot, 'src/content', collection);
+    const rel = path.relative(root, normalizedFile);
+    if (!rel.startsWith('..') && !path.isAbsolute(rel)) return cleanSlug(rel);
+  }
+
+  return cleanSlug(path.relative(path.resolve(siteRoot, 'src/content'), normalizedFile));
+}
+
+function cleanSlug(rel: string): string {
+  return rel.replace(/\\/g, '/').replace(/\.(md|mdx)$/i, '').replace(/\/index$/, '');
+}

package/src/digest/cli.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { assembleFromDistillation, buildDigest, writeCorpusInput } from './build.ts';
+import { verifyAnchors } from './verify.ts';
+
+interface Flags {
+  collections: string[];
+  basePath?: string;
+  digestPath?: string;
+  digestContentGlobs: string[];
+  chunkHeadingDepth?: number;
+  digestModel?: string;
+  buildCommand?: string;
+  skipBuild?: boolean;
+  strict?: boolean;
+  out?: string;
+  input?: string;
+}
+
+const [command = 'build', ...args] = process.argv.slice(2);
+const flags = parseFlags(args);
+
+try {
+  if (command === 'build') {
+    const result = await buildDigest({
+      siteRoot: process.cwd(),
+      collections: flags.collections.length ? flags.collections : ['docs'],
+      basePath: flags.basePath ?? '/docs/',
+      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
+      chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
+      digestModel: flags.digestModel ?? 'claude-opus-4-8',
+    });
+    console.log(`[hev-ask] digest:${result.status} ${result.path} (${result.chunks} chunks)`);
+  } else if (command === 'corpus') {
+    const result = await writeCorpusInput({
+      siteRoot: process.cwd(),
+      collections: flags.collections.length ? flags.collections : ['docs'],
+      basePath: flags.basePath ?? '/docs/',
+      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      outPath: flags.out ?? '.hev-ask/digest-input.json',
+      digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
+      chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
+    });
+    const state = result.upToDate ? 'up-to-date' : 'needs-rebuild';
+    console.log(`[hev-ask] digest:corpus ${result.path} (${result.sections} sections, ${state})`);
+  } else if (command === 'assemble') {
+    const result = await assembleFromDistillation({
+      siteRoot: process.cwd(),
+      collections: flags.collections.length ? flags.collections : ['docs'],
+      basePath: flags.basePath ?? '/docs/',
+      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      inputPath: flags.input ?? '.hev-ask/digest-distill.json',
+      digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
+      chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
+    });
+    console.log(`[hev-ask] digest:${result.status} ${result.path} (${result.chunks} chunks)`);
+  } else if (command === 'verify') {
+    const result = await verifyAnchors({
+      siteRoot: process.cwd(),
+      collections: flags.collections.length ? flags.collections : ['docs'],
+      basePath: flags.basePath ?? '/docs/',
+      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
+      chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
+      buildCommand: flags.buildCommand,
+      skipBuild: flags.skipBuild,
+    });
+
+    let failed = false;
+
+    // Anchor drift is always fatal — it is fully deterministic and keyless.
+    if (result.missing.length) {
+      for (const miss of result.missing) {
+        console.error(`[hev-ask] missing anchor ${miss.anchorId} for ${miss.url} in ${miss.file}`);
+      }
+      failed = true;
+    }
+
+    // Coverage + literal-fidelity warn by default; --strict makes them fatal.
+    if (result.uncovered.length) {
+      const sample = result.uncovered.slice(0, 5).join(', ');
+      const more = result.uncovered.length > 5 ? `, …(+${result.uncovered.length - 5})` : '';
+      console.warn(`[hev-ask] ${result.uncovered.length} section(s) missing from the digest: ${sample}${more} — run \`ask digest build\`.`);
+      if (flags.strict) failed = true;
+    }
+    if (result.dropped.length) {
+      console.warn(`[hev-ask] ${result.dropped.length} source literal(s) dropped from agent-primary nodes — run \`ask digest build\`:`);
+      for (const drop of result.dropped.slice(0, 8)) console.warn(`  - ${drop.id}: ${drop.literal}`);
+      if (flags.strict) failed = true;
+    }
+
+    if (failed) {
+      process.exitCode = 1;
+    } else {
+      const warnings = result.dropped.length || result.uncovered.length ? ' (with warnings)' : '';
+      console.log(`[hev-ask] verified ${result.checked} anchors${warnings}`);
+    }
+  } else {
+    console.error(
+      'Usage: ask digest build|corpus|assemble|verify [--collection docs] [--base-path /docs/] [--out path] [--input path] [--strict]',
+    );
+    process.exitCode = 1;
+  }
+} catch (err) {
+  console.error(`[hev-ask] ${(err as Error).message}`);
+  process.exitCode = 1;
+}
+
+function parseFlags(args: string[]): Flags {
+  const flags: Flags = { collections: [], digestContentGlobs: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    const next = args[i + 1];
+    if (arg === '--collection' && next) {
+      flags.collections.push(next);
+      i += 1;
+    } else if (arg === '--base-path' && next) {
+      flags.basePath = next;
+      i += 1;
+    } else if (arg === '--digest-path' && next) {
+      flags.digestPath = next;
+      i += 1;
+    } else if (arg === '--content-glob' && next) {
+      flags.digestContentGlobs.push(next);
+      i += 1;
+    } else if (arg === '--chunk-heading-depth' && next) {
+      flags.chunkHeadingDepth = Number(next);
+      i += 1;
+    } else if (arg === '--digest-model' && next) {
+      flags.digestModel = next;
+      i += 1;
+    } else if (arg === '--build-command' && next) {
+      flags.buildCommand = next;
+      i += 1;
+    } else if (arg === '--out' && next) {
+      flags.out = next;
+      i += 1;
+    } else if (arg === '--input' && next) {
+      flags.input = next;
+      i += 1;
+    } else if (arg === '--skip-build') {
+      flags.skipBuild = true;
+    } else if (arg === '--strict') {
+      flags.strict = true;
+    }
+  }
+  return flags;
+}