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

package/agent-docs/publish/mcp.sections/html-markdown-and-agents.md

@@ -0,0 +1,38 @@
+---
+id: guide.mcp
+title: Connect an MCP client
+summary: Connect read-only MCP clients over stdio or HTTP to search and read
+  built documentation.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /publish/mcp
+---
+
+# Connect an MCP client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
+
+**Updated: 2026-11-05.**
+
+Parent page: [Full Markdown page](/publish/mcp.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
+
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+
+You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
+
+## HTML, Markdown, and agents
+
+The website’s native publication dropdown groups rendered releases by product for HTML navigation. Its labels may hide a single language, but the language remains part of every publication coordinate. MCP clients receive those coordinates as structured data instead of operating the dropdown. Page and section tools return the selected publication’s generated Markdown; they don't combine content from another product with the same page ID. Reader-marked sections remain in published Markdown, while customer profile feature exclusions are removed during compilation.

package/agent-docs/publish/mcp.sections/related-reading.md

@@ -17,13 +17,13 @@ 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 > MCP > Connect an MCP client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
-Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
-The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
 
 You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
 

package/agent-docs/publish/mcp.sections/search-then-read.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 > MCP > Connect an MCP client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
@@ -27,9 +27,9 @@ Parent page: [Full Markdown page](/publish/mcp.md)
 
 - [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
 
-Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
-The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
 
 You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
 
@@ -37,17 +37,18 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 
 Ask the client to discover the server's tools. It should find:
 
-| Tool          | Required input  | Optional inputs                                        | Result                                                              |
-| ------------- | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
-| `search_docs` | `query`         | `limit`, `maxTokens`, `channel`, `version`, `language` | Ranked document IDs, links, summaries, and excerpts.                |
-| `get_page`    | `id`            | `maxTokens`, `channel`, `version`, `language`          | The page's generated Markdown and publication metadata.             |
-| `get_outline` | `id`            | `maxTokens`, `channel`, `version`, `language`          | Top-level section IDs, fetch URLs, digests, and sizes.              |
-| `get_section` | `id`, `section` | `maxTokens`, `channel`, `version`, `language`          | One complete section with parent context and nested reader content. |
+| Tool               | Required input  | Optional inputs                                                             | Result                                                                       |
+| ------------------ | --------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `get_publications` | None            | `product`, `channel`, `version`, `language`, `limit`, `offset`, `maxTokens` | A compact page of published coordinates and concise product labels/defaults. |
+| `search_docs`      | `query`         | `limit`, `maxTokens`, `product`, `channel`, `version`, `language`           | Ranked document IDs, links, summaries, and excerpts.                         |
+| `get_page`         | `id`            | `maxTokens`, `product`, `channel`, `version`, `language`                    | The page's generated Markdown and publication metadata.                      |
+| `get_outline`      | `id`            | `maxTokens`, `product`, `channel`, `version`, `language`                    | Top-level section IDs, fetch URLs, digests, and sizes.                       |
+| `get_section`      | `id`, `section` | `maxTokens`, `product`, `channel`, `version`, `language`                    | One complete section with parent context and nested reader content.          |
 
-For example, call `search_docs` with `{"query":"search provider","limit":5,"maxTokens":2048}`, choose a result, and call its `read.tool` with its `read.arguments` exactly. Choose a publication when the index or document ID spans multiple channels, versions, or languages. The server refuses to mix publications.
+For example, call `search_docs` with `{"query":"search provider","limit":5,"maxTokens":2048}`, choose a result, and call its `read.tool` with its `read.arguments` exactly. Choose a publication when the index or document ID spans multiple products, channels, versions, or languages. The server refuses to mix publications.
 
 Search uses the same lexical ranking as the CLI. Titles, summaries, and headings are searchable; article text is bounded. See [search index coverage](https://www.shoalrun.com/author/search.md). The page tool returns generated Markdown, including all reader-marked sections. Reader views remain visibility controls, not access controls.
 
-Search supplies the next call: `read.tool` is `get_section` for a unique matching section, or `get_page` otherwise. Its arguments include the ID, publication, section ID when needed, and a token budget based on the indexed size. Do not guess section IDs or call `get_outline` first. Check `budget.truncated` after a page read and increase the budget if needed.
+Search supplies the next call: `read.tool` is `get_section` for a unique matching section, or `get_page` otherwise. Its arguments include the ID, publication, section ID when needed, and a token budget based on the indexed size. Don't guess section IDs or call `get_outline` first. Check `budget.truncated` after a page read and increase the budget if needed.
 
-The result's `markdownUrl` fetches the recommended content directly; `pageMarkdownUrl` always fetches the full page. Use the full page when the section does not answer the question or needs more context. Search prefers the full page for short documents, broad queries, ambiguous headings, or queries spanning multiple sections. Search normally prefers complete lexical matches. With no complete match, results within one meaningful term of the best coverage (at least two matched terms) rank by non-filler field score first. A stronger result missing one meaningful term can outrank complete matches found only in body text; `matchMode: mixed` identifies that case. See [search ranking](https://www.shoalrun.com/author/search.md). A section recommendation also requires an explicit author declaration that its content and repeated introduction are self-contained. Undeclared sections use full-page reads, including indexes built before this declaration existed. The compiler checks heading identity, not prerequisite completeness. `get_outline` remains available for deliberate browsing. Retain publication coordinates and parent/section digests for citations. See [section resources](https://www.shoalrun.com/author/markdown-metadata.md).
+The result's `markdownUrl` fetches the recommended content directly; `pageMarkdownUrl` always fetches the full page. Use the full page when the section doesn't answer the question or needs more context. Search prefers the full page for short documents, broad queries, ambiguous headings, or queries spanning multiple sections. Search normally prefers complete lexical matches. With no complete match, results within one meaningful term of the best coverage (at least two matched terms) rank by non-filler field score first. A stronger result missing one meaningful term can outrank complete matches found only in body text; `matchMode: mixed` identifies that case. See [search ranking](https://www.shoalrun.com/author/search.md). A section recommendation also requires an explicit author declaration that its content and repeated introduction are self-contained. Undeclared sections use full-page reads, including indexes built before this declaration existed. The compiler checks heading identity, not prerequisite completeness. `get_outline` remains available for deliberate browsing. Retain publication coordinates and parent/section digests for citations. See [section resources](https://www.shoalrun.com/author/markdown-metadata.md).

package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.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 > MCP > Connect an MCP client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
@@ -27,15 +27,15 @@ Parent page: [Full Markdown page](/publish/mcp.md)
 
 - [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
 
-Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
-The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
 
 You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
 
 ## Serve a public endpoint on Node
 
-Use this procedure when agents should connect to a URL instead of launching the CLI themselves. Analytics is not enabled by this setting.
+Use this procedure when agents should connect to a URL instead of launching the CLI themselves. Analytics isn't enabled by this setting.
 
 1. ### Enable a public publication
 
@@ -49,6 +49,10 @@ Use this procedure when agents should connect to a URL instead of launching the
      publication: { channel: production, version: current, language: en }
    ```
 
+   Since 0.1.0-alpha.18
+
+   Add `product` to `mcp.publication` for a product release, for example `{ product: payments, channel: production, version: v3, language: en }`. Hosting remains restricted to one configured publication; adding product support doesn't open every product in the build.
+
    The endpoint supplies those publication coordinates when the client omits them. Requests for a different publication are rejected. Its lexical search index is generated even if browser search is disabled.
 
 2. ### Build and serve the site
@@ -60,20 +64,20 @@ Use this procedure when agents should connect to a URL instead of launching the
    shoalrun serve dist --port 8774
    ```
 
-   The server reads the MCP settings from that build. It does not need the source config. With no site base path, the local endpoint is `http://127.0.0.1:8774/mcp`; a base path such as `/docs` makes it `/docs/mcp`.
+   The server reads the MCP settings from that build. It doesn't need the source config. With no site base path, the local endpoint is `http://127.0.0.1:8774/mcp`; a base path such as `/docs` makes it `/docs/mcp`.
 
    Set `mcp: false` or remove the setting and rebuild to disable the endpoint. Restart a non-watching server after replacing its build; watched preview reloads settings with each successful build.
 
 3. ### Connect and check the tools
 
-   Add the endpoint URL in your client’s remote MCP settings. The client should discover the four tools listed below. Search for a known page, then follow the returned read instruction and verify its publication.
+   Add the endpoint URL in your client’s remote MCP settings. The client should discover the tools listed below for its installed release. Search for a known page, then follow the returned read instruction and verify its publication.
 
    The SDK integration is tested with legacy and automatic protocol negotiation using MCP TypeScript client version `2.2.0`. Compatibility with a specific desktop client or public host still needs its own check.
 
 ### Hosts, origins, and limits
 
-Local connections permit the configured loopback host. For a public Node deployment, `site.origin` supplies a trusted hostname and browser origin. Add explicit `mcp.allowedHosts` hostnames for other domains and `mcp.allowedOrigins` origins for browser-based clients. Forwarded host headers are not trusted. Native clients do not need an Origin header.
+Local connections permit the configured loopback host. For a public Node deployment, `site.origin` supplies a trusted hostname and browser origin. Add explicit `mcp.allowedHosts` hostnames for other domains and `mcp.allowedOrigins` origins for browser-based clients. Forwarded host headers aren't trusted. Native clients don't need an Origin header.
 
-The endpoint accepts JSON MCP requests through POST; it does not provide a persistent session or standalone event stream. GET and DELETE return 405. Browser preflight uses OPTIONS.
+The endpoint accepts JSON MCP requests through POST; it doesn't provide a persistent session or standalone event stream. GET and DELETE return 405. Browser preflight uses OPTIONS.
 
 Limits are 64 KiB per request, eight concurrent requests per handler, and a 15-second deadline. Excess concurrent requests return 429 with retry guidance. Tool token budgets still apply. These are process-local controls; configure deployment-level limits before exposing a public service. This is a public endpoint, not an authentication mechanism for private documentation.

package/agent-docs/publish/mcp.sections/verify-the-connection.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 > MCP > Connect an MCP client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
@@ -27,9 +27,9 @@ Parent page: [Full Markdown page](/publish/mcp.md)
 
 - [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
 
-Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
-The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
 
 You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
 
@@ -37,4 +37,4 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 
 Search for a known page, read the returned ID, and inspect its Markdown. Then request a nonexistent ID: it should return `unknown_page` without stopping the server. Confirm that a small budget sets `truncated` on a long page. These checks exercise the source selection and tool contract without an agent harness.
 
-The tools are read-only and do not expose authoring commands. Stdio makes them available to a local tool-capable client; clients that cannot launch a local process cannot use this transport. They can read published Markdown over HTTP when their tools support fetching URLs. Stdio has no analytics adapter. The optional HTTP adapter records tool outcomes without raw queries.
+The tools are read-only and don't expose authoring commands. Stdio makes them available to a local tool-capable client; clients that can't launch a local process can't use this transport. They can read published Markdown over HTTP when their tools support fetching URLs. Stdio has no analytics adapter. The optional HTTP adapter records tool outcomes without raw queries.

package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.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 > MCP > Connect an MCP client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
@@ -27,9 +27,9 @@ Parent page: [Full Markdown page](/publish/mcp.md)
 
 - [Measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) — Optionally measure tool calls through a server adapter.
 
-Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
+Connect an MCP client to built documentation through read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
-The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters are not implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
+The HTTP endpoint currently supports one explicitly selected public publication. The generated Vercel endpoint is deployed and verified on this site. Netlify and Cloudflare adapters aren't implemented. Analytics is off by default; an optional [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md) can measure tool calls.
 
 You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that supports MCP stdio or Streamable HTTP. Follow [Getting started](https://www.shoalrun.com/start.md) to install the public npm package.
 
@@ -37,6 +37,6 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 
 MCP gives tool-capable agents a predictable way to search your docs and request a page or section within a token budget. For example, an agent answering “How do I configure analytics?” can search and follow the returned read instruction. The result includes relevant Markdown, its publication, and a source link.
 
-The documentation can already be public. MCP adds a tool interface; it does not grant access that public Markdown lacks. Agents that can fetch and search your Markdown may not need it. Offer both when your readers use MCP clients, and check whether the tools help them find answers with fewer requests or less content.
+The documentation can already be public. MCP adds a tool interface; it doesn't grant access that public Markdown lacks. Agents that can fetch and search your Markdown may not need it. Offer both when your readers use MCP clients, and check whether the tools help them find answers with fewer requests or less content.
 
 To use Shoalrun's own live documentation endpoint, follow [use this site's MCP](https://www.shoalrun.com/connect/mcp.md). The setup below is for hosting your own project's tools.

package/agent-docs/publish/openapi-extension-mappings.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > OpenAPI extension mappings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 OpenAPI permits [specification extensions](https://spec.openapis.org/oas/v3.1.0#specification-extensions) whose names begin with `x-`. Their names and values belong to the tool or team that wrote the description. Shoalrun reads standard OpenAPI fields directly and applies an extension only when the project config explicitly maps it to a supported Shoalrun field.
 
@@ -29,7 +29,7 @@ Use these source locations and value shapes when mapping OpenAPI extensions to S
 | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
 | `subjectLifecycle` | An operation under `paths` or OpenAPI 3.1 `webhooks` | A scalar `x-*` value, or a scalar member inside an `x-*` object | `beta`, `in-development`, `experimental`, `deprecated` |
 
-Use `apis.<apiId>.mappings.subjectLifecycle`. `from` starts with an operation-level `x-*` key. For an object, add a dot and the member name; further simple member names may follow. `values` maps exact source values to Shoalrun values. Unlisted, missing, null, array, or object values do not set a badge.
+Use `apis.<apiId>.mappings.subjectLifecycle`. `from` starts with an operation-level `x-*` key. For an object, add a dot and the member name; further simple member names may follow. `values` maps exact source values to Shoalrun values. Unlisted, missing, null, array, or object values don't set a badge.
 
 For example, this fictional OpenAPI operation uses an object-shaped extension:
 
@@ -68,17 +68,17 @@ An authored reference page's `subjectLifecycle` takes precedence over the mappin
 
 Extensions outside the supported mapping may need source changes or a different Shoalrun feature.
 
-| Source extension purpose              | Current Shoalrun behavior | Use in Shoalrun today                                                                                                                                                                   |
-| ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tag names and tag groups              | No automatic mapping      | Use OpenAPI `tags` for generated groups and [navigation config](https://www.shoalrun.com/author/navigation.md) for editorial grouping and MDX pages.                                    |
-| Custom code samples                   | No automatic mapping      | Add an authored MDX example or reusable snippet; standard OpenAPI request and response examples still appear automatically.                                                             |
-| Enum labels or descriptions           | No automatic mapping      | Standard `enum` values appear in schemas. Put explanatory prose in a schema or field `description`.                                                                                     |
-| Hide or internal flags                | No automatic mapping      | Select public operations with `generateReferences.include` or explicit `operations`; set page access in authored frontmatter. Do not rely on an unrecognized extension to hide content. |
-| Explorer settings and SDK naming      | No automatic mapping      | Shoalrun does not execute API requests. Keep SDK-specific settings in their owning tool.                                                                                                |
-| Webhook markers in older descriptions | No automatic mapping      | Describe inbound events with OpenAPI 3.1 `webhooks`.                                                                                                                                    |
+| Source extension purpose              | Current Shoalrun behavior | Use in Shoalrun today                                                                                                                                                                  |
+| ------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tag names and tag groups              | No automatic mapping      | Use OpenAPI `tags` for generated groups and [navigation config](https://www.shoalrun.com/author/navigation.md) for editorial grouping and MDX pages.                                   |
+| Custom code samples                   | No automatic mapping      | Add an authored MDX example or reusable snippet; standard OpenAPI request and response examples still appear automatically.                                                            |
+| Enum labels or descriptions           | No automatic mapping      | Standard `enum` values appear in schemas. Put explanatory prose in a schema or field `description`.                                                                                    |
+| Hide or internal flags                | No automatic mapping      | Select public operations with `generateReferences.include` or explicit `operations`; set page access in authored frontmatter. Don't rely on an unrecognized extension to hide content. |
+| Explorer settings and SDK naming      | No automatic mapping      | Shoalrun doesn't execute API requests. Keep SDK-specific settings in their owning tool.                                                                                                |
+| Webhook markers in older descriptions | No automatic mapping      | Describe inbound events with OpenAPI 3.1 `webhooks`.                                                                                                                                   |
 
-An unmapped `x-*` value does not change the rendered reference. A focused contract omits extension properties while retaining literal example payload keys, even when those keys begin with `x-`. A full OpenAPI download enabled by `source.publish: true` contains the source file as authored, including its extensions. Review that file before publishing it.
+An unmapped `x-*` value doesn't change the rendered reference. A focused contract omits extension properties while retaining literal example payload keys, even when those keys begin with `x-`. A full OpenAPI download enabled by `source.publish: true` contains the source file as authored, including its extensions. Review that file before publishing it.
 
 ## Choosing a new mapping target
 
-The target list above is intentionally small. An extension can describe presentation, visibility, SDK behavior, or actual wire semantics, and identical names do not guarantee identical shapes. When adding a target, define its source location, accepted value shapes, Shoalrun output, precedence over authored metadata and standard OpenAPI, and behavior for unknown values. Keep the source name configurable so projects can adapt descriptions from different tools without baking a vendor vocabulary into Shoalrun.
+The target list above is intentionally small. An extension can describe presentation, visibility, SDK behavior, or actual wire semantics, and identical names don't guarantee identical shapes. When adding a target, define its source location, accepted value shapes, Shoalrun output, precedence over authored metadata and standard OpenAPI, and behavior for unknown values. Keep the source name configurable so projects can adapt descriptions from different tools without baking a vendor vocabulary into Shoalrun.

package/agent-docs/publish/output.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 `shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
 
@@ -27,11 +27,11 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Published-output contract
 
-This page is the consumer reference for Shoalrun's current published output. It describes the existing producer, not a general format that other generators must implement. The manifest and sync snapshot use `schemaVersion: 1`. Editorial revisions to this reference do not change that wire version.
+This page is the consumer reference for Shoalrun's current published output. It describes the existing producer, not a general format that other generators must implement. The manifest and sync snapshot use `schemaVersion: 1`. Editorial revisions to this reference don't change that wire version.
 
-The repository maintains JSON Schema 2020-12 definitions at `framework/schemas/manifest.schema.json` and `framework/schemas/sync.schema.json`. They specify required fields and known value shapes; this reference explains their meaning. Schema identifiers are stable names for local resolution, not a promise that a site hosts the schema files. Register both schemas together when validating a sync snapshot. They remain repository validation resources and are not added to site output.
+The repository maintains JSON Schema 2020-12 definitions at `framework/schemas/manifest.schema.json` and `framework/schemas/sync.schema.json`. They specify required fields and known value shapes; this reference explains their meaning. Schema identifiers are stable names for local resolution, not a promise that a site hosts the schema files. Register both schemas together when validating a sync snapshot. They remain repository validation resources and aren't added to site output.
 
-Consumers must tolerate unknown properties. Optional fields may be absent; absence is not evidence of a negative claim. Removing a required field, changing a field's meaning, or making existing valid output incompatible requires a new wire version. Adding optional fields can retain version 1. Changes to a constrained value set also need compatibility review; accepting unknown properties does not mean a consumer accepts unknown enum values.
+Consumers must tolerate unknown properties. Optional fields may be absent; absence isn't evidence of a negative claim. Removing a required field, changing a field's meaning, or making existing valid output incompatible requires a new wire version. Adding optional fields can retain version 1. Changes to a constrained value set also need compatibility review; accepting unknown properties doesn't mean a consumer accepts unknown enum values.
 
 | Capability                                                                                                        | Availability                                                                                        |
 | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
@@ -47,11 +47,11 @@ Routes include the configured base path and publication prefixes. Start at `llms
 
 A document's identity is `(id, channel, version, language)`, not its title, URL, or array position. The same ID in two publications identifies two records. That tuple must be unique in both the manifest and sync snapshot. Cite it with the resource URL; for sections, also retain section identity and parent/section digests. A manifest array pointer is a link into that snapshot, not a permanent document identifier.
 
-`indexable` describes indexing, not access. `demo: false` means unmarked, not a verified service. Missing or null `subjectLifecycle` does not mean stable. `verified` is an author's review date, not compiler or independent verification. `updated` records content freshness and can be a calendar date or a timestamp with a timezone. Reader filters control presentation, not authorization.
+`indexable` describes indexing, not access. `demo: false` means unmarked, not a verified service. Missing or null `subjectLifecycle` doesn't mean stable. `verified` is an author's review date, not compiler or independent verification. `updated` records content freshness and can be a calendar date or a timestamp with a timezone. Reader filters control presentation, not authorization.
 
 ## Page formats
 
-Both formats come from the same parsed content. Supported components preserve their documented shared content in Markdown: tab choices, disclosure bodies, reader-marked branches, table rows, resolved snippets, and API examples retain readable content and relevant labels. Unknown components and unsupported dynamic MDX fail compilation. Explicit format-specific branches follow author selection; authors must review equivalent task guidance and completeness. Rendering checks do not prove semantic equivalence or that a reader has every prerequisite. [Tabs](https://www.shoalrun.com/author/components/tabs.md) become labeled sections in Markdown. [OpenAPI examples and schemas](https://www.shoalrun.com/author/components/api-embeds.md) are expanded during the build, so their values and field details appear as readable text in the twin. A [filtered or sticky table](https://www.shoalrun.com/author/components/tables.md) keeps every row as a plain table in Markdown.
+Both formats come from the same parsed content. Supported components preserve their documented shared content in Markdown: tab choices, disclosure bodies, reader-marked branches, table rows, resolved snippets, and API examples retain readable content and relevant labels. Unknown components and unsupported dynamic MDX fail compilation. Explicit format-specific branches follow author selection; authors must review equivalent task guidance and completeness. Rendering checks don't prove semantic equivalence or that a reader has every prerequisite. [Tabs](https://www.shoalrun.com/author/components/tabs.md) become labeled sections in Markdown. [OpenAPI examples and schemas](https://www.shoalrun.com/author/components/api-embeds.md) are expanded during the build, so their values and field details appear as readable text in the twin. A [filtered or sticky table](https://www.shoalrun.com/author/components/tables.md) keeps every row as a plain table in Markdown.
 
 Write links in page content as `doc:` IDs, site paths, or relative paths such as `[Next](./next)` and `[Overview](../overview)`. Shoalrun resolves relative paths against the current page's published route. For a page at `/guides/setup`, `./next` resolves to `/guides/next`. HTML links use site paths, so local previews stay local; links to known pages in Markdown twins point to their `.md` routes. Set `site.origin` to publish full HTTPS links in Markdown twins and `/llms.txt`, so a fetched Markdown page keeps working outside the site's browser context. Fragment-only links such as `#options` stay local to the page. Explicit external URLs keep their original host.
 
@@ -63,7 +63,7 @@ See [agent-friendly documentation](https://www.shoalrun.com/publish/agent-friend
 
 ## Where files go
 
-`shoalrun build <config> <output>` writes the site to the output directory. It builds in a temporary directory, then **deletes the output directory and replaces it**, so point it at a directory that holds only build output. To protect other folders, it replaces a directory only when it is new, empty, or an earlier build. Otherwise the build stops before deleting anything.
+`shoalrun build <config> <output>` writes the site to the output directory. It builds in a temporary directory, then **deletes the output directory and replaces it**, so point it at a directory that holds only build output. To protect other folders, it replaces a directory only when it's new, empty, or an earlier build. Otherwise the build stops before deleting anything.
 
 | Output                     | Path                                                                                                                                  |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -74,15 +74,15 @@ See [agent-friendly documentation](https://www.shoalrun.com/publish/agent-friend
 | Published OpenAPI source   | `/api/<apiId>/<channel>/<version>/<file>`, plus the local files it references                                                         |
 | Focused contracts          | `/api/operations/<channel>/<version>/<language>/<name>-<hash>.json`                                                                   |
 
-The `/api` and `/.well-known` paths are reserved for these files, so page slugs cannot use them. A [diagram](https://www.shoalrun.com/author/components/diagrams.md) in the Markdown twin keeps its title, summary, a link to the light SVG, and its fenced source.
+The `/api` and `/.well-known` paths are reserved for these files, so page slugs can't use them. A [diagram](https://www.shoalrun.com/author/components/diagrams.md) in the Markdown twin keeps its title, summary, a link to the light SVG, and its fenced source.
 
 ## Site files
 
-- `documents.json` is the document manifest. Its top-level keys are `schemaVersion`, `buildId`, `configDigest`, `dependencies`, `documents`, `operations`, `relationships`, `redirects`, and `apiSources`. Each entry in `documents` describes one page variant. `contentDigest` fingerprints resolved article content for freshness; `digest` is the SHA-256 of the complete generated Markdown bytes. Use `digest` to check a fetched Markdown twin for changes, and pair the stable ID with its publication variant when comparing records. A page with an author-set `verified` date exposes it independently of `updated`. It has the stable ID, type, title, summary, subjectLifecycle, publication variant, and HTML and Markdown URLs. Optional `subjectDeprecation` carries author-declared `deprecatedOn` and `sunsetOn` dates and resolved `replacement` and `migration` targets, each with `id`, `title`, `url`, and `markdownUrl`. A changelog entry can also expose optional `change` with an author-declared `kind`, an `affects` target list, and a `migration` target when supplied. Change targets use the same `id`, `title`, `url`, and `markdownUrl` shape; absence means unclassified. Deprecation guidance appears in HTML, full Markdown, and section Markdown; it describes the subject rather than retirement of the documentation resource. Every record has a boolean `demo`, set from `outputs.llms.fictionalPrefixes`. A true value identifies an author-declared fictional example. False means unmarked; it does not verify that an API is live. The full and compact search indexes carry the same flag. Optional `product`, `area`, and `subarea` categories appear when set. It also lists card targets and queries, snippet and API embed uses, focused contract details, and a content digest. When reader views are configured, the manifest also has top-level `readerFacets` and a resolved `readerFilters` map on each page. An empty map means the page is shared. `dependencies` lists the source files the build read, without local paths. Project files are relative to `docs.config.yaml`, framework files start with `shoalrun:`, and installed packages start with `package:`.
+- `documents.json` is the document manifest. Its top-level keys are `schemaVersion`, `buildId`, `configDigest`, `dependencies`, `documents`, `operations`, `relationships`, `redirects`, and `apiSources`. Each entry in `documents` describes one page variant. `contentDigest` fingerprints resolved article content for freshness; `digest` is the SHA-256 of the complete generated Markdown bytes. Use `digest` to check a fetched Markdown twin for changes, and pair the stable ID with its publication variant when comparing records. A page with an author-set `verified` date exposes it independently of `updated`. It has the stable ID, type, title, summary, subjectLifecycle, publication variant, and HTML and Markdown URLs. Optional `subjectDeprecation` carries author-declared `deprecatedOn` and `sunsetOn` dates and resolved `replacement` and `migration` targets, each with `id`, `title`, `url`, and `markdownUrl`. A changelog entry can also expose optional `change` with an author-declared `kind`, an `affects` target list, and a `migration` target when supplied. Change targets use the same `id`, `title`, `url`, and `markdownUrl` shape; absence means unclassified. Deprecation guidance appears in HTML, full Markdown, and section Markdown; it describes the subject rather than retirement of the documentation resource. Every record has a boolean `demo`, set from `outputs.llms.fictionalPrefixes`. A true value identifies an author-declared fictional example. False means unmarked; it doesn't verify that an API is live. The full and compact search indexes carry the same flag. Optional `product`, `area`, and `subarea` categories appear when set. It also lists card targets and queries, snippet and API embed uses, focused contract details, and a content digest. When reader views are configured, the manifest also has top-level `readerFacets` and a resolved `readerFilters` map on each page. An empty map means the page is shared. `dependencies` lists the source files the build read, without local paths. Project files are relative to `docs.config.yaml`, framework files start with `shoalrun:`, and installed packages start with `package:`.
 
 - `documents.sync.json` contains the build ID and compact page signatures for comparing saved snapshots. See **Incremental sync** below.
 
-- `build-info.json` records the build ID, resolved config digest and, when supplied by the build command, the source commit and release label. It is public build provenance, not a version archive. See [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
+- `build-info.json` records the build ID, resolved config digest and, when supplied by the build command, the source commit and release label. It's public build provenance, not a version archive. See [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
 
 - `404.html` and `404.md` provide concise recovery links for missing pages. Node serving and Vercel routing preserve HTTP `404`; another static host needs an error-page rule. These files are omitted from the document manifest, sitemap, and search index.
 
@@ -94,15 +94,15 @@ The `/api` and `/.well-known` paths are reserved for these files, so page slugs
 
 - `llms.min.txt` is the compact starting point for agents. Small sites list page variants directly; larger sites link to topic indexes grouped by publication and primary taxonomy area, or page type when no area is declared. Growing topics split automatically. Each index stays within 2,000 `cl100k_base` tokens. Page entries retain stable IDs, titles, summaries, Markdown URLs, and fictional-example labels. Follow index links until you reach a matching page. All published pages remain reachable, including pages outside navigation; the complete catalog and search index remain optional.
 
-- `search-index.min.json` adds page headings to titles, summaries, IDs, types, publication variants, and URLs. It omits article text and reader segments. It is generated whenever the full search index is enabled. Both are static files, not query endpoints.
+- `search-index.min.json` adds page headings to titles, summaries, IDs, types, publication variants, and URLs. It omits article text and reader segments. It's generated whenever the full search index is enabled. Both are static files, not query endpoints.
 
 - `search-index.json` lists page IDs, HTML and Markdown URLs, titles, summaries, headings, and text for the [search box](https://www.shoalrun.com/author/search.md) and local search command. The default lexical provider needs it; a custom provider can opt in.
 
 - `/assets/search-provider.js` is the search provider module, built-in or custom.
 
-When `site.origin` is set and indexing is enabled, the build writes `/sitemap.xml` with canonical HTML page URLs, `/llms.txt`, and optional page `lastmod` values. Markdown twins are alternate representations; their HTTP `Link` header names the HTML page as canonical. They are omitted from the sitemap. `/robots.txt` advertises it. Both derive from the same published pages as `documents.json`; `seo.noindex` pages are omitted. Large sitemaps are split into direct child URL sitemaps under a single index. The manifest records `sitemap`, and each document records `indexable` and optional `updated`.
+When `site.origin` is set and indexing is enabled, the build writes `/sitemap.xml` with canonical HTML page URLs, `/llms.txt`, and optional page `lastmod` values. Markdown twins are alternate representations; their HTTP `Link` header names the HTML page as canonical. They're omitted from the sitemap. `/robots.txt` advertises it. Both derive from the same published pages as `documents.json`; `seo.noindex` pages are omitted. Large sitemaps are split into direct child URL sitemaps under a single index. The manifest records `sitemap`, and each document records `indexable` and optional `updated`.
 
-The local frontmatter inventory and JSON Schema are build outputs in `.shoalrun/` beside `docs.config.yaml`. They are available to authors and agents in the repository. A site can also publish its current field inventory on an authored page with `<FrontmatterReference />`, as [this documentation site does](https://www.shoalrun.com/author/frontmatter-reference.md).
+The local frontmatter inventory and JSON Schema are build outputs in `.shoalrun/` beside `docs.config.yaml`. They're available to authors and agents in the repository. A site can also publish its current field inventory on an authored page with `<FrontmatterReference />`, as [this documentation site does](https://www.shoalrun.com/author/frontmatter-reference.md).
 
 After publishing, run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) against the live origin to verify the host serves these formats and discovery files with the expected response headers.
 
@@ -114,9 +114,9 @@ Every document record includes identity, publication, title, summary, page type,
 
 Each record has a `sections` array, possibly empty. Each section has `id`, `title`, `depth: 2`, `markdownUrl`, `parentMarkdownUrl`, `parentDigest`, `digest`, and the three size/token fields. `standalone` is present as `true` only for an explicit author declaration. Its absence means no such declaration, not that a section has been proved incomplete.
 
-Section files preserve the parent preamble, nested reader content, and applicable page reading paths. Generation requires a parent of at least 2,000 tokens and a section no larger than half the parent in both tokens and bytes. An empty array does not imply a page has no headings. Heading-derived IDs can change after renaming, insertion, or reordering; there are no permanent section IDs or automatic section redirects. See [section retrieval and citations](https://www.shoalrun.com/author/markdown-metadata.md) for the exact policy and full-page fallback.
+Section files preserve the parent preamble, nested reader content, and applicable page reading paths. Generation requires a parent of at least 2,000 tokens and a section no larger than half the parent in both tokens and bytes. An empty array doesn't imply a page has no headings. Heading-derived IDs can change after renaming, insertion, or reordering; there are no permanent section IDs or automatic section redirects. See [section retrieval and citations](https://www.shoalrun.com/author/markdown-metadata.md) for the exact policy and full-page fallback.
 
-Optional `subjectDeprecation` requires a deprecated subject and contains supplied dates or resolved replacement/migration targets. It does not require every deprecated subject to have dates or a replacement. Optional `change` requires a changelog entry, one of `editorial`, `procedure`, `behavior`, or `breaking`, a nonempty unique affected-ID list, and an optional migration target. Published targets include `id`, `title`, `url`, and `markdownUrl`, resolved to other public documents in the same publication. The build checks references and dates; it does not verify authored classification or retirement. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and [release notes](https://www.shoalrun.com/author/release-notes.md).
+Optional `subjectDeprecation` requires a deprecated subject and contains supplied dates or resolved replacement/migration targets. It doesn't require every deprecated subject to have dates or a replacement. Optional `change` requires a changelog entry, one of `editorial`, `procedure`, `behavior`, or `breaking`, a nonempty unique affected-ID list, and an optional migration target. Published targets include `id`, `title`, `url`, and `markdownUrl`, resolved to other public documents in the same publication. The build checks references and dates; it doesn't verify authored classification or retirement. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and [release notes](https://www.shoalrun.com/author/release-notes.md).
 
 ## Navigation section indexes
 
@@ -132,7 +132,7 @@ Markdown responses link to their current manifest array entry with `rel="describ
 
 ## Incremental sync
 
-`buildId` is a SHA-256 fingerprint of the assembled publication: HTML, Markdown, contracts, assets, and metadata. The compiler hashes route names and bytes in sorted route order before adding the build ID stamps and derived sync snapshot. Identical assembled output produces the same ID. A page edit changes it even when `configDigest` stays the same. Changing an asset or supplied release label also changes it. This identity does not promise byte-identical rendering across platforms.
+`buildId` is a SHA-256 fingerprint of the assembled publication: HTML, Markdown, contracts, assets, and metadata. The compiler hashes route names and bytes in sorted route order before adding the build ID stamps and derived sync snapshot. Identical assembled output produces the same ID. A page edit changes it even when `configDigest` stays the same. Changing an asset or supplied release label also changes it. This identity doesn't promise byte-identical rendering across platforms.
 
 `documents.json`, `build-info.json`, and `documents.sync.json` carry the same build ID. The sync snapshot contains one record per stable ID and publication variant:
 
@@ -144,7 +144,7 @@ Markdown responses link to their current manifest array entry with `rel="describ
 | `contentDigest`      | Resolved content fingerprint used for freshness.                       |
 | `recordDigest`       | SHA-256 of the canonical JSON manifest record, including its metadata. |
 
-`contentDigest` is an opaque resolved-content change token, not a Markdown byte hash or a semantic-change classification. `recordDigest` hashes the full manifest record, not the smaller sync record. Do not reconstruct it from the sync fields alone. `buildId` is also opaque to consumers: hashing the final output directory does not reproduce the pre-stamp build calculation.
+`contentDigest` is an opaque resolved-content change token, not a Markdown byte hash or a semantic-change classification. `recordDigest` hashes the full manifest record, not the smaller sync record. Don't reconstruct it from the sync fields alone. `buildId` is also opaque to consumers: hashing the final output directory doesn't reproduce the pre-stamp build calculation.
 
 The snapshot's top-level `metadataDigest` covers manifest fields outside the document records, excluding build ID and dependency paths. A changed value tells a client to refresh the full manifest if it needs relationships, operations, redirects, or other global metadata. Canonical JSON sorts object keys and preserves array order.
 
@@ -163,11 +163,11 @@ shoalrun docs changes current-sync.json --since previous-sync.json
 
 It returns `fromBuildId`, `buildId`, `buildChanged`, `metadataChanged`, and `added`, `changed`, and `removed` record arrays. A route move is a change; a removed publication variant is a removal. Metadata-only page changes also appear in `changed`, even if the Markdown digest is unchanged. Asset-only changes can change the build ID with empty page arrays.
 
-These are static files. The host retains no snapshot history and does not interpret `documents.json?since=...`. Clients retain their own baseline. Without one, use the current snapshot as a full initial inventory. A build ID identifies output; it does not archive earlier page bytes or record a build timestamp.
+These are static files. The host retains no snapshot history and doesn't interpret `documents.json?since=...`. Clients retain their own baseline. Without one, use the current snapshot as a full initial inventory. A build ID identifies output; it doesn't archive earlier page bytes or record a build timestamp.
 
 ## Validate an existing build locally
 
-This checker belongs to Shoalrun’s documentation repository; it is not an installed CLI command. From that repository with its dependencies installed, run:
+This checker belongs to Shoalrun’s documentation repository; it isn't an installed CLI command. From that repository with its dependencies installed, run:
 
 ```sh
 node scripts/check-output-contract.mjs docs/dist
@@ -177,7 +177,7 @@ Replace `docs/dist` with an already-built site's directory. The checker loads bo
 
 The report has `status`, `findings`, and document/section counts. A failure exits nonzero. The command never rebuilds, writes output, evaluates model tasks, or checks live hosting. The existing repository built-site check includes this check, so run either path rather than duplicating it for unchanged output. Use the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) separately for HTTP behavior.
 
-Passing checks establish the specified structure and consistency, not authored truth, semantic completeness, or a fresh evaluation grade. The build identity is compared across files, not recomputed from final stamped artifacts. This contract does not add `llms-full.txt`, a public evaluation report, signatures, or an offline release archive.
+Passing checks establish the specified structure and consistency, not authored truth, semantic completeness, or a fresh evaluation grade. The build identity is compared across files, not recomputed from final stamped artifacts. This contract doesn't add `llms-full.txt`, a public evaluation report, signatures, or an offline release archive.
 
 ## API contracts
 

package/agent-docs/publish/output.sections/api-contracts.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/code-highlighting.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/current-limits.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/incremental-sync.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,7 +35,7 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Incremental sync
 
-`buildId` is a SHA-256 fingerprint of the assembled publication: HTML, Markdown, contracts, assets, and metadata. The compiler hashes route names and bytes in sorted route order before adding the build ID stamps and derived sync snapshot. Identical assembled output produces the same ID. A page edit changes it even when `configDigest` stays the same. Changing an asset or supplied release label also changes it. This identity does not promise byte-identical rendering across platforms.
+`buildId` is a SHA-256 fingerprint of the assembled publication: HTML, Markdown, contracts, assets, and metadata. The compiler hashes route names and bytes in sorted route order before adding the build ID stamps and derived sync snapshot. Identical assembled output produces the same ID. A page edit changes it even when `configDigest` stays the same. Changing an asset or supplied release label also changes it. This identity doesn't promise byte-identical rendering across platforms.
 
 `documents.json`, `build-info.json`, and `documents.sync.json` carry the same build ID. The sync snapshot contains one record per stable ID and publication variant:
 
@@ -47,7 +47,7 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 | `contentDigest`      | Resolved content fingerprint used for freshness.                       |
 | `recordDigest`       | SHA-256 of the canonical JSON manifest record, including its metadata. |
 
-`contentDigest` is an opaque resolved-content change token, not a Markdown byte hash or a semantic-change classification. `recordDigest` hashes the full manifest record, not the smaller sync record. Do not reconstruct it from the sync fields alone. `buildId` is also opaque to consumers: hashing the final output directory does not reproduce the pre-stamp build calculation.
+`contentDigest` is an opaque resolved-content change token, not a Markdown byte hash or a semantic-change classification. `recordDigest` hashes the full manifest record, not the smaller sync record. Don't reconstruct it from the sync fields alone. `buildId` is also opaque to consumers: hashing the final output directory doesn't reproduce the pre-stamp build calculation.
 
 The snapshot's top-level `metadataDigest` covers manifest fields outside the document records, excluding build ID and dependency paths. A changed value tells a client to refresh the full manifest if it needs relationships, operations, redirects, or other global metadata. Canonical JSON sorts object keys and preserves array order.
 
@@ -66,4 +66,4 @@ shoalrun docs changes current-sync.json --since previous-sync.json
 
 It returns `fromBuildId`, `buildId`, `buildChanged`, `metadataChanged`, and `added`, `changed`, and `removed` record arrays. A route move is a change; a removed publication variant is a removal. Metadata-only page changes also appear in `changed`, even if the Markdown digest is unchanged. Asset-only changes can change the build ID with empty page arrays.
 
-These are static files. The host retains no snapshot history and does not interpret `documents.json?since=...`. Clients retain their own baseline. Without one, use the current snapshot as a full initial inventory. A build ID identifies output; it does not archive earlier page bytes or record a build timestamp.
+These are static files. The host retains no snapshot history and doesn't interpret `documents.json?since=...`. Clients retain their own baseline. Without one, use the current snapshot as a full initial inventory. A build ID identifies output; it doesn't archive earlier page bytes or record a build timestamp.

package/agent-docs/publish/output.sections/manifest-records-and-sections.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -41,6 +41,6 @@ Every document record includes identity, publication, title, summary, page type,
 
 Each record has a `sections` array, possibly empty. Each section has `id`, `title`, `depth: 2`, `markdownUrl`, `parentMarkdownUrl`, `parentDigest`, `digest`, and the three size/token fields. `standalone` is present as `true` only for an explicit author declaration. Its absence means no such declaration, not that a section has been proved incomplete.
 
-Section files preserve the parent preamble, nested reader content, and applicable page reading paths. Generation requires a parent of at least 2,000 tokens and a section no larger than half the parent in both tokens and bytes. An empty array does not imply a page has no headings. Heading-derived IDs can change after renaming, insertion, or reordering; there are no permanent section IDs or automatic section redirects. See [section retrieval and citations](https://www.shoalrun.com/author/markdown-metadata.md) for the exact policy and full-page fallback.
+Section files preserve the parent preamble, nested reader content, and applicable page reading paths. Generation requires a parent of at least 2,000 tokens and a section no larger than half the parent in both tokens and bytes. An empty array doesn't imply a page has no headings. Heading-derived IDs can change after renaming, insertion, or reordering; there are no permanent section IDs or automatic section redirects. See [section retrieval and citations](https://www.shoalrun.com/author/markdown-metadata.md) for the exact policy and full-page fallback.
 
-Optional `subjectDeprecation` requires a deprecated subject and contains supplied dates or resolved replacement/migration targets. It does not require every deprecated subject to have dates or a replacement. Optional `change` requires a changelog entry, one of `editorial`, `procedure`, `behavior`, or `breaking`, a nonempty unique affected-ID list, and an optional migration target. Published targets include `id`, `title`, `url`, and `markdownUrl`, resolved to other public documents in the same publication. The build checks references and dates; it does not verify authored classification or retirement. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and [release notes](https://www.shoalrun.com/author/release-notes.md).
+Optional `subjectDeprecation` requires a deprecated subject and contains supplied dates or resolved replacement/migration targets. It doesn't require every deprecated subject to have dates or a replacement. Optional `change` requires a changelog entry, one of `editorial`, `procedure`, `behavior`, or `breaking`, a nonempty unique affected-ID list, and an optional migration target. Published targets include `id`, `title`, `url`, and `markdownUrl`, resolved to other public documents in the same publication. The build checks references and dates; it doesn't verify authored classification or retirement. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and [release notes](https://www.shoalrun.com/author/release-notes.md).

package/agent-docs/publish/output.sections/navigation-section-indexes.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/page-formats.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,7 +35,7 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Page formats
 
-Both formats come from the same parsed content. Supported components preserve their documented shared content in Markdown: tab choices, disclosure bodies, reader-marked branches, table rows, resolved snippets, and API examples retain readable content and relevant labels. Unknown components and unsupported dynamic MDX fail compilation. Explicit format-specific branches follow author selection; authors must review equivalent task guidance and completeness. Rendering checks do not prove semantic equivalence or that a reader has every prerequisite. [Tabs](https://www.shoalrun.com/author/components/tabs.md) become labeled sections in Markdown. [OpenAPI examples and schemas](https://www.shoalrun.com/author/components/api-embeds.md) are expanded during the build, so their values and field details appear as readable text in the twin. A [filtered or sticky table](https://www.shoalrun.com/author/components/tables.md) keeps every row as a plain table in Markdown.
+Both formats come from the same parsed content. Supported components preserve their documented shared content in Markdown: tab choices, disclosure bodies, reader-marked branches, table rows, resolved snippets, and API examples retain readable content and relevant labels. Unknown components and unsupported dynamic MDX fail compilation. Explicit format-specific branches follow author selection; authors must review equivalent task guidance and completeness. Rendering checks don't prove semantic equivalence or that a reader has every prerequisite. [Tabs](https://www.shoalrun.com/author/components/tabs.md) become labeled sections in Markdown. [OpenAPI examples and schemas](https://www.shoalrun.com/author/components/api-embeds.md) are expanded during the build, so their values and field details appear as readable text in the twin. A [filtered or sticky table](https://www.shoalrun.com/author/components/tables.md) keeps every row as a plain table in Markdown.
 
 Write links in page content as `doc:` IDs, site paths, or relative paths such as `[Next](./next)` and `[Overview](../overview)`. Shoalrun resolves relative paths against the current page's published route. For a page at `/guides/setup`, `./next` resolves to `/guides/next`. HTML links use site paths, so local previews stay local; links to known pages in Markdown twins point to their `.md` routes. Set `site.origin` to publish full HTTPS links in Markdown twins and `/llms.txt`, so a fetched Markdown page keeps working outside the site's browser context. Fragment-only links such as `#options` stay local to the page. Explicit external URLs keep their original host.