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

package/agent-docs/chat/checks.sections/reuse-answers.md

@@ -17,7 +17,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 checks and reuse
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -37,12 +37,12 @@ Citations and code are checked by default. Coverage gating, claim verification,
 
 People ask the same questions. With `chat.cache`, `serve --ask` keeps recent answers in memory and returns a stored one when the same question comes back, with no model call. The question is compared after ignoring case, extra spaces, and closing punctuation, and separately for each publication and reader view.
 
-Only an answer that passed every check is stored. A hedged answer, a declined one, and one with a flagged sentence, flagged code, or an invented citation are not. A follow-up is never stored and never served from the cache, because its meaning depends on the conversation.
+Only an answer that passed every check is stored. A hedged answer, a declined one, and one with a flagged sentence, flagged code, or an invented citation aren't. A follow-up is never stored and never served from the cache, because its meaning depends on the conversation.
 
 A cache entry is removed when:
 
-- It is older than `ttlMinutes`.
-- The cache is full and it is the least recently used entry.
+- It's older than `ttlMinutes`.
+- The cache is full and it's the least recently used entry.
 - A source passage shown to the model has changed.
 
 The local panel labels reused answers with "from the answer cache".

package/agent-docs/chat/host.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 > Host on Vercel
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -30,7 +30,7 @@ Before building the hosted function, have these ready:
 - A shared store that speaks the Upstash REST API.
 - A Vercel project and the public address in `site.origin`.
 
-The normal site build does not add this function. Hosted provider requests can incur costs.
+The normal site build doesn't add this function. Hosted provider requests can incur costs.
 
 ## Cap the daily spend
 
@@ -77,13 +77,13 @@ Because a slot is taken before the answer and not counted after, questions that
 
 ## Host the chat on Vercel
 
-The chat can run as a Vercel function on the same deployment as the site. It is optional, and a build never adds it unless you ask. Add `--chat` to the Vercel build:
+The chat can run as a Vercel function on the same deployment as the site. It's optional, and a build never adds it unless you ask. Add `--chat` to the Vercel build:
 
 ```sh
 shoalrun vercel build docs.config.yaml .vercel/output --chat
 ```
 
-The build indexes the site and puts the index inside the function's own directory, never in the public static files. It writes the chat settings, without any key, and copies the code the function needs. The function answers at `/__shoalrun/ask`. If the function cannot be added, the build fails with a reason. Check for:
+The build indexes the site and puts the index inside the function's own directory, never in the public static files. It writes the chat settings, without any key, and copies the code the function needs. The function answers at `/__shoalrun/ask`. If the function can't be added, the build fails with a reason. Check for:
 
 - A missing `chat` or `retrieval.embeddings` section.
 - A missing `chat.budget.store`.
@@ -107,7 +107,7 @@ The hosted chat shows only answers that cite the docs. When the model's answer c
 
 ### Check visitors with Turnstile
 
-`chat.challenge` turns on a Cloudflare Turnstile check. The browser gets a one-time token, and the function asks Cloudflare whether it is real. A failed check is refused before any model is called.
+`chat.challenge` turns on a Cloudflare Turnstile check. The browser gets a one-time token, and the function asks Cloudflare whether it's real. A failed check is refused before any model is called.
 
 ```yaml title="docs.config.yaml"
 chat:
@@ -116,23 +116,41 @@ chat:
 
 The site key is public and goes in the config. The secret goes in the environment variable. A check that fails, times out, or has no secret refuses the request, so an outage can't let scripts through. Without `chat.challenge`, the function logs a warning, because only the daily caps then stand in the way of a script.
 
+The function also checks the hostname returned by Cloudflare. By default, it accepts the trusted site and deployment hostnames described above, without their ports. Set `hostnames` to an explicit list to narrow that check. Names are exact: don't include a scheme, path, port, or wildcard. Keep the widget's allowed domains in Cloudflare consistent with the addresses you intend to use.
+
+Use `action` when the widget needs to identify this operation. The browser sends it when requesting a token, and the server requires the same value in Cloudflare's verification response:
+
+```yaml title="docs.config.yaml"
+chat:
+  challenge:
+    provider: turnstile
+    siteKey: 0x4AAAAAAAexample
+    secretEnv: TURNSTILE_SECRET_KEY
+    hostnames: [docs.example.com]
+    action: documentation_chat
+```
+
+A missing or mismatched hostname, or a missing or mismatched configured action, refuses the request before answering. Adding a hostname here doesn't authorize incoming requests from that host; the function's host checks still apply.
+
 The default `adaptive` mode requests a challenge when usage crosses a threshold:
 
 - A caller is asked once they have used `freeQuestions` model answers in a day. The default is 3.
 - Everyone is asked once the site has used `busyShare` of its daily budget. The default is 0.5.
 - A budget store that can't be read means "ask", so an outage never removes the check.
 
-When challenged, the panel runs the check and resends the question. It shows "Checking that you are a person…" while waiting.
+When challenged, the panel runs the check and resends the question. It shows `Checking that you are a person…` while waiting.
 
-A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address. The signing key is derived from the Turnstile secret. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
+A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address and the hostname/action policy. The signing key is derived from the Turnstile secret and that policy. Changing the policy invalidates existing passes. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
 
 | Setting         | What it does                                                                                                                                                            |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hostnames`     | Exact hostnames accepted from token verification. Defaults to the trusted runtime hostnames; an explicit list must be nonempty.                                         |
