@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# Shoalrun
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shoalrun turns Markdown and MDX into a documentation website and Markdown pages from the same content. People can browse the site; agents can read the Markdown. Native components such as steps, tabs, and API references preserve their content in both formats.
+
+This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This alpha is distributed through the public npm registry. Installation requires no npm account or package token.
+
+## Install
+
+From the project where you want to keep your documentation:
+
+```sh
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.11
+```
+
+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
+```
+
+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.
+
+## Create and preview a site
+
+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
+```
+
+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
+```
+
+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.
+
+## Work with an agent
+
+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
+```
+
+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.
+
+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
+# Edit your pages and configuration.
+npx 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.
+
+## Find documentation
+
+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
+```
+
+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
+
+Use separate entry configs with the same `site.contentDir` and shared `extends`
+presets. Each site can have its own title, origin, base path, theme, navigation,
+and output directory. `site.contentFilter` selects whole pages using any
+configured `readerFilters` facet, including audience, product, area, subarea,
+and custom facets. For example:
+
+```yaml
+extends: [./base.yaml]
+site:
+  title: Developer resources
+  origin: https://developers.example.com
+  contentFilter: { audience: [developer] }
+```
+
+Every named facet must match at least one selected choice. Unmarked pages are
+excluded; mark shared pages with all applicable choices. Unknown or empty
+selectors and selections with no published pages fail. Omit the selector to
+publish all otherwise eligible pages. Keep navigation and links inside the
+selected set. Selected pages retain their full body; this is page selection,
+not section redaction or host authorization.
+
+See [the runnable faceted-sites example](example-configs/faceted-sites/README.md)
+for main, developer, and regional sites built from one source directory.
+
+## Export content into an application
+
+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/
+```
+
+The command writes `manifest.json`, resolved Markdown, passive HTML fragments,
+referenced local assets, and `NOTICES.txt`. It does not require navigation,
+facets, a previous website build, or a Shoalrun runtime in the app. Your app maps
+stable document IDs to the exported files and owns its UI and routing.
+
+For a reusable selection, define an `exports` target:
+
+```yaml
+exports:
+  app-help:
+    formats: [markdown, html]
+    documents: [guide.api-keys, guide.billing]
+    publicBase: /help/
+```
+
+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;
+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
+keep every panel or step. Interactive browser modules are not exported.
+
+Document links use bundle locations and typed manifest targets for in-app routing.
+Omitted documents need an eligible canonical website destination. `publicBase`
+must match the bundle's app mount so images work from arbitrary app routes.
+`/help/` is an example: choose another root-relative path, such as `/resources/`,
+and update the app's manifest URL and server mount to match. The `--out`
+filesystem directory can have a different name from the URL path.
+Local assets default to the content directory; explicit `assetRoots` extend that
+boundary. Remote images remain external and are reported. API material retains
+the source-review gate; `--review` produces a review candidate and exits 2 when
+approval is needed. Unavailable targets and unsupported content fail before an
+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
+website navigation, search/chat runtimes, themes, or heuristic section resources.
+
+## Publish discovery files
+
+Set `site.origin` to the HTTPS origin (for example, `https://example.github.io`)
+and `site.basePath` to the mount path (for example, `/my-docs`). With indexing
+enabled, the origin enables canonical URLs and an XML sitemap. The generated
+`llms.txt` links to that sitemap when available. Without an origin, Shoalrun
+still publishes Markdown and documentation indexes, but omits the sitemap.
+
+For a site mounted below a path, the generated `robots.txt` lives under that
+path. Crawlers consult `/robots.txt` at the host root; configure that file at
+the host level if needed. A project-path robots file does not control the host.
+
+Shoalrun generates `llms.min.txt` and `llms.txt`, not `llms-full.txt`. Any custom
+full-document export must rewrite source-relative links to published URLs and
+retain each document's public source URL. Write page summaries that describe
+which questions the page answers; the generated indexes reuse those summaries.
+
+Compact discovery indexes have a 2,000-token limit (`cl100k_base`). Small sites
+list pages directly. Larger sites link to topic indexes, grouped by publication
+and primary taxonomy area (or page type when no area is declared). Growing topics
+split into narrower indexes automatically. Follow a matching topic or title range
+until you reach a page; every published page remains reachable, including pages
+outside navigation. Standalone sections retain their sizes and full-page links.
+Navigation-section indexes use the same limit. `llms.txt` remains the complete
+catalog and is optional for topic-based discovery. Consumers must follow index
+links instead of assuming every page appears directly in `llms.min.txt`.
+
+The limit applies to each index response, not an entire multi-step reading session.
+An individual title or summary too large to fit an index produces an explicit
+build error rather than silently dropping content.
+
+## Status and development
+
+This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
+
+Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
+
+Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
+
+## 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.

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

