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

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.1.0-alpha.13 — 2026-10-28
+
+Use documentation as content for applications, agents, services, and publishing
+workflows. Content delivery adds selected sections and named snippet instances to
+whole-page exports, with a shared client interface for static bundles and REST.
+
+- Read reviewed HTML or Markdown with `@shoalrun/cli/content`. The mount helper
+  rewrites IDs and links so the same content can appear more than once in an app.
+- Use heading-derived section IDs or preserve a reference with a trailing
+  `<Anchor id="refunds" />`. Declare `{ id: refunds, context: section }` in
+  `standaloneSections` after reviewing that section without the rest of its page.
+- Serve the same snapshots with `createContentRestHandler` and read them with
+  `openRestContentSource`. HTTP contract v1 covers resource lists, metadata,
+  representations, explicit publication and revision selection, and ETags.
+  Authentication, search, editing, and production hosting remain host concerns.
+- Compare exports using `--previous-manifest`; add `--fail-on-removed` to reject
+  removed references. Use immutable revision directories for running clients.
+- Render schema-based OpenAPI response headers in native API references. Generated
+  request samples handle HEAD responses and text representations correctly.
+- Show authored `verified` dates as labeled semantic dates in HTML page headers,
+  independently of `updated`. Set `showVerified: false` on a page or through
+  frontmatter defaults to hide verification in HTML only. Builds never assign it.
+- Find content-delivery guides, client and HTTP references, and clearer layout
+  choices in the bundled docs. The layout guide explains `layout: wide` versus
+  `tocDepth: 0`; section guidance explains what the author declaration means.
+
+- Preserve literal scaffold TODO examples inside fenced code in both outputs;
+  unfinished prompts in prose and frontmatter still block publication.
+- Suggest native relationships during project discovery and validation when
+  related-reading sections contain document links. Hints are nonblocking and
+  never create relationships automatically. The component index maps tasks to
+  native features.
+
+- Hide or rename the sidebar’s “Explore” heading with
+  `outputs.html.navigation.heading`; `false` hides it while retaining the filter label.
+
+- Remove the page-sized focus rectangle after clicking article content. Keyboard
+  jumps still focus the article and indicate the destination at its title.
+
+**Upgrade:** Rebuild exports and update custom consumers from `manifest.documents`
+to `manifest.resources` with typed `ref` objects. Existing `documents` selectors
+remain page-selection shorthand. Read paths from the new manifest; do not retain
+old payload paths. Whole-page consumers can use the updated help-drawer example;
+the content-delivery example demonstrates both transports and repeated mounts.
+
+## 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.13
 ```
 
 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.13 --@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,
@@ -122,7 +124,7 @@ exports:
 ```
 
 Run `shoalrun export docs.config.yaml --target app-help --out app/public/help`.
-Omit `documents` to export all eligible public pages in one enabled publication;
+Omit both `documents` and `resources` to export all eligible public pages in one enabled publication;
 select an explicit publication when more than one is enabled. Export selection
 is independent of the website's `site.contentFilter` and navigation. Selected
 pages retain all reader sections as labeled static content. Tabs and walkthroughs
@@ -142,10 +144,31 @@ older export is replaced.
 
 See [the help-drawer example](examples/help-drawer/README.md) for a plain-JavaScript
 consumer and local preview. The [export manifest schema](schemas/content-export.schema.json)
-describes the file contract. Mount each document once per DOM; repeated instances
-need consumer-side ID and reference rewriting. Whole-page exports do not include
+describes the file contract. Direct HTML insertion requires consumer-side ID and
+reference rewriting for repeated instances; the content-delivery mount helper
+provides that rewriting. Whole-page exports do not include
 website navigation, search/chat runtimes, themes, or heuristic section resources.
 
+## Content delivery
+
+Content delivery extends export to selected pages, standalone sections, and named snippet instances. Applications can use the browser-safe client with a static manifest or a read-only REST endpoint. Static delivery requires no server or model provider.
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const source = await openManifestContentSource({
+  manifestUrl: '/content/releases/r42/manifest.json',
+});
+const resource = await source.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'html' },
+);
+```
+
+Heading-derived section IDs are the default. Optional explicit IDs preserve references across heading renames. Export comparisons report removed references when a previous manifest is supplied. Each opened source stays on one publication and revision; open a new source to update it.
+
+See the [content-delivery example](examples/content-delivery/README.md) for resource selection, instance-safe HTML mounting, and a complete local preview. The example also runs the REST adapter and demonstrates `openRestContentSource` with the same reading interface. See the [OpenAPI contract](schemas/content-rest.openapi.json) for the HTTP API. Authentication, search, and production hosting remain application concerns.
+
 ## Publish discovery files
 
 Set `site.origin` to the HTTPS origin (for example, `https://example.github.io`)
@@ -188,3 +211,22 @@ Pin an exact package version and read the [changelog](CHANGELOG.md) before upgra
 ## License
 
 Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.
+
+## Verification dates
+
+Set `verified` only after checking a page's technical claims. It is separate from
+`updated`, which records content revision. Both appear as labeled `<time>` elements
+in the standard HTML page header, and as dates in Markdown and `documents.json`.
+Builds never assign `verified`.
+
+```yaml
+updated: 2026-10-28
+verified: 2026-10-27
+showVerified: false
+```
+
+`showVerified` defaults to `true`. Set it to `false` to hide the verification date
+in HTML only; Markdown and manifest metadata retain it. Set
+`frontmatter.defaults.showVerified: false` in project configuration for a shared
+default, then override it with `showVerified: true` on individual pages. A layout
+with a Hero replaces the standard page header and does not display its dates.

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,39 @@
-# 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.
+
+- [Content delivery, verification dates, and clearer references](https://www.shoalrun.com/changelog/2026-10-28.md) — ID: change.2026-10-28. changelog-entry; 1393 tokens. Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.
+
+- [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; 1074 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": "fe92983e9f5710d9c2265972a2477448df4ae82d",
+  "siteBuildId": "38aac8472fa1fad778acd5b5bdc30067474eca35755706d09f916914326ed2f0",
+  "manifestDigest": "c99f0684ea93c4add58ddee1fd19dc82fa1acd9099d6cc2b4b226a0ef85302fe",
+  "indexDigest": "f38899eb2e53af8600714002a64538fb436d3cf90fa8e1247d3e892ef703fc48",
+  "packageIntegrity": "sha512-Qs6yv+QFvt6L5huiKFQfIT5FYexxbSokwUVUnxIrXUx2TtY/VTdG0EKAJJuCLLi6FcrYVbnI/mC9uWqJ9nflsw=="
 }

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