@hevmind/ask 0.1.1 → 0.3.0

package/README.md

@@ -1,8 +1,11 @@
 # @hevmind/ask
 
-hev ask is a heading-anchored search overlay for Astro docs sites. Typing runs
-instant keyword search; pressing `Enter` runs an optional Claude search loop that
-chooses sub-queries and ranks section results.
+hev ask is a heading-anchored search overlay for docs sites. The digest is built
+from your markdown, not your renderer — **Astro** gets the turnkey integration
+below, and **Docusaurus, VitePress, MkDocs, or any static site** get the same
+overlay as a one-script drop-in (see [Frameworks](https://hevask.com/docs/frameworks)).
+Typing runs instant keyword search; pressing `Enter` runs an optional Claude
+search loop that chooses sub-queries and ranks section results.
 
 ## Install
 
@@ -36,7 +39,9 @@ export default defineConfig({
 | Option | Default | Description |
 | --- | --- | --- |
 | `collections` | - | Content collections to index. |
-| `model` | `claude-haiku-4-5` | Runtime search-loop model. |
+| `provider` | `anthropic` | Inference provider: `anthropic`, `openai`, or `openrouter`. Each reads its own key: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`. |
+| `providerBaseUrl` | per provider | Base URL override for the OpenAI-compatible providers (any Chat Completions endpoint). |
+| `model` | per provider | Runtime search-loop model; `claude-haiku-4-5` on the default provider. |
 | `endpoint` | `/api/ask` | Injected on-demand route. |
 | `basePath` | `/docs/` | Turns a doc slug into its page URL. |
 | `maxResults` | `6` | Max results returned. |
@@ -44,8 +49,9 @@ export default defineConfig({
 | `chunkHeadingDepth` | `3` | Chunk at `##` through this heading depth. |
 | `candidatePerSearch` | `8` | Chunks returned by each search tool call. |
 | `perDocCap` | `2` | Max chunks per document in one prefilter call. |
-| `digestModel` | `claude-opus-4-8` | Offline digest build model. |
-| `digestPath` | `.hev-ask/digest.json` | Committed digest artifact path. |
+| `digestModel` | per provider | Offline digest build model; `claude-opus-4-8` on the default provider. |
+| `digestDir` | `.hev-ask` | Committed digest tree directory. |
+| `digestPath` | `.hev-ask` | Deprecated alias for `digestDir`. |
 | `digestContentGlobs` | derived from `collections` | Build-time Markdown/MDX corpus globs. |
 
 ## Add the overlay
@@ -71,9 +77,9 @@ ask digest build
 ask digest verify
 ```
 
-The builder writes `.hev-ask/digest.json`, which should be committed. Builds are
-hash-gated, so unchanged content does not spend another Opus call. `verify`
-builds the site and checks that every chunk anchor exists in `dist`.
+The builder writes the `.hev-ask/` markdown tree, which should be committed.
+Builds are hash-gated, so unchanged content does not spend another Opus call.
+`verify` builds the site and checks that every chunk anchor exists in `dist`.
 
 hev ask uses `github-slugger` to match Astro heading anchors exactly.
 
@@ -102,12 +108,26 @@ Git `path:/packages/ui` dependency.
 Git dependencies are acceptable for local integration while the package is not
 yet published, but they are not the long-term distribution path.
 
+## Other frameworks
+
+The Astro integration above is the turnkey path. On any other framework you build
+the digest the same way (`ask digest build`), bundle the static assets
+(`ask digest bundle`), and drop in the prebuilt overlay as a `<script>` tag —
+keyword search runs fully static, no server. For agentic answers, deploy the
+standalone endpoint and point the overlay at it. See
+[Frameworks](https://hevask.com/docs/frameworks) for Docusaurus, VitePress,
+MkDocs, and plain-HTML recipes.
+
 ## Server Requirements
 
-- Set `ANTHROPIC_API_KEY` for AI search and fresh digest generation.
-- Without a runtime key, `/api/ask` still serves keyword results.
-- The search route is rendered on demand, so the site needs a server adapter in
-  production.
+- Keyword search runs **fully static** — the drop-in overlay reads the committed
+  digest in the browser, no server required.
+- The **agentic** path needs a runtime: on Astro, `/api/ask` is rendered on
+  demand (so the site needs a server adapter in production); on other frameworks,
+  it's the standalone hostable endpoint.
+- Set the provider's API key (`ANTHROPIC_API_KEY` by default) in that server
+  environment for AI search and fresh digest generation. Without a runtime key,
+  the endpoint still serves keyword results.
 
 ## Theming
 

package/openapi.yaml

@@ -1,16 +1,16 @@
 openapi: 3.1.0
 info:
   title: hev ask API
-  version: 3.0.0
+  version: 3.1.0
   summary: Search, answer, and digest read API exposed by the @hevmind/ask Astro integration.
   description: |
     `@hevmind/ask` mounts these routes on a consuming Astro site (default base `/api/ask`,
     configurable via the integration's `endpoint` option). Two paths existed in v2:
     keyword + agentic **search** (`POST /api/ask`) and **suggestions** (`GET /api/ask`).
     v3 adds keyless **read** routes over the committed ask digest
-    (`/api/ask/glossary`, `/api/ask/sections`, `/api/ask/overview`) so a coding agent —
-    via the `ask` CLI, the MCP server, or a generated client — can query the docs
-    directly.
+    (`/api/ask/glossary`, `/api/ask/sections`, `/api/ask/overview`) plus
+    `/api/ask/archive` for bulk tree hydration, so a coding agent — via the
+    `ask` CLI, the MCP server, or a generated client — can query the docs directly.
 
     Degradation: with no `ANTHROPIC_API_KEY` configured on the server, `POST /api/ask`
     falls back to keyword mode (HTTP 200 with a `warning`). The read routes never call a
@@ -18,7 +18,7 @@ info:
   license:
     name: MIT
 servers:
-  - url: https://askhev.com
+  - url: https://hevask.com
     description: The hev ask docs site (dogfoods @hevmind/ask).
   - url: "{origin}"
     description: Any site running the integration.
@@ -30,6 +30,8 @@ tags:
     description: Keyword and agentic search/answer.
   - name: digest
     description: Keyless reads over the committed ask digest.
+  - name: archive
+    description: Bulk hydrate transport for the committed `.hev-ask/` digest tree.
 
 paths:
   /api/ask:
@@ -38,7 +40,7 @@ paths:
       operationId: getSuggestions
       summary: Suggested questions and active model
       description: |
-        Returns the model-authored example questions baked into the committed graph,
+        Returns the model-authored example questions baked into the committed digest,
         shown by the overlay on open. Keyless — no model call.
       responses:
         "200":
@@ -99,7 +101,7 @@ paths:
       tags: [digest]
       operationId: listGlossary
       summary: List glossary terms
-      description: All glossary entries from the committed graph. Keyless.
+      description: All glossary entries from the committed digest. Keyless.
       responses:
         "200":
           description: The glossary.
@@ -204,6 +206,50 @@ paths:
                   overview: { type: string }
                   context: { type: string }
 
+  /api/ask/archive:
+    head:
+      tags: [archive]
+      operationId: headDigestArchive
+      summary: Check digest archive freshness
+      description: |
+        Returns cache headers for the compressed digest tree without the archive body.
+        Clients compare `x-hev-ask-content-hash` against their local cache before
+        downloading the full archive.
+      responses:
+        "200":
+          description: Digest archive metadata.
+          headers:
+            x-hev-ask-content-hash:
+              schema: { type: string }
+              description: Content hash of the committed digest tree.
+            cache-control:
+              schema: { type: string }
+            content-disposition:
+              schema: { type: string }
+    get:
+      tags: [archive]
+      operationId: getDigestArchive
+      summary: Download the digest tree archive
+      description: |
+        Returns a gzip-compressed tar archive of the committed `.hev-ask/`
+        markdown tree. This is the bulk hydrate path used by `ask mcp --endpoint`.
+      responses:
+        "200":
+          description: Gzip-compressed tar archive of the digest tree.
+          headers:
+            x-hev-ask-content-hash:
+              schema: { type: string }
+              description: Content hash of the committed digest tree.
+            cache-control:
+              schema: { type: string }
+            content-disposition:
+              schema: { type: string }
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+
 components:
   parameters:
     Term:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hevmind/ask",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "hev ask: a heading-anchored, agentic search overlay for Astro docs sites.",
   "keywords": [
@@ -28,11 +28,11 @@
     "ask": "./bin/ask.mjs"
   },
   "optionalDependencies": {
-    "@hevmind/ask-darwin-arm64": "0.1.1",
-    "@hevmind/ask-darwin-x64": "0.1.1",
-    "@hevmind/ask-win32-x64": "0.1.1",
-    "@hevmind/ask-linux-arm64": "0.1.1",
-    "@hevmind/ask-linux-x64": "0.1.1"
+    "@hevmind/ask-win32-x64": "0.3.0",
+    "@hevmind/ask-linux-arm64": "0.3.0",
+    "@hevmind/ask-darwin-arm64": "0.3.0",
+    "@hevmind/ask-linux-x64": "0.3.0",
+    "@hevmind/ask-darwin-x64": "0.3.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/skills/build-digest/SKILL.md

@@ -1,120 +1,84 @@
 ---
 name: build-digest
 description: >-
-  Build the @hevmind/ask ask digest (.hev-ask/digest.json) for an Astro docs site
-  using your Claude Code subscription instead of an ANTHROPIC_API_KEY. Use when
-  the user asks to build, rebuild, or refresh the hev ask digest, knowledge
-  graph, KG, or search index, or after docs content changes. Runs `ask digest
-  corpus --shards-dir`, distils each shard in a fresh context, and runs
-  `ask digest assemble --input-dir`.
+  Build the @hevmind/ask ask digest (the committed .hev-ask/ markdown tree) for a
+  docs site using your own agent subscription instead of a provider API key. Use
+  when asked to build, rebuild, or refresh the hev ask digest, search index, or
+  knowledge graph (KG), or after docs content changes. Shards the corpus, distils
+  each shard in a fresh context, then assembles and verifies.
 ---
 
 # Build the hev ask digest
 
-`@hevmind/ask` searches an Astro docs site. Its agentic loop, keyword ranking, and
-suggested questions are powered by a committed ask digest at
-`.hev-ask/digest.json`. Only the **distillation** needs a model — the node
-structure, verbatim facts, overview map, and content hash are computed
-deterministically by the CLI. This skill performs that distillation here, in
-the user's subscription, so it costs **no API tokens on their own key**.
-
-The corpus is split into **shards** (~200KB of text each, along slug-prefix
-boundaries) and each shard is distilled in its own fresh context. Corpus size
-is therefore never a context-limit problem — a bigger site just means more
-shards. All state lives on disk in `.hev-ask/shards/`, so the build can be
-stopped, resumed, and incrementally refreshed: after content edits, only the
-shards whose content changed need re-distilling.
-
-Run every command from the **site root** (the directory whose `astro.config.*`
-registers `hevAsk()`). Prefer `pnpm exec ask digest …`; fall back to
-`npx -p @hevmind/ask ask digest …` if pnpm isn't used. Pass the same content flags
-the site's integration uses if they differ from the defaults (`--collection`,
-`--base-path`, `--chunk-heading-depth`, `--content-glob`, `--digest-path`);
-they must match across `corpus` and `assemble`.
-
-**Never read a shard input file into the orchestrating context** (they hold
-the full corpus text). The orchestrator works only from command output,
-`manifest.json`, and `status`; shard contents are read by the per-shard
-distillation agents.
+`@hevmind/ask`'s agentic loop, keyword ranking, and suggested questions run off a
+committed digest tree at `.hev-ask/`. Only the **distillation** needs a model —
+the CLI computes the node structure, verbatim facts, overview map, and content
+hashes deterministically. This skill does that distillation here in your
+subscription, so it costs **no provider API tokens**.
 
-## Steps
+`ask` is the `@hevmind/ask` binary: install it on PATH, or it resolves via the
+package bin / `HEV_ASK_BINARY` (see `api/cli.mdx`). Run every command from the
+**site root** (the dir whose config registers `hevAsk()`). If the integration
+overrides any content flags (`--collection`, `--base-path`,
+`--chunk-heading-depth`, `--content-glob`, `--digest-dir`), pass the same ones to
+`corpus` and `assemble` — they must match.
 
-1. **Shard the corpus.**
+The corpus splits into ~200KB **shards** (`--shard-bytes` tunes it), each
+distilled in its own context, so corpus size is never a context limit. State
+lives in `.hev-ask/shards/`, so the build resumes and refreshes incrementally:
+after edits, only changed shards re-distil.
 
-   ```sh
-   pnpm exec ask digest corpus --shards-dir .hev-ask/shards
-   ```
+**Never read a shard input file yourself** — they hold the full corpus text.
+Work from command output and `status`; the per-shard agents read the shards.
 
-   Deterministic and keyless. Writes one `input-<shard-id>.json` per shard
-   plus `manifest.json`, and reports `(N sections, M shards, P pending,
-   up-to-date|needs-rebuild)`. Re-running after content edits is safe and is
-   the refresh mechanism: unchanged shards keep their distillations; changed
-   ones are marked pending again.
-
-2. **Check state.** If the corpus reported `up-to-date` AND `0 pending`, the
-   committed digest already matches the content — **stop here** and tell the
-   user nothing needs rebuilding. Otherwise:
+## Steps
 
-   ```sh
-   pnpm exec ask digest status --shards-dir .hev-ask/shards
-   ```
+1. **Shard.** `ask digest corpus --shards-dir .hev-ask/shards`
+   Deterministic and keyless. Reports `(N sections, M shards, P pending,
+   up-to-date|needs-rebuild)`. Safe to re-run; this is the refresh mechanism.
 
-   lists which shards are `pending` or `stale` (distilled against older
-   content). Both need distilling.
+2. **Check.** If corpus said `up-to-date` AND `0 pending`, the digest already
+   matches the content — **stop and tell the user nothing needs rebuilding.**
+   Otherwise `ask digest status --shards-dir .hev-ask/shards` lists the
+   `pending`/`stale` shards (both need distilling).
 
 3. **Distil each pending/stale shard in a fresh context.** Spawn one agent per
-   shard (run a few in parallel; don't read shard contents yourself). Each
-   agent gets this prompt, with `<id>` filled in:
+   shard (a few in parallel; don't read shards yourself). Give each this prompt
+   with `<id>` filled in:
 
-   > Read ONLY `.hev-ask/shards/input-<id>.json` (from the site root). It has
-   > `shardId`, `shardHash`, and a `sections` array of `{ id, url, title,
-   > text }`. Write `.hev-ask/shards/distill-<id>.json` with exactly this
-   > shape:
+   > Read ONLY `.hev-ask/shards/input-<id>.json` (from the site root): it has
+   > `shardId`, `shardHash`, and a `sections` array of `{ id, url, title, text }`.
+   > Write `.hev-ask/shards/distill-<id>.json` with exactly this shape:
    >
    > ```json
    > {
-   >   "shardHash": "<copy the shardHash from the input file verbatim>",
-   >   "notes": "5-10 lines: what this shard covers, its key concepts, and how users talk about them.",
-   >   "glossary": [
-   >     { "term": "ask digest", "aliases": ["digest", "kg"], "definition": "One-line definition." }
-   >   ],
-   >   "summaries": [
-   >     { "id": "<exact section id from sections>", "summary": "1-3 sentence distillation." }
-   >   ]
+   >   "shardHash": "<copy shardHash verbatim>",
+   >   "notes": "5-10 lines: what this shard covers, its key concepts, and how users phrase them.",
+   >   "glossary": [{ "term": "...", "aliases": ["..."], "definition": "One line." }],
+   >   "summaries": [{ "id": "<exact section id>", "summary": "1-3 sentences." }]
    > }
    > ```
    >
-   > Rules:
-   > - Emit **one `summaries` entry for every `id`** in `sections` — no more,
-   >   no fewer. Use the exact id strings.
-   > - Summaries are what the search agent reasons from: faithful,
-   >   self-contained, 1-3 sentences. **Paraphrase prose, but never restate
-   >   code, flags, commands, or exact identifiers** — those are extracted
-   >   verbatim by the CLI and would only drift if you retyped them.
-   > - `glossary`: at most the ~10 terms from this shard a real user would
-   >   type (aliases like `k8s` for `kubernetes`); one-line definitions. The
-   >   CLI dedupes and caps the merged glossary.
-   > - `notes` is NOT user-facing — it feeds a later site-wide synthesis pass.
-   > - Your final message: just the shard id and how many summaries you wrote.
-
-   If the run is interrupted, just re-run from step 1 — disk state is the
-   source of truth and `status` shows what's left.
-
-4. **Synthesize the global context.** Once every shard is distilled, extract
-   only the `notes` fields (small) — never the full distill files:
-
-   ```sh
-   python3 -c "import json,glob; [print('##', f.split('distill-')[1].removesuffix('.json'), '\n' + json.load(open(f)).get('notes','')) for f in sorted(glob.glob('.hev-ask/shards/distill-*.json'))]"
-   ```
-
-   From those notes, write `.hev-ask/shards/global.json`:
+   > - One `summaries` entry for every `id` in `sections` — exact ids, no more, no fewer.
+   > - Summaries are what the search agent reasons from: faithful, self-contained.
+   >   Paraphrase prose; **never restate code, flags, commands, or identifiers** —
+   >   the CLI extracts those verbatim, and they'd only drift if retyped.
+   > - `glossary`: ≤10 terms a real user would actually type (aliases like
+   >   `k8s`→`kubernetes`); one-line definitions. The CLI dedupes and caps them.
+   > - `notes` is not user-facing; it feeds the global synthesis pass.
+   > - Reply with just the shard id and how many summaries you wrote.
+
+   Interrupted? Re-run from step 1 — disk is the source of truth and `status`
+   shows what's left.
+
+4. **Synthesize the global context.** Once every shard is distilled, read the
+   `notes` field from each `.hev-ask/shards/distill-*.json` (small — never the
+   full files) and write `.hev-ask/shards/global.json`:
 
    ```json
    {
      "context": "Compact markdown orientation: what the product/site is, its core concepts and feature areas, and how users talk about them.",
-     "suggestions": [
-       "A natural question a reader might type that these docs answer."
-     ],
+     "suggestions": ["A natural question a reader might type that these docs answer."],
      "glossary": []
    }
    ```
@@ -122,43 +86,29 @@ distillation agents.
    `suggestions`: 3-5 questions phrased the way a user would ask them, each
    genuinely answerable from these docs (they show in the overlay on open).
 
-5. **Assemble.**
-
-   ```sh
-   pnpm exec ask digest assemble --input-dir .hev-ask/shards
-   ```
-
-   Merges every current shard distillation with the global synthesis, derives
-   the deterministic parts, and writes `.hev-ask/digest.json`. Sections from
-   undistilled shards fall back to plain excerpts and are reported — the
-   digest stays usable mid-wave, but aim for 0 pending before committing.
-
-6. **Verify.**
-
-   ```sh
-   pnpm exec ask digest verify
-   ```
+5. **Assemble.** `ask digest assemble --input-dir .hev-ask/shards`
+   Merges every shard distillation with the global synthesis, derives the
+   deterministic parts, and writes the `.hev-ask/` tree. Undistilled shards fall
+   back to excerpts and are reported — usable mid-wave, but aim for 0 pending
+   before committing.
 
-   Anchor drift is fatal; coverage/fidelity warnings are informational.
+6. **Verify.** `ask digest verify` — anchor drift is fatal; coverage/fidelity
+   warnings are informational.
 
-7. **Clean up and commit.** The shards directory is a local cache — it is the
-   resume/refresh state, so keep it on disk but out of git, and drop the bulky
-   input files (regenerated by `corpus` any time):
+7. **Commit.** The shards dir is the local resume/refresh cache — keep it on disk
+   but out of git, and drop the bulky input files (`corpus` regenerates them):
 
    ```sh
    rm -f .hev-ask/shards/input-*.json
    git check-ignore -q .hev-ask/shards || echo ".hev-ask/shards/" >> .gitignore
-   git add .gitignore .hev-ask/digest.json
+   git add .gitignore .hev-ask
    ```
 
-   Only `.hev-ask/digest.json` is committed.
+   Only the `.hev-ask/` tree is committed; `.hev-ask/shards/` stays local.
 
 ## Notes
 
-- A small site may produce a single shard; the flow is the same (you can
-  distil it yourself instead of spawning an agent — a single shard's input is
-  small enough to read directly).
-- `--shard-bytes` (default 200000) tunes shard size if a site's sections are
-  unusually dense.
-- If `corpus` fails because no content is found, you're likely not in the
-  site root, or the collection name isn't `docs` — pass `--collection <name>`.
+- A small site may produce a single shard — distil it yourself instead of
+  spawning an agent (its input is small enough to read directly).
+- If `corpus` finds no content, you're likely not in the site root, or the
+  collection isn't named `docs` — pass `--collection <name>`.

package/src/digest/build.ts

@@ -1,11 +1,13 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { callClaude, type AnthropicTool } from '../llm.ts';
+import { type AnthropicTool } from '../llm.ts';
+import { PROVIDERS, clientFor, resolveProviderName, type ProviderName } from '../providers.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';
+import { digestTreeFiles, readDigestArtifact } from './tree.ts';
 
 export interface DigestBuildOptions {
   siteRoot: string;
@@ -15,6 +17,8 @@ export interface DigestBuildOptions {
   digestContentGlobs?: string[];
   chunkHeadingDepth: number;
   digestModel: string;
+  provider?: ProviderName;
+  providerBaseUrl?: string;
   apiKey?: string;
 }
 
@@ -94,7 +98,7 @@ export interface EmittedDistillation {
 export interface DigestInput {
   contentHash: string;
   digestPath: string;
-  /** True when the committed digest.json already matches this corpus — no rebuild needed. */
+  /** True when the committed digest tree already matches this corpus — no rebuild needed. */
   upToDate: boolean;
   sections: Array<{ id: string; url: string; title: string; text: string }>;
 }
@@ -133,21 +137,22 @@ export function assembleDigest(emitted: EmittedDistillation, corpus: CorpusBuild
 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);
+  const existing = readExistingDigest(options.siteRoot, options.digestPath);
   // 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 provider = resolveProviderName(options.provider);
+  const apiKey = options.apiKey ?? process.env[PROVIDERS[provider].envKey];
+  if (!apiKey) throw new Error(`${PROVIDERS[provider].envKey} 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({
+  const response = await clientFor(provider, options.providerBaseUrl).call({
     apiKey,
     model: options.digestModel,
     maxTokens: 8192,
@@ -203,8 +208,21 @@ export function parseEmittedDigest(input: unknown): EmittedDistillation {
 }
 
 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');
+  if (path.extname(outPath).toLowerCase() === '.json') {
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, JSON.stringify(digest, null, 2) + '\n', 'utf8');
+    return;
+  }
+
+  await mkdir(outPath, { recursive: true });
+  const desired = new Set<string>();
+  for (const file of digestTreeFiles(digest)) {
+    const target = path.join(outPath, file.path);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, file.body, 'utf8');
+    desired.add(file.path);
+  }
+  await removeOrphanDigestMarkdown(outPath, desired);
 }
 
 /**
@@ -221,7 +239,7 @@ export async function writeCorpusInput(options: {
   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 committed = readExistingDigest(options.siteRoot, options.digestPath);
   const upToDate = Boolean(
     committed && committed.version === 2 && committed.contentHash === corpus.contentHash && committed.nodes.length > 0,
   );
@@ -282,6 +300,7 @@ export function buildNodes(chunks: Chunk[], summaryById: Map<string, string>): D
         group: chunk.group ?? null,
         url: chunk.url,
         summary,
+        hash: sectionHash(chunk),
         facts,
         sources: [{ chunkId: chunk.id, url: chunk.url, anchor: chunk.anchorId ?? null }],
         mode: classifyMode(chunk.group),
@@ -348,12 +367,31 @@ 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;
-  }
+function sectionHash(chunk: Chunk): string {
+  return sha256(`${chunk.id}\n${chunk.text}`);
+}
+
+function readExistingDigest(siteRoot: string, digestPath: string): Digest | null {
+  const digest = readDigestArtifact(siteRoot, digestPath);
+  return digest.version === 2 && digest.nodes.length > 0 ? digest : null;
+}
+
+async function removeOrphanDigestMarkdown(root: string, desired: Set<string>, relDir = ''): Promise<void> {
+  const dir = path.join(root, relDir);
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (entry.isDirectory()) {
+        if (entry.name === 'shards') return;
+        await removeOrphanDigestMarkdown(root, desired, path.join(relDir, entry.name));
+        return;
+      }
+      const rel = path.join(relDir, entry.name).replace(/\\/g, '/');
+      if (path.extname(entry.name).toLowerCase() === '.md' && !desired.has(rel)) {
+        await rm(path.join(root, rel), { force: true });
+      }
+    }),
+  );
 }
 
 async function resolveContentFiles(