@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.md

@@ -15,9 +15,9 @@ canonical: /publish/mcp
 
 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) > MCP > Connect an MCP client
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/verify-the-connection.md

@@ -15,9 +15,9 @@ canonical: /publish/mcp
 
 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) > MCP > Connect an MCP client
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.md

@@ -15,9 +15,9 @@ canonical: /publish/mcp
 
 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) > MCP > Connect an MCP client
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

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

@@ -13,9 +13,9 @@ canonical: /publish/openapi-extension-mappings
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > OpenAPI extension mappings
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > OpenAPI extension mappings
 
 **Updated: 2026-10-25.**
 

package/agent-docs/publish/output.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 `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.
 
@@ -65,14 +65,14 @@ See [agent-friendly documentation](https://www.shoalrun.com/publish/agent-friend
 
 `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.
 
-| Output                     | Path                                                                                                                                                     |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| HTML page                  | `<route>/index.html`                                                                                                                                     |
-| Markdown twin              | `<route>.md`; a page at `/` gets `/index.md`                                                                                                             |
-| Framework and theme assets | `/assets/`: `site.css`, `tokens.css`, `header.css`, scripts, `themes/`, and, when used, `theme.css`, `palette.css`, `project.css`, and `theme-preview.*` |
-| Diagram images             | `/assets/diagrams/<engine>-<hash>-light.svg` and `-dark.svg`, named by a hash of the source so identical diagrams share a file                           |
-| Published OpenAPI source   | `/api/<apiId>/<channel>/<version>/<file>`, plus the local files it references                                                                            |
-| Focused contracts          | `/api/operations/<channel>/<version>/<language>/<name>-<hash>.json`                                                                                      |
+| Output                     | Path                                                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| HTML page                  | `<route>/index.html`                                                                                                                  |
+| Markdown twin              | `<route>.md`; a page at `/` gets `/index.md`                                                                                          |
+| Framework and theme assets | `/assets/`: `site.css`, `tokens.css`, `header.css`, scripts, `themes/`, and, when used, `theme.css`, `palette.css`, and `project.css` |
+| Diagram images             | `/assets/diagrams/<engine>-<hash>-light.svg` and `-dark.svg`, named by a hash of the source so identical diagrams share a file        |
+| 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.
 
@@ -167,10 +167,10 @@ These are static files. The host retains no snapshot history and does not interp
 
 ## Validate an existing build locally
 
-From a repository checkout with development dependencies installed and the framework compiled, run:
+This checker belongs to Shoalrun’s documentation repository; it is not an installed CLI command. From that repository with its dependencies installed, run:
 
 ```sh
-node framework/scripts/check-output-contract.mjs docs/dist
+node scripts/check-output-contract.mjs docs/dist
 ```
 
 Replace `docs/dist` with an already-built site's directory. The checker loads both schemas locally and makes no network requests. It checks field shapes, unique document identities, manifest/sync correspondence, build/config identity agreement, record and metadata hashes, same-publication change/deprecation targets, section parent linkage, and exact Markdown byte counts, token counts, and digests. It also verifies referenced focused-contract bytes. Unknown fields remain allowed and participate in the applicable record or metadata hash.
@@ -197,7 +197,7 @@ node dist/cli.js api focused-audit <site-directory>
 
 Focused export supports local OpenAPI 3.0.x and 3.1.x files, including multi-file references. JSON Schema IDs and anchors that change the base URI need a separate adapter. Remote sources still need a pinned local snapshot.
 
