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

package/agent-docs/author/search.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 
@@ -35,14 +35,48 @@ outputs:
       provider: lexical
 ```
 
-| Provider  | Behavior                                                                |
-| --------- | ----------------------------------------------------------------------- |
-| `lexical` | The default. Builds `/search-index.json` and matches it in the browser. |
-| `custom`  | Loads your browser module. Needs `module`; `index` is optional.         |
-| `none`    | Removes the search box. Writes no index or provider file.               |
+| Provider   | Behavior                                                                                                      |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `lexical`  | The default. Builds `/search-index.json` and matches it in the browser.                                       |
+| `semantic` | Uses Shoalrun’s same-origin search endpoint, with browser keyword fallback. Available since `0.1.0-alpha.16`. |
+| `custom`   | Loads your browser module. Needs `module`; `index` is optional.                                               |
+| `none`     | Removes the search box. Writes no index or provider file.                                                     |
 
 The build copies the provider module to `/assets/search-provider.js`. The search box imports that file when a reader first focuses the box or types.
 
+## Enable included semantic search
+
+Available since `0.1.0-alpha.16`.
+
+Choose the included semantic provider to connect the search box to Shoalrun's endpoint without writing a browser adapter:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: semantic
+retrieval:
+  embeddings:
+    provider: voyage
+    model: voyage-4-large
+    queryModel: voyage-4-lite
+    dimension: 1024
+```
+
+Set `VOYAGE_API_KEY` in the terminal environment, then build the site, embed its passages, and start the local endpoint:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun index site-dist --embed --config docs.config.yaml
+npx --no-install shoalrun serve site-dist --search --config docs.config.yaml
+```
+
+Keys remain server-side. Each semantic query calls the embedding provider; no chat model is required. The browser sends the selected publication and reader view with each request. A missing or unavailable endpoint uses the included browser keyword index. Requests cancelled by further typing do not start fallback searches.
+
+Confirm `mode: vector` in the endpoint response to verify semantic retrieval. Rebuild and reindex edited content, then restart the local server. The [passage index](https://www.shoalrun.com/chat/passage-index.md) explains input reuse and release-specific passage identities.
+
+This setting selects the browser connection; it does not provision production hosting. The current [Vercel integration](https://www.shoalrun.com/publish/vercel.md) supplies search through its chat-function deployment. Profiled Vercel chat-function builds remain unsupported. Static deployments retain keyword search when no endpoint is present. Custom search services can continue to use `provider: custom`.
+
 ## Use the search box
 
 Press `/` or `Ctrl`+`K` (`⌘`+`K` on macOS) to focus the box. Use the arrow keys to move through results, Enter to open one, and Escape to close the list. When a match falls inside a section, the result names the section and links to its heading.
@@ -252,6 +286,21 @@ Result snippets prefer prose matching the substantive words in your question, om
 
 [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) covers the embedding provider key, passage index, local endpoint, lexical fallback, and Network inspector checks.
 
+## Agent and MCP search scope
+
+`outputs.html.search.provider: semantic` changes the website search box. It does not change CLI or MCP search into semantic retrieval. Those tools retain keyword search and explicit publication selection.
+
+For a multi-version Windows build, select the release when searching:
+
+```sh
+npx --no-install shoalrun search windows-site "missing events" \
+  --channel production --version 7.1 --language en
+```
+
+A local MCP server's `search_docs` tool accepts the same `channel`, `version`, and `language` fields. Follow the returned `read.tool` and `read.arguments` to read the matching page or section in that publication. Do not substitute a current-release page with the same logical ID.
+
+A hosted MCP build packages one configured publication, so its endpoint rejects requests for a different release. Product selection currently comes from the chosen build or endpoint. A combined product/version catalog is not part of this release. Customer-specific builds should expose only their selected edition to these tools.
+
 ## CLI and MCP ranking details
 
 CLI and MCP use the lexical index too, with additional ranking rules for documentation lookups. Browser search keeps its complete-match-first, coverage-first behavior.

package/agent-docs/author/search.sections/agent-and-mcp-search-scope.md

@@ -0,0 +1,48 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
+
+**Updated: 2026-11-04.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Agent and MCP search scope
+
+`outputs.html.search.provider: semantic` changes the website search box. It does not change CLI or MCP search into semantic retrieval. Those tools retain keyword search and explicit publication selection.
+
+For a multi-version Windows build, select the release when searching:
+
+```sh
+npx --no-install shoalrun search windows-site "missing events" \
+  --channel production --version 7.1 --language en
+```
+
+A local MCP server's `search_docs` tool accepts the same `channel`, `version`, and `language` fields. Follow the returned `read.tool` and `read.arguments` to read the matching page or section in that publication. Do not substitute a current-release page with the same logical ID.
+
+A hosted MCP build packages one configured publication, so its endpoint rejects requests for a different release. Product selection currently comes from the chosen build or endpoint. A combined product/version catalog is not part of this release. Customer-specific builds should expose only their selected edition to these tools.

package/agent-docs/author/search.sections/choose-a-provider.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 
@@ -43,10 +43,11 @@ outputs:
       provider: lexical
 ```
 
