Digest format

The ask digest is a single JSON file, by default .hev-ask/digest.json, built offline by ask digest build and committed to your repo. (In earlier versions it was called the knowledge graph, or kg.) The integration inlines it into the build through the virtual:hev-ask/digest module, so the running site reads it with no filesystem access.

It is the agent’s view of your docs — a distilled, source-grounded index read progressively. Humans read the rendered pages; the agentic loop reads the digest and links back to the real pages. Every node carries a url#anchor to its source.

Shape

{
  "version": 2,
  "generatedAt": "2026-05-30T12:00:00.000Z",
  "contentHash": "a1b2c3…",
  "context": "## hev ask\n\nA search overlay for Astro docs…",
  "glossary": [
    { "term": "ask digest", "aliases": ["kg", "digest"], "definition": "The offline-built artifact distilled from the docs." }
  ],
  "overview": "## Overview\n- Kubernetes autoscaling — `concepts#kubernetes-autoscaling`\n…",
  "suggestions": [
    "How does the ask digest stay fresh?",
    "What does keyword search fall back to without a digest?"
  ],
  "nodes": [
    {
      "id": "concepts#kubernetes-autoscaling",
      "kind": "section",
      "title": "Core Concepts",
      "heading": "Kubernetes autoscaling",
      "group": "Overview",
      "url": "/docs/concepts#kubernetes-autoscaling",
      "summary": "Scales workers from lag and throughput signals.",
      "facts": [{ "kind": "flag", "literal": "--max-workers", "chunkId": "concepts#kubernetes-autoscaling" }],
      "sources": [{ "chunkId": "concepts#kubernetes-autoscaling", "url": "/docs/concepts#kubernetes-autoscaling", "anchor": "kubernetes-autoscaling" }],
      "mode": "agent-primary",
      "terms": ["autoscaling", "workers", "signals"]
    }
  ],
  "edges": []
}

Fields

Field	Type	Description
version	2	Schema version.
generatedAt	string	ISO timestamp stamped by the build (Node time, not edge).
contentHash	string	sha256 of the concatenated chunk text. The freshness gate.
context	string	Compact orientation; degradation fallback when there are no nodes.
glossary	GlossaryEntry[]	Terms with aliases and definitions; widens keyword search.
overview	string	A deterministic grouped map of every section, injected into the agent’s prompt.
suggestions	string[]	Model-authored example questions the overlay shows on open. The endpoint serves them; absent ⇒ the overlay shows none.
nodes	DigestNode[]	One distilled section per doc heading — the body of the digest.
edges	DigestEdge[]	Reserved; ships empty.

DigestNode

Field	Type	Description
id	string	Equals the chunk id, so it maps 1:1 to a real anchor.
summary	string	The model’s paraphrase — what the agent reasons from.
facts	Fact[]	Verbatim literals (flags, code, identifiers) extracted deterministically. The model never authors them, so the agent quotes exact strings without re-reading the page.
sources	SourceRef[]	Provenance — the chunk the node came from, with its url/anchor.
mode	'agent-primary' | 'source-primary'	Reference/API sections are source-primary: the agent reads their source text verbatim.
terms	string[]	Distinctive tokens for the render-time link-support check.

How each field is used

• overview + nodes are injected into the agentic loop’s system prompt (prompt-cached). The agent opens the sections it needs and answers from their summaries, quoting facts verbatim for exact strings.
• glossary drives keyword query expansion — each query term picks up its aliases before retrieval, so k8s finds kubernetes sections.
• nodes also rank keyword results: a query term that hits a section’s summary, terms, or facts lifts that section above an incidental body mention. Without nodes, ranking falls back to raw token overlap.
• terms back a render-time check: a cited link degrades to plain text if the surrounding answer shares none of the cited node’s terms.
• suggestions are returned by the endpoint’s GET and rendered as the overlay’s suggested questions on open.
• contentHash is the freshness gate. build recomputes it; if a committed digest with nodes already matches, the build skips the model call.

Degradation

The digest is read defensively. If the file is missing or malformed, or it is an older node-less (v1) artifact, the integration uses it as-is: with no nodes the agentic loop falls back to keyword-style search, and keyword mode still works. Nothing hard-fails.

Regenerating

Rebuild after content changes and commit the result. The hash gate makes this safe to run on every build — it only spends model work when the content actually changed. Build it with the bundled Claude Code skill (no API key) or ask digest build (one API call, bounded at ~600KB of corpus text); the integration also runs ask digest build during astro build when a key is present. Large sites use the sharded flow, which distils the corpus shard-by-shard in fresh contexts and re-distils only the shards a content edit touches. Run ask digest verify to gate anchors, coverage, and literal fidelity.