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

package/agent-docs/publish/agent-friendliness.sections/try-the-page-controls.md

@@ -0,0 +1,62 @@
+---
+id: guide.agent-friendliness
+title: Agent-friendly documentation
+summary: See how interactive docs become readable Markdown, then discover pages
+  and verify their contents.
+type: explanation
+area: discovery
+subarea: discovery-agents
+canonical: /publish/agent-friendliness
+---
+
+# Agent-friendly documentation
+
+> 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) > Search, chat, and agent access > Agent-friendly documentation
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/agent-friendliness.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Know which HTML, Markdown, and manifest files the build writes.
+
+**Next steps**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Connect a tool-capable client to bundled or built documentation.
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
+
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+
+The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+
+Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+## Try the page controls
+
+### Command line
+
+Send the request from a terminal.
+
+### Application
+
+Send the request from application code.
+
+### Retry detail
+
+Retry only after checking whether the first request succeeded.
+
+**For Reader: UI reader.**
+
+Open the activity screen to inspect the result.
+
+**For Reader: Developer.**
+
+Inspect the response status and returned identifier.

package/agent-docs/publish/agent-friendliness.sections/use-the-transport-your-client-supports.md

@@ -0,0 +1,50 @@
+---
+id: guide.agent-friendliness
+title: Agent-friendly documentation
+summary: See how interactive docs become readable Markdown, then discover pages
+  and verify their contents.
+type: explanation
+area: discovery
+subarea: discovery-agents
+canonical: /publish/agent-friendliness
+---
+
+# Agent-friendly documentation
+
+> 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) > Search, chat, and agent access > Agent-friendly documentation
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/agent-friendliness.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Know which HTML, Markdown, and manifest files the build writes.
+
+**Next steps**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Connect a tool-capable client to bundled or built documentation.
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
+
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+
+The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+
+Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+## Use the transport your client supports
+
+A fetch-only agent can read the published files over HTTP. It needs no CLI, repository access, JavaScript, or MCP connection. Hosts must serve Markdown with the correct media type and apply content negotiation at HTML page URLs. Missing Markdown pages return HTTP `404` with compact recovery links. The [hosting and negotiation reference](https://www.shoalrun.com/publish/content-negotiation.md) describes the contract; verify it on the deployed host.
+
+The Shoalrun npm package also bundles this framework's own documentation. `shoalrun docs search` and `shoalrun docs read` use that bundle by default; `--site DIRECTORY` selects another built site. These are local tools for users with the package, not requirements imposed on public readers.
+
+`shoalrun docs mcp` exposes the local search/read core over stdio. You can also [connect to this site’s public HTTP MCP endpoint](https://www.shoalrun.com/connect/mcp.md). The local read tool applies a token budget and can truncate a response; fetch the published twin when you need complete bytes for digest verification. See [the MCP reference](https://www.shoalrun.com/publish/mcp.md) for its current contract.
+
+Shoalrun does not automatically generate a reader skill for every site. Its maintained authoring skills guide an author's existing agent through writing and validation; teams remain responsible for reviewing their instructions. The [non-goals](https://www.shoalrun.com/non-goals.md) explain that boundary.

package/agent-docs/publish/agent-friendliness.sections/verify-the-page-and-detect-changes.md

@@ -0,0 +1,58 @@
+---
+id: guide.agent-friendliness
+title: Agent-friendly documentation
+summary: See how interactive docs become readable Markdown, then discover pages
+  and verify their contents.
+type: explanation
+area: discovery
+subarea: discovery-agents
+canonical: /publish/agent-friendliness
+---
+
+# Agent-friendly documentation
+
+> 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) > Search, chat, and agent access > Agent-friendly documentation
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/agent-friendliness.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Know which HTML, Markdown, and manifest files the build writes.
+
+**Next steps**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Connect a tool-capable client to bundled or built documentation.
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
+
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+
+The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+
+Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+## Verify the page and detect changes
+
+Page identity is the stable document ID plus channel, version, and language. Different publication variants can share an ID, so comparing IDs alone can confuse their records.
+
+The manifest exposes three distinct signals:
+
+| Signal               | What it establishes                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Page `digest`        | SHA-256 of the complete generated Markdown bytes. Compare it with the bytes you fetched.                     |
+| Page `contentDigest` | A resolved article-content fingerprint used for freshness tracking. It is not the hash of the Markdown file. |
+| Top-level `buildId`  | Identity of the assembled publication, including pages, contracts, assets, and metadata.                     |
+
+An author-set `verified` date is also available in the manifest. It records supplied review metadata, separately from `updated`; it is not proof that an external reviewer approved the page.
+
+For a long-lived client, save the sync snapshot and poll the small build-information file. An unchanged build ID means the saved inventory still applies. When the ID changes, compare the current snapshot with the saved one and refresh added or changed pages. Remove records that disappeared. The comparison includes route moves, metadata changes, and removed publication variants.
+
+The local command is `shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SNAPSHOT`. Static hosts retain no snapshot history; clients keep their own baseline. If a deployment changes between the manifest and page requests, retry until the fetched Markdown matches its advertised digest. The [published outputs reference](https://www.shoalrun.com/publish/output.md) gives the fields, comparison procedure, and limits.

package/agent-docs/publish/agent-friendliness.sections/what-an-agent-reads.md

@@ -0,0 +1,68 @@
+---
+id: guide.agent-friendliness
+title: Agent-friendly documentation
+summary: See how interactive docs become readable Markdown, then discover pages
+  and verify their contents.
+type: explanation
+area: discovery
+subarea: discovery-agents
+canonical: /publish/agent-friendliness
+---
+
+# Agent-friendly documentation
+
+> 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) > Search, chat, and agent access > Agent-friendly documentation
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/agent-friendliness.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Know which HTML, Markdown, and manifest files the build writes.
+
+**Next steps**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Connect a tool-capable client to bundled or built documentation.
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
+
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+
+The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+
+Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+## What an agent reads
+
+Here is the Markdown generated from the example above. An agent does not need to click the tabs, expand the disclosure, or choose a reader to get these instructions.
+
+```md
+### Command line
+
+Send the request from a terminal.
+
+### Application
+
+Send the request from application code.
+
+### Retry detail
+
+Retry only after checking whether the first request succeeded.
+
+**For Reader: UI reader.**
+
+Open the activity screen to inspect the result.
+
+**For Reader: Developer.**
+
+Inspect the response status and returned identifier.
+```
+
+The labels become headings or ordinary text. The controls themselves are omitted. This site's test compares the example's generated Markdown with the text shown here so they cannot drift apart unnoticed. The [reader views reference](https://www.shoalrun.com/author/reader-views.md) explains how authors configure those choices.

package/agent-docs/publish/agent-friendliness.sections/what-happens-to-an-unsupported-component.md

@@ -0,0 +1,60 @@
+---
+id: guide.agent-friendliness
+title: Agent-friendly documentation
+summary: See how interactive docs become readable Markdown, then discover pages
+  and verify their contents.
+type: explanation
+area: discovery
+subarea: discovery-agents
+canonical: /publish/agent-friendliness
+---
+
+# Agent-friendly documentation
+
+> 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) > Search, chat, and agent access > Agent-friendly documentation
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/agent-friendliness.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Know which HTML, Markdown, and manifest files the build writes.
+
+**Next steps**
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Connect a tool-capable client to bundled or built documentation.
+
+- [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
+
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+
+The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+
+Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
+
+## What happens to an unsupported component?
+
+A component needs rendering support for both HTML and Markdown. The compiler calls that support an **adapter**. If a page uses an unknown component such as the one below, Shoalrun stops rather than publishing a Markdown file that silently loses its contents.
+
+```mdx
+<UnregisteredPanel>
+
+This instruction must not disappear.
+
+</UnregisteredPanel>
+```
+
+Running `shoalrun check docs.config.yaml` reports a diagnostic containing:
+
+```text
+<UnregisteredPanel> has no semantic/Markdown adapter
+```
+
+The example is displayed as code here so you can read it. A test also runs it as an actual component, checks that compilation fails, and verifies that the previous successful output remains intact. This check establishes how unsupported components are handled; it does not prove that every supported component or authored instruction is correct.

package/agent-docs/publish/api-references.md

@@ -0,0 +1,219 @@
+---
+id: guide.api-references
+title: Add an OpenAPI API
+summary: Import a local OpenAPI file, author an operation page, review its
+  public content, and build HTML and Markdown.
+type: how-to
+area: api
+subarea: api-contracts
+canonical: /publish/api-references
+---
+
+# Add an OpenAPI API
+
+> 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 > Add an OpenAPI API
+
+**Updated: 2026-10-27.**
+
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+
+Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
+
+## Put the spec in your project
+
+Create `apis/notes/openapi.yaml` with this complete fictional API. It documents a response without calling a live service:
+
+```yaml title="apis/notes/openapi.yaml"
+openapi: 3.1.0
+info: { title: Example Notes API, version: 1.0.0 }
+paths:
+  /notes:
+    post:
+      operationId: createNote
+      summary: Create a note
+      responses:
+        '201':
+          description: The note was created.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [id]
+                properties:
+                  id: { type: string, description: The new note identifier. }
+              examples:
+                created:
+                  summary: A created note
+                  value: { id: note_123 }
+```
+
+OpenAPI 3.0 or 3.1 YAML and JSON files are accepted. There is no required directory name; a spec can also reference other local files.
+
+## Register the operation
+
+Add this top-level entry to your existing `docs.config.yaml`:
+
+```yaml title="docs.config.yaml"
+apis: { $include: ./config/api.yaml }
+```
+
+Create the `config` directory if needed and add `config/api.yaml`:
+
+```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
+```
+
+`source.path` is relative to the config fragment that declares it. `notes` names this API, and `sourceOperationId` selects the spec's `operationId`. The stable operation ID `notes.create` connects the operation to authored pages; `reference` names the page that will present it. `focused: true` publishes a [one-operation contract](https://www.shoalrun.com/api-docs/focused-contracts.md).
+
+For your own API, if the source lives at a public HTTPS URL, import it into a local snapshot first. Replace the example URL below with your actual OpenAPI URL:
+
+```sh
+npx --no-install shoalrun api import https://api.example.com/openapi.yaml --output apis/remote
+```
+
+Point `source.path` at `../apis/remote/openapi.yaml` from `config/api.yaml`. Commit the snapshot and its `source-lock.json`. Normal builds use those local files and make no network request. To check for upstream changes, run `api refresh apis/remote --output apis/remote-next`. If the source changed, the command reports the changed hashes and writes a complete new snapshot while keeping `apis/remote` intact. Point `source.path` to `../apis/remote-next/openapi.yaml`, inspect a new `api review` candidate, and pin its digest before building. The [CLI reference](https://www.shoalrun.com/cli.md) lists import limits.
+
+## Author the reference page
+
+Create `content/create-note.mdx`:
+
+```mdx title="content/create-note.mdx"
+---
+id: reference.create-note
+title: Create a note
+summary: Create a note in the fictional Notes API.
+type: api-reference
+slug: /example-api/create-note
+channel: production
+version: current
+language: en
+operations: [notes.create]
+access: { policy: public }
+---
+
+This fictional operation returns the identifier of a new note. Its response
+schema and named example are generated from the local OpenAPI file.
+```
+
+The page ID must match the registry's `reference` value. An `api-reference` page lists exactly one operation. The compiler appends the method, path, parameters, authentication, schemas, and examples to your authored introduction.
+
+Append this entry to the existing `navigation` array in `docs.config.yaml`:
+
+```yaml
+  - id: notes-create
+    doc: reference.create-note
+```
+
+If your project includes navigation from another file, add the entry there. Save the page and navigation before the review so the candidate contains the page you intend to publish.
+
+## Review imported content before publishing
+
+Shoalrun requires `publicReview.digest` for every API whose content appears in a public page, embed, or focused contract. A missing or stale digest stops a normal build. Generate a local candidate in a fresh temporary directory:
+
+```sh
+API_REVIEW_DIR="$(mktemp -d /tmp/shoalrun-api-review.XXXXXX)"
+npx --no-install shoalrun api review docs.config.yaml --output "$API_REVIEW_DIR"
+```
+
+The command builds the candidate and reports each API's digest, page URLs, focused contracts, full-source downloads, and input hashes. Inspect the candidate files for private operations, fields, descriptions, examples, and credentials. For this example, check the Create a note HTML and Markdown page and its linked focused contract.
+
+Copy the reported digest for `notes` into `config/api.yaml` alongside `source` and `operations`:
+
+```yaml
+notes:
+  publicReview:
+    digest: <paste-the-reported-notes-digest>
+  # Keep source and operations here.
+```
+
+Replace the angle-bracket placeholder with the actual digest. Keep the candidate local and remove it after review. The digest records what you reviewed; it does not determine whether content is safe. Changing source bytes, selected operations or embeds, focused contracts, or full-source publication requires another review. Changing only authored page copy does not.
+
+## Build and verify the output
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun api focused-audit site-dist
+npx --no-install shoalrun serve site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/example-api/create-note/` and choose **Create a note** in the sidebar. Confirm the introduction, `POST /notes`, the `201` response with its required `id` field, and the named example. Open `http://127.0.0.1:8765/example-api/create-note.md` to check the same details as Markdown. Follow the focused contract link and check that it contains only this operation and its required contract data.
+
+The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they are not runnable payloads. Generated request commands have not been executed.
+
+For a larger live example of the documentation layout, see the [fictional Create a note reference](https://www.shoalrun.com/example-api/create-note.md). Its `archivedAt` response field is both **always present** and **nullable**: presence and nullability describe different things. A field marked **may be absent** can be omitted entirely.
+
+Next, [generate and select more API pages](https://www.shoalrun.com/api-docs/generate.md).
+
+## What readers get
+
+An authored reference adds editorial context to the operation contract. A [generated reference](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) includes the same contract details without an MDX introduction. For tasks spanning several operations, write a linked guide such as [Write a note](https://www.shoalrun.com/example-api/write-note.md). These fictional examples do not imply a live API or tested requests.
+
+Response status and media type share a heading row. Descriptions remain visible above property disclosures; enum choices appear below field descriptions. Markdown includes all of this without interactive controls. OpenAPI `deprecated: true` sets the page's status to deprecated; conflicting authored status values fail the build.
+
+## Next steps
+
+### Publish several versions
+
+[Put multiple versions on one site](https://www.shoalrun.com/publish/publications.md) explains sources for each publication and stable operation bindings across versions.
+
+### Map extension values to Shoalrun status
+
+Use the [extension mappings reference](https://www.shoalrun.com/publish/openapi-extension-mappings.md) to map vendor `x-*` values to status badges.
+
+### Describe filters that do not use their OpenAPI parameter name
+
+The [query syntax example](https://www.shoalrun.com/api-docs/generate.md) configures direct query expressions and generated cURL.
+
+### Generate many pages selectively
+
+[Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) covers include/exclude lists, stable generated IDs, webhooks, interactive selection, and tag navigation.
+
+### Use a template for editorial context
+
+[API reference templates](https://www.shoalrun.com/api-docs/generate.md) add editorial prompts without duplicating contract fields.
+
+### Add useful examples
+
+[Named examples and generated commands](https://www.shoalrun.com/api-docs/generate.md) explains example selection, JSON shapes, and cURL behavior.
+
+### Link guides to API references
+
+[Related API references](https://www.shoalrun.com/api-docs/generate.md) connects guides and references in both directions using stable page IDs.
+
+## Inspect the machine-readable contract
+
+[Focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) retain transitive schemas, examples, and security schemes for one operation. To publish the full source instead, set `source.publish: true`. That also enables focused contracts. A discovery endpoint must use HTTPS and needs `site.origin`; see [configuration](https://www.shoalrun.com/config.md).
+
+## Preview a small API reference
+
+Compare the authored [Create a note](https://www.shoalrun.com/example-api/create-note.md) and generated [Get a note](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) with their [fictional source](https://www.shoalrun.com/api/notes/production/current/openapi.yaml), Markdown twins, and focused contracts.
+
+The [Cedar Parcel styling lab](https://www.shoalrun.com/example-api/cedar.md) exercises direct query filters, conditional bodies, JSON and file responses, server and authentication overrides, extension mappings, and a webhook.
+
+## Related reading
+
+### Next steps
+
+- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
+
+### Reference while working
+
+- [Focused OpenAPI contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) — Give tools one operation and its required schemas.
+
+### Related topics
+
+- [Create a note](https://www.shoalrun.com/example-api/create-note.md) — A finished operation page built from a small, fictional OpenAPI file.
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Configure the stable operation ID and review the OpenAPI source used by an API ingredient draft.

package/agent-docs/publish/api-references.sections/author-the-reference-page.md

@@ -0,0 +1,65 @@
+---
+id: guide.api-references
+title: Add an OpenAPI API
+summary: Import a local OpenAPI file, author an operation page, review its
+  public content, and build HTML and Markdown.
+type: how-to
+area: api
+subarea: api-contracts
+canonical: /publish/api-references
+---
+
+# Add an OpenAPI API
+
+> 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 > Add an OpenAPI API
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/api-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
+
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+
+Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
+
+## Author the reference page
+
+Create `content/create-note.mdx`:
+
+```mdx title="content/create-note.mdx"
+---
+id: reference.create-note
+title: Create a note
+summary: Create a note in the fictional Notes API.
+type: api-reference
+slug: /example-api/create-note
+channel: production
+version: current
+language: en
+operations: [notes.create]
+access: { policy: public }
+---
+
+This fictional operation returns the identifier of a new note. Its response
+schema and named example are generated from the local OpenAPI file.
+```
+
+The page ID must match the registry's `reference` value. An `api-reference` page lists exactly one operation. The compiler appends the method, path, parameters, authentication, schemas, and examples to your authored introduction.
+
+Append this entry to the existing `navigation` array in `docs.config.yaml`:
+
+```yaml
+  - id: notes-create
+    doc: reference.create-note
+```
+
+If your project includes navigation from another file, add the entry there. Save the page and navigation before the review so the candidate contains the page you intend to publish.

package/agent-docs/publish/api-references.sections/build-and-verify-the-output.md

@@ -0,0 +1,48 @@
+---
+id: guide.api-references
+title: Add an OpenAPI API
+summary: Import a local OpenAPI file, author an operation page, review its
+  public content, and build HTML and Markdown.
+type: how-to
+area: api
+subarea: api-contracts
+canonical: /publish/api-references
+---
+
+# Add an OpenAPI API
+
+> 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 > Add an OpenAPI API
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/api-references.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
+
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+
+Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
+
+## Build and verify the output
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun api focused-audit site-dist
+npx --no-install shoalrun serve site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/example-api/create-note/` and choose **Create a note** in the sidebar. Confirm the introduction, `POST /notes`, the `201` response with its required `id` field, and the named example. Open `http://127.0.0.1:8765/example-api/create-note.md` to check the same details as Markdown. Follow the focused contract link and check that it contains only this operation and its required contract data.
+
+The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they are not runnable payloads. Generated request commands have not been executed.
+
+For a larger live example of the documentation layout, see the [fictional Create a note reference](https://www.shoalrun.com/example-api/create-note.md). Its `archivedAt` response field is both **always present** and **nullable**: presence and nullability describe different things. A field marked **may be absent** can be omitted entirely.
+
+Next, [generate and select more API pages](https://www.shoalrun.com/api-docs/generate.md).