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

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.0-alpha.12 — 2026-10-27
+
+- Refresh the bundled documentation from the reviewed public site: organize navigation into Docs, Reference, Examples, and Project; use installed-package commands in customer workflows; and standardize component reference sections.
+- Explain HTML, Markdown, and agent behavior across feature references, and remove customer-facing embedding instructions for the site’s theme demo.
+
+Upgrade to alpha.12 to use the refreshed offline documentation through the CLI and MCP tools. Runtime behavior, components, and configuration are unchanged from alpha.11.
+
 ## 0.1.0-alpha.11 — 2026-10-27
 
 - Move package distribution to the public npm registry. New installations need no GitHub package access or token. Existing users should remove the old `@shoalrun` registry override and update their manifest and lockfile together; see the README.

package/README.md

@@ -9,13 +9,13 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.11
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.12
 ```
 
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.11 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.12 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
@@ -25,15 +25,15 @@ Commit the updated package manifest and lockfile together. Check that the lockfi
 Run these commands from the directory where you installed the package:
 
 ```sh
-npx shoalrun init my-docs --starter showcase
-npx shoalrun build my-docs/docs.config.yaml my-docs/site-dist
-npx shoalrun serve my-docs/site-dist --port 8770
+npx --no-install shoalrun init my-docs --starter showcase
+npx --no-install shoalrun build my-docs/docs.config.yaml my-docs/site-dist
+npx --no-install shoalrun serve my-docs/site-dist --port 8770
 ```
 
 Open <http://127.0.0.1:8770/>. Edit the pages in `my-docs/content/` and the site settings and navigation in `my-docs/docs.config.yaml`. Rebuild to update the preview, or use the development server to rebuild on changes:
 
 ```sh
-npx shoalrun dev my-docs/docs.config.yaml my-docs/site-dist --port 8770
+npx --no-install shoalrun dev my-docs/docs.config.yaml my-docs/site-dist --port 8770
 ```
 
 Stop the existing preview with Ctrl-C before starting the development server on the same port. Choose **Explore the starter**, the first item in the left navigation, to find component examples, diagrams, reader views, themes, and generated API references. The service and API hosts are fictional; replace them before sending requests. Choose `--starter minimal` for a smaller starting point or `--starter api-docs` for a focused OpenAPI example. All three starters build without provider credentials.
@@ -43,8 +43,8 @@ Stop the existing preview with Ctrl-C before starting the development server on
 Shoalrun works with your existing coding agent. Its packaged skills explain how to set up a site, edit pages, and develop components:
 
 ```sh
-npx shoalrun skills list
-npx shoalrun skills read shoalrun-setup
+npx --no-install shoalrun skills list
+npx --no-install shoalrun skills read shoalrun-setup
 ```
 
 Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
@@ -52,9 +52,9 @@ Ask your agent to read the skill for the task. `skills list` returns names, desc
 The usual editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
 ```sh
-npx shoalrun docs baseline --out .shoalrun/task-baseline.json
+npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
 # Edit your pages and configuration.
-npx shoalrun docs validate --baseline .shoalrun/task-baseline.json
+npx --no-install shoalrun docs validate --baseline .shoalrun/task-baseline.json
 ```
 
 Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements—the starter does not define them for you.
@@ -64,11 +64,13 @@ Validation returns a report path. Pass that path to `shoalrun docs review` and `
 Read the documentation bundled with your installed version without a provider key or website connection:
 
 ```sh
-npx shoalrun --help
-npx shoalrun docs search "Steps" --json
-npx shoalrun docs read guide.component.steps --json
+npx --no-install shoalrun --help
+npx --no-install shoalrun docs search "Steps" --json
+npx --no-install shoalrun docs read guide.component.steps --json
 ```
 
