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

package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md

@@ -17,11 +17,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Page purpose and structure
 
@@ -44,6 +44,6 @@ Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and a
 
 Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
 
-Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
+Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Don't assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
 
-These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
+These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Don't add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.

package/agent-docs/author/writing-style.sections/procedures-and-examples.md

@@ -17,16 +17,16 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Procedures and examples
 
-Show the starting directory, required inputs, and expected result when a command depends on them. Say which values readers must replace. Keep commands supported by source or verified behavior; do not invent flags to make an example look complete.
+Show the starting directory, required inputs, and expected result when a command depends on them. Say which values readers must replace. Keep commands supported by source or verified behavior; don't invent flags to make an example look complete.
 
 Give each procedure step one purpose. Put the explanation beside the action it supports. Include a check that readers can perform and describe what success looks like. Troubleshooting should identify a symptom, likely cause, and concrete next action.
 
-Examples demonstrate the feature under discussion. Use the smallest example that still shows the important behavior. Preserve required fields, defaults, constraints, and meaningful errors during a rewrite. An example copied from a different page is not evidence that it applies to this task.
+Examples demonstrate the feature under discussion. Use the smallest example that still shows the important behavior. Preserve required fields, defaults, constraints, and meaningful errors during a rewrite. An example copied from a different page isn't evidence that it applies to this task.

package/agent-docs/author/writing-style.sections/related-reading.md

@@ -17,11 +17,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Related reading
 

package/agent-docs/author/writing-style.sections/review-a-draft.md

@@ -17,14 +17,14 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Review a draft
 
-Check purpose, organization, definitions, factual support, examples, and the success check. Compare technical details with the original source. Run the compiler and Vale, then inspect HTML and Markdown. This site's Vale configuration enables Voices, Direct, and Shoalrun; those rules catch detectable wording and structure problems. Passing them does not establish factual accuracy or usefulness.
+Check purpose, organization, definitions, factual support, examples, and the success check. Compare technical details with the original source. Run the compiler and Vale, then inspect HTML and Markdown. This site's Vale configuration enables Voices, Direct, and Shoalrun; those rules catch detectable wording and structure problems. Passing them doesn't establish factual accuracy or usefulness.
 
 Give your agent this guide and an example appropriate to the page's purpose. Examples guide structure and tone; verify technical claims against the relevant sources.

package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md

@@ -17,11 +17,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Reviewed writing examples
 

package/agent-docs/author/writing-style.sections/voice-and-explanations.md

@@ -17,14 +17,16 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
-This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
 ## Voice and explanations
 
+Use natural contractions such as “don't,” “can't,” “it's,” and “you're.” Keep expanded forms when emphasis or clarity needs them. Preserve exact commands, configuration values, API fields, error messages, and quotations. Vale's `Shoalrun.Contractions` rule flags common expanded forms for review; contractions themselves are accepted.
+
 Address the reader as “you.” Use active voice and concrete verbs. Start a paragraph with its main point, then supply the reason or example needed to understand it. Keep sentences short enough to follow without breaking every thought into a separate paragraph.
 
 Name the action and its result. Replace claims such as “powerful,” “seamless,” and “easy” with behavior the reader can observe. Avoid inflated words, ceremonial introductions, repeated summaries, and invented terminology.

package/agent-docs/changelog/2026-10-14-agent-readiness.md

@@ -15,11 +15,11 @@ date: 2026-10-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 > Agent discovery, verified Markdown, and incremental sync
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-14: Agent discovery
 
 **Published: 2026-10-14.**
 
-Agents can now find pages through smaller indexes, check which build they are reading, and compare saved page inventories before fetching updates.
+Agents can now find pages through smaller indexes, check which build they're reading, and compare saved page inventories before fetching updates.
 
 - **Smaller discovery files.** `llms.min.txt` lists page IDs, titles, summaries, and Markdown links. `search-index.min.json` adds headings without article text. Markdown 404 responses point to these compact files.
 - **Incremental sync.** Clients can check `build-info.json` for a new build, then compare `documents.sync.json` with their saved snapshot to find added, changed, and removed pages. They can fetch only the pages that need updating instead of downloading the full manifest and every page again. `shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SNAPSHOT` performs the comparison locally.

package/agent-docs/changelog/2026-10-15-evaluation-builds.md

@@ -15,11 +15,11 @@ date: 2026-10-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 > Agent reading and evaluation
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-15: Agent evaluation
 
 **Published: 2026-10-15.**
 
-This entry combines the October 15 changes to the private prototype. It does not announce a package release or a verified deployment.
+This entry combines the October 15 changes to the private prototype. It doesn't announce a package release or a verified deployment.
 
 ## Compare evaluation builds
 
@@ -27,9 +27,9 @@ Evaluation reports can now identify which published files changed. New report te
 
 Use `shoalrun eval snapshot` to save an inventory and `shoalrun eval compare` to compare builds. The check still requires the exact evaluated output. Copying a build to another machine preserves its identity; rebuilding it may produce different bytes.
 
