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

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:
@@ -122,7 +122,7 @@ The default `adaptive` mode requests a challenge when usage crosses a threshold:
 - 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.
 
@@ -153,7 +153,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 +203,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-10-25.**
+**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 custom passage-search providers use it to find relevant parts of a page.
+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 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.
+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:
 
@@ -90,7 +90,7 @@ Each entry in `chunks` describes one passage:
 
 ```json title="ai/chunks.json"
 {
-  "id": "guide.configuration#understand-the-three-stages",
+  "id": "production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages",
   "docId": "guide.configuration",
   "title": "Organize project configuration",
   "type": "how-to",
@@ -108,20 +108,20 @@ 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.      |
-
-The file also records `schemaVersion` and a `sourceDigest` that changes when any page's digest changes.
+| 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.
 
 ### Embedding input
 
@@ -135,19 +135,23 @@ 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
 
-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:
+Since `0.1.0-alpha.16`, a passage ID contains the URL-encoded publication, `:`, the URL-encoded page ID, `#`, and a slug of the heading path. Repeated logical page IDs in different releases have distinct passage IDs. 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. |
+| ID                                                                            | Meaning                                                    |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages`   | The first passage in that section.                         |
+| `production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages~2` | The second part of a section that split.                   |
+| `production%7Ccurrent%7Cen: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.
+IDs stay the same when body text changes. They change when you rename a heading, the page ID, or its publication. Treat the complete passage ID as an opaque identifier; use `docId` for the logical page identity.
+
+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 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.
 
@@ -184,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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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:
 
@@ -39,14 +39,18 @@ Indexing leaves published page content unchanged. The files sit beside the build
 
 ## 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:
+Since `0.1.0-alpha.16`, a passage ID contains the URL-encoded publication, `:`, the URL-encoded page ID, `#`, and a slug of the heading path. Repeated logical page IDs in different releases have distinct passage IDs. 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. |
+| ID                                                                            | Meaning                                                    |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages`   | The first passage in that section.                         |
+| `production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages~2` | The second part of a section that split.                   |
+| `production%7Ccurrent%7Cen: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.
+IDs stay the same when body text changes. They change when you rename a heading, the page ID, or its publication. Treat the complete passage ID as an opaque identifier; use `docId` for the logical page identity.
+
+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 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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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,15 +18,15 @@ 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-10-25.**
+**Updated: 2026-11-05.**
 
 **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.
+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 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.
+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:
 
@@ -43,7 +43,7 @@ Each entry in `chunks` describes one passage:
 
 ```json title="ai/chunks.json"
 {
-  "id": "guide.configuration#understand-the-three-stages",
+  "id": "production%7Ccurrent%7Cen:guide.configuration#understand-the-three-stages",
   "docId": "guide.configuration",
   "title": "Organize project configuration",
   "type": "how-to",
@@ -61,20 +61,20 @@ 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.      |
-
-The file also records `schemaVersion` and a `sourceDigest` that changes when any page's digest changes.
+| 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.
 
 ### Embedding input
 
@@ -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.