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

package/agent-docs/publish/api-references.sections/inspect-the-machine-readable-contract.md

@@ -0,0 +1,36 @@
+---
+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.
+
+## 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).

package/agent-docs/publish/api-references.sections/next-steps.md

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

package/agent-docs/publish/api-references.sections/preview-a-small-api-reference.md

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

package/agent-docs/publish/api-references.sections/put-the-spec-in-your-project.md

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

package/agent-docs/publish/api-references.sections/register-the-operation.md

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

package/agent-docs/publish/api-references.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+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)
+
+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.
+
+## 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/review-imported-content-before-publishing.md

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

package/agent-docs/publish/api-references.sections/what-readers-get.md

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

package/agent-docs/publish/audit.md

@@ -0,0 +1,160 @@
+---
+id: guide.audit
+title: Audit a docs project
+summary: Run project tests and local API representation checks with one CI command.
+type: how-to
+area: quality
+subarea: quality-audits
+canonical: /publish/audit
+---
+
+# Audit a docs project
+
+> 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) > Publish and maintain > Audit a docs project
+
+**Updated: 2026-10-26.**
+
+Run `shoalrun audit` from a project directory before publishing. The command combines tests that your project configures with Shoalrun's build and API representation checks. It reports each result as JSON and exits with code `1` if any result fails.
+
+From `framework/`, this example needs no extra setup after `npm run build`:
+
+```sh
+node dist/cli.js audit example/docs.config.yaml
+```
+
+With no `audit` setting, Shoalrun runs the API source and focused-contract audits and builds the site. No project test commands run until you configure them.
+
+## Check before pushing
+
+Run this from your docs project:
+
+```sh
+shoalrun check
+shoalrun check docs.config.yaml --json
+```
+
+The first command discovers `docs.config.yaml` in the current directory or a parent and prints PASS/FAIL results. Use `--json` for a structured report in CI. A failed check exits with code 1. `shoalrun audit` runs the same checks and retains its JSON output.
+
+Checks include configured test commands, local OpenAPI sources, a complete temporary build, focused contracts, and local links. The build validates config, frontmatter, and supported MDX. YAML duplicate keys, excessive alias expansion, and cyclic aliases fail with a source-file diagnostic. OpenAPI inputs must declare a supported 3.0 or 3.1 version, an info title and version, and mapping-shaped paths.
+
+Link checks inspect generated HTML and Markdown. They verify local destinations and HTML fragments, including same-origin absolute links. Markdown fragments are not checked because heading rules vary between readers. Links in code samples are ignored. Built-in checks need no browser or running server and do not fetch external URLs. Existing site output is preserved; normal generated metadata can still be written under `.shoalrun/`.
+
+Add a package script to make the check easy to run:
+
+```json
+{ "scripts": { "docs:check": "shoalrun check docs.config.yaml" } }
+```
+
+An optional Git pre-push hook can run that script. Put these lines in `.git/hooks/pre-push` and make it executable with `chmod +x .git/hooks/pre-push`:
+
+```sh
+#!/bin/sh
+exec npm run docs:check
+```
+
+The CLI does not install hooks. Configured test commands can perform their own network requests or writes.
+
+To include a dependency check for a project with a package lock, configure:
+
+```yaml
+audit:
+  tests:
+    - id: dependencies
+      run: [npm, audit, --omit=dev]
+```
+
+This optional command contacts the npm registry. Omit `--omit=dev` to include development dependencies. Commands run beside the docs config; use npm's `--prefix` option when the package lives elsewhere.
+
+## Add project tests
+
+Add `audit` to `docs.config.yaml`. This example assumes your project has a `scripts/docs.test.mjs` file that Node's test runner can execute:
+
+```yaml title="docs.config.yaml"
+audit:
+  tests:
+    - id: project-tests
+      run: [node, --test, scripts/docs.test.mjs]
+  api: true
+  focusedContracts: true
+  links: true
+```
+
+Each test has a unique lowercase `id` (letters, digits, and hyphens) and a nonempty `run` list of strings. Shoalrun starts the executable in the first item and passes the rest as arguments. It does not invoke a shell, so shell operators, pipes, and redirection do not work in `run`. Tests run in list order from the directory containing the config file. They run before API audits and the build. A failing test does not stop the other tests or audits.
+
+Each test has a two minute timeout. Shoalrun captures its output and includes the last 16,000 characters in a failure finding. Successful test output is omitted from the report. Because the commands are executable code, review test entries before running an unfamiliar project. Set `audit.api: false` to skip local OpenAPI source audits, or `audit.focusedContracts: false` to skip focused-contract checks. Set `audit.links: false` to skip local link checks. All three default to `true`; the build always runs.
+
+## Connect a documentation test suite
+
+`audit.tests` is the hookup for an external test suite. We recommend [Doc Detective](https://docs.doc-detective.com/docs/get-started/how-testing-works) for testing documentation behavior, but you can run any installed command that exits nonzero on failure. Shoalrun passes the arguments and records the process exit status; the tool owns its test specifications, fixtures, assertions, and detailed results. For a project with Doc Detective installed locally and its configuration in `.doc-detective.json` beside `docs.config.yaml`:
+
+```yaml title="docs.config.yaml"
+audit:
+  tests:
+    - id: doc-detective
+      run: [npx, --no-install, doc-detective, --config, .doc-detective.json, --exit-on-fail]
+```
+
+The `--exit-on-fail` flag matters: Doc Detective's standalone CLI otherwise [can exit successfully when a test fails](https://docs.doc-detective.com/docs/ci/reporters-and-artifacts). `npx --no-install` uses the locally installed package without downloading one during the audit. Configure tests and report artifacts with Doc Detective. Shoalrun's audit report only records the command's success or failure and the end of its output on failure. To use another suite, replace the `run` list with its command and failure-exit option.
+
+Configured test commands run before Shoalrun's temporary site build. If a tool needs a built or deployed site, run it as a separate step after building or deploying. Shoalrun does not define a competing documentation assertion format or CLI, HTTP, or browser test engine.
+
+## Check agent evaluation reports
+
+Use [`audit.evals`](https://www.shoalrun.com/publish/evals.md) to import reviewed task results and check them against the temporary build. Task definitions, build freshness, citation IDs and publications, criterion judgments, and required outcomes are checked mechanically. Your team runs the agent and owns the review of its answers.
+
+```yaml title="docs.config.yaml"
+audit:
+  evals:
+    tasks: ./evals/tasks.yaml
+    report: ./evals/results.json
+```
+
+An optional `audit.evals.run` command executes after the build and receives the temporary site path, task/report paths, and their digests through environment variables. This differs from ordinary `audit.tests`, which run before the build. The eval command's exit status and report checks are separate results; passing one does not bypass the other. See [evaluate agent tasks](https://www.shoalrun.com/publish/evals.md) for the format, preparation commands, optional-task behavior, and limits. No evals run unless configured.
+
+## Read the report
+
+The default example produces this shape (counts and source paths depend on the project):
+
+```json
+{
+  "status": "ok",
+  "results": [
+    {
+      "id": "api:payments:default",
+      "status": "ok",
+      "findings": [],
+      "details": { "source": "/path/to/openapi.yaml", "operations": 1, "rendered": 1, "namedExamples": 7 }
+    },
+    { "id": "build", "status": "ok", "findings": [], "details": { "documents": 3 } },
+    { "id": "focused-contracts", "status": "ok", "findings": [], "details": { "contracts": 1 } }
+  ]
+}
+```
+
+Configured tests have IDs such as `test:project-tests`. Additional API publications use IDs such as `api:payments:publication-0`. A failing result has `status: "error"` and one or more `findings`, each with a `target` and `message`. The top-level status becomes `error`, and the process exits with code `1`. Config or command-line errors occur before a report can be produced; the CLI writes `{"status":"error","message":"..."}` to standard error instead.
+
+Shoalrun audits each configured local OpenAPI source, including sources that are not published. It checks operation IDs, unique HTML field anchors, and named examples in both representations. The build checks project content and writes a temporary site. If the build succeeds, the focused-contract audit checks each generated contract and its Markdown link. If the build fails, the report keeps test and API results and adds a `build` finding; it cannot run the focused-contract audit.
+
+The temporary site is removed after the audit. Like a normal build, this command also writes the generated frontmatter reference and schema to `.shoalrun/` beside the config. Add `.shoalrun/` to your project's `.gitignore`.
+
+These checks cover the rules Shoalrun implements and any tests you supply. A passing audit does not establish the factual accuracy of prose, full OpenAPI semantic fidelity, accessibility conformance, or live deployment behavior. Use the [post-deploy checker](https://www.shoalrun.com/publish/deployment-check.md) for HTTP behavior on a hosted site.
+
+## Related reading
+
+### Next steps
+
+- [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) — Add task definitions and reviewed result reports to the audit.
+
+- [Use Manni with Shoalrun](https://www.shoalrun.com/publish/manni.md) — Add conditional editorial metadata checks through an audit hook.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up the audit and api audit commands.
+
+### Often confused with
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — The audit checks project sources in CI; the deployment check tests the published site over HTTP.

package/agent-docs/publish/audit.sections/add-project-tests.md

@@ -0,0 +1,57 @@
+---
+id: guide.audit
+title: Audit a docs project
+summary: Run project tests and local API representation checks with one CI command.
+type: how-to
+area: quality
+subarea: quality-audits
+canonical: /publish/audit
+---
+
+# Audit a docs project
+
+> 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) > Publish and maintain > Audit a docs project
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/audit.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) — Add task definitions and reviewed result reports to the audit.
+
+- [Use Manni with Shoalrun](https://www.shoalrun.com/publish/manni.md) — Add conditional editorial metadata checks through an audit hook.
+
+Run `shoalrun audit` from a project directory before publishing. The command combines tests that your project configures with Shoalrun's build and API representation checks. It reports each result as JSON and exits with code `1` if any result fails.
+
+From `framework/`, this example needs no extra setup after `npm run build`:
+
+```sh
+node dist/cli.js audit example/docs.config.yaml
+```
+
+With no `audit` setting, Shoalrun runs the API source and focused-contract audits and builds the site. No project test commands run until you configure them.
+
+## Add project tests
+
+Add `audit` to `docs.config.yaml`. This example assumes your project has a `scripts/docs.test.mjs` file that Node's test runner can execute:
+
+```yaml title="docs.config.yaml"
+audit:
+  tests:
+    - id: project-tests
+      run: [node, --test, scripts/docs.test.mjs]
+  api: true
+  focusedContracts: true
+  links: true
+```
+
+Each test has a unique lowercase `id` (letters, digits, and hyphens) and a nonempty `run` list of strings. Shoalrun starts the executable in the first item and passes the rest as arguments. It does not invoke a shell, so shell operators, pipes, and redirection do not work in `run`. Tests run in list order from the directory containing the config file. They run before API audits and the build. A failing test does not stop the other tests or audits.
+
+Each test has a two minute timeout. Shoalrun captures its output and includes the last 16,000 characters in a failure finding. Successful test output is omitted from the report. Because the commands are executable code, review test entries before running an unfamiliar project. Set `audit.api: false` to skip local OpenAPI source audits, or `audit.focusedContracts: false` to skip focused-contract checks. Set `audit.links: false` to skip local link checks. All three default to `true`; the build always runs.