Introduction

hev ask distills a docs site into an ask digest: a compact directory with one small markdown file per section. The digest is a distilled mirror of your docs that an agent navigates the way it navigates any directory, and that a ⌘K overlay answers your readers from. It works with Astro, Docusaurus, VitePress, MkDocs, or any folder of markdown.

The digest is host-neutral: it’s built from your markdown, not your renderer. hev ask ships a turnkey integration for Astro, and every other framework can add the same overlay with a single script. Build the digest offline with the bundled skill (and your Claude Code subscription), commit the tree, and your docs become readable three ways from one artifact. It’s a good fit for technical documentation, internal wikis, and other medium-sized corpora.

  ask digest build
      glob collections → chunk by headings → distil each section (Opus 4.8)
      one markdown file per section · hash-gated, incremental
      │
      ▼
  .hev-ask/                a committed, distilled mirror of your docs
  ├─ _meta.md              overview · context · suggestions · content hash
  ├─ _glossary/
  │  └─ digest.md          a term · its aliases · its definition
  ├─ overview/
  │  ├─ quick-start.md     one markdown + frontmatter file per section:
  │  └─ limits.md          title · summary · body · facts · url#anchor
  └─ api/
     └─ cli.md
      │
      ▼
  read three ways
  ├─ ⌘K overlay · humans   keyword search + a grounded answer · synthesis
  ├─ ask CLI    · agents   tree · ls · head · cat · facts · grep · keyless
  └─ ask mcp    · agents   one tool hydrates the tree; the agent reads it

One artifact, three readers

The digest is built inside your coding agent — the bundled Claude Code skill writes the .hev-ask/ tree using your existing agentic coding subscription, so there’s no ANTHROPIC_API_KEY and no per-build token spend. Commit the tree, and the same files serve:

• the ⌘K overlay, for humans — instant keyword results as readers type, plus a grounded Claude answer on Enter, every result deep-linked to the exact heading;
• the ask CLI, for agents — tree, ls, head, cat, facts, grep over path keys, keyless, from any shell;
• the ask mcp server, for agents — one tool that hydrates the whole tree to local disk, after which the agent reads it with the file tools it already has.

The overlay synthesizes an answer for the human reader. The CLI and MCP hand an agent the raw files and let its own tools do the rest.

Who this is for

You’re building or maintaining a docs site whose content lives in Markdown or MDX — on Astro (the turnkey integration), Docusaurus, VitePress, MkDocs, or anything that renders a folder of markdown. 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.

On Astro, one integration covers all of that. Other frameworks drop in the static overlay and, for the agentic answers, point it at an optional hosted endpoint. See the drop-in overlay for the path on yours.

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 an Astro site in five minutes.
• Digest creation — how the tree is built, kept fresh, and verified.
• Concepts — chunks, anchors, the disclosure ladder, the agentic loop, and the ask digest directory.
• Tradeoffs and Limits — what you’re choosing, and what hev ask deliberately doesn’t do.
• CLI — browse and search the digest tree with ask: tree, cat, grep.
• API reference — every option, the component props, and the endpoint contract.