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

package/agent-docs/chat/passage-index.sections/build-the-index.md

@@ -0,0 +1,72 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## Build the index
+
+Build the site, then run `shoalrun index` on the output directory:
+
+```sh
+shoalrun build docs.config.yaml site-dist
+shoalrun index site-dist
+```
+
+The command prints a summary as JSON:
+
+```json
+{
+  "status": "ok",
+  "documents": 77,
+  "chunks": 725,
+  "output": "/path/to/site-dist/ai/chunks.json"
+}
+```
+
+The command reads three files from the build output:
+
+| File                   | Use                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------- |
+| `documents.json`       | The list of published pages, with each page's ID, URL, publication, and digest. |
+| Each page's `.md` twin | The text to split.                                                              |
+| `search-index.json`    | The heading IDs that passage links use. Optional.                               |
+
+It writes `ai/chunks.json`. Without `--embed`, it makes no network requests. Run it after each build. It replaces the previous file.
+
+Indexing also prepares readable paragraphs, code lines, and table rows for passage-search results. Search requests use that prepared data instead of parsing Markdown on first use. If serving search rejects an older index, rerun `shoalrun index site-dist`. Existing embeddings remain usable when the passage text and embedding settings are unchanged.
+
+Because it reads built output, the index holds only published pages in each publication. Drafts and pages outside enabled publications never appear.

package/agent-docs/chat/passage-index.sections/embed-passages.md

@@ -0,0 +1,103 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## Embed passages
+
+Add `--embed` to turn each passage into a vector. Shoalrun has no default embedding provider, so choose one under [`retrieval.embeddings`](https://www.shoalrun.com/config.md) in your config:
+
+```yaml title="docs.config.yaml"
+retrieval:
+  embeddings:
+    provider: voyage
+    model: voyage-4-large
+    dimension: 1024
+```
+
+Set the provider's key in the environment, `VOYAGE_API_KEY` for Voyage, then run:
+
+```sh
+shoalrun index site-dist --embed --config docs.config.yaml
+```
+
+The summary gains an `embeddings` object:
+
+```json
+{
+  "embeddings": {
+    "passages": 725,
+    "embedded": 725,
+    "reused": 0,
+    "model": "voyage-4-large",
+    "dimension": 1024,
+    "bytes": 2969600
+  }
+}
+```
+
+The command sends each passage's [embedding input](https://www.shoalrun.com/chat/passage-index.md#embedding-input) to the configured provider. The key is not written to the output.
+
+It writes two files next to `chunks.json`:
+
+| File                 | Content                                                                                                                              |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `ai/embeddings.json` | The provider, model, embedding space, dimension, the `sourceDigest` of the build, and each passage's `id` and `digest` in row order. |
+| `ai/embeddings.bin`  | One row of 32-bit floats per passage, in the same order. Each row has unit length, so a dot product is the cosine similarity.        |
+
+The vector-file size grows with passage count and dimension. The files don't record the provider's URL or key variable, so an internal server's address never reaches your published site.
+
+A rerun embeds only passages whose digest changed. Changing the model or the dimension re-embeds every passage. A vector is never used for a passage whose text changed after it was embedded, because the digests no longer match.
+
+### Choose a provider
+
+Two providers are built in, and you can switch by editing the config and rerunning the command.
+
+| Provider | Use it for                                                                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `voyage` | Voyage AI's embedding models.                                                                                                                     |
+| `openai` | OpenAI's embedding models, and servers that copy OpenAI's embeddings API, such as Ollama, vLLM, and a LiteLLM proxy. Set `baseUrl` to reach them. |
+
+Vectors from different models can't be compared, so switching provider or model means embedding every passage again. Queries must use a model from the same embedding space as the passages.
+
+OpenAI's API has no separate query and document mode, so models that need one lose it behind an OpenAI-style server. Shoalrun sends the `dimensions` request only for OpenAI's `text-embedding-3` models. If a proxy renames a model, set `dimension` to the size the backend returns.
+
+### Embed queries with a different model
+
+Queries use the model that embedded the passages unless you set `queryModel`. A different query model must share the stored vectors’ embedding space and dimension.
+
+Voyage 4 models share a space. For example, you can embed passages with `voyage-4-large` and queries with `voyage-4-lite` without re-embedding the passages. Check provider availability before choosing a query model.

package/agent-docs/chat/passage-index.sections/how-the-default-chunker-splits-a-page.md

@@ -0,0 +1,53 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## How the default chunker splits a page
+
+The default chunker follows structure. It doesn't cut text into fixed-length windows.
+
+1. **Split at `##` and `###` headings.** Text before the first `##` heading forms an intro passage. Headings at `####` and below stay inside their section's text.
+2. **Keep blocks whole.** A paragraph, list, table, or code block is never cut mid-block, except for large tables in step 4.
+3. **Fill passages up to 2,000 characters.** A section longer than that splits between blocks into a first passage and later parts.
+4. **Split large tables between rows.** Each part repeats the table's header rows, so every row keeps its column names.
+5. **Keep large code blocks whole.** A code block over the limit becomes one passage that exceeds it. Fenced code never starts a heading, so `#` comments inside a fence don't split a section.
+6. **Merge short sections into their first subsection.** A section under 200 characters with a subsection below it joins that subsection's first passage. A short section with no subsection stays a passage of its own.
+
+These limits are fixed. You can't configure the chunker or replace it yet.
+
+The number of passages changes as the documentation grows. Most passages are a few hundred characters long, and nearly all stay under 2,000.

package/agent-docs/chat/passage-index.sections/limits.md

@@ -0,0 +1,45 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## Limits
+
+- Reader marks are copied from the page, so a section inside a page can't have its own audience. Run `shoalrun index` again after you change a page's marks. They aren't part of the embedding input, so changing them never re-embeds a passage.
+- Passages don't overlap. The heading path supplies the context that overlap would.
+- A few passages are very short, such as an empty related-reading block or a one-line API note.
+- The chunker reads Markdown twins only. It doesn't read the OpenAPI source directly, so API detail appears only as far as the reference pages show it.

package/agent-docs/chat/passage-index.sections/passage-ids-and-links.md

@@ -0,0 +1,52 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## Passage IDs and links
+
+A passage ID is the page ID, `#`, and a slug of the heading path. A passage without headings uses `intro`. The chunker adds a suffix when IDs would collide:
+
+| ID                                                  | Meaning                                                    |
+| --------------------------------------------------- | ---------------------------------------------------------- |
+| `guide.configuration#understand-the-three-stages`   | The first passage in that section.                         |
+| `guide.configuration#understand-the-three-stages~2` | The second part of a section that split.                   |
+| `guide.configuration#notes-2`                       | The second section on the page with the same heading path. |
+
+IDs stay the same when body text changes. They change when you rename a heading or the page ID.
+
+Section links come from the heading IDs in `search-index.json`. A passage links to the page, without a `#` anchor, when the build has no search index or when a component generated the heading. Walkthrough steps and tab labels are examples. The [site search](https://www.shoalrun.com/author/search.md) page describes the index.

package/agent-docs/chat/passage-index.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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.
+
+## Related reading
+
+No matching documents.

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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > 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, chat, and agent access > 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.)