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

package/agent-docs/example-api/cedar.md

@@ -17,11 +17,11 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Examples > Cedar Parcel API · styling lab > API reference styling lab
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 > Fictional API example. This page demonstrates documentation features; its operations do not describe a live service.
 
-The Cedar Parcel API is fictional. Its `.example` hosts do not accept requests, and its OpenAPI examples have not been executed. We keep it in the Shoalrun docs to check API reference layouts alongside other pages. It uses the same navigation, search, themes, and Markdown output.
+The Cedar Parcel API is fictional. Its `.example` hosts don't accept requests, and its OpenAPI examples haven't been executed. We keep it in the Shoalrun docs to check API reference layouts alongside other pages. It uses the same navigation, search, themes, and Markdown output.
 
 Use these pages to inspect the hardest layouts:
 
@@ -32,8 +32,8 @@ Use these pages to inspect the hardest layouts:
 - [Get a parcel through the old route](https://www.shoalrun.com/example-api/cedar/get-legacy-parcel-6758d051.md) shows OpenAPI deprecation overriding an extension value.
 - [Parcel delivered event](https://www.shoalrun.com/example-api/cedar/parcel-delivered-7d1ba6db.md) shows an inbound OpenAPI 3.1 webhook with a nested `oneOf` proof.
 
-The source and standalone test project live at `framework/example-configs/reference-stress/` in the repository. The source is not copied into the built site; each operation publishes only its focused contract.
+The source and standalone test project live at `framework/example-configs/reference-stress/` in the repository. The source isn't copied into the built site; each operation publishes only its focused contract.
 
 ## How it works for agents
 
-Every operation has a complete `.md` page and a focused OpenAPI contract. Schema fields remain in Markdown even when their HTML disclosure is closed. The site manifest and search index include these pages, and the reader's theme choice does not change what an agent can read.
+Every operation has a complete `.md` page and a focused OpenAPI contract. Schema fields remain in Markdown even when their HTML disclosure is closed. The site manifest and search index include these pages, and the reader's theme choice doesn't change what an agent can read.

package/agent-docs/features.md

@@ -0,0 +1,49 @@
+---
+id: guide.features
+title: Shoalrun features
+summary: A concise overview of Shoalrun's capabilities and operating limits.
+type: overview
+area: project
+subarea: project-overview
+canonical: /features
+---
+
+# Shoalrun features
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Shoalrun features
+
+**Updated: 2026-11-05.**
+
+Shoalrun compiles product and API documentation into a website and agent-readable content from the same source. You own the source files, build output, and deployment. The normal compiler build makes no model calls or network requests.
+
+## What you can build
+
+Follow a topic link for configuration, examples, and limits.
+
+| Capability                                                                             | What you can do                                                                                                                                                                                                               |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [One source, multiple outputs](https://www.shoalrun.com/publish/agent-friendliness.md) | Write Markdown and supported MDX; publish HTML, Markdown copies, discovery indexes, manifests, and readable sections.                                                                                                         |
+| [Structured authoring](https://www.shoalrun.com/author/content.md)                     | Give documents stable IDs; reuse templates, snippets, variables, metadata, and configuration. Connect navigation and related reading by ID.                                                                                   |
+| [Documentation components](https://www.shoalrun.com/author/components.md)              | Use tabs, callouts, tables, steps, walkthroughs, diagrams, and trusted custom components with defined Markdown representations.                                                                                               |
+| [OpenAPI documentation](https://www.shoalrun.com/publish/api-references.md)            | Generate reference pages, embed API examples and schemas, show request samples, and publish focused operation contracts. Review source changes before publishing.                                                             |
+| [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md)           | Select exact product releases, SKU revisions, and feature grants. Remove excluded pages and sections during compilation.                                                                                                      |
+| [Independent products and versions](https://www.shoalrun.com/publish/publications.md)  | Give each product its own documentation versions and defaults, with explicit languages and routes.                                                                                                                            |
+| [Search and agent tools](https://www.shoalrun.com/search-and-chat.md)                  | Search the selected publication by keyword or optional semantic retrieval. Read-only Model Context Protocol (MCP) tools discover publications and read pages within token budgets. Optional cited answers use your providers. |
+| [Content delivery](https://www.shoalrun.com/content-delivery.md)                       | Export selected pages, approved sections, and snippets for an application. Clients and REST retain exact product scope; productless version 1 contracts remain supported.                                                     |
+| [Workflows and validation](https://www.shoalrun.com/author/agent-overview.md)          | Use your coding agent with project discovery, isolated validation, and matching previews. Watch a customer edition with `dev --profile`. Compose recipes and cookbooks.                                                       |
+| [Presentation and navigation](https://www.shoalrun.com/styling/themes.md)              | Configure themes, layouts, branding, and navigation. Switch publications through a grouped dropdown, with language labels hidden automatically for single-language editions.                                                  |
+| [Publishing and measurement](https://www.shoalrun.com/publish.md)                      | Publish static output or use Node and Vercel serving options. Add analytics through optional adapters.                                                                                                                        |
+
+## Before you choose Shoalrun
+
+Configuration and output contracts can change as Shoalrun develops. OpenAPI and JSON Schema support is partial. Arbitrary executable MDX and a live API request explorer aren't supported.
+
+You supply hosting, reader authentication, authored translations, and any optional model or analytics services. Reader views change browsing convenience; they don't restrict access to published files. The hosted public MCP endpoint serves one configured publication, and profiled Vercel chat builds aren't supported.
+
+## HTML, Markdown, and agents
+
+This overview keeps the same feature descriptions and topic links in HTML and Markdown. Topic links lead to the detailed instructions. Agents can read the overview without browser scripts, then discover and retain the exact publication when searching or requesting a page. Interactive components have their own output and keyboard behavior documented in their references.

package/agent-docs/glossary.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Glossary
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 This page defines the terms used across Shoalrun's documentation. Look a term up when a guide uses a word you don't know. Terms are sorted A to Z, and each definition links to the full guide. Filter the list by a term or a word in its definition, for example `publication` or `agent`. In the Markdown version, use your reader's Find command. To see how the main terms fit together, read [How Shoalrun works](https://www.shoalrun.com/concepts.md).
 
@@ -34,7 +34,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Access policy**
 
-  The `access.policy` field. `public` puts a page in the build. Any other value, such as `draft`, keeps it out. It does not control who can read a published page. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
+  The `access.policy` field. `public` puts a page in the build. Any other value, such as `draft`, keeps it out. It doesn't control who can read a published page. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
 
 - **AFDocs**
 
@@ -42,7 +42,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Agent intent**
 
-  A self-reported category describing why an agent called an MCP tool. Optional analytics can record allowed categories; it does not reveal private model reasoning. See [MCP analytics](https://www.shoalrun.com/publish/mcp-analytics.md).
+  A self-reported category describing why an agent called an MCP tool. Optional analytics can record allowed categories; it doesn't reveal private model reasoning. See [MCP analytics](https://www.shoalrun.com/publish/mcp-analytics.md).
 
 - **Agent skill**
 
@@ -50,7 +50,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Alt text**
 
-  Text describing an image for readers who cannot see it. `<Image>` requires `alt`; `alt=""` marks a decorative image for screen readers to skip. See [Images](https://www.shoalrun.com/author/components/images.md).
+  Text describing an image for readers who can't see it. `<Image>` requires `alt`; `alt=""` marks a decorative image for screen readers to skip. See [Images](https://www.shoalrun.com/author/components/images.md).
 
 - **Analytics adapter**
 
@@ -58,11 +58,11 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Answer cache**
 
-  Temporary storage for checked answers in a running chat server. Matching repeated questions can reuse them while their source passages remain current. It is separate from prepared answer cards. See [Answer checks and reuse](https://www.shoalrun.com/chat/checks.md).
+  Temporary storage for checked answers in a running chat server. Matching repeated questions can reuse them while their source passages remain current. It's separate from prepared answer cards. See [Answer checks and reuse](https://www.shoalrun.com/chat/checks.md).
 
 - **Answer card**
 
-  A reviewed answer to a common question, generated ahead of time with `shoalrun answers` using a chat model. A confirmed match serves it without a new chat-model answer, though matching uses an embedding provider and scorer. It is not a page-preview card. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md).
+  A reviewed answer to a common question, generated ahead of time with `shoalrun answers` using a chat model. A confirmed match serves it without a new chat-model answer, though matching uses an embedding provider and scorer. It isn't a page-preview card. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md).
 
 - **API catalog**
 
@@ -126,7 +126,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Card**
 
-  A linked preview of another page. It shows the target's title and summary and follows the target's current URL. It is not an [answer card](https://www.shoalrun.com/chat/prepared-answers.md). See [Cards and collections](https://www.shoalrun.com/author/components/cards.md).
+  A linked preview of another page. It shows the target's title and summary and follows the target's current URL. It isn't an [answer card](https://www.shoalrun.com/chat/prepared-answers.md). See [Cards and collections](https://www.shoalrun.com/author/components/cards.md).
 
 - **Changelog identifier**
 
@@ -134,7 +134,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Channel**
 
-  An audience or environment, such as `production` or `sandbox`. It is one third of a publication. See [How Shoalrun works](https://www.shoalrun.com/concepts.md).
+  An audience or environment, such as `production` or `sandbox`. It's one third of a publication. See [How Shoalrun works](https://www.shoalrun.com/concepts.md).
 
 - **Chat answer**
 
@@ -198,7 +198,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Cookbook**
 
-  A page that helps readers choose among complete published recipe pages. Its introduction is authored separately; an optional chooser loads selected recipe instructions in the browser. It does not assemble ingredients or execute tasks. See [How recipes and cookbooks work](https://www.shoalrun.com/author/recipes.md).
+  A page that helps readers choose among complete published recipe pages. Its introduction is authored separately; an optional chooser loads selected recipe instructions in the browser. It doesn't assemble ingredients or execute tasks. See [How recipes and cookbooks work](https://www.shoalrun.com/author/recipes.md).
 
 - **Curated list**
 
@@ -302,7 +302,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Example project**
 
-  The `framework/example/` project used as a test fixture. It is not a deployed API. See [Example configs](https://www.shoalrun.com/config/examples.md).
+  The `framework/example/` project used as a test fixture. It isn't a deployed API. See [Example configs](https://www.shoalrun.com/config/examples.md).
 
 - **`extends`**
 
@@ -382,7 +382,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Harness**
 
-  The application running an agent and its tools, such as a coding-agent client. Its reported name does not establish which model it uses. See [MCP client metadata](https://www.shoalrun.com/publish/mcp-analytics.md).
+  The application running an agent and its tools, such as a coding-agent client. Its reported name doesn't establish which model it uses. See [MCP client metadata](https://www.shoalrun.com/publish/mcp-analytics.md).
 
 - **Header link**
 
@@ -418,11 +418,11 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Ingredient**
 
-  A reusable source document containing instructions for one action or check. Authors can copy it into several recipe drafts with the recipe assembler. Optional workflow metadata declares inputs, outputs, prerequisites, and a success check; it does not execute the action. See [How recipes and cookbooks work](https://www.shoalrun.com/author/recipes.md).
+  A reusable source document containing instructions for one action or check. Authors can copy it into several recipe drafts with the recipe assembler. Optional workflow metadata declares inputs, outputs, prerequisites, and a success check; it doesn't execute the action. See [How recipes and cookbooks work](https://www.shoalrun.com/author/recipes.md).
 
 - **Jev**
 
-  The supported relevance-scoring protocol used by `chat.rerank`. A compatible service rates passage relevance and support for claims; it does not write the answer. See [Scorer settings](https://www.shoalrun.com/chat/settings.md).
+  The supported relevance-scoring protocol used by `chat.rerank`. A compatible service rates passage relevance and support for claims; it doesn't write the answer. See [Scorer settings](https://www.shoalrun.com/chat/settings.md).
 
 - **JSON shape**
 
@@ -430,7 +430,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Language**
 
-  The content language of a publication, such as `en`. The default language has no route prefix. Shoalrun does not translate text. See [Share pages across versions](https://www.shoalrun.com/publish/publications.md).
+  The content language of a publication, such as `en`. The default language has no route prefix. Shoalrun doesn't translate text. See [Share pages across versions](https://www.shoalrun.com/publish/publications.md).
 
 - **Layout**
 
@@ -446,7 +446,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Locale**
 
-  An optional `locale` field for date, number, and currency conventions. It does not choose a publication. Use `language` for that. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
+  An optional `locale` field for date, number, and currency conventions. It doesn't choose a publication. Use `language` for that. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
 
 - **Local MCP**
 
@@ -474,7 +474,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **MCP endpoint**
 
-  The HTTP address of a hosted documentation MCP server, such as this site’s `/mcp` endpoint. It requires a running server or host function; static files alone cannot serve it. See [Host an MCP endpoint](https://www.shoalrun.com/publish/mcp.md).
+  The HTTP address of a hosted documentation MCP server, such as this site’s `/mcp` endpoint. It requires a running server or host function; static files alone can't serve it. See [Host an MCP endpoint](https://www.shoalrun.com/publish/mcp.md).
 
 - **MDX**
 
@@ -502,7 +502,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Navigation tab**
 
-  A top-level site section, such as Docs or Changelog, with its own navigation scope. It is separate from the in-page `Tabs` component. See [Navigation](https://www.shoalrun.com/author/navigation.md).
+  A top-level site section, such as Docs or Changelog, with its own navigation scope. It's separate from the in-page `Tabs` component. See [Navigation](https://www.shoalrun.com/author/navigation.md).
 
 - **`Only`**
 
@@ -586,7 +586,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Reader view**
 
-  A reader's saved choice of audience, product, or another facet. It narrows navigation, search, cards, and marked sections. It is not access control. See [Reader views](https://www.shoalrun.com/author/reader-views.md).
+  A reader's saved choice of audience, product, or another facet. It narrows navigation, search, cards, and marked sections. It isn't access control. See [Reader views](https://www.shoalrun.com/author/reader-views.md).
 
 - **Recipe**
 
@@ -686,7 +686,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Sidebar filter**
 
-  The menu filter that matches navigation labels and optional node-level `search` words. It does not change site search. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md).
+  The menu filter that matches navigation labels and optional node-level `search` words. It doesn't change site search. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md).
 
 - **Site search**
 
@@ -774,11 +774,11 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Title**
 
-  The required `title` field. It is the page heading and the default browser title. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
+  The required `title` field. It's the page heading and the default browser title. See [Page metadata](https://www.shoalrun.com/author/frontmatter.md).
 
 - **Token**
 
-  A unit of text counted by a model or tokenizer. Token budgets limit how much text a tool or model processes; a token is not necessarily a word. For styling values, see Design token. See [CLI token limits](https://www.shoalrun.com/cli.md).
+  A unit of text counted by a model or tokenizer. Token budgets limit how much text a tool or model processes; a token isn't necessarily a word. For styling values, see Design token. See [CLI token limits](https://www.shoalrun.com/cli.md).
 
 - **`Tooltip`**
 
@@ -806,7 +806,7 @@ This page defines the terms used across Shoalrun's documentation. Look a term up
 
 - **Version**
 
-  An API or documentation edition, such as `v1` or `current`. It is one third of a publication. See [How Shoalrun works](https://www.shoalrun.com/concepts.md).
+  An API or documentation edition, such as `v1` or `current`. It's one third of a publication. See [How Shoalrun works](https://www.shoalrun.com/concepts.md).
 
 - **`Walkthrough`, `Step`**
 

package/agent-docs/index.md

@@ -12,7 +12,7 @@ canonical: /
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-05.**
 
 **Docs for people. Context for agents.**
 
@@ -85,7 +85,7 @@ FAIL build
 Checks failed. Fix the findings above and rerun shoalrun check.
 ```
 
-This output is illustrative, not a failure on the current site. The check catches unsupported representations; it does not establish that every sentence is correct.
+This output is illustrative, not a failure on the current site. The check catches unsupported representations; it doesn't establish that every sentence is correct.
 
 [Eval reports](https://www.shoalrun.com/publish/evals.md) add reviewed agent-task results to the gate. You supply the agent run and the review. Shoalrun's five example tasks are a self-reviewed demonstration, not an independent measure of agent accuracy.
 
@@ -103,7 +103,7 @@ This output is illustrative, not a failure on the current site. The check catche
 
 ## Let agents read your docs, and help write them
 
-Agents search and read built docs through the CLI or a read-only MCP server with four tools: `search_docs`, `get_page`, `get_outline`, and `get_section`. MCP cannot edit files or deploy. Writing and checking use your agent's own file tools, CLI commands such as `docs validate` and `audit`, and five bundled skills.
+Agents search and read built docs through the CLI or a read-only MCP server with four tools: `search_docs`, `get_page`, `get_outline`, and `get_section`. MCP can't edit files or deploy. Writing and checking use your agent's own file tools, CLI commands such as `docs validate` and `audit`, and five bundled skills.
 
 ```sh
 shoalrun docs mcp --site docs/dist
@@ -147,9 +147,9 @@ Keep one content directory and give each site its own config, origin, theme, and
 
   Publish separate sites from shared content using optional facet selection.
 
-- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md)
+- [Share pages across products and documentation versions](https://www.shoalrun.com/publish/publications.md)
 
-  Versioning one docs site without copying every page: share unchanged pages, vary sections, and publish changed pages separately.
+  Configure independent product versioning and reuse pages across releases, channels, and languages.
 
 ## Make it look like yours
 

package/agent-docs/ingredients/audit-site.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Reusable Shoalrun steps > Audit the Shoalrun docs project
 
-**Updated: 2026-10-19.**
+**Updated: 2026-11-05.**
 
 Run Shoalrun's configured checks. This repository's formatting check requires [Vale](https://vale.sh/) 3.20 or newer:
 
@@ -24,4 +24,4 @@ Run Shoalrun's configured checks. This repository's formatting check requires [V
 npx --no-install shoalrun audit docs/docs.config.yaml
 ```
 
-The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command doesn't run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.

package/agent-docs/ingredients/build-site.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Reusable Shoalrun steps > Build the Shoalrun docs site
 
-**Updated: 2026-10-19.**
+**Updated: 2026-11-05.**
 
 Use the installed CLI to build Shoalrun's documentation:
 
@@ -26,4 +26,4 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.

package/agent-docs/ingredients/complete-page.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Reusable Shoalrun steps > Complete the guide and add navigation
 
-**Updated: 2026-10-19.**
+**Updated: 2026-11-05.**
 
 Open the scaffolded file and write the actual task, prerequisites, steps, and an observable success check. Set `updated` to today's date, replace the draft summary, and resolve every generated TODO prompt. Check every technical claim against the implementation or a tested workflow.
 
@@ -27,4 +27,4 @@ Set a suitable `card.icon`, such as `file-text`, to meet this site's page-card a
 - { id: my-new-guide, doc: guide.my-new-guide }
 ```
 
-For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it does not deploy the site.
+For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it doesn't deploy the site.

package/agent-docs/ingredients/refresh-agent-bundle.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Reusable Shoalrun steps > Regenerate the agent documentation bundle
 
-**Updated: 2026-10-19.**
+**Updated: 2026-11-05.**
 
 Export the already built site for the framework’s next documentation snapshot:
 
@@ -24,6 +24,6 @@ Export the already built site for the framework’s next documentation snapshot:
 npm run agent-docs:build
 ```
 
-Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It does not modify the installed package.
+Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It doesn't modify the installed package.
 
 Review and transfer the export as a versioned artifact to the framework repository. Framework releases consume an explicitly selected snapshot; they must not fetch the latest site during a package build.

package/agent-docs/non-goals.md

@@ -17,17 +17,17 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Project > Non-goals
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Shoalrun's scope includes publishing documentation that people and agents can discover and read. This page records capabilities we deliberately exclude and the reasoning behind those decisions.
 
 ## Shipping a skill builder with the tool
 
-Shoalrun does not ship a non-interactive skill builder or automatically generate a reader-side skill for each site it builds.
+Shoalrun doesn't ship a non-interactive skill builder or automatically generate a reader-side skill for each site it builds.
 
 Skills need a human expert to guide their creation and maintenance. That expert brings knowledge of the domain, decides which workflows are appropriate, tests the instructions against real tasks, and keeps them accurate as the product changes.
 
-A non-interactive builder could produce something that looks complete and give users false confidence that they have “automatic agent skills.” Generating instructions alone does not establish that those instructions are useful, reliable, or kept current. We are not yet comfortable shipping a feature that implies that confidence.
+A non-interactive builder could produce something that looks complete and give users false confidence that they have “automatic agent skills.” Generating instructions alone doesn't establish that those instructions are useful, reliable, or kept current. We aren't yet comfortable shipping a feature that implies that confidence.
 
 Shoalrun's bundled authoring skills are maintained instructions for working with Shoalrun. Published sites receive Markdown pages and discovery files during the build. Teams that create their own skills remain responsible for expert guidance, review, evaluation, and maintenance.
 
@@ -39,7 +39,7 @@ The [evaluation task format and audit hook](https://www.shoalrun.com/publish/eva
 
 ## Using reader views for authorization
 
-[Reader views](https://www.shoalrun.com/author/reader-views.md) shape navigation and visible sections. They do not protect content: published files and Markdown twins remain available. Using a reader's selected view as an authorization boundary is outside their purpose. Exclude nonpublic pages from a public build and use host-level authorization when private content must be protected.
+[Reader views](https://www.shoalrun.com/author/reader-views.md) shape navigation and visible sections. They don't protect content: published files and Markdown twins remain available. Using a reader's selected view as an authorization boundary is outside their purpose. Exclude nonpublic pages from a public build and use host-level authorization when private content must be protected.
 
 ## Related reading
 

package/agent-docs/provenance.json

@@ -2,9 +2,15 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "dbf7c31e789550be5349dea0d314dfdc2b97ba70c7b1b3f1eebf6122c622be27",
-    "buildId": "60f6dc0eaa4cc7c73333e0bdfdf837bdd83c1636d96a92e98e93b28bbdfcb773"
+    "configDigest": "2a4f31a26f253a82d999fa1ed1d2a1220053ba53bea00435844ec76815e67bfa",
+    "buildId": "3ca70f64a4b3562b2c51fd6a4a6beceb3578705d2fc545b7788589aebd0e6ff5"
   },
-  "packageIntegrity": "sha512-5N/QcKQJaX3YZ3EUBPWAaBmvIR+bphIJnijgQtIKpYd22MrMGU+gtmB1Ke9Cpw9KgNCtImQsnNKt5gTUID8Mvw==",
-  "manifestDigest": "79a5524ecf5a8dfc44207e1d72b7558805cc6545b9178d2b6facdde584e43d37"
+  "packageIntegrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA==",
+  "compilerPackage": {
+    "kind": "reviewed-local-artifact",
+    "name": "@shoalrun/cli",
+    "version": "0.1.0-alpha.19",
+    "integrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA=="
+  },
+  "manifestDigest": "2fb2a205cf322384919c7546e0626c42de82c34cfcdc2f5e244c92968993fd03"
 }

package/agent-docs/publish/agent-discovery.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 > Configure the agent discovery block
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Configure the early HTML guidance so readers and agents can find the article, Markdown twin, and documentation index. Work in an existing Shoalrun project with a working local build.
 
@@ -25,7 +25,7 @@ Configure the early HTML guidance so readers and agents can find the article, Ma
 
 Set `site.agentDiscovery` to change the early HTML instruction. The default `mode: focus` hides it visually until keyboard focus enters its links. Choose `visible` for an always-shown banner, or `disclosure` for a compact **For agents** toggle in the header that starts closed. All three modes include the guidance links in the HTML source. Choose `off` to omit the block from HTML entirely.
 
-The mode controls visual presentation and whether the block is included. Screen readers and agents parsing raw HTML can encounter the guidance in both `focus` and `visible` modes. The disclosure uses native HTML `details` and `summary`, so it works without JavaScript. Agents using screenshots see the same visual presentation as humans and need to open the disclosure to see its links. Some HTML extraction tools discard visually hidden elements; the document head also provides discovery links. This setting does not control access to documentation or make the guidance private.
+The mode controls visual presentation and whether the block is included. Screen readers and agents parsing raw HTML can encounter the guidance in both `focus` and `visible` modes. The disclosure uses native HTML `details` and `summary`, so it works without JavaScript. Agents using screenshots see the same visual presentation as humans and need to open the disclosure to see its links. Some HTML extraction tools discard visually hidden elements; the document head also provides discovery links. This setting doesn't control access to documentation or make the guidance private.
 
 ## Set the message and link labels
 
@@ -68,6 +68,12 @@ Use **Copy as Markdown** beside **Read as Markdown** to copy the current page's
 
 Activate the button with Enter, Space, or a tap. A visible status announces success or failure to screen readers. If fetching or clipboard access fails, use **Read as Markdown** to open and copy the file manually. The plain link also works without JavaScript; the copy button appears when its script loads. Browser clipboard access requires a secure context and permission.
 
+## HTML, Markdown, and agents
+
+The agent discovery block links to the current page’s published Markdown and the site’s compact documentation index. The Markdown link retains the current product release. Product-aware discovery Since 0.1.0-alpha.18 preserves these coordinates. The header’s publication dropdown is a separate HTML navigation control. It doesn't become an interactive Markdown element or change which files a customer edition publishes.
+
+An MCP agent can discover product releases with the `get_publications` tool. Follow its `nextOffset`, then retain the chosen product/channel/version/language in later reads. A hosted endpoint exposes only its configured publication. A local server can select among publications in its built site. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for exact inputs and scope. A reader view or a hidden language label doesn't replace explicit publication selection.
+
 ## Related reading
 
 ### Reference while working

package/agent-docs/publish/agent-friendliness.md

@@ -17,11 +17,11 @@ 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 > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
@@ -49,7 +49,7 @@ Inspect the response status and returned identifier.
 
 ## What an agent reads
 
-Here is the Markdown generated from the example above. An agent does not need to click the tabs, expand the disclosure, or choose a reader to get these instructions.
+Here is the Markdown generated from the example above. An agent doesn't need to click the tabs, expand the disclosure, or choose a reader to get these instructions.
 
 ```md
 ### Command line
@@ -73,7 +73,7 @@ Open the activity screen to inspect the result.
 Inspect the response status and returned identifier.
 ```
 
-The labels become headings or ordinary text. The controls themselves are omitted. This site's test compares the example's generated Markdown with the text shown here so they cannot drift apart unnoticed. The [reader views reference](https://www.shoalrun.com/author/reader-views.md) explains how authors configure those choices.
+The labels become headings or ordinary text. The controls themselves are omitted. This site's test compares the example's generated Markdown with the text shown here so they can't drift apart unnoticed. The [reader views reference](https://www.shoalrun.com/author/reader-views.md) explains how authors configure those choices.
 
 ## What happens to an unsupported component?
 
@@ -93,11 +93,11 @@ Running `shoalrun check docs.config.yaml` reports a diagnostic containing:
 <UnregisteredPanel> has no semantic/Markdown adapter
 ```
 
-The example is displayed as code here so you can read it. A test also runs it as an actual component, checks that compilation fails, and verifies that the previous successful output remains intact. This check establishes how unsupported components are handled; it does not prove that every supported component or authored instruction is correct.
+The example is displayed as code here so you can read it. A test also runs it as an actual component, checks that compilation fails, and verifies that the previous successful output remains intact. This check establishes how unsupported components are handled; it doesn't prove that every supported component or authored instruction is correct.
 
 ## Discover a page with a small context budget
 
-An agent does not need to download every discovery artifact. Start with [`/llms.min.txt`](https://www.shoalrun.com/llms.min.txt), follow a matching topic index when present, and fetch the supplied Markdown page URL. Small indexes list pages directly. Larger indexes group pages by publication and primary taxonomy area, or page type when no area is declared. Topics split into narrower indexes as they grow.
+An agent doesn't need to download every discovery artifact. Start with [`/llms.min.txt`](https://www.shoalrun.com/llms.min.txt), follow a matching topic index when present, and fetch the supplied Markdown page URL. Small indexes list pages directly. Larger indexes group pages by publication and primary taxonomy area, or page type when no area is declared. Topics split into narrower indexes as they grow.
 
 Each compact or navigation-section index is limited to 2,000 `cl100k_base` tokens. This is a limit per response, not a fixed total for every reading task. Page entries retain IDs, titles, summaries, publication labels, and Markdown links. Author-declared standalone sections retain exact sizes and a **Full page** fallback. Default to the full page for setup or broader questions. Every published page remains reachable, including pages outside navigation.
 
@@ -112,7 +112,7 @@ Choose another artifact only when the task needs it:
 | [`documents.sync.json`](https://www.shoalrun.com/documents.sync.json)     | Compare a saved inventory with the current build.                        |
 | [`build-info.json`](https://www.shoalrun.com/build-info.json)             | Check whether the assembled build has changed.                           |
 
-Both search indexes are generated when search indexing is enabled. The full `/search-index.json` includes bounded article text for browser search, CLI search, and custom lexical fallbacks. It remains available, but it is not needed to find a page through the compact list. These files are downloadable indexes, not query endpoints. Shoalrun does not produce `llms-full.txt`.
+Both search indexes are generated when search indexing is enabled. The full `/search-index.json` includes bounded article text for browser search, CLI search, and custom lexical fallbacks. It remains available, but it isn't needed to find a page through the compact list. These files are downloadable indexes, not query endpoints. Shoalrun doesn't produce `llms-full.txt`.
 
 HTML pages provide a visible **Read as Markdown** link, a `rel="alternate"` link, and optional early agent guidance. The guidance links to the article, the compact index, and the current twin. The HTML head’s `rel="describedby"` link and Markdown index backlinks also point to `/llms.min.txt`, so entering through either format leads to the same starting list. Follow those supplied links when a fetch tool rejects guessed URLs. Compact-list links are site-relative; resolve them against the fetched index's origin. Markdown page links use the configured public origin when present.
 
@@ -122,13 +122,13 @@ Page identity is the stable document ID plus channel, version, and language. Dif
 
 The manifest exposes three distinct signals:
 
-| Signal               | What it establishes                                                                                          |
-| -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Page `digest`        | SHA-256 of the complete generated Markdown bytes. Compare it with the bytes you fetched.                     |
-| Page `contentDigest` | A resolved article-content fingerprint used for freshness tracking. It is not the hash of the Markdown file. |
-| Top-level `buildId`  | Identity of the assembled publication, including pages, contracts, assets, and metadata.                     |
+| Signal               | What it establishes                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Page `digest`        | SHA-256 of the complete generated Markdown bytes. Compare it with the bytes you fetched.                    |
+| Page `contentDigest` | A resolved article-content fingerprint used for freshness tracking. It isn't the hash of the Markdown file. |
+| Top-level `buildId`  | Identity of the assembled publication, including pages, contracts, assets, and metadata.                    |
 
-An author-set `verified` date is also available in the manifest. It records supplied review metadata, separately from `updated`; it is not proof that an external reviewer approved the page.
+An author-set `verified` date is also available in the manifest. It records supplied review metadata, separately from `updated`; it isn't proof that an external reviewer approved the page.
 
 For a long-lived client, save the sync snapshot and poll the small build-information file. An unchanged build ID means the saved inventory still applies. When the ID changes, compare the current snapshot with the saved one and refresh added or changed pages. Remove records that disappeared. The comparison includes route moves, metadata changes, and removed publication variants.
 
@@ -138,17 +138,17 @@ The local command is `shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SN
 
 Supported tabs and disclosures expand into readable Markdown sections. Reader-marked sections remain present with readable labels, even when a reader choice hides them in interactive HTML. Snippets and API examples resolve during the build. Unknown components and unsupported dynamic MDX fail compilation.
 
-The example above preserves the instructions while changing how they are presented. HTML still has tabs, disclosures, and reader controls. Markdown presents the content in reading order. The formats do not need identical bytes to be useful.
+The example above preserves the instructions while changing how they're presented. HTML still has tabs, disclosures, and reader controls. Markdown presents the content in reading order. The formats don't need identical bytes to be useful.
 
-Authors can deliberately tailor sections to each format with [Only](https://www.shoalrun.com/author/components/only.md). Review those choices for missing prerequisites, warnings, or shared product facts. A build gate can reject an unknown component; it cannot decide whether an intentional omission makes a task impossible. Similarly, [reader views](https://www.shoalrun.com/author/reader-views.md) are presentation controls. They do not authorize access or remove published content from the site's files.
+Authors can deliberately tailor sections to each format with [Only](https://www.shoalrun.com/author/components/only.md). Review those choices for missing prerequisites, warnings, or shared product facts. A build gate can reject an unknown component; it can't decide whether an intentional omission makes a task impossible. Similarly, [reader views](https://www.shoalrun.com/author/reader-views.md) are presentation controls. They don't authorize access or remove published content from the site's files.
 
 ## Distinguish examples from a real service
 
-Pages under configured `outputs.llms.fictionalPrefixes` carry `demo: true` in the document manifest and both search indexes. The plain-text indexes retain their fictional-example labels. Software can filter these records without interpreting prose. `demo: false` means unmarked; it does not certify that a service exists or is available.
+Pages under configured `outputs.llms.fictionalPrefixes` carry `demo: true` in the document manifest and both search indexes. The plain-text indexes retain their fictional-example labels. Software can filter these records without interpreting prose. `demo: false` means unmarked; it doesn't certify that a service exists or is available.
 
 API-reference pages can also link to a focused, digest-addressed OpenAPI contract containing one operation and its local definitions. This gives an agent an exact contract without requiring the complete API description. The [focused-contract reference](https://www.shoalrun.com/api-docs/focused-contracts.md) explains the export and audit checks.
 
-An API catalog, when configured, links a declared endpoint to its description and documentation. This site's example endpoint uses a reserved `.test` domain and does not describe a live service. A contract or catalog entry is a description, not permission to execute an operation.
+An API catalog, when configured, links a declared endpoint to its description and documentation. This site's example endpoint uses a reserved `.test` domain and doesn't describe a live service. A contract or catalog entry is a description, not permission to execute an operation.
 
 ## Use the transport your client supports
 
@@ -158,13 +158,13 @@ The Shoalrun npm package also bundles this framework's own documentation. `shoal
 
 `shoalrun docs mcp` exposes the local search/read core over stdio. You can also [connect to this site’s public HTTP MCP endpoint](https://www.shoalrun.com/connect/mcp.md). The local read tool applies a token budget and can truncate a response; fetch the published twin when you need complete bytes for digest verification. See [the MCP reference](https://www.shoalrun.com/publish/mcp.md) for its current contract.
 
-Shoalrun does not automatically generate a reader skill for every site. Its maintained authoring skills guide an author's existing agent through writing and validation; teams remain responsible for reviewing their instructions. The [non-goals](https://www.shoalrun.com/non-goals.md) explain that boundary.
+Shoalrun doesn't automatically generate a reader skill for every site. Its maintained authoring skills guide an author's existing agent through writing and validation; teams remain responsible for reviewing their instructions. The [non-goals](https://www.shoalrun.com/non-goals.md) explain that boundary.
 
 ## Evidence has a scope
 
-Compiler tests, the example above, and digest checks establish specific behavior. They do not substitute for task evaluation or independent factual review. AFDocs checks also inspect discovery, Markdown availability, and HTTP behavior; parity findings need review because authors can intentionally tailor each format.
+Compiler tests, the example above, and digest checks establish specific behavior. They don't substitute for task evaluation or independent factual review. AFDocs checks also inspect discovery, Markdown availability, and HTTP behavior; parity findings need review because authors can intentionally tailor each format.
 
-A local build and passing Node-host checks do not establish what a production host currently serves. Run the deployment checks against the published origin after releasing a build. The [output reference](https://www.shoalrun.com/publish/output.md) and [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) describe the artifacts and live checks separately.
+A local build and passing Node-host checks don't establish what a production host currently serves. Run the deployment checks against the published origin after releasing a build. The [output reference](https://www.shoalrun.com/publish/output.md) and [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) describe the artifacts and live checks separately.
 
 ## Secret handshake