@@ -0,0 +1,33 @@
+# Changelog
+
+Full-page token counts use cl100k_base. Navigation section ID: changelog-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.
+
+- [Agent discovery, verified Markdown, and incremental sync](https://www.shoalrun.com/changelog/2026-10-14-agent-readiness.md) — ID: change.agent-readiness. changelog-entry; 549 tokens. Compact discovery, content verification, and incremental fetching.
+
+- [Agent reading and evaluation](https://www.shoalrun.com/changelog/2026-10-15-evaluation-builds.md) — ID: change.evaluation-builds. changelog-entry; 1699 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; 671 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; 1291 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; 1226 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; 554 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; 469 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; 381 tokens. Project discovery and captured working-tree validation.
+
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1002 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; 1148 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; 1095 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; 671 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; 749 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; 481 tokens. Agent discovery, native editing, validation, and snapshot review.

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

@@ -0,0 +1,24 @@
+# Docs
+
+Full-page token counts use cl100k_base. Navigation section ID: docs. 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/docs-50f26fe22670-indexes/ea97da4000b0c4ddfd69fa8c.txt): scoped index.
+
+- [Site appearance](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/ccbd7ed463b8cd3112e9740e.txt): scoped index.
+
+- [Authoring](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/b240b4f0095dcac710d3d244.txt): scoped index.
+
+- [Content components](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/0192a1b49bb31c8f8d9bce80.txt): scoped index.
+
+- [Search & discovery](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/adbd3bda7ff4c15a893b0dbd.txt): scoped index.
+
+- [Project](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/9accc04fcdbda3d485b38406.txt): scoped index.
+
+- [Publishing](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/90e999b5c3e3ef0d2bd3ce4e.txt): scoped index.
+
+- [Quality & measurement](/.well-known/shoalrun/navigation/docs-50f26fe22670-indexes/e27cd9625df147549caa6261.txt): scoped index.

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

@@ -0,0 +1,9 @@
+# Project updates
+
+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.
+
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1653 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/SNAPSHOT.json

@@ -0,0 +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=="
+}

package/agent-docs/about.md

