Tradeoffs

Every search tool makes choices. This page is the honest version: what hev ask trades away to get what it gives, so you can decide whether the trade fits your docs.

Two paths instead of one

hev ask runs an instant keyword path and an agentic path, and asks the reader to choose between them by pressing Enter. The upside is that the common case (a word or two) stays instant and keyless, while hard questions get a smarter ranker. The cost is a slightly more complex interaction model than a single search box — readers have to learn that Enter means “ask AI”.

We think that’s the right trade for docs, where queries split cleanly into “jump to the thing I know exists” and “help me find the thing I can’t name.”

A committed digest

The digest is generated offline and committed to git as a markdown tree, one file per section, rather than computed at runtime or hidden in a service.

• Upside: it’s reviewable in pull requests one section at a time, deterministic at runtime, free to read (no model call on the request path), bundled into the edge worker with no runtime filesystem access, and, being a real directory, something an agent can tree/cat/grep directly.
• Cost: it can go stale. It only regenerates when content changes and a build runs. hev ask logs a warning when the live content hash differs from the digest’s, but a forgotten rebuild means a slightly outdated glossary.

The per-section hash gate makes regeneration cheap, idempotent, and incremental, so “rebuild on every content change in CI” is the intended workflow.

A flagship adapter, primitives for the rest

hev ask is host-neutral at the core but opinionated about Astro: the Astro integration is batteries-included (build, endpoint, and overlay from one config block) while every other framework wires two primitives itself: drop in the static overlay, and, for agentic answers, deploy the standalone endpoint.

• Upside: the digest, the overlay, the CLI, and MCP are the same everywhere; adopting a new framework is an adapter, not a fork. The keyword path is fully static and needs nothing hosted.
• Cost: off Astro, you do the wiring the integration would have done — add a <script> tag, and stand up the /api/ask endpoint yourself if you want the agentic path. A turnkey plugin for each framework is a goal, not a guarantee.

If you’re on Astro this is invisible — it’s one integration. If you’re not, the drop-in overlay reference is the honest map of what you wire by hand today.

Keyword retrieval, not embeddings

Retrieval is dependency-free token overlap widened by the glossary — no embeddings, no vector store.

• Upside: nothing to host, nothing to keep in sync, edge-safe, and instant. The glossary recovers a lot of the synonym recall embeddings would give.
• Cost: paraphrase recall has a ceiling. The agent answers well but can only ground in what keyword retrieval found. If your readers routinely search in words that share no tokens with your docs and aren’t in the glossary, embeddings would do better. That upgrade is deferred, not designed out.

One dependency, deliberately

hev ask aims to be close to zero-dependency, with one exception: github-slugger (~3 KB, pure JS, edge-safe).

Cost and latency of agentic search

The agentic path calls Claude. That means real, if small, money and latency:

• Latency: worst case is roughly maxIterations Haiku round-trips (a few seconds). The keyword path stays instant as the fast lane, and maxIterations is the knob if you want to bound it tighter.
• Cost: one bounded loop per submitted query, on the default Haiku model, with the domain context prompt-cached across rounds. The offline digest build uses Opus, but the hash gate means you pay for it only when content changes.

If you can’t or don’t want an API key in the loop at all, run keyword-only — it’s a first-class mode, not a fallback afterthought.

How it compares

Tool	Retrieval	AI ranking	Deep links	Hosting
hev ask	keyword + glossary	yes, on Enter	heading anchors	your adapter + optional API key
Pagefind	keyword (static index)	no	page / anchor	static, none
Algolia DocSearch	keyword (hosted)	no (classic)	page / anchor	hosted service + crawler
Orama	keyword + vector	no (search only)	configurable	client or hosted index

The short version:

• Choose Pagefind if you want excellent keyword search over a static site with zero services and no key. It’s simpler, and that simplicity is a feature.
• Choose Algolia if you want a managed, battle-tested keyword service and are happy running a crawler and a dashboard.
• Choose Orama if you specifically want client-side vector search and will manage embeddings.
• Choose hev ask if your docs are a folder of markdown (on Astro, Docusaurus, VitePress, MkDocs, or anything), you want deep links to sections, and you want a reader’s question, not just their keywords, to find the right section.

For the hard boundaries, continue to Limits.