@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

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

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Passage index
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -26,7 +26,7 @@ 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 the optional semantic search endpoint use it to find relevant parts of a page.
 
-The default keyword [search box](https://www.shoalrun.com/author/search.md) uses the separate page-level `search-index.json`. The included `semantic` provider connects that box to the passage-search endpoint. You do not need a passage index for normal static-site keyword search.
+The default keyword [search box](https://www.shoalrun.com/author/search.md) uses the separate page-level `search-index.json`. The included `semantic` provider connects that box to the passage-search endpoint. You don't need a passage index for normal static-site keyword search.
 
 Create the files after building the site:
 
@@ -61,18 +61,18 @@ Each entry in `chunks` describes one passage:
 }
 ```
 
-| 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.      |
+| 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's 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`. Since `0.1.0-alpha.16`, this digest identifies passage content, publication membership, routes, reader marks, and prepared search evidence. Metadata changes can change this digest without requiring new embeddings.
 
@@ -88,4 +88,4 @@ 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.
+The derived `search` data isn't part of the embedding input or its digest. Preparing it doesn't require new embeddings for unchanged passages.

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

@@ -18,7 +18,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Documentation chat > Answer cards
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -26,7 +26,7 @@ An answer card stores a reviewed answer to a recurring question. Generate cards
 
 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.
+> **Note:** An answer card isn't 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
 
@@ -61,7 +61,7 @@ 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:
+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 don't 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.
@@ -103,7 +103,7 @@ shoalrun ask-log ask.jsonl --cards-out candidates.yaml
 
 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.
+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 doesn't 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.
 

package/agent-docs/chat/settings.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -123,7 +123,7 @@ chat:
 
 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.
+Service-specific fields can affect latency, cost, and quality. Test them with your own questions and model; support and effects vary by service. Shoalrun doesn't interpret those extra fields.
 
 ## Choose the scorer
 
@@ -206,7 +206,7 @@ The main model answers first, and the checks run. If one of the `when` reasons a
 
 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.
+Choose an escalation model using reviewed questions that your primary model handles poorly. A larger model isn't automatically a better fit.
 
 ## Related reading
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

package/agent-docs/chat/settings.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

package/agent-docs/chat/settings.sections/send-extra-request-fields.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -39,4 +39,4 @@ chat:
 
 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.
+Service-specific fields can affect latency, cost, and quality. Test them with your own questions and model; support and effects vary by service. Shoalrun doesn't interpret those extra fields.

package/agent-docs/chat/settings.sections/use-more-than-one-model.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -59,4 +59,4 @@ The main model answers first, and the checks run. If one of the `when` reasons a
 
 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.
+Choose an escalation model using reviewed questions that your primary model handles poorly. A larger model isn't automatically a better fit.

package/agent-docs/chat/settings.sections/when-the-scorer-is-down.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

package/agent-docs/chat/setup.md

@@ -18,13 +18,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Documentation chat > Set up locally
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
 Set up a local chat panel, then check that its answers cite the right documentation. Start in the root of a Shoalrun project that already builds, with the CLI available in your terminal.
 
-You need a chat-service account and its API key. Meaning-based retrieval also needs an embedding provider and key. These commands make provider requests; they do not deploy your site.
+You need a chat-service account and its API key. Meaning-based retrieval also needs an embedding provider and key. These commands make provider requests; they don't deploy your site.
 
 For keyword-only retrieval, omit `retrieval` from the example below and omit `--embed` from the indexing command. You still need the passage index and a chat service.
 

package/agent-docs/chat.md

@@ -18,11 +18,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Documentation chat > How answers work
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
-Documentation chat reads a site you have already built. It is optional: a normal `shoalrun build` does not call the retrieval or chat providers.
+Documentation chat reads a site you have already built. It's optional: a normal `shoalrun build` doesn't 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.
 
@@ -34,7 +34,7 @@ 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.                     |
+| Keyword matching | Finds the most relevant passages by their words. It's 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.                        |