Knowledge graph format

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

It is the agent’s view of your docs — a distilled, source-grounded “shadow site.” Humans read the rendered pages; the agentic loop reads the graph 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": "knowledge graph", "aliases": ["kg"], "definition": "An offline-built artifact of the docs." }
  ],
  "overview": "## Overview\n- Kubernetes autoscaling — `concepts#kubernetes-autoscaling`\n…",
  "suggestions": [
    "How does the knowledge graph stay fresh?",
    "What does keyword search fall back to without a graph?"
  ],
  "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	KnowledgeNode[]	One distilled section per doc heading — the shadow site.
edges	KnowledgeEdge[]	Reserved for a future node-to-node graph; ships empty.

KnowledgeNode

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 graph with nodes already matches, the build skips the model call.

Degradation

The graph 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 kg build (one API call); the integration also runs ask kg build during astro build when a key is present. Run ask kg verify to gate anchors, coverage, and literal fidelity.