-For config provenance, run `node framework/dist/cli.js config explain site.title docs/docs.config.yaml` from the repository root. The [CLI reference](https://www.shoalrun.com/cli.md) covers this and the other inspection commands.
+For config provenance, run `npx --no-install shoalrun config explain site.title docs.config.yaml` from your documentation project root. The [CLI reference](https://www.shoalrun.com/cli.md) covers this and the other inspection commands.
 
 ## Code highlighting
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -37,4 +37,4 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 Focused export supports local OpenAPI 3.0.x and 3.1.x files, including multi-file references. JSON Schema IDs and anchors that change the base URI need a separate adapter. Remote sources still need a pinned local snapshot.
 
-For config provenance, run `node framework/dist/cli.js config explain site.title docs/docs.config.yaml` from the repository root. The [CLI reference](https://www.shoalrun.com/cli.md) covers this and the other inspection commands.
+For config provenance, run `npx --no-install shoalrun config explain site.title docs.config.yaml` from your documentation project root. The [CLI reference](https://www.shoalrun.com/cli.md) covers this and the other inspection commands.

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/published-output-contract.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/reader-appearance-and-controls.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

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

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/response-identity.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/site-files.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 

package/agent-docs/publish/output.sections/validate-an-existing-build-locally.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -35,10 +35,10 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 ## Validate an existing build locally
 
-From a repository checkout with development dependencies installed and the framework compiled, run:
+This checker belongs to Shoalrun’s documentation repository; it is not an installed CLI command. From that repository with its dependencies installed, run:
 
 ```sh
-node framework/scripts/check-output-contract.mjs docs/dist
+node scripts/check-output-contract.mjs docs/dist
 ```
 
 Replace `docs/dist` with an already-built site's directory. The checker loads both schemas locally and makes no network requests. It checks field shapes, unique document identities, manifest/sync correspondence, build/config identity agreement, record and metadata hashes, same-publication change/deprecation targets, section parent linkage, and exact Markdown byte counts, token counts, and digests. It also verifies referenced focused-contract bytes. Unknown fields remain allowed and participate in the applicable record or metadata hash.

package/agent-docs/publish/output.sections/where-files-go.md

@@ -13,11 +13,11 @@ canonical: /publish/output
 
 > 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)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Generated outputs
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > Generated outputs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/publish/output.md)
 
@@ -37,13 +37,13 @@ The site also includes a **document manifest**, `documents.json`, which indexes
 
 `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.
 
-| Output                     | Path                                                                                                                                                     |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| HTML page                  | `<route>/index.html`                                                                                                                                     |
-| Markdown twin              | `<route>.md`; a page at `/` gets `/index.md`                                                                                                             |
-| Framework and theme assets | `/assets/`: `site.css`, `tokens.css`, `header.css`, scripts, `themes/`, and, when used, `theme.css`, `palette.css`, `project.css`, and `theme-preview.*` |
-| Diagram images             | `/assets/diagrams/<engine>-<hash>-light.svg` and `-dark.svg`, named by a hash of the source so identical diagrams share a file                           |
-| Published OpenAPI source   | `/api/<apiId>/<channel>/<version>/<file>`, plus the local files it references                                                                            |
-| Focused contracts          | `/api/operations/<channel>/<version>/<language>/<name>-<hash>.json`                                                                                      |
+| Output                     | Path                                                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| HTML page                  | `<route>/index.html`                                                                                                                  |
+| Markdown twin              | `<route>.md`; a page at `/` gets `/index.md`                                                                                          |
+| Framework and theme assets | `/assets/`: `site.css`, `tokens.css`, `header.css`, scripts, `themes/`, and, when used, `theme.css`, `palette.css`, and `project.css` |
+| Diagram images             | `/assets/diagrams/<engine>-<hash>-light.svg` and `-dark.svg`, named by a hash of the source so identical diagrams share a file        |
+| 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.

package/agent-docs/publish/publications.md

@@ -15,7 +15,7 @@ canonical: /publish/publications
 
 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) > Publish > Share pages across documentation versions
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Share pages across documentation versions
 
 **Updated: 2026-10-26.**
 

package/agent-docs/publish/revisions.md

@@ -15,7 +15,7 @@ canonical: /publish/revisions
 
 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) > Publish > Use Git branches for separate docs sites
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Use Git branches for separate docs sites
 
 **Updated: 2026-10-26.**
 

package/agent-docs/publish/seo.md

@@ -15,9 +15,9 @@ canonical: /publish/seo
 
 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) > Publish > SEO and social previews
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-29.**
 
 When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
 
@@ -106,7 +106,21 @@ Set native frontmatter `verified` only when someone checks the page's technical
 verified: 2026-10-01
 ```
 
-The HTML page, Markdown twin, and manifest expose this date independently of Updated. A build never assigns it. This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
+The standard HTML page header displays `Verified` with a semantic `<time>` element. Markdown and `documents.json` expose the same date independently of `Updated`, which records content revision. A build never assigns `verified`; a build or editorial review alone does not establish technical verification.
+
+The HTML verification-date display and `showVerified` setting are available since `0.1.0-alpha.13`.
+
+Set `showVerified: false` in a page's frontmatter to hide the verification date in HTML only. It remains in Markdown and the manifest. The default is `true`. To hide it throughout a project, set a shared default:
+
+```yaml title="docs.config.yaml"
+frontmatter:
+  defaults:
+    showVerified: false
+```
+
+An individual page can override that default with `showVerified: true`. A page using a Hero replaces the standard header, so its header dates are not displayed.
+
+This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
 
 Search indexing still depends on the public host and crawler access; metadata alone does not guarantee it. If Slack does not unfurl after a corrected deployment, confirm the page and image are public, then try sharing the link in a new conversation. [Slack may omit a preview](https://slack.com/help/articles/204399343-Share-links-and-set-preview-preferences) when the same link was recently posted in that conversation.
 

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

@@ -0,0 +1,28 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [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) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Related reading
+
+No matching documents.

package/agent-docs/publish/seo.sections/set-the-public-address.md

@@ -0,0 +1,36 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [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) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Set the public address
+
+Put the address readers actually use in `site.origin`. This is where crawlers will fetch the page and its image:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Acme API docs
+  origin: https://docs.acme.com
+```
+
+Check the domain in the built `og:image` URL. A page may display in a browser while its social preview cannot load an image from that domain. Preview deployments behind sign-in cannot be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.

package/agent-docs/publish/seo.sections/what-agents-receive.md

@@ -0,0 +1,28 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [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) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## What agents receive
+
+The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body does not contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image does not replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.

package/agent-docs/publish/seo.sections/what-the-build-adds.md

@@ -0,0 +1,42 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [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) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## What the build adds
+
+The build derives these metadata and discovery outputs from your site and page settings.
+
+| Output                                     | Default source                                                       |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| HTML `<title>`                             | `seo.title`, then page `title`                                       |
+| HTML `name="description"`                  | `seo.description`, then configured HTML description                  |
+| `og:title` and `twitter:title`             | Browser title, with `site.title` added for short titles when it fits |
+| `og:description` and `twitter:description` | Selected social description, falling back to the page `summary`      |
+| `og:url`                                   | `site.origin` plus the published page route                          |
+| Canonical URL                              | `site.origin` plus the published page route                          |
+| XML sitemap `lastmod`                      | Page `updated`, then optional `site.updated`                         |
+| `og:image` and `twitter:image`             | Absolute URL of that page's share image                              |
+| `twitter:card`                             | `summary_large_image` when a share image exists                      |
+
+The default image is a 1200×630 PNG with the page type, title, summary, site name, and URL. [Share images and favicon](https://www.shoalrun.com/styling/share-images.md) shows how to replace a page image or the site-wide design. Turning off share images removes image tags on pages without their own image.