Start with site search if readers need links to pages and sections. It is built in, works on a static host, and needs no provider account. Add chat when readers need answers written from your documentation.
Choose the result you want
These features have different setup and hosting needs. Passage retrieval and chat are experimental.
| Reader needs | Feature | Requirements |
|---|---|---|
| Page and section links | Site search | A normal site build and a browser with JavaScript. |
| Links that can match different wording | Semantic search preview | A passage index, embeddings, and a local search endpoint. The provider can fall back to keyword search. |
| An answer with source citations | Documentation chat | A passage index, a configured chat service, and a terminal or server. Embeddings and a scorer are optional additions. |
The sidebar's navigation filter only narrows the menu. Its search words do not change site-search results. The search dropdown returns links; it does not call a chat model.
Start with a local chat
Follow Set up local documentation chat to configure a service, index your pages, and inspect an answer with sources.
Once that works, choose the next capability you need:
- Answer checks explain coverage, citations, code checks, and answer reuse.
- Answer cards prepare reviewed answers to recurring questions.
- Hosting adds a Vercel function, shared limits, and an off switch.
- Settings define the provider fields and optional layers.
Which index does each feature use?
Shoalrun keeps page search and passage retrieval separate.
| File | Created by | Used for |
|---|---|---|
search-index.json |
The normal site build when search indexing is enabled. | Browser page search and local documentation search. Contains titles, summaries, headings, and text excerpts. |
ai/chunks.json |
shoalrun index after the build. |
Passage retrieval for semantic search and chat. Contains text from built Markdown pages, with source links. |
ai/embeddings.json and .bin |
shoalrun index --embed |
Comparing the meaning of queries and passages. Requires an embedding provider. |
An embedding represents text as numbers. Keyword, or lexical, retrieval compares words. Semantic retrieval compares embeddings; hybrid retrieval combines word-based and meaning-based rankings. Neither requires a chat model just to return search links.
The passage reference describes these files in detail. The glossary defines the related terms.
When an optional service is unavailable
Fallback behavior depends on the configured feature.
| Situation | Result |
|---|---|
| Built-in search has no server or provider key | Browser keyword search still works. |
| This site's custom search provider cannot reach its endpoint | It uses the browser keyword index. |
| A search endpoint has no current vectors, or embeddings fail | It returns keyword passage results. |
| Chat has no current vectors | Retrieval uses keywords. A configured chat model can still write an answer. |
| A deployment has no chat function | The site remains available, but has no chat endpoint. |
A Vercel build with --chat includes search and answer endpoints. Semantic queries have shared rate and daily limits. When the embedding budget is exhausted, search returns keyword results. A static deployment can use browser search without those endpoints.