+| `action`        | Optional operation name sent by the widget and checked by the server. Use 1–32 letters, digits, underscores, or hyphens.                                                |
 | `when`          | `adaptive` (the default) asks only when needed. `always` checks every conversation. It runs in the background when the panel opens, so the first question doesn't wait. |
 | `freeQuestions` | Model answers a caller gets before being asked. The default is 3.                                                                                                       |
 | `busyShare`     | The share of the daily budget at which everyone is asked. A number above 0 and at most 1. The default is 0.5.                                                           |
 
-Cloudflare publishes test keys for development. They work on any address and accept only their own test token, so a test site key needs the matching test secret. Use them for preview deployments, so you never have to register preview addresses.
+Cloudflare publishes test keys for development. A test site key needs the matching test secret. Test responses use synthetic hostname metadata and don't prove a production domain or action. `serve --ask --public-preview` configures its local test expectations for you. For hosted previews with real verification, register the preview hostname in the widget and include it among the function's trusted hosts. Keep test keys and test grants out of production.
 
 ### Record questions
 
@@ -153,7 +171,7 @@ shoalrun ask-log --kv --config docs.config.yaml --days 30
 
 The command reads the store's address and token from the environment variables the config names. Recording a question never delays or changes the answer, and a failed write is logged and dropped.
 
-Each recorded hosted answer has a **Delete logged question** button. The reader can remove that one record even while chat is paused. Its unguessable deletion code also appears under the answer so the reader can save it for a later request. Deleting a record does not delete the docs answer from the conversation. Earlier records made before deletion codes were added expire under the retention rule.
+Each recorded hosted answer has a **Delete logged question** button. The reader can remove that one record even while chat is paused. Its unguessable deletion code also appears under the answer so the reader can save it for a later request. Deleting a record doesn't delete the docs answer from the conversation. Earlier records made before deletion codes were added expire under the retention rule.
 
 For a later request, send the saved code to the same site's answer endpoint:
 
@@ -203,7 +221,7 @@ It also counts how questions were answered and how many called the model. It cou
 
 ### Local log privacy
 
-Questions can contain personal details. These controls reduce exposure but do not guarantee that sensitive text is removed:
+Questions can contain personal details. These controls reduce exposure but don't guarantee that sensitive text is removed:
 
 - Emails, phone and card-length numbers, keys, and the query part of a web address are replaced before the line is written. That's best effort and no guarantee.
 - The file is created with owner-only permissions and rotates at 5 MB, keeping one older file.

package/agent-docs/chat/host.sections/cap-the-daily-spend.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 > Host on Vercel
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -32,7 +32,7 @@ Before building the hosted function, have these ready:
 - A shared store that speaks the Upstash REST API.
 - A Vercel project and the public address in `site.origin`.
 
-The normal site build does not add this function. Hosted provider requests can incur costs.
+The normal site build doesn't add this function. Hosted provider requests can incur costs.
 
 ## Cap the daily spend
 

package/agent-docs/chat/host.sections/keep-a-record-of-questions.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 > Host on Vercel
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -32,7 +32,7 @@ Before building the hosted function, have these ready:
 - A shared store that speaks the Upstash REST API.
 - A Vercel project and the public address in `site.origin`.
 
-The normal site build does not add this function. Hosted provider requests can incur costs.
+The normal site build doesn't add this function. Hosted provider requests can incur costs.
 
 ## Keep a record of questions
 
@@ -53,7 +53,7 @@ It also counts how questions were answered and how many called the model. It cou
 
 ### Local log privacy
 
