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

package/agent-docs/concepts.md

@@ -0,0 +1,133 @@
+---
+id: guide.concepts
+title: How Shoalrun works
+summary: Follow a page from source file to published HTML and Markdown, and
+  learn the terms the rest of these docs use.
+type: explanation
+area: project
+subarea: project-overview
+canonical: /concepts
+---
+
+# How Shoalrun works
+
+> 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) > Get started > How Shoalrun works
+
+**Updated: 2026-10-26.**
+
+Shoalrun is a static documentation compiler. It reads a project config, Markdown and MDX pages, and local OpenAPI files. It writes an HTML site and a Markdown copy of every page. A build makes no network requests and no model calls, so the same inputs always give the same output.
+
+## Choose your focus
+
+Pick a path to narrow the site's navigation and search. The choice persists across visits; **All** in the header shows every page again. Both paths keep foundational guides like this one visible.
+
+[Write documentation](https://www.shoalrun.com/concepts?view=focus%3Awrite)
+
+[Configure & publish](https://www.shoalrun.com/concepts?view=focus%3Aconfigure)
+
+**For Focus: Write documentation.**
+
+Start with [adding a page](https://www.shoalrun.com/author/add-page.md), then use [page metadata](https://www.shoalrun.com/author/frontmatter.md) and [components](https://www.shoalrun.com/author/components.md) to shape it.
+
+**For Focus: Configure & publish.**
+
+Start with [project configuration](https://www.shoalrun.com/configuration.md), then explore [themes](https://www.shoalrun.com/styling/themes.md) and [publishing](https://www.shoalrun.com/publish.md).
+
+## The build pipeline
+
+**Shoalrun build pipeline**
+
+Config and sources pass through validation and one shared content tree, which produces HTML pages, Markdown twins, and manifests.
+
+[View Shoalrun build pipeline diagram](https://www.shoalrun.com/assets/diagrams/mermaid-98a388873e52f66c5f05-light.svg)
+
+```mermaid
+flowchart LR
+ config["docs.config.yaml"] --> validate["Validate frontmatter<br/>and publications"]
+ pages["Pages (.md, .mdx)"] --> validate
+ validate --> tree["Shared content tree"]
+ openapi["OpenAPI files"] -->|"examples, schemas,<br/>reference pages"| tree
+ tree --> html["HTML pages"]
+ tree --> md["Markdown twins"]
+ tree --> manifests["Manifests and<br/>discovery files"]
+```
+
+1. **Load config.** The build reads `docs.config.yaml` and every file it includes or extends. Unknown top-level keys fail. See the [configuration reference](https://www.shoalrun.com/config.md).
+2. **Read pages.** Every `.md` and `.mdx` file in the content directory is parsed, and its frontmatter is merged with project defaults and checked. Drafts are checked too.
+3. **Choose publications.** A public page can name one publication or list several. One source file can therefore produce several page variants, with optional version-specific sections. Write separate files only when the pages need substantially different content.
+4. **Build the content tree.** MDX components, snippets, `doc:` links, cards, API embeds, and diagrams become one shared tree. Generated API reference pages join here.
+5. **Render.** The same tree produces the HTML page and its Markdown twin, so the two can't drift apart. Diagrams are rendered to SVG at this step: D2 and Pele both run in-process, without a browser.
+6. **Write the site.** The build writes pages, assets, API contracts, and manifests. See [published outputs](https://www.shoalrun.com/publish/output.md).
+
+## Identity: IDs, slugs, and routes
+
+A page has a stable **ID**, such as `guide.concepts`, and a **slug**, such as `/concepts`. Links, cards, navigation, and relationships use the ID, so you can rename a file or change a slug without breaking them. The slug sets the URL path, so changing a slug changes the URL. Add a [redirect](https://www.shoalrun.com/config.md) from the old path if readers or other sites link to it.
+
+The **route** is the final URL. It combines `site.basePath`, a language prefix for a non-default language, the channel's and version's `pathPrefix`, and the slug. For example, a German page at `/guides/retry` in a `v2` version with `pathPrefix: /v2` has the route `/de/v2/guides/retry`.
+
+API operations have three identifiers:
+
+| Identifier           | Example                 | Where it comes from                                     |
+| -------------------- | ----------------------- | ------------------------------------------------------- |
+| Source `operationId` | `createNote`            | The OpenAPI file.                                       |
+| Stable operation ID  | `notes.create`          | Your `apis` config. Pages and navigation refer to this. |
+| Reference page ID    | `reference.create-note` | The page that presents the operation.                   |
+
+The stable operation ID keeps pages linked even if the OpenAPI `operationId` changes. See [API references](https://www.shoalrun.com/publish/api-references.md).
+
+## Publications
+
+A **publication** is one enabled combination of channel, version, and language:
+
+- A **channel** is an audience or environment, such as `production` or `sandbox`.
+- A **version** is an API or documentation edition, such as `v1` or `current`.
+- A **language** is a content language, such as `en`.
+
+`publications.enabled` lists the combinations to build. A page's frontmatter picks one or several of them; files for other versions or languages can share its `id`. Links, cards, and related reading stay inside the current publication, so a v1 page never links to a v2 page by accident. Each published copy of a page is a **variant**. The HTML and Markdown copy for each variant include only content selected for that publication.
+
+Git branches and tags select source revisions for a build; they do not select publication channels or preserve earlier deployed sites. The [deployment and version guide](https://www.shoalrun.com/publish/revisions.md) explains how those choices fit together.
+
+For a complete versioning and translation workflow, follow [put multiple versions on one site](https://www.shoalrun.com/publish/publications.md).
+
+## Drafts and publishing
+
+Only pages with `access.policy: public` are published. Anything else, such as `draft`, is still validated but never written to the site. New pages from `shoalrun scaffold` start as drafts with placeholder prompts. A public page fails the build until every placeholder is replaced. See [templates](https://www.shoalrun.com/author/templates.md).
+
+## Config composition
+
+A project config can be one file or many. Four directives combine files:
+
+- `$include` replaces a value with the contents of another YAML file.
+- `extends` layers the current file over one or more preset files.
+- `$concat` appends to a list inherited from a preset.
+- `$remove` drops inherited map keys or list items by `id`.
+
+`shoalrun config explain <key>` reports which file set a value. Follow [configure your project](https://www.shoalrun.com/configuration.md) for a worked example of composition, precedence, file paths, and debugging.
+
+## Glossary
+
+Terms such as **publication**, **variant**, **Markdown twin**, and **focused contract** are defined in the [glossary](https://www.shoalrun.com/glossary.md). It lists more than a hundred terms, sorted A to Z, and links each one to its guide.
+
+## Related reading
+
+### Next steps
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Compose your project settings and trace how they resolve.
+
+- [Content and stable IDs](https://www.shoalrun.com/author/content.md) — Apply IDs, slugs, and publication variants to your own pages.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Check every top-level setting the build reads.
+
+- [Glossary](https://www.shoalrun.com/glossary.md) — Look up any term used on this page, and more than a hundred others.
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Find each HTML, Markdown, and manifest file the pipeline writes.
+
+### Related topics
+
+- [Getting started](https://www.shoalrun.com/start.md) — Learn the build pipeline and the terms the rest of these docs use.

package/agent-docs/config/apis.md

@@ -0,0 +1,136 @@
+---
+id: reference.config-apis
+title: API and audit settings
+summary: Configure OpenAPI sources, generated references, focused contracts, and
+  local validation.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/apis
+---
+
+# API and audit settings
+
+> 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) > Configuration reference > API and audit
+
+**Updated: 2026-10-27.**
+
+Configure OpenAPI sources, generated references, focused contracts, and local validation. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `apis`
+
+A mapping from API ID to its source and operations. See [API references](https://www.shoalrun.com/publish/api-references.md) and [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md).
+
+| Key                         | Meaning                                                                                                                                                                                                                                            |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source.kind`               | Must be `file`.                                                                                                                                                                                                                                    |
+| `source.path`               | Local OpenAPI 3.0 or 3.1 file, relative to the declaring config file.                                                                                                                                                                              |
+| `source.focused`            | `true` writes a [focused contract](https://www.shoalrun.com/api-docs/focused-contracts.md) for each reference page.                                                                                                                                |
+| `source.publish`            | `true` publishes the full source file, which must end in `.yaml`, `.yml`, or `.json`. Also turns on focused contracts.                                                                                                                             |
+| `publicReview.digest`       | Required SHA-256 review digest when API content appears on a public page or in a focused contract. Generate a candidate with `shoalrun api review <config> --output <local-directory>`, inspect it, then pin the reported digest.                  |
+| `discovery.endpoint`        | Public HTTPS API URL for `/.well-known/api-catalog`. Needs `source.publish` and `site.origin`.                                                                                                                                                     |
+| `operations`                | A list of `{ id, sourceOperationId, reference }` bindings. Stable IDs are unique across all APIs.                                                                                                                                                  |
+| `publications`              | A list of `{ channel, version, source, discovery }` entries for publications other than the default.                                                                                                                                               |
+| `generateReferences`        | `true`, or `{ pathPrefix, include }` or `{ pathPrefix, exclude }`. `pathPrefix` defaults to `/reference/<apiId>`.                                                                                                                                  |
+| `mappings.subjectLifecycle` | Explicitly map an operation-level `x-*` scalar or dotted property to `beta`, `in-development`, `experimental`, or `deprecated`. See [OpenAPI extension mappings](https://www.shoalrun.com/publish/openapi-extension-mappings.md).                  |
+| `querySyntax`               | Opt-in rules for a placeholder query parameter whose filter expressions go directly in the URL. Each rule has `parameter`, `pathPrefixes`, `style: unwrapped`, and `example`. See [API generation](https://www.shoalrun.com/api-docs/generate.md). |
+
+One authored reference page for one operation. The spec stays private:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml }
+  operations:
+    - id: payments.create
+      sourceOperationId: createPayment
+      reference: reference.create-payment
+```
+
+Publish the spec, a focused contract per page, and the API catalog. This also needs `site.origin`:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml, publish: true }
+  discovery:
+    endpoint: https://api.example.com
+  operations:
+    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }
+```
+
+Keep the spec private but publish focused contracts:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml, focused: true }
+  operations:
+    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }
+```
+
+Generate reference pages for every operation except two:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/openapi.yaml }
+  generateReferences:
+    pathPrefix: /api-reference/payments
+    exclude: [internalReconcile, debugEcho]
+```
+
+Give the v2 publication its own spec. The top-level `source` covers the default publication:
+
+```yaml title="config/api.yaml"
+payments:
+  source: { kind: file, path: ../apis/payments/v1.yaml }
+  publications:
+    - channel: production
+      version: v2
+      source: { kind: file, path: ../apis/payments/v2.yaml, publish: true }
+  operations:
+    - { id: payments.create, sourceOperationId: createPayment, reference: reference.create-payment }
+```
+
+## `audit`
+
+Optional local audit settings. Run `shoalrun check [config]` or `shoalrun audit [config]` to execute configured tests and build a temporary site. The checks compare API representations, inspect focused contracts, and validate local links. `check` prints readable results (`--json` selects JSON); `audit` returns JSON. Both exit with code 1 on failure.
+
+```yaml title="docs.config.yaml"
+audit:
+  tests:
+    - id: project-tests
+      run: [node, --test, scripts/docs.test.mjs]
+  api: true
+  focusedContracts: true
+  links: true
+```
+
+`audit.tests` is the integration point for external test suites. We recommend Doc Detective for documentation behavior tests; any command that exits nonzero on failure can be used. Each test needs a unique lowercase `id` and a nonempty `run` argument list. The first argument names the executable; the rest are passed without a shell. Commands run from the directory containing `docs.config.yaml`, so use project-relative paths. The `api`, `focusedContracts`, and `links` switches default to `true`. Set any to `false` to skip that group. The site build always runs because it checks the complete project and supplies focused contracts. See [audit a docs project](https://www.shoalrun.com/publish/audit.md) for a Doc Detective example, execution order, output, timeouts, and limits.
+
+For snapshot validation, declare local check dependencies with optional `inputs` paths relative to the directory containing `docs.config.yaml`:
+
+```yaml title="docs.config.yaml"
+audit:
+  tests:
+    - id: formatting
+      run: [vale, --config=../format.ini, content]
+      inputs: [../format.ini, ../styles]
+```
+
+The snapshot copies declared files and directories within the project parent. It rejects missing inputs, symlinks, credentials, dependency folders, and paths outside that boundary. Directory declarations also track added and deleted files for freshness. Declare the configuration's supporting files too; Shoalrun does not infer dependencies from command arguments. Ordinary `check` and `audit` commands still run in the original project.
+
+### Agent evaluation reports
+
+`audit.evals` opts into checking a reviewed task report after the audit's temporary build. Set `tasks` to a YAML or JSON task file and `report` to a JSON result file. Both paths resolve relative to the file declaring them. Optional `run` is a nonempty command/argument list. It runs without a shell from the root config directory after a successful build. The timeout is two minutes; environment variables supply eval paths and digests. It can call external services and write the report; a nonzero exit fails independently of report validation. No evaluator is built into Shoalrun. See [evaluate agent tasks](https://www.shoalrun.com/publish/evals.md) for the report format, environment variables, and CLI commands.
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.

package/agent-docs/config/content.md

@@ -0,0 +1,264 @@
+---
+id: reference.config-content
+title: Authoring and content settings
+summary: Configure authoring guidance, page defaults, reusable content, reading
+  paths, and reader views.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/content
+---
+
+# Authoring and content settings
+
+> 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) > Configuration reference > Authoring and content
+
+**Updated: 2026-10-27.**
+
+Configure authoring guidance, page defaults, reusable content, reading paths, and reader views. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `authoring`
+
+Optional project guidance and read-only source locations. These settings do not choose a model or read external files during a site build.
+
+| Key             | Meaning                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `directives`    | Nonempty project writing instructions.                                                                                          |
+| `guideFiles`    | Project-relative writing-guide paths.                                                                                           |
+| `exemplarFiles` | Project-relative reviewed examples.                                                                                             |
+| `sourceRoots`   | Named local folders for source search. Each entry has `path`, optional `name`, and optional `include` and `exclude` glob lists. |
+| `pageSources`   | Stable page IDs mapped to source file paths or globs. These seed evidence selection for known features.                         |
+
+Source paths resolve from the root configuration directory. Source folders and page-source files may be outside the docs project; guide and exemplar paths remain inside it. URLs are not source folders. Git is not required. Your coding agent selects the evidence scope under its own permissions.
+
+```yaml title="docs.config.yaml"
+authoring:
+  sourceRoots:
+    - name: Application implementation
+      path: ../application/src
+      include: ["**/*.ts", "**/*.tsx"]
+      exclude: ["**/*.test.ts"]
+  pageSources:
+    guide.authentication:
+      - ../application/src/authentication.ts
+```
+
+Project discovery reports these configured source locations. Use your coding agent's own search and read tools, with its execution permissions, to investigate external implementation files. `docs source` reads only paths inside the project. See [authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) for current discovery and validation commands.
+
+## `frontmatter`
+
+Global `defaults`, `enforced` values, per-language formatting `locales`, custom `fields` declarations, and `changelogIdentifier`. Pages can replace defaults but not enforced values. `id` and `slug` can't be set globally. See [frontmatter](https://www.shoalrun.com/author/frontmatter.md) and [release notes and changelog](https://www.shoalrun.com/author/release-notes.md).
+
+Let pages leave out common values:
+
+```yaml title="config/frontmatter.yaml"
+defaults:
+  type: guide
+  channel: production
+  version: current
+  access: { policy: public }
+```
+
+Force a value on every page:
+
+```yaml title="config/frontmatter.yaml"
+enforced:
+  audiences: [partners]
+```
+
+Choose what identifies each changelog entry. The default is `either`; `date` and `version` are also available:
+
+```yaml title="config/frontmatter.yaml"
+changelogIdentifier: either
+```
+
+Here `version` means the page's `releaseVersion` field, not the documentation publication version.
+
+Declare custom fields. `public: true` lets a field appear in the Markdown twin's header:
+
+```yaml title="config/frontmatter.yaml"
+fields:
+  owner:
+    type: string
+    required: true
+    description: Team that maintains the page.
+  agent.intent:
+    type: string
+    public: true
+  reviewStatus:
+    type: string
+    enum: [draft, reviewed, approved]
+```
+
+## `variables`
+
+A mapping of project-wide values for [snippets](https://www.shoalrun.com/author/snippets.md). They override snippet defaults and are overridden by page `variables` and invocation values. Values are strings, numbers, or booleans.
+
+```yaml title="docs.config.yaml"
+variables:
+  product: Payments
+  supportEmail: support@example.com
+  retryLimit: 3
+  betaFeatures: false
+```
+
+A page overrides a project value for itself:
+
+```yaml title="content/sandbox-guide.mdx (frontmatter)"
+variables:
+  product: Payments sandbox
+```
+
+A single include overrides both:
+
+```mdx title="content/sandbox-guide.mdx"
+<Snippet id="payment.request-prep" values={{ product: "Payments test mode" }} />
+```
+
+## `snippets`
+
+A mapping from snippet ID to `{ file, variables }`. Each variable has a `type` (`string`, `number`, or `boolean`) and optional `required`, `default`, and `enum`. See [snippets](https://www.shoalrun.com/author/snippets.md).
+
+A snippet with no variables:
+
+```yaml title="config/snippets.yaml"
+legal.beta-notice:
+  file: ../snippets/beta-notice.mdx
+```
+
+Required and default values:
+
+```yaml title="config/snippets.yaml"
+payment.request-prep:
+  file: ../snippets/request-prep.mdx
+  variables:
+    product: { type: string, required: true }
+    header: { type: string, default: Idempotency-Key }
+```
+
+A value limited to a list, and a number:
+
+```yaml title="config/snippets.yaml"
+limits.rate:
+  file: ../snippets/rate-limit.mdx
+  variables:
+    plan: { type: string, enum: [free, team, enterprise], default: free }
+    perMinute: { type: number, required: true }
+```
+
+## `templates`
+
+An optional mapping from template ID to `{ type, body, required }`. Built-in templates need no registration; reuse a built-in ID to override it or add a custom ID. `type` becomes the new page's `type`, and `body` is a `.md` or `.mdx` file that can open with commented frontmatter. The only `required` value is `operations`. See [templates](https://www.shoalrun.com/author/templates.md).
+
+```yaml title="config/templates.yaml"
+how-to:
+  type: how-to
+  body: ../templates/how-to.mdx
+```
+
+Override the built-in API reference while retaining its operation requirement:
+
+```yaml title="config/templates.yaml"
+api-reference:
+  type: api-reference
+  body: ../templates/api-reference.mdx
+  required: [operations]
+```
+
+Replace a built-in template by reusing its ID:
+
+```yaml title="config/templates.yaml"
+guide:
+  type: guide
+  body: ../templates/our-guide.mdx
+```
+
+## `callouts`
+
+Custom callout `types` and color `tones`. A type has a `label`, a `tone`, and an optional Lucide `icon`. A tone has `line`, `background`, and `text` colors, and an optional `dark` set. See [callouts](https://www.shoalrun.com/author/components/callout.md) for configuration examples and contrast requirements.
+
+## `badges`
+
+`badges.variants` adds or overrides inline badge colors. Each lowercase kebab-case name needs `light.background` and `light.text` hex colors; `light.border` is optional and defaults to the text color. Add the same fields under `dark` when the site uses dark or system mode. The build checks badge text contrast in every shown mode. See [Badges](https://www.shoalrun.com/author/components/badge.md) for the built-in variant table and a separate custom `partner` example.
+
+## `cookbooks`
+
+Optional mapping of cookbook IDs to a chooser title and ordered reader options. Each option has a unique `id`, `label`, and `doc` ID for a public `type: recipe` page in the same publication as the chooser. The build rejects duplicate options and unavailable targets. Set `mode: single` for alternative goals or use `mode: multiple` (the default) for compatible recipes. Optional option fields `when`, `needs`, and `outcome` explain each choice. The browser loads selected published recipe content in configured order and supports selection links, Markdown downloads, and printing. The [CookbookChooser reference](https://www.shoalrun.com/author/components/cookbook-chooser.md) shows a live example and the HTML and Markdown behavior.
+
+```yaml title="docs.config.yaml"
+cookbooks: { $include: ./config/cookbooks.yaml }
+```
+
+## `relationships`
+
+A list of authored links between pages, with `id`, `from`, `to`, `type`, `reason`, and optional `order`. `type` is `prerequisite`, `next-step`, `reference`, `advanced`, `see-also`, or `not-confused-with`. See [related reading](https://www.shoalrun.com/author/related-reading.md).
+
+A reading path through three pages:
+
+```yaml title="config/relationships.yaml"
+- id: auth-before-payment
+  from: guide.create-payment
+  to: guide.authentication
+  type: prerequisite
+  reason: Create an API key before sending a payment request.
+- id: payment-then-refund
+  from: guide.create-payment
+  to: guide.refunds
+  type: next-step
+  reason: Refund a payment that was created by mistake.
+```
+
+Order links in a group. Lower numbers come first:
+
+```yaml title="config/relationships.yaml"
+- id: payment-reference
+  from: guide.create-payment
+  to: reference.create-payment
+  type: reference
+  reason: Check every request field and error code.
+  order: 1
+- id: payment-errors
+  from: guide.create-payment
+  to: guide.handle-errors
+  type: reference
+  reason: Look up what each decline code means.
+  order: 2
+```
+
+Two-way links. Declare `see-also` and `not-confused-with` once; both pages show them:
+
+```yaml title="config/relationships.yaml"
+- id: refunds-vs-disputes
+  from: guide.refunds
+  to: guide.disputes
+  type: not-confused-with
+  reason: A refund is sent by you; a dispute is started by the cardholder's bank.
+```
+
+## `readerFilters`
+
+Optional reader views for one site. `facets` maps each stable facet ID to a reader-facing `label` and an `options` map of stable choice IDs to labels. `typeDefaults` optionally marks all pages of a document type unless a page supplies a value for that facet. `controls` selects sidebar and header pickers; `module` names a local browser module for custom controls. The first visit shows all content. See [reader views](https://www.shoalrun.com/author/reader-views.md) for page and section marks, controls, saved choices, and share links.
+
+```yaml title="docs.config.yaml"
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options: { ui: Use the UI, developer: Build with the API }
+  typeDefaults:
+    api-reference: { audience: [developer] }
+```
+
+## Related reading
+
+### Read first
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Find configuration settings in another topic.

package/agent-docs/config/content.sections/authoring.md

@@ -0,0 +1,58 @@
+---
+id: reference.config-content
+title: Authoring and content settings
+summary: Configure authoring guidance, page defaults, reusable content, reading
+  paths, and reader views.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/content
+---
+
+# Authoring and content settings
+
+> 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) > Configuration reference > Authoring and content
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/content.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+Configure authoring guidance, page defaults, reusable content, reading paths, and reader views. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `authoring`
+
+Optional project guidance and read-only source locations. These settings do not choose a model or read external files during a site build.
+
+| Key             | Meaning                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `directives`    | Nonempty project writing instructions.                                                                                          |
+| `guideFiles`    | Project-relative writing-guide paths.                                                                                           |
+| `exemplarFiles` | Project-relative reviewed examples.                                                                                             |
+| `sourceRoots`   | Named local folders for source search. Each entry has `path`, optional `name`, and optional `include` and `exclude` glob lists. |
+| `pageSources`   | Stable page IDs mapped to source file paths or globs. These seed evidence selection for known features.                         |
+
+Source paths resolve from the root configuration directory. Source folders and page-source files may be outside the docs project; guide and exemplar paths remain inside it. URLs are not source folders. Git is not required. Your coding agent selects the evidence scope under its own permissions.
+
+```yaml title="docs.config.yaml"
+authoring:
+  sourceRoots:
+    - name: Application implementation
+      path: ../application/src
+      include: ["**/*.ts", "**/*.tsx"]
+      exclude: ["**/*.test.ts"]
+  pageSources:
+    guide.authentication:
+      - ../application/src/authentication.ts
+```
+
+Project discovery reports these configured source locations. Use your coding agent's own search and read tools, with its execution permissions, to investigate external implementation files. `docs source` reads only paths inside the project. See [authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) for current discovery and validation commands.

package/agent-docs/config/content.sections/badges.md

@@ -0,0 +1,34 @@
+---
+id: reference.config-content
+title: Authoring and content settings
+summary: Configure authoring guidance, page defaults, reusable content, reading
+  paths, and reader views.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/content
+---
+
+# Authoring and content settings
+
+> 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) > Configuration reference > Authoring and content
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/content.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+Configure authoring guidance, page defaults, reusable content, reading paths, and reader views. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## `badges`
+
+`badges.variants` adds or overrides inline badge colors. Each lowercase kebab-case name needs `light.background` and `light.text` hex colors; `light.border` is optional and defaults to the text color. Add the same fields under `dark` when the site uses dark or system mode. The build checks badge text contrast in every shown mode. See [Badges](https://www.shoalrun.com/author/components/badge.md) for the built-in variant table and a separate custom `partner` example.