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

package/agent-docs/config/examples.sections/parcel-api-documentation.md

@@ -0,0 +1,153 @@
+---
+id: reference.config-examples
+title: Example configs
+summary: Complete, working docs.config.yaml files for common kinds of
+  documentation sites.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/examples
+---
+
+# Example configs
+
+> 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 > Example projects
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/examples.md)
+
+Each example below is a complete project in the repository's `framework/example-configs/` directory, with pages and any OpenAPI files it needs. The test suite builds every one, and checks that the configs on this page match the files, so they stay correct. Start with the bundled `minimal`, `api-docs`, or `showcase` project, then build it:
+
+```sh
+shoalrun init my-docs --starter minimal
+cd my-docs
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist
+```
+
+Use `--starter api-docs` for the Cedar Parcel API example, or `--starter showcase` for a complete component handbook built around that fictional service. The other examples remain available to copy from `framework/example-configs/`.
+
+The `notifications` project demonstrates an optional [cookbook chooser](https://www.shoalrun.com/author/components/cookbook-chooser.md) with email, push, and SMS choices. Its YAML maps supported selections to prebuilt recipe pages. It also includes unpublished ingredient and recipe drafts to show the authoring path. Build it from the repository root:
+
+```sh
+node framework/dist/cli.js build framework/example-configs/notifications/docs.config.yaml /tmp/notifications-site
+node framework/dist/cli.js serve /tmp/notifications-site
+```
+
+The [configuration reference](https://www.shoalrun.com/config.md) explains every key.
+
+## Parcel API documentation
+
+The fictional Cedar Parcel API demonstrates enrollment shapes, parcel filters, several response formats, binary uploads, deprecation, and a delivery webhook. Its source matches the API reference styling lab. An overview and quickstart introduce the API; enrollment has an authored reference page and the other operations are generated. The complete spec, focused contracts, and API catalog are published. The Markdown twins get a short header, with operation IDs added on reference pages.
+
+```yaml title="example-configs/api-docs/docs.config.yaml"
+# Cedar Parcel API: guides, generated references, and agent-friendly contracts.
+schemaVersion: 1
+
+site:
+  title: Cedar Parcel API
+  origin: https://docs.cedar-parcel.example
+  # Hidden visually until focused; present in HTML for agents and screen readers.
+  agentDiscovery:
+    mode: focus
+    message: Use Markdown for complete examples and the linked focused API contracts.
+  header:
+    links:
+      - { label: Quickstart, href: /quickstart, style: primary }
+  footer:
+    columns:
+      - title: Start building
+        links:
+          - { label: Overview, href: / }
+          - { label: Quickstart, href: /quickstart }
+          - { label: Enrollment reference, href: /reference/create-enrollment }
+    text: Cedar Parcel is a fictional example API.
+
+theme:
+  preset: shoal
+  palette: kelp
+  mode: system
+  toggle: true
+
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current, language: en }
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    language: en
+    access: { policy: public }
+
+apis:
+  cedar:
+    source: { kind: file, path: ./apis/cedar-parcel.yaml, publish: true }
+    discovery: { endpoint: https://api.cedar-parcel.example/v1 }
+    publicReview:
+      digest: a7a7e8eb427a7481f1c1f357d03db40319ad2e79bdeea926501da744cbecfd6f
+    mappings:
+      subjectLifecycle:
+        from: x-docs-availability.phase
+        values:
+          limited: beta
+          building: in-development
+          retired: deprecated
+    querySyntax:
+      - parameter: parameters
+        pathPrefixes: [/Search/]
+        style: unwrapped
+        example: declaredValue(gt)=100
+    operations:
+      - id: cedar.createEnrollment
+        sourceOperationId: createEnrollment
+        reference: reference.create-enrollment
+    generateReferences:
+      pathPrefix: /reference
+
+navigation:
+  - { id: overview, doc: guide.overview }
+  - { id: quickstart, doc: guide.quickstart }
+  - id: reference
+    label: API reference
+    api: cedar
+    items:
+      - { id: create-enrollment, operation: cedar.createEnrollment }
+      - { id: generated, generated: tags }
+
+relationships:
+  - id: overview-to-quickstart
+    from: guide.overview
+    to: guide.quickstart
+    type: next-step
+    reason: Prepare a local-shop enrollment and inspect its receipt.
+  - id: quickstart-to-reference
+    from: guide.quickstart
+    to: reference.create-enrollment
+    type: next-step
+    reason: Compare all four program shapes and their required fields.
+
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields:
+        id: frontmatter.id
+        title: frontmatter.title
+        summary: frontmatter.summary
+        canonical: publication.canonicalUrl
+      byType:
+        api-reference:
+          addFields: { operations: frontmatter.operations }
+```

package/agent-docs/config/examples.sections/related-reading.md

@@ -0,0 +1,50 @@
+---
+id: reference.config-examples
+title: Example configs
+summary: Complete, working docs.config.yaml files for common kinds of
+  documentation sites.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/examples
+---
+
+# Example configs
+
+> 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 > Example projects
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/examples.md)
+
+Each example below is a complete project in the repository's `framework/example-configs/` directory, with pages and any OpenAPI files it needs. The test suite builds every one, and checks that the configs on this page match the files, so they stay correct. Start with the bundled `minimal`, `api-docs`, or `showcase` project, then build it:
+
+```sh
+shoalrun init my-docs --starter minimal
+cd my-docs
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist
+```
+
+Use `--starter api-docs` for the Cedar Parcel API example, or `--starter showcase` for a complete component handbook built around that fictional service. The other examples remain available to copy from `framework/example-configs/`.
+
+The `notifications` project demonstrates an optional [cookbook chooser](https://www.shoalrun.com/author/components/cookbook-chooser.md) with email, push, and SMS choices. Its YAML maps supported selections to prebuilt recipe pages. It also includes unpublished ingredient and recipe drafts to show the authoring path. Build it from the repository root:
+
+```sh
+node framework/dist/cli.js build framework/example-configs/notifications/docs.config.yaml /tmp/notifications-site
+node framework/dist/cli.js serve /tmp/notifications-site
+```
+
+The [configuration reference](https://www.shoalrun.com/config.md) explains every key.
+
+## Related reading
+
+### Related topics
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — The same settings, combined into complete, working files.
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Explore complete projects using composition, versions, and languages.

package/agent-docs/config/examples.sections/shared-company-preset.md

@@ -0,0 +1,118 @@
+---
+id: reference.config-examples
+title: Example configs
+summary: Complete, working docs.config.yaml files for common kinds of
+  documentation sites.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/examples
+---
+
+# Example configs
+
+> 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 > Example projects
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/examples.md)
+
+Each example below is a complete project in the repository's `framework/example-configs/` directory, with pages and any OpenAPI files it needs. The test suite builds every one, and checks that the configs on this page match the files, so they stay correct. Start with the bundled `minimal`, `api-docs`, or `showcase` project, then build it:
+
+```sh
+shoalrun init my-docs --starter minimal
+cd my-docs
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist
+```
+
+Use `--starter api-docs` for the Cedar Parcel API example, or `--starter showcase` for a complete component handbook built around that fictional service. The other examples remain available to copy from `framework/example-configs/`.
+
+The `notifications` project demonstrates an optional [cookbook chooser](https://www.shoalrun.com/author/components/cookbook-chooser.md) with email, push, and SMS choices. Its YAML maps supported selections to prebuilt recipe pages. It also includes unpublished ingredient and recipe drafts to show the authoring path. Build it from the repository root:
+
+```sh
+node framework/dist/cli.js build framework/example-configs/notifications/docs.config.yaml /tmp/notifications-site
+node framework/dist/cli.js serve /tmp/notifications-site
+```
+
+The [configuration reference](https://www.shoalrun.com/config.md) explains every key.
+
+## Shared company preset
+
+Several sites share one base file. Each site's config extends it and changes only what differs: here, the title, the palette, and extra navigation. The shared file also declares a required `owner` field and a `runbook` template for every site.
+
+```yaml title="example-configs/shared-preset/shared/company-docs.yaml"
+# Settings every docs site in the company shares. Sites layer their
+# own docs.config.yaml over this file with `extends`.
+schemaVersion: 1
+
+site:
+  title: Company docs
+  header:
+    links:
+      - { label: All docs, href: "https://docs.example.com" }
+      - { label: Support, href: "https://support.example.com", style: button }
+
+theme:
+  preset: ledger
+  palette: ink
+
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+  fields:
+    owner:
+      type: string
+      required: true
+      description: Team that maintains the page.
+
+# Every site starts with the same first page. Paths in an extended file
+# resolve from that file, so this template body lives next to it.
+navigation:
+  - id: start
+    doc: guide.start
+
+templates:
+  runbook:
+    type: guide
+    body: ./runbook.mdx
+```
+
+```yaml title="example-configs/shared-preset/site/docs.config.yaml"
+# One team's site. It inherits the shared theme, publication, page
+# defaults, the required `owner` field, and the runbook template.
+schemaVersion: 1
+extends: [../shared/company-docs.yaml]
+
+site:
+  title: Billing team docs     # replaces the shared title; header links stay
+
+theme:
+  palette: coral               # keeps the shared ledger preset
+
+navigation:
+  $concat:                     # adds pages after the shared start page
+    - id: runbooks
+      label: Runbooks
+      items:
+        - id: failed-invoices
+          doc: guide.failed-invoices
+```
+
+Run `shoalrun config explain theme.preset example-configs/shared-preset/site/docs.config.yaml` to see that the preset comes from the shared file.

package/agent-docs/config/integrations.md

@@ -0,0 +1,76 @@
+---
+id: reference.config-integrations
+title: Search and integration settings
+summary: Configure search synonyms, the read-only MCP endpoint, and browser analytics.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/integrations
+---
+
+# Search and integration 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: [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) > Reference > Configuration reference > Search and integration
+
+**Updated: 2026-10-27.**
+
+Configure search synonyms, the read-only MCP endpoint, and browser analytics. 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.
+
+## `search`
+
+Optional. `search.synonyms` is a list of groups of two or more words or phrases. Each term in a group can find the others, with exact matches ranked higher. A term can appear in only one group. Use `$include` to keep the groups in a project-owned YAML file. The [site search guide](https://www.shoalrun.com/author/search.md) shows the format and which search paths use it.
+
+## `mcp`
+
+Enable a read-only HTTP MCP endpoint on Node or in Vercel output for one public publication:
+
+```yaml title="docs.config.yaml"
+mcp:
+  enabled: true
+  access: public
+  path: /mcp
+  publication: { channel: production, version: current, language: en }
+```
+
+`path` defaults to `/mcp` and is mounted beneath `site.basePath`. The build rejects conflicting output routes. `enabled` must be a boolean, and enabled configurations require `access: public` and all three publication coordinates.
+
+Optional `allowedHosts` lists exact hostnames without ports or wildcards. Optional `allowedOrigins` lists exact HTTP(S) browser origins. `site.origin` contributes its hostname and origin automatically; the local Node server also permits loopback requests. Unknown settings fail validation.
+
+Omit the section, set `mcp: false`, or set `enabled: false` to disable it. The Node server reads generated settings, and `shoalrun vercel build` packages an independent function automatically. Read-only SDK calls have been verified on this site’s production Vercel endpoint. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for setup and request limits.
+
+Optional `mcp.analytics.module` names a local `.js` or `.mjs` server adapter exporting `capture(event)` and optional `flush()`. It resolves relative to the declaring config file. The build copies the module and its dependencies without executing it. Relative imports must stay within its directory. Credentials belong in runtime environment variables.
+
+Optional `mcp.analytics.consent` contains `header` and `value`. When configured, only requests with that exact header value can load or call the analytics adapter. Other requests can use the documentation tools without tracking. The header must be a lowercase custom `x-` name; forwarded, Vercel, and MCP protocol headers are reserved. The value is a case-sensitive policy identifier of up to 64 letters, digits, dots, underscores, or hyphens.
+
+The header gate is off when omitted or set to `false`; readers then need no special client configuration for analytics. Use the gate only when your deployment requires explicit caller opt-in. In that mode, removing the header stops collection on future requests. This feature does not determine your privacy obligations. See [analytics safeguards](https://www.shoalrun.com/publish/mcp-analytics.md).
+
+Optional `mcp.analytics.clientMetadata: true` adds normalized client labels and model labels from a fixed registry when supported request metadata is present. It defaults to `false`. Labels are unverified; raw headers, unrelated metadata, queries, and intent are excluded.
+
+Optional `mcp.analytics.intent` and `mcp.analytics.conversationIds` are booleans that default to `false`. An adapter’s optional `instrument(server, options)` hook implements them. The PostHog example can add context/model arguments and conversation handles while excluding raw queries and results. Its context argument requests a fixed intent category. Free-text or invalid values are replaced with a per-tool category before analytics delivery; raw intent is never stored by that example. Other adapters must implement their own safeguards.
+
+Omit `mcp.analytics` or set it to `false` to disable collection. It is independent of browser analytics and does not instrument stdio. See [measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) for fields, service mappings, and a PostHog example.
+
+## `analytics`
+
+Analytics is disabled by default. Configure a local browser adapter to receive interaction events:
+
+```yaml title="docs.config.yaml"
+analytics:
+  module: ./analytics.js
+```
+
+The adapter must export `track(event)` and can export an asynchronous `init(context)`. `module` resolves relative to the declaring config file and is copied to the public assets without being executed during the build. `analytics: false` disables it. Shoalrun emits documented events; your adapter owns the service, consent, and delivery. See [bring your own analytics](https://www.shoalrun.com/author/analytics.md).
+
+## 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/outputs.md

@@ -0,0 +1,160 @@
+---
+id: reference.config-outputs
+title: Output and export settings
+summary: Configure metadata providers, application exports, Markdown headers,
+  and discovery indexes.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/outputs
+---
+
+# Output and export 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: [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) > Reference > Configuration reference > Output and export
+
+**Updated: 2026-10-27.**
+
+Configure metadata providers, application exports, Markdown headers, and discovery indexes. 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.
+
+## `metadata`
+
+`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework does not run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
+
+```yaml title="docs.config.yaml"
+metadata:
+  provider:
+    module: ./metadata/provider.mjs
+```
+
+The path is relative to the config file that declares it. `provider` accepts only `module`.
+
+## `exports`
+
+Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
+
+Each target accepts these fields:
+
+| Field           | Default                             | Meaning                                                                                                                  |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `formats`       | `[markdown, html]`                  | A nonempty unique list of `markdown` and/or `html`.                                                                      |
+| `documents`     | All eligible pages                  | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail.                                               |
+| `publication`   | The only enabled publication        | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
+| `contentFilter` | None                                | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
+| `publicBase`    | `/`                                 | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
+| `assetRoots`    | Content directory only              | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
+| `notices`       | Renderer notices only               | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
+| `apiReview`     | Matching API-level approval, if any | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+
+```yaml
+exports:
+  app-help:
+    formats: [markdown, html]
+    documents: [guide.api-keys, guide.billing]
+    publicBase: /help/
+```
+
+The export preserves whole-page content, including all reader sections. It flattens interactive components into readable static content and omits website/browser runtimes. Unsupported output, escaping assets, and unavailable document fallbacks fail. `exports` and its target fields are validated for unknown keys.
+
+## `outputs`
+
+Use `outputs` to configure the HTML, Markdown, discovery, and text artifacts produced by a build.
+
+| Key                          | Meaning                                                                                                                                                                                                                             |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `markdown.metadata`          | The Markdown twin's YAML header: `format`, `fields`, `addFields`, `removeFields`, `omitNull`, `byType`, and `profiles`. `format` defaults to `none`. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md). |
+| `html.shareImages`           | `true`: a generated 1200×630 link-preview image per page. `false` turns them off; a mapping with `template` and `fonts` replaces the design. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).      |
+| `html.highlighting`          | Code highlighting `provider`, `theme`, and `module`. Defaults to Shiki with the `site` theme, which takes code colors from the palette. See [code blocks](https://www.shoalrun.com/author/components/code-blocks.md).               |
+| `html.navigation.showCounts` | Show page counts beside navigation groups. Defaults to `true`; set `false` to omit them. See [navigation](https://www.shoalrun.com/author/navigation.md).                                                                           |
+| `html.search`                | Search `provider`, `module`, and `index`. See [search](https://www.shoalrun.com/author/search.md).                                                                                                                                  |
+| `text`                       | Ordered frontmatter field paths for `card`, `pageHeader`, `search`, `htmlDescription`, and `socialCard`. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md).                                                 |
+
+The build always writes `/llms.txt`, `documents.json`, `redirects.json`, and `resource-headers.json`; there are no settings for them.
+
+A short Markdown header on every page:
+
+```yaml title="docs.config.yaml"
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields:
+        id: frontmatter.id
+        title: frontmatter.title
+        summary: frontmatter.summary
+        description: frontmatter.description
+        canonical: publication.canonicalUrl
+```
+
+Add fields for one page type, and define a profile pages can select with `markdownMetadata: versioned`:
+
+```yaml title="docs.config.yaml"
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields: { id: frontmatter.id, title: frontmatter.title }
+      byType:
+        api-reference:
+          addFields: { operations: frontmatter.operations }
+      profiles:
+        versioned:
+          addFields: { version: publication.version, language: publication.language }
+```
+
+Use another Shiki theme, and turn off search:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    highlighting: { provider: shiki, theme: github-light }
+    search: { provider: none }
+```
+
+Plug in your own search and highlighter modules:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    highlighting: { provider: custom, module: ./highlight.mjs }
+    search: { provider: custom, module: ./search/hosted.js }
+```
+
+### Agent discovery index
+
+Every published page is included automatically, using its title and frontmatter summary. You do not need to list page IDs. Omit `outputs.llms` for automatic grouping, or choose a bare alphabetical list of links and summaries:
+
+```yaml title="docs.config.yaml"
+outputs:
+  llms:
+    format: flat
+```
+
+`format` accepts `grouped` (the default) or `flat`. Flat mode includes all pages under `Pages`, without optional groups or repeated type labels. Discovery resources and API contracts remain linked, and fictional labels still apply. Grouping overrides are optional; `primaryIds` is an exception list, not an inventory.
+
+`outputs.llms` controls grouping in `/llms.txt`. The build groups primary pages by type, puts secondary pages under `## Optional`, and lists `/search-index.json` under Discovery only when that file is generated. The complete manifest remains available for inventory. `fictionalPrefixes` also sets `demo: true` on matching pages in `documents.json`, `search-index.json`, and `search-index.min.json`. Matching uses the authored slug, including descendants, independently of publication or site path prefixes. Other pages receive `demo: false`, meaning unmarked rather than verified as a live service.
+
+```yaml title="docs.config.yaml"
+outputs:
+  llms:
+    primaryIds: [guide.components]
+    optionalTypes: [recipe, ingredient, cookbook]
+    optionalPrefixes: [/author/components]
+    fictionalPrefixes: [/example-api]
+```
+
+`primaryIds` keeps named document IDs in their primary type section even when an optional type or prefix matches; fictional examples remain optional. Entries sort alphabetically within each section or optional group. Type labels appear only in the mixed optional groups. `optionalTypes` defaults to recipe, ingredient, and cookbook. Both prefix lists default to empty. Prefixes match page slugs before publication and base-path prefixes, on path boundaries. Fictional entries are always optional, labeled in the index, and carry a disclaimer in their Markdown twins. Use fictional prefixes only for synthetic examples, not real product API references.
+
+## 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/outputs.sections/exports.md

@@ -0,0 +1,57 @@
+---
+id: reference.config-outputs
+title: Output and export settings
+summary: Configure metadata providers, application exports, Markdown headers,
+  and discovery indexes.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/outputs
+---
+
+# Output and export 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: [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) > Reference > Configuration reference > Output and export
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/outputs.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 metadata providers, application exports, Markdown headers, and discovery indexes. 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.
+
+## `exports`
+
+Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
+
+Each target accepts these fields:
+
+| Field           | Default                             | Meaning                                                                                                                  |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `formats`       | `[markdown, html]`                  | A nonempty unique list of `markdown` and/or `html`.                                                                      |
+| `documents`     | All eligible pages                  | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail.                                               |
+| `publication`   | The only enabled publication        | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
+| `contentFilter` | None                                | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
+| `publicBase`    | `/`                                 | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
+| `assetRoots`    | Content directory only              | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
+| `notices`       | Renderer notices only               | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
+| `apiReview`     | Matching API-level approval, if any | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+
+```yaml
+exports:
+  app-help:
+    formats: [markdown, html]
+    documents: [guide.api-keys, guide.billing]
+    publicBase: /help/
+```
+
+The export preserves whole-page content, including all reader sections. It flattens interactive components into readable static content and omits website/browser runtimes. Unsupported output, escaping assets, and unavailable document fallbacks fail. `exports` and its target fields are validated for unknown keys.

package/agent-docs/config/outputs.sections/metadata.md

@@ -0,0 +1,42 @@
+---
+id: reference.config-outputs
+title: Output and export settings
+summary: Configure metadata providers, application exports, Markdown headers,
+  and discovery indexes.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/outputs
+---
+
+# Output and export 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: [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) > Reference > Configuration reference > Output and export
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/config/outputs.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 metadata providers, application exports, Markdown headers, and discovery indexes. 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.
+
+## `metadata`
+
+`metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework does not run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
+
+```yaml title="docs.config.yaml"
+metadata:
+  provider:
+    module: ./metadata/provider.mjs
+```
+
+The path is relative to the config file that declares it. `provider` accepts only `module`.