-The repository can also capture hosted builds with their tasks and an ungraded report template for later review. Capturing a build does not run the tasks or award a passing grade.
+The repository can also capture hosted builds with their tasks and an ungraded report template for later review. Capturing a build doesn't run the tasks or award a passing grade.
 
-The packaged Markdown bundle also stops carrying a whole-site build ID for assets it does not include. Its page digests and metadata remain intact.
+The packaged Markdown bundle also stops carrying a whole-site build ID for assets it doesn't include. Its page digests and metadata remain intact.
 
 [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) explains the workflow and its limits.
 
@@ -55,7 +55,7 @@ This private prototype update adds `subjectDeprecation` to page metadata. Author
 
 Readers see the same guidance in HTML, full-page Markdown, and published section resources. Fetch-only agents can follow the Markdown links directly. The document manifest also exposes the dates and resolved targets. Builds reject invalid dates and references outside the current publication.
 
-The guidance describes the documented subject. It does not remove the documentation page or emit HTTP retirement headers. Dates are author declarations, not evidence that a service has retired.
+The guidance describes the documented subject. It doesn't remove the documentation page or emit HTTP retirement headers. Dates are author declarations, not evidence that a service has retired.
 
 See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for syntax and validation rules.
 
@@ -63,9 +63,9 @@ See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for syntax a
 
 This private prototype update preserves reading guidance when an agent fetches one section of a longer page. Prerequisites and next steps from top-level, current-page `RelatedReading` views now travel with the section, including the reason to follow each link and the target's status.
 
-The added block says that the links apply to the full page. Links already in the section or its introduction are not repeated. Conditional and nested reading views stay with their original content. HTML and full-page Markdown keep their authored placement.
+The added block says that the links apply to the full page. Links already in the section or its introduction aren't repeated. Conditional and nested reading views stay with their original content. HTML and full-page Markdown keep their authored placement.
 
