@hevmind/ask 0.1.0 → 0.2.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/bin/ask-launcher.mjs

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { accessSync, chmodSync, constants as fsConstants, existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -42,12 +42,29 @@ function resolvePackagedBinary() {
   try {
     const packageJson = require.resolve(`${packageName}/package.json`);
     const candidate = path.join(path.dirname(packageJson), 'bin', executableName());
-    return existsSync(candidate) ? candidate : null;
+    if (!existsSync(candidate)) return null;
+    ensureExecutable(candidate);
+    return candidate;
   } catch {
     return null;
   }
 }
 
+// Some package managers strip the executable bit when packing/extracting
+// (pnpm pack only preserves it for a package's own declared bins).
+function ensureExecutable(file) {
+  if (process.platform === 'win32') return;
+  try {
+    accessSync(file, fsConstants.X_OK);
+  } catch {
+    try {
+      chmodSync(file, 0o755);
+    } catch {
+      // spawn will surface the real error if this didn't help
+    }
+  }
+}
+
 function platformPackageName() {
   const platform = process.platform;
   const arch = process.arch;

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.0",
+  "version": "0.2.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.0",
-    "@hevmind/ask-linux-arm64": "0.1.0",
-    "@hevmind/ask-darwin-x64": "0.1.0",
-    "@hevmind/ask-linux-x64": "0.1.0",
-    "@hevmind/ask-win32-x64": "0.1.0"
+    "@hevmind/ask-darwin-arm64": "0.2.0",
+    "@hevmind/ask-linux-x64": "0.2.0",
+    "@hevmind/ask-win32-x64": "0.2.0",
+    "@hevmind/ask-linux-arm64": "0.2.0",
+    "@hevmind/ask-darwin-x64": "0.2.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/skills/build-digest/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build-digest
 description: >-
-  Build the @hevmind/ask ask digest (.hev-ask/digest.json) for an Astro docs site
+  Build the @hevmind/ask ask digest (.hev-ask/ markdown tree) 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
@@ -12,8 +12,8 @@ description: >-
 # 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
+suggested questions are powered by a committed ask digest tree at
+`.hev-ask/`. 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**.
@@ -29,7 +29,7 @@ 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`);
+`--base-path`, `--chunk-heading-depth`, `--content-glob`, `--digest-dir`);
 they must match across `corpus` and `assemble`.
 
 **Never read a shard input file into the orchestrating context** (they hold
@@ -129,7 +129,7 @@ distillation agents.
    ```
 
    Merges every current shard distillation with the global synthesis, derives
-   the deterministic parts, and writes `.hev-ask/digest.json`. Sections from
+   the deterministic parts, and writes the `.hev-ask/` markdown tree. 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.
 
@@ -148,10 +148,10 @@ distillation agents.
    ```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/` remains local.
 
 ## Notes
 

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(

package/src/digest/cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { PROVIDERS, resolveProviderName } from '../providers.ts';
 import { assembleFromDistillation, buildDigest, writeCorpusInput } from './build.ts';
 import { verifyAnchors } from './verify.ts';
 
@@ -9,6 +10,8 @@ interface Flags {
   digestContentGlobs: string[];
   chunkHeadingDepth?: number;
   digestModel?: string;
+  provider?: string;
+  providerBaseUrl?: string;
   buildCommand?: string;
   skipBuild?: boolean;
   strict?: boolean;
@@ -21,14 +24,17 @@ const flags = parseFlags(args);
 
 try {
   if (command === 'build') {
+    const provider = resolveProviderName(flags.provider);
     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',
+      digestPath: flags.digestPath ?? '.hev-ask',
       digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
       chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
-      digestModel: flags.digestModel ?? 'claude-opus-4-8',
+      digestModel: flags.digestModel ?? PROVIDERS[provider].defaultDigestModel,
+      provider,
+      providerBaseUrl: flags.providerBaseUrl,
     });
     console.log(`[hev-ask] digest:${result.status} ${result.path} (${result.chunks} chunks)`);
   } else if (command === 'corpus') {
@@ -36,7 +42,7 @@ try {
       siteRoot: process.cwd(),
       collections: flags.collections.length ? flags.collections : ['docs'],
       basePath: flags.basePath ?? '/docs/',
-      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      digestPath: flags.digestPath ?? '.hev-ask',
       outPath: flags.out ?? '.hev-ask/digest-input.json',
       digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
       chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
@@ -48,7 +54,7 @@ try {
       siteRoot: process.cwd(),
       collections: flags.collections.length ? flags.collections : ['docs'],
       basePath: flags.basePath ?? '/docs/',
-      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      digestPath: flags.digestPath ?? '.hev-ask',
       inputPath: flags.input ?? '.hev-ask/digest-distill.json',
       digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
       chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
@@ -59,7 +65,7 @@ try {
       siteRoot: process.cwd(),
       collections: flags.collections.length ? flags.collections : ['docs'],
       basePath: flags.basePath ?? '/docs/',
-      digestPath: flags.digestPath ?? '.hev-ask/digest.json',
+      digestPath: flags.digestPath ?? '.hev-ask',
       digestContentGlobs: flags.digestContentGlobs.length ? flags.digestContentGlobs : undefined,
       chunkHeadingDepth: flags.chunkHeadingDepth ?? 3,
       buildCommand: flags.buildCommand,
@@ -97,7 +103,7 @@ try {
     }
   } else {
     console.error(
-      'Usage: ask digest build|corpus|assemble|verify [--collection docs] [--base-path /docs/] [--out path] [--input path] [--strict]',
+      'Usage: ask digest build|corpus|assemble|verify [--collection docs] [--base-path /docs/] [--digest-dir .hev-ask] [--provider anthropic|openai|openrouter] [--out path] [--input path] [--strict]',
     );
     process.exitCode = 1;
   }
@@ -117,7 +123,7 @@ function parseFlags(args: string[]): Flags {
     } else if (arg === '--base-path' && next) {
       flags.basePath = next;
       i += 1;
-    } else if (arg === '--digest-path' && next) {
+    } else if ((arg === '--digest-dir' || arg === '--digest-path') && next) {
       flags.digestPath = next;
       i += 1;
     } else if (arg === '--content-glob' && next) {
@@ -129,6 +135,12 @@ function parseFlags(args: string[]): Flags {
     } else if (arg === '--digest-model' && next) {
       flags.digestModel = next;
       i += 1;
+    } else if (arg === '--provider' && next) {
+      flags.provider = next;
+      i += 1;
+    } else if (arg === '--provider-url' && next) {
+      flags.providerBaseUrl = next;
+      i += 1;
     } else if (arg === '--build-command' && next) {
       flags.buildCommand = next;
       i += 1;

package/src/digest/frontmatter.ts

@@ -37,5 +37,12 @@ function parseScalar(value: string): unknown {
   if (value === 'false') return false;
   const numberValue = Number(value);
   if (Number.isFinite(numberValue) && /^-?\d+(\.\d+)?$/.test(value)) return numberValue;
+  if (value.startsWith('[') || value.startsWith('{') || value === 'null') {
+    try {
+      return JSON.parse(value);
+    } catch {
+      // Fall through to the raw scalar.
+    }
+  }
   return value;
 }

package/src/digest/schema.ts

@@ -36,6 +36,8 @@ export interface DigestNode {
   url: string;
   /** Model-distilled prose. May paraphrase; exact strings live in `facts`. */
   summary: string;
+  /** Per-section source hash used by the incremental digest builder. */
+  hash?: string;
   /** Deterministically extracted verbatim literals. */
   facts: Fact[];
   /** Provenance — for a section node, its own chunk. */
@@ -144,6 +146,7 @@ function normalizeNode(value: unknown): DigestNode | null {
     group: typeof maybe.group === 'string' ? maybe.group : null,
     url: maybe.url,
     summary: typeof maybe.summary === 'string' ? maybe.summary : '',
+    hash: typeof maybe.hash === 'string' ? maybe.hash : undefined,
     facts: Array.isArray(maybe.facts)
       ? maybe.facts.map((fact) => normalizeFact(fact)).filter((fact): fact is Fact => fact !== null)
       : [],