Introduction

hev ask turns an Astro docs site into a small knowledge graph — one distilled, source-grounded entry per heading section, plus a glossary — and then serves that graph to whoever needs to read your docs: a human pressing ⌘K, or a coding agent working in your repo.

The graph is built offline and committed to your repo as .hev-ask/kg.json — reviewable JSON that’s the single source everything else reads.

       BUILD TIME (CLI / Skill)                RUNTIME (edge)
  ╔═════════════════════════════════╗    ╔════════════════════════════════════╗░
  ║  ask kg build                   ║    ║  /api/ask   (prerender: false)     ║░
  ║                                 ║    ║                                    ║░
  ║  glob src/content/docs/**       ║    ║  ┌─── keyword mode · no key ────┐  ║░
  ║   → chunk by heading            ║    ║  │ prefilter chunks + glossary  │  ║░
  ║   → sha256 content hash         ║    ║  └──────────────────────────────┘  ║░
  ║   → Opus 4.8 builds the graph   ║    ║  ┌──── agentic loop · Haiku ────┐  ║░
  ║   → write .hev-ask/kg.json      ║    ║  │ system: kg.context (cached)  │  ║░
  ║                                 ║    ║  │ tool: search(q)  ≤ 4 times   │  ║░
  ╚═════════════════════════════════╝    ║  │ then stream answer, no tools │  ║░
   ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░    ║  │ grounded in /page#anchor     │  ║░
                                         ║  └──────────────────────────────┘  ║░
     .hev-ask/kg.json  (committed)       ╚════════════════════════════════════╝░
           │                              ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
           ▼
     virtual:hev-ask/kg  ──── bundled into /api/ask ────▶

Build it with your coding agent

The knowledge graph is built inside your coding agent — the bundled Claude Code skill generates .hev-ask/kg.json using your existing agentic coding subscription, so there’s no ANTHROPIC_API_KEY and no per-build token spend. Commit the JSON, drop SearchOverlay.astro into a layout, and your site has search — instant keyword results as readers type, plus a Claude answer loop on Enter, every result deep-linked to the exact heading.

Who this is for

You’re building or maintaining an Astro 5 docs site whose content lives in a content collection as Markdown or MDX. You want search and answers that:

• work out of the box without standing up a service or running a crawler,
• deep-link to the right section instead of dumping the reader at the top of a long page,
• can answer a question phrased in the reader’s words, not just match keywords, and
• are queryable by your coding agent, not only by humans in a browser.

If you only need keyword search over a static site and never want an API key in the loop, Pagefind is simpler and a great fit — see Tradeoffs for an honest comparison.

Next steps

• Quick start — add search to your site in five minutes.
• Concepts — chunks, anchors, the agentic loop, and the knowledge graph.
• Tradeoffs and Limits — what you’re choosing, and what hev ask deliberately doesn’t do.
• CLI — build, verify, and query the graph from ask.
• API reference — every option, the component props, and the endpoint contract.