-| Provider  | Behavior                                                                |
-| --------- | ----------------------------------------------------------------------- |
-| `lexical` | The default. Builds `/search-index.json` and matches it in the browser. |
-| `custom`  | Loads your browser module. Needs `module`; `index` is optional.         |
-| `none`    | Removes the search box. Writes no index or provider file.               |
+| Provider   | Behavior                                                                                                      |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `lexical`  | The default. Builds `/search-index.json` and matches it in the browser.                                       |
+| `semantic` | Uses Shoalrun’s same-origin search endpoint, with browser keyword fallback. Available since `0.1.0-alpha.16`. |
+| `custom`   | Loads your browser module. Needs `module`; `index` is optional.                                               |
+| `none`     | Removes the search box. Writes no index or provider file.                                                     |
 
 The build copies the provider module to `/assets/search-provider.js`. The search box imports that file when a reader first focuses the box or types.

package/agent-docs/author/search.sections/cli-and-mcp-ranking-details.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/enable-included-semantic-search.md

@@ -0,0 +1,66 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
+
+**Updated: 2026-11-04.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Enable included semantic search
+
+Available since `0.1.0-alpha.16`.
+
+Choose the included semantic provider to connect the search box to Shoalrun's endpoint without writing a browser adapter:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: semantic
+retrieval:
+  embeddings:
+    provider: voyage
+    model: voyage-4-large
+    queryModel: voyage-4-lite
+    dimension: 1024
+```
+
+Set `VOYAGE_API_KEY` in the terminal environment, then build the site, embed its passages, and start the local endpoint:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun index site-dist --embed --config docs.config.yaml
+npx --no-install shoalrun serve site-dist --search --config docs.config.yaml
+```
+
+Keys remain server-side. Each semantic query calls the embedding provider; no chat model is required. The browser sends the selected publication and reader view with each request. A missing or unavailable endpoint uses the included browser keyword index. Requests cancelled by further typing do not start fallback searches.
+
+Confirm `mode: vector` in the endpoint response to verify semantic retrieval. Rebuild and reindex edited content, then restart the local server. The [passage index](https://www.shoalrun.com/chat/passage-index.md) explains input reuse and release-specific passage identities.
+
+This setting selects the browser connection; it does not provision production hosting. The current [Vercel integration](https://www.shoalrun.com/publish/vercel.md) supplies search through its chat-function deployment. Profiled Vercel chat-function builds remain unsupported. Static deployments retain keyword search when no endpoint is present. Custom search services can continue to use `provider: custom`.

package/agent-docs/author/search.sections/hosted-semantic-search-limits.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/html-markdown-and-agents.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/lexical-search.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/local-semantic-preview.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/related-reading.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/reuse-the-lexical-index.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/turn-search-off.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/use-the-search-box.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

package/agent-docs/author/search.sections/write-a-custom-provider.md

@@ -16,7 +16,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 > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-04.**
 
 **Verified: 2026-10-01.**
 

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-04.**
 
 **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 do not 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",
@@ -121,7 +121,7 @@ Each entry in `chunks` describes one passage:
 | `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.
+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
 
@@ -139,15 +139,19 @@ The derived `search` data is not part of the embedding input or its digest. Prep
 
 ## 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 does not 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/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-04.**
 
 **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 do not 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-04.**
 
 **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 do not need a passage index for normal static-site keyword search.
 
 Create the files after building the site:
 

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-04.**
 
 **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 do not 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-04.**
 
 **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 do not 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-04.**
 
 **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 do not 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 does not 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-04.**
 
 **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 do not 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-04.**
 
 **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 do not 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",
@@ -74,7 +74,7 @@ Each entry in `chunks` describes one passage:
 | `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.
+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