+Alpha.12 includes the reviewed documentation refresh: clearer organization, installed-package workflows, and consistent explanations of HTML, Markdown, and agent behavior. The bundled snapshot stays fixed until you upgrade the package.
+
 See the [authoring command reference](AUTHORING.md) for project inspection, validation, report schemas, and the public authoring API. Visit [shoalrun.com](https://www.shoalrun.com) for the full documentation; it may describe changes newer than your installed package.
 
 ## Build sites from shared content
@@ -103,7 +105,7 @@ Export pages from the same source into a portable directory for an application's
 help drawer, onboarding screens, or other content surfaces:
 
 ```sh
-npx shoalrun export docs.config.yaml --out app/public/help --public-base /help/
+npx --no-install shoalrun export docs.config.yaml --out app/public/help --public-base /help/
 ```
 
 The command writes `manifest.json`, resolved Markdown, passive HTML fragments,

package/agent-docs/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt

@@ -0,0 +1,22 @@
+# Examples
+
+Full-page token counts use cl100k_base. Navigation section ID: examples-tab. Publication: production/current/en.
+
+[All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
+
+Choose a topic index below, then follow a matching page or narrower index. All published pages in this scope remain reachable, including pages outside navigation.
+
+
+- [API documentation](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/ea97da4000b0c4ddfd69fa8c.txt): scoped index.
+
+- [Site appearance](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/ccbd7ed463b8cd3112e9740e.txt): scoped index.
+
+- [Authoring](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/b240b4f0095dcac710d3d244.txt): scoped index.
+
+- [Content components](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/0192a1b49bb31c8f8d9bce80.txt): scoped index.
+
+- [Search & discovery](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/adbd3bda7ff4c15a893b0dbd.txt): scoped index.
+
+- [Publishing](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/90e999b5c3e3ef0d2bd3ce4e.txt): scoped index.
+
+- [Quality & measurement](/.well-known/shoalrun/navigation/examples-tab-50f26fe22670-indexes/e27cd9625df147549caa6261.txt): scoped index.

package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -1,9 +1,37 @@
-# Project updates
+# Project
 
 Full-page token counts use cl100k_base. Navigation section ID: project-updates. Publication: production/current/en.
 
 [All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
 
-- [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 823 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
+- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 546 tokens. Compact discovery, content verification, and incremental fetching.
 
-- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1653 tokens. Current capabilities, planned features, and known limits.
+- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1696 tokens. Smaller reads, lifecycle guidance, and reproducible evaluations.
+
+- [Content exports and documentation checks](https://www.shoalrun.com/changelog/2026-10-25.md) — ID: change.2026-10-25. changelog-entry; 668 tokens. Content exports and documentation checks.
+
+- [Safer exports and easier discovery for AI assistants](https://www.shoalrun.com/changelog/2026-10-26.md) — ID: change.2026-10-26. changelog-entry; 1288 tokens. Keep exported images and links with their pages, and help AI assistants find docs by topic.
+
+- [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1223 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
+
+- [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 551 tokens. Snapshot previews with coverage and freshness reports.
+
+- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 466 tokens. Reviewed agent drafts, search improvements, and answer context.
+
+- [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 378 tokens. Project discovery and captured working-tree validation.
+
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 999 tokens. Compiler, CLI, and reader changes.
+
+- [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1145 tokens. MCP hosting, analytics, and shared component content.
+
+- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1092 tokens. Navigation sections, reader controls, layouts, and browser analytics.
+
+- [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 668 tokens. Indexed search and hover and focus tooltips.
+
+- [Experimental visual navigation and taxonomy enforcement](https://www.shoalrun.com/changelog/2026-10-19-visual-navigation.md) — ID: change.visual-navigation. changelog-entry; 746 tokens. Visual navigation and taxonomy validation.
+
+- [Portable working-tree authoring workflow](https://www.shoalrun.com/changelog/working-tree-skill.md) — ID: change.working-tree-skill. changelog-entry; 478 tokens. Agent discovery, native editing, validation, and snapshot review.
+
+- [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 821 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
+
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1651 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt

@@ -0,0 +1,22 @@
+# Reference
+
+Full-page token counts use cl100k_base. Navigation section ID: reference-tab. Publication: production/current/en.
+
+[All sections and published pages](https://www.shoalrun.com/llms.min.txt). This index covers this section only; shared and unlisted pages remain reachable through the global index. Reader views do not remove pages from this index.
+
+Choose a topic index below, then follow a matching page or narrower index. All published pages in this scope remain reachable, including pages outside navigation.
+
+
+- [API documentation](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/ea97da4000b0c4ddfd69fa8c.txt): scoped index.
+
+- [Site appearance](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/ccbd7ed463b8cd3112e9740e.txt): scoped index.
+
+- [Authoring](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/b240b4f0095dcac710d3d244.txt): scoped index.
+
+- [Content components](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/0192a1b49bb31c8f8d9bce80.txt): scoped index.
+
+- [Search & discovery](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/adbd3bda7ff4c15a893b0dbd.txt): scoped index.
+
+- [Project](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/9accc04fcdbda3d485b38406.txt): scoped index.
+
+- [Publishing](/.well-known/shoalrun/navigation/reference-tab-50f26fe22670-indexes/90e999b5c3e3ef0d2bd3ce4e.txt): scoped index.

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "45a0923117a2572d8bc578fac8a8dea4e6b6bfb6",
-  "siteBuildId": "68177258b5815d788ec3e5e31995885d8f6800cb329751f710eb73e5d6baad26",
-  "manifestDigest": "f570f7f8d8d54dab43681fde79d884528c41c33a710168260d08691eadeef7b0",
-  "indexDigest": "b586084c1743627b095705d7c3c64b0854864ec4d3fb96a236bd373d7fdfe408",
-  "packageIntegrity": "sha512-rmqYv+uNY4P/fdwJAlJNfODcRQdLxgWJpVcdT20a/7MdDRfqO3GTYR7sZxF7Dbqw+zVQhvmjPQDnUs5A60VktQ=="
+  "sourceCommit": "0e40930cc80207ff9cb22fcaade5fc5dbdd464a5",
+  "siteBuildId": "1aae676cf02856842a383f9e8f28b2b126e18cfbc75050227980b1d3d82762b6",
+  "manifestDigest": "5b181b5e3d09eaae37afaf0f08ce5c725ea393029df4cec8ad62c44939b07fe7",
+  "indexDigest": "57736349c41e4b36d0b9726e76b512415b85443d49eababbd3387fa416c996c9",
+  "packageIntegrity": "sha512-NmM2tIR7SSyz8STTZluEsATZZBcTrgH6mWBTjOju7Qz3E60onSrQF93IXmBuhBiInw+Zq9mysUAk8Lvo/UDj6Q=="
 }

package/agent-docs/api-docs/focused-contracts.md

@@ -13,9 +13,9 @@ canonical: /api-docs/focused-contracts
 
 > 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 > Focused OpenAPI contracts
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > Focused OpenAPI contracts
 
 **Updated: 2026-10-26.**
 

package/agent-docs/api-docs/generate.md

@@ -17,9 +17,9 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Choose generated references or MDX
 
@@ -28,9 +28,9 @@ Use build-time generated references when the OpenAPI contract already gives read
 The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It does not change config or navigation and never rewrites an existing page. For example:
 
 ```sh
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --all
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --operation getNote
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --route 'GET /notes/{id}'
+npx --no-install shoalrun api materialize notes docs.config.yaml --all
+npx --no-install shoalrun api materialize notes docs.config.yaml --operation getNote
+npx --no-install shoalrun api materialize notes docs.config.yaml --route 'GET /notes/{id}'
 ```
 
 The default destination is `content/api/<api-id>/`; use `--output` for another directory inside the configured content tree. Selectors use the OpenAPI `operationId` or exact uppercase method and path. Repeating a command reports the existing matching page as skipped. A file with a conflicting identity stops the job before it writes anything. Existing authored references also count as skipped.
@@ -93,7 +93,7 @@ Here `GET /Query/widgets` may have the OpenAPI tag `Query`, but its generated re
 To review the default publication's spec operation by operation, run:
 
 ```sh
-node "$SHOALRUN_CLI" api select notes docs.config.yaml --output config/notes-pages.yaml
+npx --no-install shoalrun api select notes docs.config.yaml --output config/notes-pages.yaml
 ```
 
 The command shows the method, path, ID, and summary for each operation and asks **yes** or **no**. It shows operations with authored pages but does not replace them. After the choices are complete, it writes the `pathPrefix` and `include` list to the selection file; `q` cancels without writing. Run `api review` again, inspect the candidate, and update `publicReview.digest` before rebuilding to apply the choices. Add `{ id: notes-generated, api: notes, generated: tags }` under a navigation group to display the generated pages by their first OpenAPI tag, or place selected operations explicitly in navigation. This site's [Example Notes API subnav](https://www.shoalrun.com/author/navigation.md) uses the tag generator.

package/agent-docs/api-docs/generate.sections/add-useful-examples.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Add useful examples
 

package/agent-docs/api-docs/generate.sections/choose-generated-references-or-mdx.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Choose generated references or MDX
 
@@ -40,9 +40,9 @@ Use build-time generated references when the OpenAPI contract already gives read
 The one-time `api materialize` command creates draft MDX references for every endpoint or selected source operation IDs or method/path routes. It does not change config or navigation and never rewrites an existing page. For example:
 
 ```sh
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --all
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --operation getNote
-node "$SHOALRUN_CLI" api materialize notes docs.config.yaml --route 'GET /notes/{id}'
+npx --no-install shoalrun api materialize notes docs.config.yaml --all
+npx --no-install shoalrun api materialize notes docs.config.yaml --operation getNote
+npx --no-install shoalrun api materialize notes docs.config.yaml --route 'GET /notes/{id}'
 ```
 
 The default destination is `content/api/<api-id>/`; use `--output` for another directory inside the configured content tree. Selectors use the OpenAPI `operationId` or exact uppercase method and path. Repeating a command reports the existing matching page as skipped. A file with a conflicting identity stops the job before it writes anything. Existing authored references also count as skipped.

package/agent-docs/api-docs/generate.sections/describe-filters-that-do-not-use-their-openapi-parameter-name.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Describe filters that do not use their OpenAPI parameter name
 

package/agent-docs/api-docs/generate.sections/generate-many-pages-selectively.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Generate many pages selectively
 

package/agent-docs/api-docs/generate.sections/link-guides-to-api-references.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Link guides to API references
 

package/agent-docs/api-docs/generate.sections/map-extension-values-to-shoalrun-status.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Map extension values to Shoalrun status
 

package/agent-docs/api-docs/generate.sections/override-generated-reference-order-in-navigation.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Override generated reference order in navigation
 
@@ -52,7 +52,7 @@ Here `GET /Query/widgets` may have the OpenAPI tag `Query`, but its generated re
 To review the default publication's spec operation by operation, run:
 
 ```sh
-node "$SHOALRUN_CLI" api select notes docs.config.yaml --output config/notes-pages.yaml
+npx --no-install shoalrun api select notes docs.config.yaml --output config/notes-pages.yaml
 ```
 
 The command shows the method, path, ID, and summary for each operation and asks **yes** or **no**. It shows operations with authored pages but does not replace them. After the choices are complete, it writes the `pathPrefix` and `include` list to the selection file; `q` cancels without writing. Run `api review` again, inspect the candidate, and update `publicReview.digest` before rebuilding to apply the choices. Add `{ id: notes-generated, api: notes, generated: tags }` under a navigation group to display the generated pages by their first OpenAPI tag, or place selected operations explicitly in navigation. This site's [Example Notes API subnav](https://www.shoalrun.com/author/navigation.md) uses the tag generator.

package/agent-docs/api-docs/generate.sections/related-reading.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Related reading
 

package/agent-docs/api-docs/generate.sections/use-a-template-for-editorial-context.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) > Document an API > Generate and select API pages
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/api-docs/generate.md)
 
@@ -31,7 +31,7 @@ Parent page: [Full Markdown page](/api-docs/generate.md)
 
 - [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
 
-Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `SHOALRUN_CLI` set as in the quickstart.
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
 
 ## Use a template for editorial context
 

package/agent-docs/api-docs/support.md

@@ -13,11 +13,11 @@ canonical: /api-docs/support
 
 > 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 support and limits
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > OpenAPI support and limits
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Shoalrun renders a defined subset of OpenAPI into HTML, Markdown, and focused contracts. Check these limits before importing a large specification. A supported OpenAPI version does not mean every feature in that version can be rendered.
 
@@ -77,7 +77,7 @@ Avoid removing source semantics silently. If your API needs an unsupported featu
 With the CLI built as in the [quickstart](https://www.shoalrun.com/start.md), run:
 
 ```sh
-node "$SHOALRUN_CLI" api audit apis/notes/openapi.yaml
+npx --no-install shoalrun api audit apis/notes/openapi.yaml
 ```
 
 The audit renders every operation in the supplied source and checks field anchors and named examples across HTML and Markdown. It reports every unsupported schema keyword it finds for each operation, with the source file and schema location, before the strict renderer runs. It can reveal unsupported features beyond the operations you initially plan to publish. It does not call a live API or establish complete semantic fidelity.

package/agent-docs/author/add-page.md

@@ -17,11 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Create a page
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Create a page from a template with `scaffold`. Templates prompt you for the page's frontmatter, an introduction, the main content, and related pages before you publish. This is the recommended authoring workflow for new pages.
 
-This guide assumes you have completed [getting started](https://www.shoalrun.com/start.md) and are working in `my-docs/`. Keep `SHOALRUN_CLI` pointing to the checkout's `framework/dist/cli.js`.
+## Before you begin
+
+Complete [getting started](https://www.shoalrun.com/start.md), then run the commands from `my-docs/`, where `@shoalrun/cli` is installed. You will create a page at `/track-parcel` and verify both published formats.
 
 ## Choose a template
 
@@ -49,7 +51,7 @@ Use the project's template for the document type when one exists. Project templa
 From the project directory:
 
 ```sh
-node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx \
+npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx \
   --id how-to.track-parcel --title 'Track a parcel'
 ```
 
@@ -99,13 +101,13 @@ A public page can have a working URL without appearing in the sidebar. Adding th
 From the project directory:
 
 ```sh
-node "$SHOALRUN_CLI" build docs.config.yaml site-dist
-node "$SHOALRUN_CLI" serve site-dist --port 8765
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8765
 ```
 
 Open `http://127.0.0.1:8765/track-parcel` and confirm that the page appears in navigation and that its links work. Then open `http://127.0.0.1:8765/track-parcel.md` and confirm that the same prose is available and internal links point to Markdown pages. Press **Ctrl+C** to stop the server.
 
-If you use another publication or a language prefix, inspect the built `documents.json` for the resolved URLs. To preview edits continuously, use `node "$SHOALRUN_CLI" dev docs.config.yaml site-dist --port 8765`.
+If you use another publication or a language prefix, inspect the built `documents.json` for the resolved URLs. To preview edits continuously, use `npx --no-install shoalrun dev docs.config.yaml site-dist --port 8765`.
 
 Next, [organize your navigation](https://www.shoalrun.com/author/navigation.md) as the site grows.
 

package/agent-docs/author/agent-overview.md

@@ -18,7 +18,7 @@ canonical: /author/agent-overview
 
 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) > Write documentation > Write with agents > Project tools > Tools overview
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Tools overview
 
 **Updated: 2026-10-27.**
 

package/agent-docs/author/agent-workflow.md

@@ -18,7 +18,7 @@ canonical: /author/agent-workflow
 
 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) > Write documentation > Write with agents > Project tools > Snapshot validation
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Snapshot validation
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/adapter-exports-and-consent.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/built-in-events.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/configure-an-adapter.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/custom-interactions.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/event-format.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/analytics.sections/html-markdown-and-agents.md

@@ -15,7 +15,7 @@ canonical: /author/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) > Customize > Analytics
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Analytics
 
 **Updated: 2026-10-26.**