Documentation chat reads a site you have already built. It is optional: a normal shoalrun build does not call the retrieval or chat providers.
Chat first finds relevant passages, then uses them to produce a cited answer. A passage is a short part of a built Markdown page with a link back to its source. Some configurations can return an existing answer or an excerpt instead of generating new text.
For commands, start with local chat setup. Search and chat compares chat with the page-search box.
How the layers fit
Each layer adds a retrieval or answer capability and has its own prerequisites.
| Layer | What it adds | It needs |
|---|---|---|
| Keyword matching | Finds the most relevant passages by their words. It is what the chat uses when there are no vectors, or the embedding service is unavailable. | The passage index. No key. |
| Semantic search | Finds passages by meaning, so a question matches even when it shares no words with the page. | An embedding service and key. |
| Relevance scorer | Reorders the results and declines a question the docs don't cover. It checks each sentence of an answer, and shows a passage word for word when one is clearly the answer. | A scorer service that speaks the Jev protocol. |
| Chat model | Writes a cited answer from the best passages. | A chat service and key. |
| Hosting | Runs the chat beside your site with spending caps and an off switch. | Vercel, and a key-value store. |
The site-search box returns links from its own page index. Chat retrieves passages to answer a question. An embedding service helps match different wording; a scorer rates whether the passages support an answer. The settings reference describes supported providers and the Jev scoring protocol.
Choose services and models in config. Keep their keys in the environment variables named by that config.
How a question is answered
The diagram shows a chat with optional reuse and scoring enabled. A question stops at an existing answer or direct excerpt when the configured checks accept one.
The minimal setup uses keyword retrieval, a chat model, and citation and code checks. Caching, answer cards, scoring, and claim verification need extra configuration. Without a scorer, there is no score-based coverage gate.
For an explicit request with up to three action clauses, retrieval can find evidence for each part and include page introductions. This helps keep one topic from filling the passage budget. Answer checks explains that behavior and its limits.
Put the model into practice
Add optional layers after testing the minimal setup with questions your readers actually ask. Check source coverage and response quality before choosing scoring thresholds or enabling answer reuse.
Use set up local documentation chat for commands and verification. The retrieval and chat settings define provider fields and defaults. Passage index describes the files used by retrieval.