@@ -0,0 +1,49 @@
+---
+id: guide.about
+title: About Shoalrun
+summary: Learn what Shoalrun is exploring and where the alpha stands.
+type: overview
+area: project
+subarea: project-overview
+canonical: /about
+---
+
+# About Shoalrun
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+**Updated: 2026-10-27.**
+
+I'm CT Smith, and I'm building Shoalrun cause there's no such thing as a perfect doc tool. I have opinions, undirected rage, and curiosity about doc-building tools. I built my first documentation generator back in 2015. It was based on Jekyll and relied heavily (probably too heavily) on general templating and... you guessed it... *page metadata*.
+
+Shoalrun is part art project, part portfolio piece, and part laboratory. I use it to push the limits of content and tooling in whatever domain I'm working in.
+
+I had a lot of sources of inspiration (both negative and positive) from my years as a tech writer and tooling lover. I wanted to build something maximally flexible that also could keep things on the rails. I wanted something that uses frontmatter for deterministic features that *feel* like AI. I also wanted to play with what a BYO search and chat hookup could look like. And also leave room for others to use as much AI as they want.
+
+I wanted to chew on how to give human and AI readers content that works for them without cognitive—or contextual???—overload. No, I'm not saying AI has true cognition; stick with me here. I want flashy interactive components that help humans understand a concept. I also want agents to get the useful information without the extra junk—and WITHOUT extra authoring work.
+
+I centered the design with this project around making everything for two audiences: humans and agents. Not one above the other because it's honestly trivial to give them both what they need.
+
+I guess the more polished marketing-friendly summary is:
+
+> One source can serve different readers without fuss. Shoalrun lets authors shape the browser experience and choose what enters agent-facing Markdown. Authors can add content for one format when readers need different explanations. The framework also provides settings and extension points for the rest of a documentation site.
+
+## What makes Shoalrun special
+
+What interests me most is the interconnectedness that comes from treating information as a first-class object. Each doc has its own identity, metadata, and relationships. Its stable ID connects links, navigation, cards, and related reading, so I can move the source file without breaking those connections. [See how Shoalrun works](https://www.shoalrun.com/concepts.md).
+
+I want config to be composable, too. I can keep navigation, API sources, templates, and other settings in small YAML files. Includes and presets combine them; I can trace each value's source. The project can grow without forcing every concern into one config file. [See configuration composition](https://www.shoalrun.com/configuration.md).
+
+Presenting and linking content for humans and agents are first-class features. A rich component has an explicit form in both the browser and the page's Markdown twin. The build can turn one accepted source into interactive HTML, agent-readable Markdown, `/llms.txt`, and a document manifest. It rejects unsupported dynamic MDX instead of silently dropping content. Authors can still write a section for just one output when that reader needs a different explanation. [See agent-friendly output](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+This structure also makes workflows easier to connect. An ingredient can be reused in a complete recipe, and a cookbook can assemble the reviewed recipes a reader selects into one path. [See recipes and cookbooks](https://www.shoalrun.com/author/recipes.md).
+
+API content follows the same approach. Local OpenAPI files can supply reference pages, examples, and focused contracts for individual operations. A public build requires a review digest for imported API content, so a changed source returns to review before publication. [See API review](https://www.shoalrun.com/publish/api-references.md).
+
+I'm building Shoalrun for tinkerers like me, who will never be fully satisfied with a mass market docs tool. Docs are never one-size-fits-all, on any level.
+
+You can try the alpha CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
+
+yee haw forever,
+
+CT

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

@@ -0,0 +1,68 @@
+---
+id: guide.focused-contracts
+title: Focused OpenAPI contracts
+summary: Give tools one operation and its required schemas without the rest of
+  the API source.
+type: reference
+area: api
+subarea: api-contracts
+canonical: /api-docs/focused-contracts
+---
+
+# Focused OpenAPI 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)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Focused OpenAPI contracts
+
+**Updated: 2026-10-26.**
+
+A **focused contract** is a generated OpenAPI JSON file for one operation. It contains that operation's path and method, parameters, request and response definitions, named examples, and the schemas and security schemes those definitions use. The build resolves local references so the file stands on its own. Each API reference page links to its focused contract.
+
+## Why use one
+
+An API reference page is made for reading. A focused contract gives an agent, test tool, or client generator the exact machine-readable shape of the operation. A large OpenAPI source can contain many unrelated operations and schemas; the focused file keeps the context to what this operation needs. It is also useful when the full source should stay internal but a selected operation can be published.
+
+## Generate and inspect it
+
+Set `focused: true` on a local API source. The source can stay unpublished:
+
+```yaml title="config/api.yaml"
+notes:
+  source:
+    kind: file
+    path: ../apis/notes/openapi.yaml
+    focused: true
+  operations:
+    - id: notes.create
+      sourceOperationId: createNote
+      reference: reference.create-note
+```
+
+The build writes a JSON file under `/api/operations/` and links to it from the API reference page. If `publish: true` also publishes the source OpenAPI file, the focused contract is generated automatically. Open the [Create a note reference](https://www.shoalrun.com/example-api/create-note.md), then follow its **Download JSON** link to inspect the output from this site's fictional API. That site's full [OpenAPI source](https://www.shoalrun.com/api/notes/production/current/openapi.yaml) is published too, so you can compare them.
+
+Before a normal build publishes the contract, review the local candidate and pin the API's `publicReview.digest` as described in [API references](https://www.shoalrun.com/publish/api-references.md). The review covers the contract's transitive schemas and examples as well as the page that links to it.
+
+The focused contract describes the selected operation, not the entire API. Use the full source when a tool needs operations outside that page.
+
+## What the export keeps and drops
+
+- It keeps the selected path and method, their parameters, and the schemas, examples, and security schemes they reference. The root `servers` and `security` carry over, and `tags` lists only the operation's tags.
+- It drops every `x-*` extension key, so vendor extensions and internal notes stored there stay out of the public file.
+- It supports local OpenAPI 3.0.x and 3.1.x files with internal and multi-file references. Referenced files must stay inside the main OpenAPI file's directory, including after resolving symlinks. Absolute local paths are rejected. A Path Item `$ref`, or a JSON Schema `$id`, `$anchor`, `$dynamicRef`, or `$dynamicAnchor`, stops the build.
+
+The URL pattern is `/api/operations/<channel>/<version>/<language>/<name>-<sha256>.json`. The suffix is the full SHA-256 of the generated JSON bytes. Changing the contract changes its URL; an unchanged contract keeps the same URL. Earlier prototype filenames hashed the operation ID, which did not provide this property.
+
+The generated hosting metadata gives these URLs `Cache-Control: public, max-age=31536000, immutable` and a strong ETag containing the same digest. The Node server applies these headers, and the Vercel adapter includes them in its routing configuration. A CDN can replace the ETag with its own validator. Use the returned ETag for conditional requests and the manifest's `focusedContractDigest` to verify downloaded bytes. Mutable Markdown and JSON indexes require revalidation. Other hosts must apply the generated cache policy. Old builds are not archived automatically, so the URL identity does not guarantee permanent availability. To check every contract in a built site, run `shoalrun api focused-audit <site-directory>`. The [CLI reference](https://www.shoalrun.com/cli.md) lists what it checks.
+
+## Related reading
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Check every focused contract in a built site with api focused-audit.
+
+### Related topics
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Focused contracts are how agents find exact API details without the full spec.

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

@@ -0,0 +1,189 @@
+---
+id: guide.api-generation
+title: Generate and select API pages
+summary: Choose operations, generate reference pages, and add editorial context
+  to an API reference.
+type: how-to
+area: api
+subarea: api-generation
+canonical: /api-docs/generate
+---
+
+# Generate and select API pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Generate and select API pages
+
+**Updated: 2026-10-26.**
+
+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.
+
+## Choose generated references or MDX
+
+Use build-time generated references when the OpenAPI contract already gives readers the method, path, parameters, schemas, and examples they need. The pages update whenever the reviewed source changes, and there are no MDX files to maintain. Use an authored MDX reference when an endpoint needs a reviewed introduction, prerequisites, limitations, or task-specific context that the contract cannot express. The compiler still appends the contract details from OpenAPI, so do not copy field tables and example payloads into MDX. Use a guide for a task spanning several endpoints; link its reference pages with `relatedApiReferences`.
+
+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}'
+```
+
+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.
+
+Each new page has a stable document ID, slug, operation binding, and `access.policy: draft`. The draft contains an editorial prompt. While it remains a draft, any already selected build-time reference continues to publish. Review the text, replace the prompt, then set access to `public`; that MDX page takes the generated page's place for its publication. This also works when `generateReferences` is off: the authored page binds to the registered API's local OpenAPI source. The command never enables build-time generation, changes the public review digest, or chooses navigation order for you. Run `api review` before publishing changed API content, and place the reference with `operation:` or `doc:` in navigation if it is not already covered by a generator.
+
+## Generate many pages selectively
+
+For a large API, set `generateReferences` on its API config. This avoids writing one MDX file and registry entry for every operation. The build scans the local spec and creates HTML and Markdown reference pages for selected operations. An explicit `operations` entry and authored page take precedence for that operation. The example [Create a note page](https://www.shoalrun.com/example-api/create-note.md) is authored, while its [Get a note page](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) is generated.
+
+The example below uses this site's [two-operation Notes source](https://www.shoalrun.com/api/notes/production/current/openapi.yaml), which contains `createNote` and `getNote`. To try it after the tutorial, replace your one-operation `apis/notes/openapi.yaml` with that source first. Keep the authored Create a note page and its binding. Store the generation choices in a separate config file:
+
+```yaml title="config/api.yaml"
+notes:
+  publicReview:
+    digest: <digest-from-your-api-review>
+  source: { kind: file, path: ../apis/notes/openapi.yaml, publish: true }
+  operations:
+    - { id: notes.create, sourceOperationId: createNote, reference: reference.create-note }
+  generateReferences: { $include: ./notes-pages.yaml }
+```
+
+```yaml title="config/notes-pages.yaml"
+pathPrefix: /example-api/generated
+include: [getNote]
+```
+
+`include` lists source `operationId` values to generate; an empty list generates none. You can use `exclude` instead to generate all but named operations, or set `generateReferences: true` to generate every operation without an authored binding. The build rejects unknown selection IDs. Generated IDs and URLs derive from the API ID and source `operationId`, not the operation summary, so editing a title does not move the page. If an `operationId` changes, add an authored binding when the old public identity must remain stable.
+
+For an API `notes` and `operationId: getNote`, the generator creates:
+
+| Value               | Pattern                                                    | Example                                    |
+| ------------------- | ---------------------------------------------------------- | ------------------------------------------ |
+| Stable operation ID | `<apiId>.<operationId>`                                    | `notes.getNote`                            |
+| Page ID             | `reference.<apiId>.<operationId>`                          | `reference.notes.getNote`                  |
+| Slug                | `<pathPrefix>/<kebab-case operationId>-<8-character hash>` | `/example-api/generated/get-note-cbedb319` |
+
+`pathPrefix` defaults to `/reference/<apiId>`. An `operationId` with characters outside letters, digits, `.`, `_`, and `-` uses the kebab-case name plus the hash in place of the raw ID. Use the page ID in `relatedApiReferences` and the stable operation ID in navigation `operation:` entries. Generated pages pass through [global frontmatter](https://www.shoalrun.com/author/frontmatter.md) defaults and enforced values, so an enforced value or a required custom field applies to them too. The page title is the operation `summary`, or the method and path when there is no summary.
+
+OpenAPI 3.1 `webhooks` can use the same authored bindings or generated-page selection. A webhook reference labels the inbound event, shows the request payload and expected acknowledgement, and omits the outbound cURL example. A focused contract for that page keeps the operation under `webhooks`. A spec can contain only `webhooks` without `paths`.
+
+You can place an MDX guide among operation links in `navigation` by adding a `doc:` entry in the same group. Generated tag groups can sit before or after that entry; a guide within a particular tag can sit beside that tag's `{ id: tag-remaining, generated: remaining }` entry.
+
+## Override generated reference order in navigation
+
+`generateReferences` chooses which reference pages exist. The `navigation` list chooses where they appear. **You can put a generated reference's stable operation ID in an `operation:` entry to override its OpenAPI tag group and source order. No MDX page is needed.** Write those entries in the exact order readers should see them, then use `generated: tags` to place only the operations you did not list.
+
+```yaml title="config/nav.yaml"
+- id: widgets
+  label: Widgets
+  items:
+    - { id: get-widget-nav, operation: widgets.getWidget }
+    - { id: query-widgets-nav, operation: widgets.queryWidgets }
+    - { id: create-widget-nav, operation: widgets.createWidget }
+    - { id: other-widgets, api: widgets, generated: tags }
+```
+
+Here `GET /Query/widgets` may have the OpenAPI tag `Query`, but its generated reference appears second under **Widgets**. The listed operations appear in this YAML order, regardless of their path, tag, or position in the OpenAPI file. They are removed from the `generated: tags` remainder, so each appears once. The `id` fields such as `query-widgets-nav` identify menu entries; `operation` values are the stable IDs that select the reference pages. An authored MDX reference uses the same navigation rule. See [Organize site navigation](https://www.shoalrun.com/author/navigation.md) for the full layout.
+
+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
+```
+
+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.
+
+The digest shown above is a placeholder. Keep your existing review digest while editing. After reviewing the new selection, replace it with the reported value. Selection limits generated pages; `source.publish: true` still publishes the full source, including operations without pages. Use `focused: true` and omit `publish` when you only need individual operation contracts.
+
+## Use a template for editorial context
+
+Use the built-in `api-reference` template for details OpenAPI cannot supply, such as operational context, task links, prerequisites, and limitations. Keep method, path, field lists, and example values in the spec so generated references have one source for those facts.
+
+```sh
+shoalrun scaffold api-reference -n content/create-enrollment.mdx \
+  --id reference.create-enrollment --operation cedar.createEnrollment
+```
+
+No template registration is needed. The scaffold requires exactly one known stable operation ID. Check that the page ID matches that operation's `reference` entry in API config. A scaffold is a draft; replace every prompt and review the operation against the spec before publishing. The [Templates guide](https://www.shoalrun.com/author/templates.md) shows how to override the built-in outline for your project. Editing a template later affects new drafts, not existing pages.
+
+## Add useful examples
+
+API reference pages display the examples defined in the OpenAPI file; the build does not invent them. Give each example a clear name and include the fields a reader needs to use it. In this site's Notes spec, [Create a note](https://www.shoalrun.com/example-api/create-note.md) has request and response examples. [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) has a note ID and a response example.
+
+The right panel offers **Examples** first when the spec provides them, plus a **JSON shape** view built from each JSON request or response schema. Shape values are type placeholders, not a runnable payload. Request and response examples stay in separate groups, with response status and media type in each heading. Groups of three or fewer use native disclosures. Larger groups use a compact selector with one visible preview when JavaScript is available; without JavaScript, every disclosure remains usable. The Create a note request has ten named examples so you can inspect this layout. Direct links still open the selected example.
+
+Local named request examples for ordinary, non-multipart operations also have copyable request samples. In HTML, each sample has a language selector. It offers cURL, JavaScript, Node.js, Python, Go, Java, PHP, Ruby, and C#. Webhooks have no generated request samples. A sample uses the first declared server and security option, required parameters, the example body, and its media type. Replace `YOUR_` credential and parameter placeholders before using it. Ordinary operations without a request body show a general request sample. An operation with a request body but no local named request examples usually shows no sample. A multipart body whose required fields are all binary strings can produce a file-upload sample in cURL only. An `externalValue` example has no example-specific sample. These samples are generated from the OpenAPI source and have not been executed. **The Markdown twin and agent bundle keep only the cURL sample.** Agents can translate cURL; one canonical sample keeps the `.md` output small.
+
+An OpenAPI `summary` names an example, and `description` adds context. Without a summary, the reader turns its source key into a readable title and still shows the original key. A response without an example still has a shape: Get a note's `404` response shows `code` and `message` as strings. The full field descriptions and presence rules remain in the main reference and its Markdown twin.
+
+If a guide shows only part of a payload to explain one field, call it an excerpt. Readers can then distinguish it from a complete request or response. To show a full named example from the spec in a guide, use [`ApiExample`](https://www.shoalrun.com/author/components/api-embeds.md). It stays tied to the same source as the API reference.
+The build expands that include in the guide's Markdown twin as a heading, source context, and a fenced payload or external example link. Agents can read the selected example directly in the `.md` page; the [API embeds guide](https://www.shoalrun.com/author/components/api-embeds.md) shows the exact output.
+
+## Link guides to API references
+
+Add `relatedApiReferences` to a guide or how-to page to name API reference pages by stable document ID:
+
+```yaml title="docs/content/write-note.mdx"
+relatedApiReferences:
+  - reference.create-note
+  - reference.notes.getNote
+```
+
+This array contains two page IDs. One points to the authored Create a note reference; the other points to the generated Get a note reference. The build adds a **Related API references** list to the guide and a **Related guides** list to each named reference. Links use the current page titles and routes, so they stay correct when a slug changes. The lists appear in HTML and the Markdown twins. A missing ID or an ID for another page type fails the build; a reference unavailable in the guide's publication is omitted.
+
+The [Write a note guide](https://www.shoalrun.com/example-api/write-note.md) uses this field to link to the [Create a note reference](https://www.shoalrun.com/example-api/create-note.md). You can inspect the generated lists at the bottom of both pages.
+
+## Map extension values to Shoalrun status
+
+If a spec uses an `x-*` extension for availability, explicitly map its values to Shoalrun's status badges in the API config. This works with extension names from any OpenAPI authoring service:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml }
+  mappings:
+    subjectLifecycle:
+      from: x-vendor-availability
+      values:
+        preview: beta
+        building: in-development
+        retired: deprecated
+```
+
+Only mapped values change a page's status. OpenAPI `deprecated: true` always yields **Deprecated**. An authored page can also set `subjectLifecycle` directly. The [OpenAPI extension mappings reference](https://www.shoalrun.com/publish/openapi-extension-mappings.md) specifies accepted scalar and nested value shapes, precedence, and how other extensions are handled.
+
+## Describe filters that do not use their OpenAPI parameter name
+
+Some APIs put filter expressions directly in the query string even though their OpenAPI description has one placeholder parameter. Opt in by path prefix so examples and generated cURL use the actual wire form:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml }
+  querySyntax:
+    - parameter: filters
+      pathPrefixes: [/Query/]
+      style: unwrapped
+      example: FIELD(eq)=VALUE
+```
+
+For a matching operation, the reference explains the direct `?FIELD(eq)=VALUE` form and omits `filters=` from its generated cURL. The source's notes on accepted fields stay in a disclosure. Named examples with one field and value supply a more specific cURL filter. Other endpoints keep ordinary OpenAPI parameter behavior.
+
+Next, [organize generated operations in navigation](https://www.shoalrun.com/author/navigation.md).
+
+## Related reading
+
+### Read first
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register and review an API source before generating its pages.
+
+### Next steps
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
+
+### Related topics
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Generate the API reference pages that fill a tag group in the menu.