Limits

These are the boundaries you should know before adopting hev ask. None of them are bugs — they’re the edges of what the current design covers.

The corpus is your content collection

hev ask searches the Astro content collection(s) you configure, and nothing else. There is no crawler, no external sitemap ingestion, and no way to index pages that aren’t collection entries (hand-written .astro pages, for example).

If a doc isn’t in a configured collection, it won’t appear in search. Put what you want searchable in a collection.

Recall has a keyword ceiling

Retrieval is keyword token-overlap widened by the glossary — not embeddings. The agentic loop grounds its answer in what retrieval surfaces; it cannot ground in — or link to — what retrieval missed.

In practice the glossary recovers most synonym cases (k8s → kubernetes, abbreviations, product aliases). But if a reader searches in language that shares no tokens with your docs and isn’t covered by the glossary, the right section may never enter the candidate pool.

The one-shot digest build is bounded; sharded builds are not

ask digest build sends your full cleaned corpus to the model in one call. For a typical docs site (dozens of pages) this fits comfortably; past ~600KB of section text it fails loudly instead of degrading.

Beyond that, use the sharded build: the corpus splits into prefix-stable shards, each distilled in its own fresh context, then merged deterministically. Corpus size stops being a context-window problem — a Cloudflare-docs-scale corpus (~30MB, ~25k sections) shards into ~170 pieces and re-distils only the shard a content edit touches. The runtime prompt is the remaining scale consideration: the agentic path inlines node summaries, so digests with tens of thousands of nodes are not yet a fit for the answer loop.

Frontmatter parsing is a flat-YAML subset

The offline build parses frontmatter with a small flat-YAML splitter, not a full YAML parser. It handles the common docs schema (string and number fields). Nested frontmatter structures aren’t supported by the build-time parser.

This only affects the offline digest build reading files from disk; the runtime index uses Astro’s own getCollection, which honors your real schema.

Agentic search adds latency

The agentic path is bounded by maxIterations (default 4) Claude round-trips — worst case a few seconds. It is not instant, by nature. The keyword path is the instant lane and always available; agentic search is the considered one. Tune maxIterations down if you need a tighter ceiling.

Anchors depend on Astro’s slugger

Deep links are only correct as long as the heading slugs hev ask generates match Astro’s rendered id attributes. hev ask uses the same github-slugger to stay aligned, and ships an ask digest verify command that fails if any chunk anchor is missing from the built HTML.

Wire verify into CI. If Astro ever changes its slugging, the verifier is what catches it before a broken link ships.

A server route is required

The /api/ask endpoint renders on demand, so a fully static build cannot serve search. You need a server or hybrid adapter (Node, Cloudflare, Vercel, etc.). Static-only sites should use a static search tool instead — see Tradeoffs.

Secrets live server-side

The agentic path needs ANTHROPIC_API_KEY in the server environment that runs /api/ask. The key is never exposed to the browser. If the key isn’t present at runtime, the endpoint serves keyword results — search degrades, it doesn’t break.