npm - @shoalrun/cli - Versions diffs - 0.1.0-alpha.11 → 0.1.0-alpha.12 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (513) hide show

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

@@ -15,7 +15,7 @@ canonical: /publish/mcp-analytics
 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 > Measure MCP tool usage
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
 **Updated: 2026-10-26.**

package/agent-docs/publish/mcp-analytics.sections/safeguards-and-limits.md CHANGED Viewed

@@ -15,7 +15,7 @@ canonical: /publish/mcp-analytics
 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 > Measure MCP tool usage
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Measure MCP tool usage
 **Updated: 2026-10-26.**

package/agent-docs/publish/mcp.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**
@@ -96,34 +96,34 @@ Local package tests cover SDK clients and the generated function. Read-only SDK
 ## Choose the documentation source
-From `framework/`, start a server for Shoalrun's bundled documentation:
+From your documentation project with the CLI installed, start a server for Shoalrun's bundled documentation:
 ```sh
-node dist/cli.js docs mcp
+npx --no-install shoalrun docs mcp
 ```
-For your site's documentation, build it first and pass the output directory. The following example runs from the repository root:
+For your site's documentation, build it first and pass the output directory. The following example runs from your documentation project root:
 ```sh
-node framework/dist/cli.js build docs/docs.config.yaml docs/dist
-node framework/dist/cli.js docs mcp --site docs/dist
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun docs mcp --site site-dist
 ```
 Search needs `search-index.json`; page reads need `documents.json` and the generated Markdown files. The server does not rebuild the site or fetch remote pages. Rebuild after editing your site's sources. The shared core reads the built files on each call.
 ## Configure the client
-Enter a stdio server command and arguments in your client's MCP settings. For this checkout, use absolute paths so the client's working directory does not affect resolution:
+Enter a stdio server command and arguments in your client's MCP settings. Use absolute paths to your installed package and built site so the client's working directory does not affect resolution:
 ```json
 {
   "command": "node",
   "args": [
-    "/absolute/path/to/shoalrun/framework/dist/cli.js",
+    "/absolute/path/to/my-docs/node_modules/@shoalrun/cli/dist/cli.js",
     "docs",
     "mcp",
     "--site",
-    "/absolute/path/to/shoalrun/docs/dist"
+    "/absolute/path/to/my-docs/site-dist"
   ]
 }
 ```

package/agent-docs/publish/mcp.sections/check-budgets-and-errors.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**

package/agent-docs/publish/mcp.sections/choose-the-documentation-source.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**
@@ -35,17 +35,17 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 ## Choose the documentation source
-From `framework/`, start a server for Shoalrun's bundled documentation:
+From your documentation project with the CLI installed, start a server for Shoalrun's bundled documentation:
 ```sh
-node dist/cli.js docs mcp
+npx --no-install shoalrun docs mcp
 ```
-For your site's documentation, build it first and pass the output directory. The following example runs from the repository root:
+For your site's documentation, build it first and pass the output directory. The following example runs from your documentation project root:
 ```sh
-node framework/dist/cli.js build docs/docs.config.yaml docs/dist
-node framework/dist/cli.js docs mcp --site docs/dist
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun docs mcp --site site-dist
 ```
 Search needs `search-index.json`; page reads need `documents.json` and the generated Markdown files. The server does not rebuild the site or fetch remote pages. Rebuild after editing your site's sources. The shared core reads the built files on each call.

package/agent-docs/publish/mcp.sections/configure-the-client.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**
@@ -35,17 +35,17 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 ## Configure the client
-Enter a stdio server command and arguments in your client's MCP settings. For this checkout, use absolute paths so the client's working directory does not affect resolution:
+Enter a stdio server command and arguments in your client's MCP settings. Use absolute paths to your installed package and built site so the client's working directory does not affect resolution:
 ```json
 {
   "command": "node",
   "args": [
-    "/absolute/path/to/shoalrun/framework/dist/cli.js",
+    "/absolute/path/to/my-docs/node_modules/@shoalrun/cli/dist/cli.js",
     "docs",
     "mcp",
     "--site",
-    "/absolute/path/to/shoalrun/docs/dist"
+    "/absolute/path/to/my-docs/site-dist"
   ]
 }
 ```

package/agent-docs/publish/mcp.sections/generate-a-vercel-endpoint.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**

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

@@ -15,7 +15,7 @@ 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.**

package/agent-docs/publish/mcp.sections/search-then-read.md CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**

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

@@ -15,7 +15,7 @@ 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.**

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

@@ -15,7 +15,7 @@ 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.**

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

@@ -15,7 +15,7 @@ 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.**

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -15,7 +15,7 @@ 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.**