API

CLI

@hev/ask ships the ask binary. It has two command groups:

Consumer commands read the committed graph for agents: glossary, sections, section get, overview, search, answer, and mcp.
Producer commands live under ask kg: build, corpus, assemble, and verify.

hev-ask-kg is kept as a deprecated compatibility alias for one minor cycle. It forwards to ask kg ... and prints a one-line migration notice.

Reading the graph

By default, ask reads .hev-ask/kg.json from the current repo. Pass --endpoint <url> to read from a deployed site’s HTTP API instead.

ask glossary list
ask glossary get "knowledge graph"
ask sections list --group API
ask section get api/endpoint#knowledge-graph-reads-get
ask overview
ask search "read endpoints"
ask --endpoint https://askhev.com/api/ask answer "what read routes exist?"
ask mcp

ask answer uses the deployed endpoint’s agentic SSE path, so it requires --endpoint. For keyless local retrieval, use ask search.

Building the graph

Run producer commands from the Astro site root:

ask kg build        # one-shot build; needs ANTHROPIC_API_KEY only when stale
ask kg corpus       # emit sections for a keyless skill/model distillation
ask kg assemble     # assemble .hev-ask/kg.json from that distillation
ask kg verify       # build the site and verify anchors, coverage, fidelity

ask kg build is hash-gated. If the committed graph already matches the corpus, it exits without calling the model. Otherwise it asks the KG model for the distillation and writes .hev-ask/kg.json.

ask kg corpus writes .hev-ask/kg-input.json; ask kg assemble reads .hev-ask/kg-distill.json and writes .hev-ask/kg.json. These commands expose the same deterministic seam used by the bundled Claude Code skill: the model authors only context, glossary, per-section summaries, and suggestions. Chunking, facts, overview, node sources, and the content hash are computed in code.

ask kg verify builds the site unless --skip-build is set, then checks rendered heading anchors, graph coverage, and literal fidelity against the committed graph. Anchor drift is always fatal; coverage and literal-fidelity are warnings unless --strict is set.

Package scripts

Use ask kg in site scripts:

{
  "scripts": {
    "kg:build": "ask kg build",
    "kg:verify": "ask kg verify"
  }
}

Existing scripts that call hev-ask-kg build or hev-ask-kg verify keep working through the alias, but new scripts should use ask kg.

Claude Code skill

The bundled build-kg skill can build a graph without using your ANTHROPIC_API_KEY. It runs the deterministic producer seam:

ask kg corpus       -> .hev-ask/kg-input.json
...writes .hev-ask/kg-distill.json...
ask kg assemble     -> .hev-ask/kg.json

Because the model step runs inside your Claude Code subscription, the graph build costs no API tokens on your own key. The resulting kg.json has the same shape as ask kg build output, and the same hash gate applies.

Flags

Flag	Default	Description
`--kg-path <path>`	`.hev-ask/kg.json`	Local graph path for reads; output/input path for producer commands.
`--endpoint <url>`	-	Remote `/api/ask` base URL for read commands and `answer`.
`--json`	automatic for non-TTY in the standalone CLI	Force machine-readable JSON output.
`--max-results <n>`	`8`	Local search result cap.
`--collection <name>`	`docs`	Collection to read for producer commands. Repeat for multiple.
`--base-path <path>`	`/docs/`	Slug to URL prefix for producer commands.
`--content-glob <glob>`	derived	Source globs for producer commands. Repeat for multiple.
`--chunk-heading-depth <n>`	`3`	Deepest heading used as a chunk boundary.
`--kg-model <model>`	`claude-opus-4-8`	Model used by `ask kg build`.
`--out <path>`	`.hev-ask/kg-input.json`	Output path for `ask kg corpus`.
`--input <path>`	`.hev-ask/kg-distill.json`	Input path for `ask kg assemble`.
`--build-command <cmd>`	`pnpm build`	Override the build command for `ask kg verify`.
`--skip-build`	off	Verify against an existing `dist/` without rebuilding.
`--strict`	off	Treat graph coverage and literal-fidelity warnings as failures.

Global flags come before the command:

ask --kg-path .hev-ask/kg.json --json search "openapi"
ask --endpoint https://askhev.com/api/ask mcp
ask kg build --collection docs --collection guides --chunk-heading-depth 2
ask kg verify --skip-build

MCP

ask mcp runs a stdio MCP server over the same read/search surface: glossary_list, glossary_get, sections_list, section_get, overview, search, and answer.

Use local graph reads for checked-out repos:

{
  "mcpServers": {
    "docs": {
      "command": "ask",
      "args": ["--kg-path", ".hev-ask/kg.json", "mcp"]
    }
  }
}

Use a deployed endpoint when the agent needs the remote graph or answer:

{
  "mcpServers": {
    "askhev": {
      "command": "ask",
      "args": ["--endpoint", "https://askhev.com/api/ask", "mcp"]
    }
  }
}

See the MCP page for tool schemas and behavior.

Go library

The reusable Go API lives in pkg/ask. Use pure helpers when you want direct control, or mount the dependency-free command group in your own CLI.

group := ask.NewCommandGroup(ask.CommandOptions{
	KGPath: ".hev-ask/kg.json",
})
err := group.Run(ctx, []string{"search", "read endpoints"}, os.Stdin, os.Stdout, os.Stderr)

The lower-level helpers include LoadGraph, ListGlossary, GetSection, SearchGraph, NewEndpointClient, BuildKnowledgeGraph, VerifyAnchors, and ServeMCP.

Distribution

The npm package exposes two bins:

Bin	Purpose
`ask`	Main v3 CLI.
`hev-ask-kg`	Deprecated alias that forwards to `ask kg ...`.

The launcher resolves HEV_ASK_BINARY first, then a platform-specific optional binary package when installed, then the checked-out Go source in this monorepo. That source fallback is for development; published installs use the packaged binary path.

Where it runs

The producer commands run locally or in CI with filesystem access. The Astro integration also invokes ask kg build during astro build when ANTHROPIC_API_KEY is present, then falls back to the committed artifact if the build command cannot run. The deployed site reads the committed graph through virtual:hev-ask/kg; it does not need filesystem access for graph reads.