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

package/README.md

@@ -1,3 +1,192 @@
-# 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.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.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.
+
+## Create and preview a site
+
+Run these commands from the directory where you installed the package:
+
+```sh
+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 --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.
+
+## 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 --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.
+
+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 --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
+# Edit your pages and configuration.
+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.
+
+## Find documentation
+
+Read the documentation bundled with your installed version without a provider key or website connection:
+
+```sh
+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
+
+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 --no-install 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/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/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

@@ -0,0 +1,37 @@
+# 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.
+
+- [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.
+
+- [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

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "sourceRepository": "https://github.com/shoalrun/docs",
+  "sourceCommit": "0e40930cc80207ff9cb22fcaade5fc5dbdd464a5",
+  "siteBuildId": "1aae676cf02856842a383f9e8f28b2b126e18cfbc75050227980b1d3d82762b6",
+  "manifestDigest": "5b181b5e3d09eaae37afaf0f08ce5c725ea393029df4cec8ad62c44939b07fe7",
+  "indexDigest": "57736349c41e4b36d0b9726e76b512415b85443d49eababbd3387fa416c996c9",
+  "packageIntegrity": "sha512-NmM2tIR7SSyz8STTZluEsATZZBcTrgH6mWBTjOju7Qz3E60onSrQF93IXmBuhBiInw+Zq9mysUAk8Lvo/UDj6Q=="
+}

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: [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: [Reference](https://www.shoalrun.com/cli.md) > API support > 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.