-The extra guidance counts toward exact section sizes and can make a section too large to publish separately. It does not establish that a section is self-contained or that the reader has completed its prerequisites. See [related reading](https://www.shoalrun.com/author/related-reading.md) for the rules.
+The extra guidance counts toward exact section sizes and can make a section too large to publish separately. It doesn't establish that a section is self-contained or that the reader has completed its prerequisites. See [related reading](https://www.shoalrun.com/author/related-reading.md) for the rules.
 
 ## Understand authored change meaning
 
@@ -73,12 +73,12 @@ This private prototype update adds optional `change` metadata to changelog entri
 
 The declaration appears in HTML, full-page Markdown, section Markdown, and the document manifest. Fetch-only agents can read it and follow the links without a tool integration.
 
-The build validates the fields and resolves public targets within the entry's publication. It does not verify the author's classification. Older entries remain visible without metadata and are unclassified. No separate change feed or deployment claim is added.
+The build validates the fields and resolves public targets within the entry's publication. It doesn't verify the author's classification. Older entries remain visible without metadata and are unclassified. No separate change feed or deployment claim is added.
 
 See [write release notes and changelog entries](https://www.shoalrun.com/author/release-notes.md) for syntax and limits.
 
 ## Check the published-output contract
 
-The [output reference](https://www.shoalrun.com/publish/output.md) now defines the existing manifest and sync contract, including optional capabilities, section identity, field meanings, and the limits of byte verification. Two repository JSON Schemas and a local check validate existing build output without rebuilding or making network requests. The check covers field shapes, document identities, manifest/sync agreement, and referenced Markdown sizes and digests. This documentation and validation update does not change the published format or enable hosted checks.
+The [output reference](https://www.shoalrun.com/publish/output.md) now defines the existing manifest and sync contract, including optional capabilities, section identity, field meanings, and the limits of byte verification. Two repository JSON Schemas and a local check validate existing build output without rebuilding or making network requests. The check covers field shapes, document identities, manifest/sync agreement, and referenced Markdown sizes and digests. This documentation and validation update doesn't change the published format or enable hosted checks.
 
 The site's five-question agent self-assessment is now retained as historical example evidence instead of a routine audit requirement. Local build, link, schema, output-consistency, behavior, and browser checks remain available. New agent evaluations should address a concrete product question.

package/agent-docs/changelog/2026-10-16-navigation-layouts.md

@@ -15,11 +15,11 @@ date: 2026-10-16
 
 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 > Navigation, page layouts, and browser analytics
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-16: Navigation and analytics
 
 **Published: 2026-10-16.**
 
-This entry groups the October 16 changes to Shoalrun's private prototype and documentation. It does not announce a package release or a verified deployment.
+This entry groups the October 16 changes to Shoalrun's private prototype and documentation. It doesn't announce a package release or a verified deployment.
 
 ## Navigate between sections
 
@@ -49,11 +49,11 @@ Pages led by a Hero omit the page-level Markdown action row. Markdown twins and
 
 Projects can now connect browser analytics through the top-level `analytics.module` setting. Shoalrun supplies versioned events for navigation, content tabs, disclosures, clipboard successes, search outcomes, and reader selections. Events include stable page IDs and publication context. Site scripts can emit additional events through the same hook.
 
-The browser adapter owns service initialization, consent, and delivery. Analytics is off by default, and disabled builds omit its runtime and adapter. SDK failures do not interrupt the site. Browser instrumentation leaves Markdown and agent discovery unchanged; agent request measurements belong at the host or server. See [bring your own analytics](https://www.shoalrun.com/author/analytics.md).
+The browser adapter owns service initialization, consent, and delivery. Analytics is off by default, and disabled builds omit its runtime and adapter. SDK failures don't interrupt the site. Browser instrumentation leaves Markdown and agent discovery unchanged; agent request measurements belong at the host or server. See [bring your own analytics](https://www.shoalrun.com/author/analytics.md).
 
 ## Add contributor documentation
 
-Repository contributors now have a separate maintainer guide covering architecture, development, validation, hosting, and release work. It is separate from the public documentation and packaged agent bundle.
+Repository contributors now have a separate maintainer guide covering architecture, development, validation, hosting, and release work. It's separate from the public documentation and packaged agent bundle.
 
 ## Related reading
 

package/agent-docs/changelog/2026-10-17-mcp-hosting.md

@@ -15,11 +15,11 @@ date: 2026-10-17
 
 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 > MCP hosting, analytics, and component improvements
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-17: MCP hosting
 
 **Published: 2026-10-17.**
 
-This entry groups the October 17 changes to Shoalrun’s private prototype. It does not announce a package release.
+This entry groups the October 17 changes to Shoalrun’s private prototype. It doesn't announce a package release.
 
 ## Serve documentation tools over HTTP
 

package/agent-docs/changelog/2026-10-18-search-and-tooltips.md

@@ -15,11 +15,11 @@ date: 2026-10-18
 
 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 > Search results and tooltips
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-18: Search and tooltips
 
 **Published: 2026-10-18.**
 
-These October 18 changes improve search and supporting explanations in Shoalrun’s private prototype. This entry does not announce a package release.
+These October 18 changes improve search and supporting explanations in Shoalrun’s private prototype. This entry doesn't announce a package release.
 
 ## Find useful search results
 
@@ -29,7 +29,7 @@ Explicit identifiers and commands remain searchable in code and tables. Matching
 
 The [passage index](https://www.shoalrun.com/chat/passage-index.md) prepares result paragraphs, code lines, and table rows during indexing. Search requests no longer parse the Markdown passages to prepare these results.
 
-Preparing this data does not change the embedding input, so unchanged passages reuse their existing vectors.
+Preparing this data doesn't change the embedding input, so unchanged passages reuse their existing vectors.
 
 Queries such as “charts” and “graphs” lead to chart and diagram examples with readable descriptions. Searching “diagrams” opens the [Diagrams guide](https://www.shoalrun.com/author/components/diagrams.md). Semantic search retains its keyword fallback when embeddings are unavailable; Ask passage retrieval is unchanged.
 

package/agent-docs/changelog/2026-10-19-visual-navigation.md

@@ -15,11 +15,11 @@ date: 2026-10-19
 
 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 > Experimental visual navigation and taxonomy enforcement
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 2026-10-19: Visual navigation
 
 **Published: 2026-10-19.**
 
-These October 19 changes cover the documentation site's experimental explorer and taxonomy enforcement in CLI `0.1.0-alpha.3`. This entry does not announce a package release or a verified deployment.
+These October 19 changes cover the documentation site's experimental explorer and taxonomy enforcement in CLI `0.1.0-alpha.3`. This entry doesn't announce a package release or a verified deployment.
 
 ## Explore documentation visually
 
@@ -27,7 +27,7 @@ The site's [experimental explorer](https://www.shoalrun.com/explore.md) provides
 
 Views support zoom and pan, with native browser fullscreen where supported. Fullscreen keeps layout controls visible and makes filters and the relationship key available in expandable panels. The matrix distinguishes source rows from destination columns and offers readable sizing alongside the full overview.
 
-Relationship arrows show direction. Related topics and comparisons apply in both directions. Line patterns, matrix symbols, labels, and a monochrome option supplement color. The sidebar identifies incoming, outgoing, and two-way relationships, their page endpoints, and why they are connected.
+Relationship arrows show direction. Related topics and comparisons apply in both directions. Line patterns, matrix symbols, labels, and a monochrome option supplement color. The sidebar identifies incoming, outgoing, and two-way relationships, their page endpoints, and why they're connected.
 
 Those explanations come from authored `reason` fields in the relationship configuration. The build publishes them in `documents.json`; the explorer makes no model calls and infers no new connections. [Related reading](https://www.shoalrun.com/author/related-reading.md) documents the authoring and validation rules.
 

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