@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/agent-docs/chat/passage-index.sections/what-a-passage-contains.md

@@ -0,0 +1,91 @@
+---
+id: guide.passage-index
+title: Passage index
+summary: Passage file formats, chunking rules, identifiers, embedding behavior,
+  and limits.
+type: reference
+area: discovery
+subarea: discovery-search
+subjectLifecycle: experimental
+canonical: /chat/passage-index
+---
+
+# Passage index
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Reference > Passage index
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+Parent page: [Full Markdown page](/chat/passage-index.md)
+
+A passage index splits built Markdown pages into smaller pieces for retrieval. Each passage keeps its page title, heading path, and source link. [Chat](https://www.shoalrun.com/chat.md) and custom passage-search providers use it to find relevant parts of a page.
+
+The built-in [search box](https://www.shoalrun.com/author/search.md) uses the separate page-level `search-index.json`. You do not need a passage index for normal static-site search.
+
+Create the files after building the site:
+
+| Command                  | Adds                                               | Provider requests                                 |
+| ------------------------ | -------------------------------------------------- | ------------------------------------------------- |
+| `shoalrun index`         | `ai/chunks.json`, the passage text and metadata.   | None.                                             |
+| `shoalrun index --embed` | Passage index plus embedding metadata and vectors. | Sends embedding input to the configured provider. |
+
+Indexing leaves published page content unchanged. The files sit beside the build output, and you must rebuild the index when that output changes.
+
+## What a passage contains
+
+Each entry in `chunks` describes one passage:
+
+```json title="ai/chunks.json"
+{
+  "id": "guide.configuration#understand-the-three-stages",
+  "docId": "guide.configuration",
+  "title": "Organize project configuration",
+  "type": "how-to",
+  "variant": "production|current|en",
+  "headingPath": ["Understand the three stages"],
+  "url": "/configuration#understand-the-three-stages",
+  "markdownUrl": "/configuration.md",
+  "text": "Configuration takes effect in three stages:\n\n1. **Resolve co…",
+  "digest": "be259c2f4c0c896d1fe25ed496ac642f97391744675e06ee844f09372e47767a",
+  "search": {
+    "schemaVersion": 1,
+    "paragraphs": ["Configuration takes effect in three stages: …"],
+    "literalLines": []
+  }
+}
+```
+
+| Field                    | Value                                                                                                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                     | The passage ID. See [Passage IDs](https://www.shoalrun.com/chat/passage-index.md#passage-ids-and-links).                                                                |
+| `docId`, `title`, `type` | The page's ID, title, and type.                                                                                                                                         |
+| `variant`                | The page's channel, version, and language, joined by `\|`. Passages from different publications never mix.                                                              |
+| `headingPath`            | The `##` and `###` headings above the passage, outermost first. Empty for an intro passage.                                                                             |
+| `url`                    | The page URL, plus `#` and the section's heading ID when one exists.                                                                                                    |
+| `markdownUrl`            | The page's Markdown twin.                                                                                                                                               |
+| `readerFilters`          | Optional. The page's reader marks, such as `{ "audience": ["maintainers"] }`. It is present only when the page has marks. Retrieval uses it to answer for one audience. |
+| `text`                   | The passage's Markdown, without its own heading.                                                                                                                        |
+| `digest`                 | A SHA-256 hash of the passage's embedding input.                                                                                                                        |
+| `search`                 | Prepared result content: `schemaVersion: 1`, explanatory `paragraphs`, and code/table `literalLines`. Generated navigation lists are excluded from the paragraphs.      |
+
+The file also records `schemaVersion` and a `sourceDigest` that changes when any page's digest changes.
+
+### Embedding input
+
+The heading path isn't part of `text`. Anything that scores or embeds a passage reads the page title, the heading path, and the text together:
+
+```text
+Organize project configuration > Understand the three stages
+
+Configuration takes effect in three stages: …
+```
+
+`digest` hashes that string, so it changes when the title, the heading path, or the text changes. A stored vector or score that no longer matches a passage's digest is stale.
+
+The derived `search` data is not part of the embedding input or its digest. Preparing it does not require new embeddings for unchanged passages.

package/agent-docs/chat/prepared-answers.md

@@ -0,0 +1,116 @@
+---
+id: guide.prepared-answers
+title: Generate and refresh answer cards
+summary: Generate and review common answers ahead of time, then serve confirmed
+  cards without a new chat-model answer.
+type: how-to
+area: discovery
+subarea: discovery-chat
+subjectLifecycle: experimental
+canonical: /chat/prepared-answers
+---
+
+# Generate and refresh answer cards
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Documentation chat > Answer cards
+
+**Updated: 2026-10-26.**
+
+**Status: Experimental.**
+
+An answer card stores a reviewed answer to a recurring question. Generate cards after local chat works, then review their text before serving them. Start in your documentation project root with the CLI available.
+
+A confirmed card avoids generating a new answer. Matching still calls the embedding provider and relevance scorer.
+
+> **Note:** An answer card is not a page card. Page cards preview another page; see [Cards and collections](https://www.shoalrun.com/author/components/cards.md). Answer cards are stored answers.
+
+## What you need
+
+- A site indexed with `--embed`. See [Passage index](https://www.shoalrun.com/chat/passage-index.md).
+- A `chat` section with `rerank: jev` and a `cards` setting. See [Retrieval and chat settings](https://www.shoalrun.com/chat/settings.md).
+- A configured chat service and the provider keys used by `shoalrun ask`. Card generation can make new provider requests each time it runs.
+
+## List the questions
+
+Write the questions in a YAML or JSON file. Each is a string, or a mapping with `question` and `aliases`. Aliases are other ways to ask the same thing.
+
+```yaml title="config/answers.yaml"
+- question: how do I reset my password
+  aliases: [forgot my password, change my password]
+- question: how do I export my data
+```
+
+The file can live anywhere. You pass its path to the next command.
+
+## Build the cards
+
+Card generation uses providers and can produce different wording on each run:
+
+- `index --embed` sends new or changed passages to the embedding provider.
+- `answers` calls the embedding provider and scorer, then the chat model for questions that pass the coverage gate.
+- Fallback and escalation settings can add chat-model calls.
+
+Run the commands, then review the generated file before publishing:
+
+```sh
+shoalrun index site-dist --embed
+shoalrun answers site-dist --questions config/answers.yaml
+```
+
+Each question goes through the normal retrieval and answer checks. The command turns off card reuse and direct excerpts while generating cards, so an accepted card contains a freshly written answer. It also embeds each kept question and its aliases for later similarity matching. A question the docs do not cover may be declined before a chat-model call. The command writes `ai/answers.json` and reports kept and skipped questions. It skips a question when:
+
+- The docs don't cover it.
+- The answer was hedged.
+- The answer cites nothing.
+- A check flagged a sentence, some code, or a citation.
+
+A skipped question is a signal. Either the docs need a page for it, or the question is too broad for one answer.
+
+`ai/answers.json` is plain JSON. Each card holds its question, aliases, answer, sources, and the digest of every passage behind it. Read the answers before you ship them. The command writes the whole file each time, so to drop a card, remove its question from your list and run the command again.
+
+## How a card is used
+
+With `chat.cards` set, a question that opens a conversation is checked against cards in two steps:
+
+1. The query embedding provider embeds the new question. Its vector is compared with each card's question vectors. A card at least `threshold` similar is shortlisted. The default is 0.75.
+2. The relevance scorer checks whether the card's stored answer really answers this question. The card is used only at `confirm` or higher. The default is 0.9. A confirmed card needs no new chat-model answer.
+
+Similarity alone can confuse related questions, such as turning notifications on versus turning them off. Scorer confirmation is a separate check against the stored answer. If no card is confirmed, the question follows the normal answer pipeline.
+
+A follow-up never uses a card. A card also belongs to one publication and reader view, and a question asked in another view never uses it. `--no-cards` on `shoalrun ask` turns cards off for one run.
+
+## Keep cards current
+
+A card records the digest of each source passage. When a passage changes, the card stops being used without a warning. Run `shoalrun answers` after documentation changes to refresh the cards.
+
+If `ai/answers.json` is missing, or was made with a different embedding model, `ask` says so and carries on without cards.
+
+## Find questions worth a card
+
+The question log shows what readers ask. Questions that were asked at least twice, that the model answered cleanly, and that no card covers make good candidates.
+
+```sh
+shoalrun ask-log ask.jsonl --cards-out candidates.yaml
+```
+
+`--cards-out` writes a new file and never replaces one. Review the list and move the questions you want into your questions file. Change the repeat count with `--min-repeats`. See [Keep a record of questions](https://www.shoalrun.com/chat/host.md) for how to record the log.
+
+## Where cards work
+
+Cards work in the terminal, the local panel, and the Vercel chat function.
+
+For Vercel, build with `--chat`, then run `shoalrun answers` against the function's private `site` directory before deployment. The function reads `site/ai/answers.json` from that directory. A plain `shoalrun vercel build --chat` embeds passages but does not generate cards.
+
+This repository's `npm run docs:build-all` performs both steps. See [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) for the deployment workflow.
+
+## Related reading
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up the answers and ask-log commands and the --no-cards option.
+
+- [Retrieval and chat settings](https://www.shoalrun.com/chat/settings.md) — Look up the chat.cards settings. (Status: experimental.)

package/agent-docs/chat/settings.md

@@ -0,0 +1,213 @@
+---
+id: reference.chat-config
+title: Retrieval and chat settings
+summary: Look up embedding, chat-model, scoring, and answer-reuse configuration.
+type: reference
+area: discovery
+subarea: discovery-chat
+subjectLifecycle: experimental
+canonical: /chat/settings
+---
+
+# Retrieval and chat settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Reference > Retrieval and chat settings
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+Use this reference to look up fields after choosing a setup. For a working sequence, start with [local chat setup](https://www.shoalrun.com/chat/setup.md).
+
+`retrieval` configures embeddings; `chat` configures answer generation and optional checks. Both sections are optional. A normal site build validates them without calling these providers.
+
+## Configure retrieval
+
+`retrieval.embeddings` supplies embeddings for passage indexing, semantic queries, and hosted chat builds. Choose a provider and model when you need meaning-based retrieval.
+
+```yaml title="docs.config.yaml"
+retrieval:
+  embeddings:
+    provider: voyage
+    model: voyage-4-large
+    dimension: 1024
+    queryModel: voyage-4-lite
+```
+
+To use OpenAI's embeddings, or a server that copies its API, such as Ollama, vLLM, or a LiteLLM proxy, name the `openai` provider:
+
+```yaml title="docs.config.yaml"
+retrieval:
+  embeddings:
+    provider: openai
+    model: text-embedding-3-small
+    keyEnv: OPENAI_API_KEY
+```
+
+| Key          | Meaning                                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`   | Required. `voyage` or `openai`.                                                                                                           |
+| `model`      | Required. The embedding model ID.                                                                                                         |
+| `dimension`  | The vector size. Voyage accepts 256, 512, 1024, or 2048. Other models need it unless Shoalrun knows the model's size.                     |
+| `queryModel` | The model that embeds queries. It must share an embedding space with `model`, as the Voyage 4 models do. Without it, queries use `model`. |
+| `baseUrl`    | `openai` only. An OpenAI-style server, such as `http://localhost:11434/v1` for Ollama.                                                    |
+| `keyEnv`     | The name of the environment variable that holds the key. It defaults to `VOYAGE_API_KEY` or `OPENAI_API_KEY`.                             |
+
+The config never holds a key. A key setting fails validation, and `keyEnv` fails if its value isn't a variable name. Command-line flags on `shoalrun index` override these settings. See [Passage index](https://www.shoalrun.com/chat/passage-index.md) for the files that `--embed` writes.
+
+## Configure chat
+
+`chat` configures the OpenAI-compatible service that writes answers. Choose a provider and model; there is no default model. Start with these fields, then add optional checks or reuse settings as needed.
+
+```yaml title="docs.config.yaml"
+chat:
+  provider: openai
+  model: deepseek/deepseek-v4-flash
+  baseUrl: https://openrouter.ai/api/v1
+  keyEnv: OPENROUTER_API_KEY
+```
+
+These fields configure the service and answer limits:
+
+| Key           | Meaning                                                                                                                                 |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`    | Required. `openai`, which covers any OpenAI-style service.                                                                              |
+| `model`       | Required. The model ID that your service uses.                                                                                          |
+| `baseUrl`     | The service's API address. It defaults to `https://api.openai.com/v1`.                                                                  |
+| `keyEnv`      | The name of the environment variable that holds the key. It defaults to `OPENAI_API_KEY`. Services on `localhost` need no key.          |
+| `body`        | Extra fields to send with every request, such as OpenRouter's `reasoning`. See [Send extra request fields](#send-extra-request-fields). |
+| `passages`    | How many passages the model sees, from 1 to 20.                                                                                         |
+| `maxTokens`   | The longest answer the model may write. Reasoning models need a larger value.                                                           |
+| `temperature` | A number from 0 to 2. Without it, the service's default applies.                                                                        |
+
+### Optional layers
+
+Add these fields to `chat` when the corresponding capability is needed. Scorer-dependent fields require `rerank: jev` or an equivalent scorer mapping.
+
+| Key          | Meaning                                                                                                                                                                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readerView` | Whose questions the chat answers, as reader filter choices. See [Answer for one audience](https://www.shoalrun.com/chat/checks.md).                                                                                                                                  |
+| `rerank`     | `jev` reorders the top 24 results with a relevance scorer. It needs `JEV_API_KEY`. To use a different service, give a mapping instead. See [Choose the scorer](#choose-the-scorer).                                                                                  |
+| `gate`       | Needs `rerank: jev`. `decline` and `hedge` are Jev scores from 0 to 1, and `decline` must be lower.                                                                                                                                                                  |
+| `verify`     | Needs `rerank: jev`. `threshold` is a Jev score above 0 and below 1. `onUnsupported` is `flag` (the default) or `remove`. See [How an answer is checked](https://www.shoalrun.com/chat/checks.md).                                                                   |
+| `direct`     | Needs `rerank: jev`. Shows a passage word for word instead of calling the model. See [Answer without a model](https://www.shoalrun.com/chat/checks.md).                                                                                                              |
+| `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](#use-more-than-one-model).                                                                                                                               |
+| `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](#use-more-than-one-model).                                                                                                                         |
+| `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
+| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
+| `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
+| `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |
+
+The gate uses the best passage score:
+
+- Below `decline`: return a not-covered response without a chat-model call.
+- Between `decline` and `hedge`: generate an answer with a partial-coverage warning.
+- At or above `hedge`: generate an answer normally.
+
+The config never holds a key. A key setting fails validation, and `keyEnv` fails if its value isn't a variable name. The `--model` flag on `shoalrun ask` overrides `model`, so you can try another model without editing the config.
+
+## Send extra request fields
+
+Some services accept request fields that Shoalrun doesn't know about. `chat.body` adds them to every request. On OpenRouter, the useful ones are `reasoning`, which controls whether a model thinks before it answers, and `provider`, which picks who serves the model.
+
+```yaml title="docs.config.yaml"
+chat:
+  model: deepseek/deepseek-v4-flash
+  body: { reasoning: { enabled: false } }
+```
+
+The fields can add to a request but can't replace what Shoalrun sets, which is `model`, `messages`, `max_tokens`, `temperature`, and `stream`. Use `chat.model`, `chat.maxTokens`, and `chat.temperature` for those. A field whose name looks like a secret, such as a key, token, or password, fails validation, because the config never holds a key. Each fallback and escalation model inherits `body` and can replace it with its own. An empty `body: {}` clears it. Another service may reject a field it doesn't know, so check what yours accepts.
+
+Service-specific fields can affect latency, cost, and quality. Test them with your own questions and model; support and effects vary by service. Shoalrun does not interpret those extra fields.
+
+## Choose the scorer
+
+The scorer behind `rerank`, `gate`, `verify`, `direct`, and `cards` is a service that answers yes-or-no questions about a passage. `provider: jev` names the protocol it speaks, `POST /v1/systemone`, and not one vendor. Any service or local server that speaks it works. With no other settings, Shoalrun reads the address, model, and key from `JEV_API_KEY`, `TYPESAFE_API_KEY`, `TYPESAFE_ENDPOINT`, and `JEV_MODEL`. To choose them in config, use a mapping.
+
+```yaml title="docs.config.yaml"
+chat:
+  rerank:
+    provider: jev
+    endpoint: https://scorer.example.com
+    model: your-model-name
+    keyEnv: SCORER_API_KEY
+```
+
+| Setting       | What it does                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`    | Must be `jev`.                                                                                                                                                             |
+| `endpoint`    | The service address. It must use `https`, except for `localhost`, and can't hold credentials or a query. Shoalrun adds `/v1/systemone` when the address doesn't end there. |
+| `model`       | The model name the service expects.                                                                                                                                        |
+| `onError`     | What to do when the scorer fails: `search` (the default) or `answer`. See [When the scorer is down](#when-the-scorer-is-down).                                             |
+| `keyEnv`      | The name of the environment variable that holds the key. The config never holds the key.                                                                                   |
+| `stateFormat` | `object` (the default) or `string`. Some scorers accept the text to judge only as a string. Use `string` for those.                                                        |
+
+OpenRouter serves Jev at the same protocol and price, so the chat model and the scorer can share one key:
+
+```yaml title="docs.config.yaml"
+chat:
+  rerank:
+    provider: jev
+    endpoint: https://openrouter.ai/api/v1
+    model: typesafe/jev-1.13
+    keyEnv: OPENROUTER_API_KEY
+```
+
+Scores from different services aren't comparable. The gate, `verify`, `direct`, and `cards` thresholds are numbers on one scorer's scale. After a change, run `shoalrun answers` and the answer eval again, and expect to adjust them. Cached scores are kept per address and model, so a change never reuses an old service's scores.
+
+## When the scorer is down
+
+The scorer is what keeps a question the docs don't cover from reaching the model. If it fails, by timing out, running out of budget, returning an error, or having no key, there are two ways to go.
+
+- **`search` (the default).** The chat doesn't call the model. It shows the closest pages from retrieval and says it can't check answers right now. Nobody can use an outage to get free model output for any question, and readers still get somewhere to go.
+- **`answer`.** The model answers without the gate and the claim check, and the answer carries a note that the checks were skipped. Use this when a reader-facing outage costs more than the risk. On a public site, every question then reaches the model, and only the rate limits and token caps stand in the way.
+
+```yaml title="docs.config.yaml"
+chat:
+  rerank: { provider: jev, onError: answer }
+```
+
+Neither mode caches anything from an outage, so an unchecked answer can't outlive it. This applies only when a scorer is configured. With no `rerank`, the model answers every question, because you chose that.
+
+## Use more than one model
+
+Use `fallback` for provider failures and `escalate` for answers flagged by checks. Both are optional:
+
+```yaml title="docs.config.yaml"
+chat:
+  provider: openai
+  model: deepseek/deepseek-v4-flash
+  baseUrl: https://openrouter.ai/api/v1
+  keyEnv: OPENROUTER_API_KEY
+  fallback: [{ model: openai/gpt-6-luna }]
+  escalate: { model: z-ai/glm-5.3-flash, when: [unsupported-claim, uncited] }
+```
+
+Each extra model inherits the provider, address, key variable, and limits from the main settings. Name only what differs. A model on a different service can set its own `baseUrl` and `keyEnv`. The `--model` flag on `ask` replaces the main model and leaves the others alone.
+
+### Fallback
+
+If the main model errors, times out, or returns no text, `ask` tries the next model in the list. Use a model from a different lab, so one outage doesn't stop the chat. The result records which model answered and which failed, with the reason. If every model fails, the error lists all of them.
+
+### Escalation
+
+The main model answers first, and the checks run. If one of the `when` reasons applies, `ask` asks the escalation model the same question with the same passages and runs the same checks. It shows whichever answer has fewer flags, and the first one if they tie. The supported reasons are:
+
+| Reason              | Fires when                                                 |
+| ------------------- | ---------------------------------------------------------- |
+| `unsupported-code`  | The answer has code that isn't in the passages.            |
+| `uncited`           | The answer cites no passage.                               |
+| `unsupported-claim` | A sentence fails the claims check. It needs `chat.verify`. |
+
+Without `when`, the reasons are `unsupported-code` and `uncited`, plus `unsupported-claim` when `verify` is set. The code check is a heuristic that can misjudge a valid example. A second answer from a thinking model adds seconds. So many sites limit `when` to `unsupported-claim` and `uncited`. A declined answer or a direct excerpt is never escalated. If the escalation model fails, the first answer is shown with a note. `--no-escalate` on `ask` turns it off for one run.
+
+Choose an escalation model using reviewed questions that your primary model handles poorly. A larger model is not automatically a better fit.
+
+## Related reading
+
+No matching documents.

package/agent-docs/chat/settings.sections/choose-the-scorer.md

@@ -0,0 +1,63 @@
+---
+id: reference.chat-config
+title: Retrieval and chat settings
+summary: Look up embedding, chat-model, scoring, and answer-reuse configuration.
+type: reference
+area: discovery
+subarea: discovery-chat
+subjectLifecycle: experimental
+canonical: /chat/settings
+---
+
+# Retrieval and chat settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Reference > Retrieval and chat settings
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+Parent page: [Full Markdown page](/chat/settings.md)
+
+Use this reference to look up fields after choosing a setup. For a working sequence, start with [local chat setup](https://www.shoalrun.com/chat/setup.md).
+
+`retrieval` configures embeddings; `chat` configures answer generation and optional checks. Both sections are optional. A normal site build validates them without calling these providers.
+
+## Choose the scorer
+
+The scorer behind `rerank`, `gate`, `verify`, `direct`, and `cards` is a service that answers yes-or-no questions about a passage. `provider: jev` names the protocol it speaks, `POST /v1/systemone`, and not one vendor. Any service or local server that speaks it works. With no other settings, Shoalrun reads the address, model, and key from `JEV_API_KEY`, `TYPESAFE_API_KEY`, `TYPESAFE_ENDPOINT`, and `JEV_MODEL`. To choose them in config, use a mapping.
+
+```yaml title="docs.config.yaml"
+chat:
+  rerank:
+    provider: jev
+    endpoint: https://scorer.example.com
+    model: your-model-name
+    keyEnv: SCORER_API_KEY
+```
+
+| Setting       | What it does                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`    | Must be `jev`.                                                                                                                                                             |
+| `endpoint`    | The service address. It must use `https`, except for `localhost`, and can't hold credentials or a query. Shoalrun adds `/v1/systemone` when the address doesn't end there. |
+| `model`       | The model name the service expects.                                                                                                                                        |
+| `onError`     | What to do when the scorer fails: `search` (the default) or `answer`. See [When the scorer is down](https://www.shoalrun.com/chat/settings.md#when-the-scorer-is-down).    |
+| `keyEnv`      | The name of the environment variable that holds the key. The config never holds the key.                                                                                   |
+| `stateFormat` | `object` (the default) or `string`. Some scorers accept the text to judge only as a string. Use `string` for those.                                                        |
+
+OpenRouter serves Jev at the same protocol and price, so the chat model and the scorer can share one key:
+
+```yaml title="docs.config.yaml"
+chat:
+  rerank:
+    provider: jev
+    endpoint: https://openrouter.ai/api/v1
+    model: typesafe/jev-1.13
+    keyEnv: OPENROUTER_API_KEY
+```
+
+Scores from different services aren't comparable. The gate, `verify`, `direct`, and `cards` thresholds are numbers on one scorer's scale. After a change, run `shoalrun answers` and the answer eval again, and expect to adjust them. Cached scores are kept per address and model, so a change never reuses an old service's scores.

package/agent-docs/chat/settings.sections/configure-chat.md

@@ -0,0 +1,80 @@
+---
+id: reference.chat-config
+title: Retrieval and chat settings
+summary: Look up embedding, chat-model, scoring, and answer-reuse configuration.
+type: reference
+area: discovery
+subarea: discovery-chat
+subjectLifecycle: experimental
+canonical: /chat/settings
+---
+
+# Retrieval and chat settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Reference > Retrieval and chat settings
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+Parent page: [Full Markdown page](/chat/settings.md)
+
+Use this reference to look up fields after choosing a setup. For a working sequence, start with [local chat setup](https://www.shoalrun.com/chat/setup.md).
+
+`retrieval` configures embeddings; `chat` configures answer generation and optional checks. Both sections are optional. A normal site build validates them without calling these providers.
+
+## Configure chat
+
+`chat` configures the OpenAI-compatible service that writes answers. Choose a provider and model; there is no default model. Start with these fields, then add optional checks or reuse settings as needed.
+
+```yaml title="docs.config.yaml"
+chat:
+  provider: openai
+  model: deepseek/deepseek-v4-flash
+  baseUrl: https://openrouter.ai/api/v1
+  keyEnv: OPENROUTER_API_KEY
+```
+
+These fields configure the service and answer limits:
+
+| Key           | Meaning                                                                                                                                                                          |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`    | Required. `openai`, which covers any OpenAI-style service.                                                                                                                       |
+| `model`       | Required. The model ID that your service uses.                                                                                                                                   |
+| `baseUrl`     | The service's API address. It defaults to `https://api.openai.com/v1`.                                                                                                           |
+| `keyEnv`      | The name of the environment variable that holds the key. It defaults to `OPENAI_API_KEY`. Services on `localhost` need no key.                                                   |
+| `body`        | Extra fields to send with every request, such as OpenRouter's `reasoning`. See [Send extra request fields](https://www.shoalrun.com/chat/settings.md#send-extra-request-fields). |
+| `passages`    | How many passages the model sees, from 1 to 20.                                                                                                                                  |
+| `maxTokens`   | The longest answer the model may write. Reasoning models need a larger value.                                                                                                    |
+| `temperature` | A number from 0 to 2. Without it, the service's default applies.                                                                                                                 |
+
+### Optional layers
+
+Add these fields to `chat` when the corresponding capability is needed. Scorer-dependent fields require `rerank: jev` or an equivalent scorer mapping.
+
+| Key          | Meaning                                                                                                                                                                                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readerView` | Whose questions the chat answers, as reader filter choices. See [Answer for one audience](https://www.shoalrun.com/chat/checks.md).                                                                                                                                  |
+| `rerank`     | `jev` reorders the top 24 results with a relevance scorer. It needs `JEV_API_KEY`. To use a different service, give a mapping instead. See [Choose the scorer](https://www.shoalrun.com/chat/settings.md#choose-the-scorer).                                         |
+| `gate`       | Needs `rerank: jev`. `decline` and `hedge` are Jev scores from 0 to 1, and `decline` must be lower.                                                                                                                                                                  |
+| `verify`     | Needs `rerank: jev`. `threshold` is a Jev score above 0 and below 1. `onUnsupported` is `flag` (the default) or `remove`. See [How an answer is checked](https://www.shoalrun.com/chat/checks.md).                                                                   |
+| `direct`     | Needs `rerank: jev`. Shows a passage word for word instead of calling the model. See [Answer without a model](https://www.shoalrun.com/chat/checks.md).                                                                                                              |
+| `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                      |
+| `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                |
+| `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
+| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
+| `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
+| `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |
+
+The gate uses the best passage score:
+
+- Below `decline`: return a not-covered response without a chat-model call.
+- Between `decline` and `hedge`: generate an answer with a partial-coverage warning.
+- At or above `hedge`: generate an answer normally.
+
+The config never holds a key. A key setting fails validation, and `keyEnv` fails if its value isn't a variable name. The `--model` flag on `shoalrun ask` overrides `model`, so you can try another model without editing the config.

package/agent-docs/chat/settings.sections/configure-retrieval.md

@@ -0,0 +1,62 @@
+---
+id: reference.chat-config
+title: Retrieval and chat settings
+summary: Look up embedding, chat-model, scoring, and answer-reuse configuration.
+type: reference
+area: discovery
+subarea: discovery-chat
+subjectLifecycle: experimental
+canonical: /chat/settings
+---
+
+# Retrieval and chat settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search and chat > Reference > Retrieval and chat settings
+
+**Updated: 2026-10-25.**
+
+**Status: Experimental.**
+
+Parent page: [Full Markdown page](/chat/settings.md)
+
+Use this reference to look up fields after choosing a setup. For a working sequence, start with [local chat setup](https://www.shoalrun.com/chat/setup.md).
+
+`retrieval` configures embeddings; `chat` configures answer generation and optional checks. Both sections are optional. A normal site build validates them without calling these providers.
+
+## Configure retrieval
+
+`retrieval.embeddings` supplies embeddings for passage indexing, semantic queries, and hosted chat builds. Choose a provider and model when you need meaning-based retrieval.
+
+```yaml title="docs.config.yaml"
+retrieval:
+  embeddings:
+    provider: voyage
+    model: voyage-4-large
+    dimension: 1024
+    queryModel: voyage-4-lite
+```
+
+To use OpenAI's embeddings, or a server that copies its API, such as Ollama, vLLM, or a LiteLLM proxy, name the `openai` provider:
+
+```yaml title="docs.config.yaml"
+retrieval:
+  embeddings:
+    provider: openai
+    model: text-embedding-3-small
+    keyEnv: OPENAI_API_KEY
+```
+
+| Key          | Meaning                                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `provider`   | Required. `voyage` or `openai`.                                                                                                           |
+| `model`      | Required. The embedding model ID.                                                                                                         |
+| `dimension`  | The vector size. Voyage accepts 256, 512, 1024, or 2048. Other models need it unless Shoalrun knows the model's size.                     |
+| `queryModel` | The model that embeds queries. It must share an embedding space with `model`, as the Voyage 4 models do. Without it, queries use `model`. |
+| `baseUrl`    | `openai` only. An OpenAI-style server, such as `http://localhost:11434/v1` for Ollama.                                                    |
+| `keyEnv`     | The name of the environment variable that holds the key. It defaults to `VOYAGE_API_KEY` or `OPENAI_API_KEY`.                             |
+
+The config never holds a key. A key setting fails validation, and `keyEnv` fails if its value isn't a variable name. Command-line flags on `shoalrun index` override these settings. See [Passage index](https://www.shoalrun.com/chat/passage-index.md) for the files that `--embed` writes.