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

package/agent-docs/changelog.md

@@ -16,12 +16,28 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > All changes
 
-**Updated: 2026-11-03.**
+**Updated: 2026-11-05.**
 
 Updates to Shoalrun and its documentation. Each entry identifies the affected versions and any upgrade steps. Earlier entries retain their private-prototype release context.
 
 ## Latest changes
 
+- 2026-11-04
+
+  Version 0.1.0-alpha.17
+
+  [Smaller hosted search and Ask functions](https://www.shoalrun.com/changelog/2026-11-04-runtime-packaging.md)
+
+  Rebuild hosted docs with alpha.17 to reduce deployment files while keeping semantic search and Ask available.
+
+- 2026-11-04
+
+  Version 0.1.0-alpha.18
+
+  [Independent product versions and customer previews](https://www.shoalrun.com/changelog/product-publications.md)
+
+  Publish independent product releases together and preview each customer's selected edition while editing.
+
 - 2026-11-03
 
   Version 0.1.0-alpha.15

package/agent-docs/chat/checks.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.**
 
@@ -52,11 +52,11 @@ Jev reads each sentence that carries a citation, together with the passage it ci
 
 Fenced code, lead-ins that end in a colon, and statements that the docs lack something are skipped, because no passage can support an absence. That covers phrasings such as "the docs don't specifically describe", "no other information is given", and "it only shows".
 
-A sentence below `verify.threshold` is flagged in the notes, or removed when `onUnsupported` is `remove`. If removal leaves no supported sentence, the answer becomes "The documentation does not cover that." The check costs one more Jev call for each answer.
+A sentence below `verify.threshold` is flagged in the notes, or removed when `onUnsupported` is `remove`. If removal leaves no supported sentence, the answer becomes `The documentation does not cover that.` The check costs one more Jev call for each answer.
 
 Start with flagging while you review the results. Choose a threshold using questions and source passages from your own project; scores and useful thresholds vary by scorer. Removing sentences can leave an answer incomplete.
 
-The claims check can't catch a wrong sentence that a passage loosely supports, or a passage that is itself wrong. It reads only the passage a sentence cites.
+The claims check can't catch a wrong sentence that a passage loosely supports, or a passage that's itself wrong. It reads only the passage a sentence cites.
 
 ## Answer without a model
 
@@ -72,7 +72,7 @@ A passage is shown only when all of these are true:
 
 - Jev scores the best passage at `threshold` or higher.
 - At most `others` other passages score within `margin` of the best. A broad question has many strong passages and needs a model to combine them.
-- It is a question that stands on its own. A follow-up, which needs the conversation to make sense, always goes to the model.
+- It's a question that stands on its own. A follow-up, which needs the conversation to make sense, always goes to the model.
 
 Every other question goes to the model as usual. A passage longer than `maxChars` (default 1,200) is cut to the block that answers the question. The cut keeps the sentence that introduces a code example, or the example that a sentence introduces. If trimming fails, the whole passage is shown. The answer begins with **From the docs** and the page and section, and the result's decision is `excerpt`. `--no-direct` on `ask` turns the mode off for one run.
 
@@ -86,12 +86,12 @@ Some questions are asked so often that they deserve a reviewed answer. An answer
 
 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".
@@ -114,7 +114,7 @@ A rewrite is accepted only when it meets these constraints:
 - No web address or proposed instruction such as “Set the draft property to false.”
 - Technical names in backticks, dotted identifiers, and command flags already occur in the conversation.
 
-If the rewrite or service fails, retrieval combines the previous and current questions. The rejected rewrite is not displayed; a note records the fallback. These checks do not prove that an accepted rewrite preserves the reader's intent.
+If the rewrite or service fails, retrieval combines the previous and current questions. The rejected rewrite isn't displayed; a note records the fallback. These checks don't prove that an accepted rewrite preserves the reader's intent.
 
 Rewriting makes a model call and is skipped when the model budget is spent.
 
@@ -124,13 +124,13 @@ An explicit request such as “Compare templates and snippets, then explain navi
 
 For each part, Ask also considers introductions from up to three matching pages. An introduction can explain a prerequisite or automatic build behavior that a matching subsection omits. Related-reading lists are excluded from this evidence selection. With Jev, up to 36 topic/passage pairs are scored in at most two additional batches. Semantic retrieval can make one additional query-embedding request per part.
 
-Evidence selection reserves a passage for each part before adding a second round, up to `chat.passages`. The model is asked to address every part and state when evidence is missing. A part with no passage above the relevance threshold makes the answer partial; when none qualify, Ask declines. Multi-part requests do not use the direct-excerpt or answer-card shortcuts.
+Evidence selection reserves a passage for each part before adding a second round, up to `chat.passages`. The model is asked to address every part and state when evidence is missing. A part with no passage above the relevance threshold makes the answer partial; when none qualify, Ask declines. Multi-part requests don't use the direct-excerpt or answer-card shortcuts.
 
-The result's optional `coverage` field records the topic and whether selected evidence passed the relevance threshold. Without a scorer, that value is `null`. A positive relevance score means a passage may help; it does not prove the answer is complete or correct. Citation and claim checks still run on the generated answer. Questions whose meaning depends on several sources remain experimental.
+The result's optional `coverage` field records the topic and whether selected evidence passed the relevance threshold. Without a scorer, that value is `null`. A positive relevance score means a passage may help; it doesn't prove the answer is complete or correct. Citation and claim checks still run on the generated answer. Questions whose meaning depends on several sources remain experimental.
 
 ## Answer for one audience
 
-`chat.readerView` limits retrieval to the configured audience, such as customers or staff. It filters whole pages using their reader marks. It does not make published files private; use host-level access controls for confidential content.
+`chat.readerView` limits retrieval to the configured audience, such as customers or staff. It filters whole pages using their reader marks. It doesn't make published files private; use host-level access controls for confidential content.
 
 It uses the same reader filters as the search box. Define the audiences once under `readerFilters.facets`, name one in the chat, and tag pages with `audiences`:
 

package/agent-docs/chat/checks.sections/answer-ahead-of-time.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.**
 

package/agent-docs/chat/checks.sections/answer-for-one-audience.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.**
 
@@ -35,7 +35,7 @@ Citations and code are checked by default. Coverage gating, claim verification,
 
 ## Answer for one audience
 
-`chat.readerView` limits retrieval to the configured audience, such as customers or staff. It filters whole pages using their reader marks. It does not make published files private; use host-level access controls for confidential content.
+`chat.readerView` limits retrieval to the configured audience, such as customers or staff. It filters whole pages using their reader marks. It doesn't make published files private; use host-level access controls for confidential content.
 
 It uses the same reader filters as the search box. Define the audiences once under `readerFilters.facets`, name one in the chat, and tag pages with `audiences`:
 

package/agent-docs/chat/checks.sections/answer-without-a-model.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.**
 
@@ -47,7 +47,7 @@ A passage is shown only when all of these are true:
 
 - Jev scores the best passage at `threshold` or higher.
 - At most `others` other passages score within `margin` of the best. A broad question has many strong passages and needs a model to combine them.
-- It is a question that stands on its own. A follow-up, which needs the conversation to make sense, always goes to the model.
+- It's a question that stands on its own. A follow-up, which needs the conversation to make sense, always goes to the model.
 
 Every other question goes to the model as usual. A passage longer than `maxChars` (default 1,200) is cut to the block that answers the question. The cut keeps the sentence that introduces a code example, or the example that a sentence introduces. If trimming fails, the whole passage is shown. The answer begins with **From the docs** and the page and section, and the result's decision is `excerpt`. `--no-direct` on `ask` turns the mode off for one run.
 

package/agent-docs/chat/checks.sections/follow-up-questions.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.**
 
@@ -49,6 +49,6 @@ A rewrite is accepted only when it meets these constraints:
 - No web address or proposed instruction such as “Set the draft property to false.”
 - Technical names in backticks, dotted identifiers, and command flags already occur in the conversation.
 
-If the rewrite or service fails, retrieval combines the previous and current questions. The rejected rewrite is not displayed; a note records the fallback. These checks do not prove that an accepted rewrite preserves the reader's intent.
+If the rewrite or service fails, retrieval combines the previous and current questions. The rejected rewrite isn't displayed; a note records the fallback. These checks don't prove that an accepted rewrite preserves the reader's intent.
 
 Rewriting makes a model call and is skipped when the model budget is spent.

package/agent-docs/chat/checks.sections/how-an-answer-is-checked.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.**
 
@@ -60,8 +60,8 @@ Jev reads each sentence that carries a citation, together with the passage it ci
 
 Fenced code, lead-ins that end in a colon, and statements that the docs lack something are skipped, because no passage can support an absence. That covers phrasings such as "the docs don't specifically describe", "no other information is given", and "it only shows".
 
-A sentence below `verify.threshold` is flagged in the notes, or removed when `onUnsupported` is `remove`. If removal leaves no supported sentence, the answer becomes "The documentation does not cover that." The check costs one more Jev call for each answer.
+A sentence below `verify.threshold` is flagged in the notes, or removed when `onUnsupported` is `remove`. If removal leaves no supported sentence, the answer becomes `The documentation does not cover that.` The check costs one more Jev call for each answer.
 
 Start with flagging while you review the results. Choose a threshold using questions and source passages from your own project; scores and useful thresholds vary by scorer. Removing sentences can leave an answer incomplete.
 
-The claims check can't catch a wrong sentence that a passage loosely supports, or a passage that is itself wrong. It reads only the passage a sentence cites.
+The claims check can't catch a wrong sentence that a passage loosely supports, or a passage that's itself wrong. It reads only the passage a sentence cites.

package/agent-docs/chat/checks.sections/questions-with-several-parts.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.**
 
@@ -39,6 +39,6 @@ An explicit request such as “Compare templates and snippets, then explain navi
 
 For each part, Ask also considers introductions from up to three matching pages. An introduction can explain a prerequisite or automatic build behavior that a matching subsection omits. Related-reading lists are excluded from this evidence selection. With Jev, up to 36 topic/passage pairs are scored in at most two additional batches. Semantic retrieval can make one additional query-embedding request per part.
 
-Evidence selection reserves a passage for each part before adding a second round, up to `chat.passages`. The model is asked to address every part and state when evidence is missing. A part with no passage above the relevance threshold makes the answer partial; when none qualify, Ask declines. Multi-part requests do not use the direct-excerpt or answer-card shortcuts.
+Evidence selection reserves a passage for each part before adding a second round, up to `chat.passages`. The model is asked to address every part and state when evidence is missing. A part with no passage above the relevance threshold makes the answer partial; when none qualify, Ask declines. Multi-part requests don't use the direct-excerpt or answer-card shortcuts.
 
-The result's optional `coverage` field records the topic and whether selected evidence passed the relevance threshold. Without a scorer, that value is `null`. A positive relevance score means a passage may help; it does not prove the answer is complete or correct. Citation and claim checks still run on the generated answer. Questions whose meaning depends on several sources remain experimental.
+The result's optional `coverage` field records the topic and whether selected evidence passed the relevance threshold. Without a scorer, that value is `null`. A positive relevance score means a passage may help; it doesn't prove the answer is complete or correct. Citation and claim checks still run on the generated answer. Questions whose meaning depends on several sources remain experimental.

package/agent-docs/chat/checks.sections/related-reading.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.**
 

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