-Questions can contain personal details. These controls reduce exposure but do not guarantee that sensitive text is removed:
+Questions can contain personal details. These controls reduce exposure but don't guarantee that sensitive text is removed:
 
 - Emails, phone and card-length numbers, keys, and the query part of a web address are replaced before the line is written. That's best effort and no guarantee.
 - The file is created with owner-only permissions and rotates at 5 MB, keeping one older file.

package/agent-docs/chat/host.sections/related-reading.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 > Host on Vercel
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -32,7 +32,7 @@ Before building the hosted function, have these ready:
 - A shared store that speaks the Upstash REST API.
 - A Vercel project and the public address in `site.origin`.
 
-The normal site build does not add this function. Hosted provider requests can incur costs.
+The normal site build doesn't add this function. Hosted provider requests can incur costs.
 
 ## Related reading
 

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

@@ -18,13 +18,13 @@ 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.**
 
 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:
 
@@ -108,18 +108,18 @@ Each entry in `chunks` describes one passage:
 }
 ```
 
-| Field                    | Value                                                                                                                                                                   |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                     | The passage ID. See [Passage IDs](#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](#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.
 
@@ -135,7 +135,7 @@ 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.
 
 ## Passage IDs and links
 
@@ -151,7 +151,7 @@ IDs stay the same when body text changes. They change when you rename a heading,
 
 When upgrading an existing index, rerun `shoalrun index site-dist --embed --config docs.config.yaml` with the same embedding configuration. Matching input vectors are reused even when stored passage IDs change. Regenerate answer cards after rebuilding their cited IDs. Older indexes with duplicate passage IDs fail with rebuild instructions instead of silently sharing vectors across releases.
 
-The index command’s JSON summary includes `sourceDigest` and passage counts for each publication. Check these fields before starting a server, and index each customer’s already-pruned build separately. A running preview reads indexes at startup, so restart it after reindexing. Stored vectors remain file-backed; this release does not add an external vector database.
+The index command’s JSON summary includes `sourceDigest` and passage counts for each publication. Check these fields before starting a server, and index each customer’s already-pruned build separately. A running preview reads indexes at startup, so restart it after reindexing. Stored vectors remain file-backed; this release doesn't add an external vector database.
 
 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.
 
@@ -188,7 +188,7 @@ The summary gains an `embeddings` object:
 }
 ```
 
-The command sends each passage's [embedding input](#embedding-input) to the configured provider. The key is not written to the output.
+The command sends each passage's [embedding input](#embedding-input) to the configured provider. The key isn't written to the output.
 
 It writes two files next to `chunks.json`:
 

package/agent-docs/chat/passage-index.sections/build-the-index.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:
 

package/agent-docs/chat/passage-index.sections/embed-passages.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:
 
@@ -70,7 +70,7 @@ The summary gains an `embeddings` object:
 }
 ```
 
-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.
+The command sends each passage's [embedding input](https://www.shoalrun.com/chat/passage-index.md#embedding-input) to the configured provider. The key isn't written to the output.
 
 It writes two files next to `chunks.json`:
 

package/agent-docs/chat/passage-index.sections/how-the-default-chunker-splits-a-page.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:
 

package/agent-docs/chat/passage-index.sections/limits.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:
 

package/agent-docs/chat/passage-index.sections/passage-ids-and-links.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:
 
@@ -51,6 +51,6 @@ IDs stay the same when body text changes. They change when you rename a heading,
 
 When upgrading an existing index, rerun `shoalrun index site-dist --embed --config docs.config.yaml` with the same embedding configuration. Matching input vectors are reused even when stored passage IDs change. Regenerate answer cards after rebuilding their cited IDs. Older indexes with duplicate passage IDs fail with rebuild instructions instead of silently sharing vectors across releases.
 
-The index command’s JSON summary includes `sourceDigest` and passage counts for each publication. Check these fields before starting a server, and index each customer’s already-pruned build separately. A running preview reads indexes at startup, so restart it after reindexing. Stored vectors remain file-backed; this release does not add an external vector database.
+The index command’s JSON summary includes `sourceDigest` and passage counts for each publication. Check these fields before starting a server, and index each customer’s already-pruned build separately. A running preview reads indexes at startup, so restart it after reindexing. Stored vectors remain file-backed; this release doesn't add an external vector database.
 
 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

@@ -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:
 

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.**
 
@@ -98,7 +98,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `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).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. 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). |
@@ -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.**
 
@@ -66,7 +66,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `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).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. 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). |

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.**