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

package/agent-docs/changelog/2026-10-25.md

@@ -16,7 +16,7 @@ releaseVersion: 0.1.0-alpha.6
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Content exports and documentation checks
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.6: Content exports
 
 **Published: 2026-10-25.**
 
@@ -42,4 +42,4 @@ A source citation connects one metadata explanation to its framework implementat
 
 ## Planned work
 
-[Project status](https://www.shoalrun.com/status.md) also records optional vector-store connections as planned work. They are not required for content exports or the existing file-based retrieval path.
+[Project status](https://www.shoalrun.com/status.md) also records optional vector-store connections as planned work. They aren't required for content exports or the existing file-based retrieval path.

package/agent-docs/changelog/2026-10-26.md

@@ -21,7 +21,7 @@ releaseVersion: 0.1.0-alpha.7 and 0.1.0-alpha.8
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Safer exports and easier discovery for AI assistants
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.7–8: Export safety
 
 **Published: 2026-10-26.**
 
@@ -49,13 +49,13 @@ The [help-drawer example](https://www.shoalrun.com/publish/content-export.md) no
 
 ## Check your output destination
 
-Use a real directory as the build or export destination. A destination that is itself a symbolic link is now rejected; symbolic links in its parent directories remain supported.
+Use a real directory as the build or export destination. A destination that's itself a symbolic link is now rejected; symbolic links in its parent directories remain supported.
 
 Shoalrun also rejects paths that escape the output directory, empty path segments, unsafe export mount paths, and duplicate output aliases before writing. Different paths to the same parent directory share one output lock, preventing competing builds from writing there at the same time. The export manifest remains at schema version 1.
 
 ## Technical details and validation
 
-Compact directories have a 2,000-token limit, measured with `cl100k_base`. This limits each response, not the total reading needed for a question. A title or summary that cannot fit in one entry still needs shortening. Tests cover 160 to 1,600 pages, large topics, hundreds of topics, and reachability of every published page and declared standalone section.
+Compact directories have a 2,000-token limit, measured with `cl100k_base`. This limits each response, not the total reading needed for a question. A title or summary that can't fit in one entry still needs shortening. Tests cover 160 to 1,600 pages, large topics, hundreds of topics, and reachability of every published page and declared standalone section.
 
 The MCP server and client packages move to version `2.3.0`. Zod moves to `4.6.6`, and KaTeX to `0.18.2`. MCP tool arguments are limited to 1,024 elements before schema validation. HTTP requests retain the 64 KiB body limit and a separate server instance for each request.
 
@@ -63,4 +63,4 @@ These updates address advisories for [MCP connection isolation](https://github.c
 
 Alpha.7 validation passed 723 framework tests, all five packaged skill checks, and clean installations of the minimal and API-documentation starters. Its dependency audit reported no vulnerabilities at validation time. Package checks also inspect the file inventory and exercise the installed help drawer in a browser. Test runs limit concurrency to four files, rebuild tests wait for complete server events, and skill validation reports missing Python prerequisites with setup instructions.
 
-This remains an alpha release. Publishing the CLI does not automatically upgrade or deploy an existing site. See [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) for the reading workflow and [portable content exports](https://www.shoalrun.com/publish/content-export.md) for reuse in another application.
+This remains an alpha release. Publishing the CLI doesn't automatically upgrade or deploy an existing site. See [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) for the reading workflow and [portable content exports](https://www.shoalrun.com/publish/content-export.md) for reuse in another application.

package/agent-docs/changelog/2026-10-27.md

@@ -25,7 +25,7 @@ releaseVersion: 0.1.0-alpha.11
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Clearer defaults, a feature showcase, and easier navigation
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.11: Navigation and defaults
 
 **Published: 2026-10-27.**
 

package/agent-docs/changelog/2026-10-28.md

@@ -23,7 +23,7 @@ releaseVersion: 0.1.0-alpha.13
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Content delivery, verification dates, and clearer references
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.13: Content delivery
 
 **Published: 2026-10-28.**
 
@@ -82,8 +82,8 @@ Clicking article content no longer draws a rectangle around the entire page body
 
 Fenced code blocks can contain literal scaffold TODO examples without failing publication. Those examples remain readable in HTML and Markdown. Unresolved prompts in prose or frontmatter still fail the public build.
 
-Project discovery and validation now suggest native relationships when a related-reading or related-material section contains document links. The hint is nonblocking and does not generate relationships. Authors still choose the purpose and reason for each connection. The component index also maps reader tasks to native features.
+Project discovery and validation now suggest native relationships when a related-reading or related-material section contains document links. The hint is nonblocking and doesn't generate relationships. Authors still choose the purpose and reason for each connection. The component index also maps reader tasks to native features.
 
 ## HTML, Markdown, and agents
 
-Content exports contain passive HTML or readable Markdown, without website controls. Applications own rendering and interaction; agents can read typed references and retrieve Markdown without operating a browser. HTML visibility settings such as `showVerified` do not remove the underlying verification date from Markdown or the manifest.
+Content exports contain passive HTML or readable Markdown, without website controls. Applications own rendering and interaction; agents can read typed references and retrieve Markdown without operating a browser. HTML visibility settings such as `showVerified` don't remove the underlying verification date from Markdown or the manifest.

package/agent-docs/changelog/2026-10-30.md

@@ -20,7 +20,7 @@ releaseVersion: 0.1.0-alpha.14
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Readable selections and wider layouts
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.14: Layouts and selection
 
 **Published: 2026-10-30.**
 

package/agent-docs/changelog/2026-11-03.md

@@ -23,7 +23,7 @@ releaseVersion: 0.1.0-alpha.15
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Customer documentation editions
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.15: Customer editions
 
 **Published: 2026-11-03.**
 
@@ -35,13 +35,13 @@ Upgrade to CLI `0.1.0-alpha.15` and rebuild your site and content exports to use
 
 ## Select purchased and grandfathered features
 
-A shared stock keeping unit (SKU) manifest maps explicit product revisions to feature IDs. Profiles combine those grants with direct feature entries, including features customers still own without a SKU. Historical revisions remain selectable; lifecycle labels do not revoke grants or automatically select older documentation versions.
+A shared stock keeping unit (SKU) manifest maps explicit product revisions to feature IDs. Profiles combine those grants with direct feature entries, including features customers still own without a SKU. Historical revisions remain selectable; lifecycle labels don't revoke grants or automatically select older documentation versions.
 
 Pages use feature requirements, and `<ForFeature>` selects sections inside shared pages. Selection removes excluded content from the build instead of hiding it in the browser. Deployment profiles can also apply supported titles, logos, favicons, theme choices, links, and publication subsets.
 
 ## Require deliberate page classification
 
-By default, pages without feature requirements remain shared. Enable `profiles.requireClassification: true` to require each eligible source page to explicitly declare `shared: true` or feature requirements. Inherited defaults do not satisfy the check, and missing classification fails before customer selection.
+By default, pages without feature requirements remain shared. Enable `profiles.requireClassification: true` to require each eligible source page to explicitly declare `shared: true` or feature requirements. Inherited defaults don't satisfy the check, and missing classification fails before customer selection.
 
 Shared pages can still contain feature-specific sections. Classification catches forgotten declarations; authors must still review the content and place requirements around product-specific instructions.
 
@@ -49,8 +49,8 @@ Shared pages can still contain feature-specific sections. Classification catches
 
 Pass the same external profile to baseline capture, authoring validation, build, and export. Validation captures the profile and its declared assets; later changes make that evidence stale. The packaged authoring, setup, and recipe skills explain this workflow and how to check included and excluded content.
 
-Profiled API builds support selected references and focused operation contracts. Full raw OpenAPI downloads, standalone schema embeds, and profiled chat-function builds are not supported. Use build/serve or snapshot validation/preview rather than `dev` for customer editions.
+Profiled API builds support selected references and focused operation contracts. Full raw OpenAPI downloads, standalone schema embeds, and profiled chat-function builds aren't supported. Use build/serve or snapshot validation/preview rather than `dev` for customer editions.
 
 ## HTML, Markdown, and agents
 
-The compiler applies feature selection to HTML, Markdown, search, discovery, and content exports. Agents receive the selected content rather than browser-hidden alternatives. Pages excluded by the chosen profile have not had their rendered content validated; check another profile that includes a changed page before accepting that edit. Customer access to the resulting edition remains the deployment's responsibility.
+The compiler applies feature selection to HTML, Markdown, search, discovery, and content exports. Agents receive the selected content rather than browser-hidden alternatives. Pages excluded by the chosen profile haven't had their rendered content validated; check another profile that includes a changed page before accepting that edit. Customer access to the resulting edition remains the deployment's responsibility.

package/agent-docs/changelog/2026-11-04-runtime-packaging.md

@@ -0,0 +1,46 @@
+---
+id: change.2026-11-04-runtime-packaging
+title: Smaller hosted search and Ask functions
+summary: Rebuild hosted docs with alpha.17 to reduce deployment files while
+  keeping semantic search and Ask available.
+type: changelog-entry
+area:
+  - publishing
+  - discovery
+  - project
+subarea:
+  - publishing-configuration
+  - discovery-search
+  - project-releases
+canonical: /changelog/2026-11-04-runtime-packaging
+date: 2026-11-04
+releaseVersion: 0.1.0-alpha.17
+---
+
+# Smaller hosted search and Ask functions
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.17: Hosted search and Ask
+
+**Published: 2026-11-04.**
+
+**Version: 0.1.0-alpha.17.**
+
+Alpha.17 reduces the files packaged with hosted Search and Ask. Large deployments previously included tools used to compile documentation, even though the hosted functions didn't need them to answer requests.
+
+Upgrade to CLI `0.1.0-alpha.17` and rebuild your hosted bundle to apply the change. Existing deployments keep their current files until you deploy the rebuilt output. No configuration migration is required.
+
+## Package each function's required files
+
+Hosted Search now has its own runtime package instead of receiving a copy of the Ask function. It keeps its private passage index and embeddings, with the same semantic endpoint, keyword fallback, and usage limits. Ask keeps its answer generation and card support. Both functions avoid the component compiler, icon library, syntax highlighter, math renderer, and browser bundler.
+
+A local comparison using Shoalrun's documentation corpus reduced the complete deployment from 18,205 files to 3,995 files. Its size fell from about 202 MB to 93 MB before compression. Those measurements include static documentation and MCP. Results depend on your site's content and enabled services; they aren't a per-site size guarantee.
+
+The MCP function retains its existing runtime and scope. This release doesn't add semantic retrieval to MCP or the CLI, or introduce a vector database backend.
+
+## Check the rebuilt deployment
+
+Build and validate your production output before uploading it. Verify that Search and Ask still answer requests after deployment, and inspect semantic search fallback reasons if results use keyword matching. See [Configure site search](https://www.shoalrun.com/author/search.md) for the search setup and [Deploy with Vercel](https://www.shoalrun.com/publish/vercel.md) for hosted deployment instructions.

package/agent-docs/changelog/authoring-preview.md

@@ -15,7 +15,7 @@ date: 2026-10-13
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Authoring snapshot previews and review reports
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-13: Snapshot previews
 
 **Published: 2026-10-13.**
 
@@ -25,9 +25,9 @@ This change concerns the private prototype; no package release or deployment is
 
 `docs preview REPORT` serves a private copy of that exact build on a loopback address. It returns a browser review URL and routes for every affected page that rendered. HTML pages display freshness and a review link. Source edits make the preview stale rather than replacing its content; validate again and restart from the new report. Changed artifacts prevent startup or serving.
 
-Ctrl-C or SIGTERM closes the foreground server and removes its serving copy. Validation artifacts remain available separately. Failed or skipped checks retain their actual status while previewing. The tools make no authoring provider calls and do not apply edits, commit, or publish.
+Ctrl-C or SIGTERM closes the foreground server and removes its serving copy. Validation artifacts remain available separately. Failed or skipped checks retain their actual status while previewing. The tools make no authoring provider calls and don't apply edits, commit, or publish.
 
-Snapshot builds preserve captured freshness history. Configured checks can declare sibling files and directories with `audit.tests[].inputs`; validation captures those inputs and tracks their changes. Compiler checks do not replace factual or editorial review.
+Snapshot builds preserve captured freshness history. Configured checks can declare sibling files and directories with `audit.tests[].inputs`; validation captures those inputs and tracks their changes. Compiler checks don't replace factual or editorial review.
 
 ## Related reading
 

package/agent-docs/changelog/authoring-search.md

@@ -15,7 +15,7 @@ date: 2026-10-03
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Agent authoring, search, and documentation answers
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-03: Agent authoring
 
 **Published: 2026-10-03.**
 

package/agent-docs/changelog/authoring-tools.md

@@ -15,7 +15,7 @@ date: 2026-10-13
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Working-tree authoring tools
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-13: Authoring tools
 
 **Published: 2026-10-13.**
 
@@ -25,7 +25,7 @@ This change concerns the private prototype; no package release is claimed.
 - Existing coding agents edit ordinary working-tree files. Baselines record the starting state; validation checks a separate capture and retains findings and build artifacts. Freshness checks detect later source changes.
 - Checked plan/apply commands retain their existing protections.
 
-Snapshot preview serving, consolidated review reports, and the portable skill's complete working-tree workflow remain planned. Compiler checks do not replace factual or editorial review.
+Snapshot preview serving, consolidated review reports, and the portable skill's complete working-tree workflow remain planned. Compiler checks don't replace factual or editorial review.
 
 ## Related reading
 

package/agent-docs/changelog/product-publications.md

@@ -0,0 +1,60 @@
+---
+id: change.product-publications
+title: Independent product versions and customer previews
+summary: Publish independent product releases together and preview each
+  customer's selected edition while editing.
+type: changelog-entry
+area:
+  - publishing
+  - discovery
+  - project
+subarea:
+  - publishing-versions
+  - discovery-agents
+  - project-releases
+canonical: /changelog/product-publications
+date: 2026-11-04
+releaseVersion: 0.1.0-alpha.18
+---
+
+# Independent product versions and customer previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.18: Product versions
+
+**Published: 2026-11-04.**
+
+**Version: 0.1.0-alpha.18.**
+
+Alpha.18 lets each product keep its own documentation releases. For example, a company with two products could publish v3 of one and v1 of the other. Each customer edition can select the versions that customer uses. You can preview either customer edition while editing, without separately rebuilding and starting a server after each change.
+
+Upgrade to CLI `0.1.0-alpha.18`, rebuild the site and content exports, and deploy the reviewed output. Existing deployments keep their current behavior until replaced. Ordinary builds don't automatically call embedding or answer-generation providers; regenerate those assets separately when their inputs change.
+
+Page availability can now appear as “Since” and “Through” labels beside the page dates, using the existing release-version style. Use `availability` frontmatter for page-wide support and inline badges for newer options within an older guide. Both boundaries are inclusive, and Markdown and document manifests retain the information. See [page metadata](https://www.shoalrun.com/author/frontmatter-reference.md).
+
+## Publish product releases independently
+
+Declare each product's versions, default version, and route prefix in `publications.products`. Add product coordinates to enabled publications, page memberships, API sources, and customer profile selections. Product identity stays with links, navigation, search, and agent reads. A version in one product doesn't select a similarly named version in another.
+
+This is an opt-in migration. Without a product catalog, existing productless routes and identities stay unchanged, and `frontmatter.product` remains metadata or a reader facet. With a catalog, review those values as publication IDs and add redirects for moved URLs. See [Share pages across products and versions](https://www.shoalrun.com/publish/publications.md).
+
+Customer profiles select releases separately from feature grants. Existing page-level `requires` and section-level `<ForFeature>` continue to remove excluded content during compilation. `shared: true` classifies feature eligibility; explicit publication memberships determine where a shared page appears.
+
+## Preview the customer edition as you edit
+
+Run `npx --no-install shoalrun dev docs.config.yaml dist/customer --profile /run/config/customer.yaml`. The server watches the chosen profile, SKU manifest, content, and declared branding assets, including external inputs. Successful changes replace the selected edition. Failed rebuilds keep the last successful output and display an error; correcting the declared input triggers recovery.
+
+The preview identifies the profile and successful build. When a successful edition change removes the open page, the browser moves to a published landing page. See [Build customer documentation editions](https://www.shoalrun.com/publish/deployment-profiles.md) for profile selection and preview commands.
+
+## HTML, Markdown, and agents
+
+Sites with product catalogs show a native publication dropdown in HTML, grouped by product, with language labels hidden when only one language is available. It supports the browser's keyboard interaction. JavaScript handles selection changes; ordinary links remain available without JavaScript. Markdown contains the selected publication's instructions and links without the dropdown.
+
+Agents can enumerate publications through paginated MCP `get_publications`, then retain product coordinates in scoped searches and reads. Discovery indexes keep their configured output bounds. Product-aware content exports use v2 contracts without changing resource representation paths. Productless exports retain v1 contracts. See [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) and [Export content into your application](https://www.shoalrun.com/publish/content-export.md).
+
+The release also keeps a published OpenAPI source shared across documentation languages and preserves the selected language in API authoring. Answer-card generation accepts explicit publication selectors so a multi-product site doesn't silently choose another edition.
+
+For the complete capability overview, see [Shoalrun features](https://www.shoalrun.com/features.md).

package/agent-docs/changelog/working-tree-skill.md

@@ -15,7 +15,7 @@ date: 2026-10-13
 
 Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Portable working-tree authoring workflow
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-13: Working-tree skill
 
 **Published: 2026-10-13.**
 

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