@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/agent-docs/features.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Shoalrun features
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Shoalrun compiles product and API documentation into a website and agent-readable content from the same source. You own the source files, build output, and deployment. The normal compiler build makes no model calls or network requests.
 
@@ -24,26 +24,28 @@ Shoalrun compiles product and API documentation into a website and agent-readabl
 
 Follow a topic link for configuration, examples, and limits.
 
-| Capability                                                                             | What you can do                                                                                                                                                                                                               |
-| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [One source, multiple outputs](https://www.shoalrun.com/publish/agent-friendliness.md) | Write Markdown and supported MDX; publish HTML, Markdown copies, discovery indexes, manifests, and readable sections.                                                                                                         |
-| [Structured authoring](https://www.shoalrun.com/author/content.md)                     | Give documents stable IDs; reuse templates, snippets, variables, metadata, and configuration. Connect navigation and related reading by ID.                                                                                   |
-| [Documentation components](https://www.shoalrun.com/author/components.md)              | Use tabs, callouts, tables, steps, walkthroughs, diagrams, and trusted custom components with defined Markdown representations.                                                                                               |
-| [Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md)         | Highlight built-in languages or register a custom language with a local TextMate JSON grammar and aliases. Preserve the original code in Markdown.                                                                            |
-| [OpenAPI documentation](https://www.shoalrun.com/publish/api-references.md)            | Generate reference pages, embed API examples and schemas, show request samples, and publish focused operation contracts. Review source changes before publishing.                                                             |
-| [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md)           | Select exact product releases, SKU revisions, and feature grants. Remove excluded pages and sections during compilation.                                                                                                      |
-| [Independent products and versions](https://www.shoalrun.com/publish/publications.md)  | Give each product its own documentation versions and defaults, with explicit languages and routes.                                                                                                                            |
-| [Search and agent tools](https://www.shoalrun.com/search-and-chat.md)                  | Search the selected publication by keyword or optional semantic retrieval. Read-only Model Context Protocol (MCP) tools discover publications and read pages within token budgets. Optional cited answers use your providers. |
-| [Content delivery](https://www.shoalrun.com/content-delivery.md)                       | Export selected pages, approved sections, and snippets for an application. Clients and REST retain exact product scope; productless version 1 contracts remain supported.                                                     |
-| [Printing and styled PDFs](https://www.shoalrun.com/publish/pdf.md)                    | Offer branded Print PDF buttons, export styled pages or full manuals with the CLI, and serve optional page PDF downloads through a Node host.                                                                                 |
-| [Workflows and validation](https://www.shoalrun.com/author/agent-overview.md)          | Use your coding agent with project discovery, isolated validation, and matching previews. Watch a customer edition with `dev --profile`. Compose recipes and cookbooks.                                                       |
-| [Agent skills](https://www.shoalrun.com/reference/agent-skills.md)                     | Use packaged workflows for setup, authoring, components, recipes, walkthroughs, branding, and PDF design with `shoalrun-pdf`.                                                                                                 |
-| [Presentation and navigation](https://www.shoalrun.com/styling/themes.md)              | Configure themes, layouts, branding, and navigation. Switch publications through a grouped dropdown, with language labels hidden automatically for single-language editions.                                                  |
-| [Publishing and measurement](https://www.shoalrun.com/publish.md)                      | Publish static output or use Node and Vercel serving options. Add analytics through optional adapters.                                                                                                                        |
+| Capability                                                                             | What you can do                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [One source, multiple outputs](https://www.shoalrun.com/publish/agent-friendliness.md) | Write Markdown and supported MDX; publish HTML, Markdown copies, discovery indexes, manifests, and readable sections.                                                                                                                                                                            |
+| [Structured authoring](https://www.shoalrun.com/author/content.md)                     | Give documents stable IDs; reuse templates, snippets, variables, metadata, and configuration. Connect navigation and related reading by ID.                                                                                                                                                      |
+| [Documentation components](https://www.shoalrun.com/author/components.md)              | Use tabs, callouts, tables, steps, walkthroughs, diagrams, and trusted custom components with defined Markdown representations.                                                                                                                                                                  |
+| [Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md)         | Highlight built-in languages or register a custom language with a local TextMate JSON grammar and aliases. Preserve the original code in Markdown.                                                                                                                                               |
+| [OpenAPI documentation](https://www.shoalrun.com/publish/api-references.md)            | Generate reference pages, embed API examples and schemas, show request samples, and publish focused operation contracts. Review source changes before publishing.                                                                                                                                |
+| [Code API references](https://www.shoalrun.com/api-docs/code-references.md)            | Generate SDK references from Python docstrings, [public TypeScript declarations and JSDoc](https://www.shoalrun.com/api-docs/typescript-references.md), or a converter snapshot. Show linked types, defaults, and member details on symbol, class, module, or optional complete-reference pages. |
+| [Build selection](https://www.shoalrun.com/publish/single-source-sites.md)             | Select pages and sections with your own configured facets and choices, without customer profiles.                                                                                                                                                                                                |
+| [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md)           | Select exact product releases, SKU revisions, and feature grants. Remove excluded pages and sections during compilation.                                                                                                                                                                         |
+| [Independent products and versions](https://www.shoalrun.com/publish/publications.md)  | Give each product its own documentation versions and defaults, with explicit languages and routes.                                                                                                                                                                                               |
+| [Search and agent tools](https://www.shoalrun.com/search-and-chat.md)                  | Search the selected publication by keyword or optional semantic retrieval. Read-only Model Context Protocol (MCP) tools discover publications and read pages within token budgets. Optional cited answers use your providers.                                                                    |
+| [Content delivery](https://www.shoalrun.com/content-delivery.md)                       | Export selected pages, approved sections, and snippets for an application. Clients and REST retain exact product scope; productless version 1 contracts remain supported.                                                                                                                        |
+| [Printing and styled PDFs](https://www.shoalrun.com/publish/pdf.md)                    | Offer branded Print PDF buttons, export styled pages or full manuals with the CLI, and serve optional page PDF downloads through a Node host.                                                                                                                                                    |
+| [Workflows and validation](https://www.shoalrun.com/author/agent-overview.md)          | Use your coding agent with project discovery, isolated validation, and matching previews. Watch a customer edition with `dev --profile`. Compose recipes and cookbooks.                                                                                                                          |
+| [Agent skills](https://www.shoalrun.com/reference/agent-skills.md)                     | Use packaged workflows for setup, authoring, components, recipes, walkthroughs, branding, and PDF design. Expose skills through your agent's discovery directory and follow their task checklists.                                                                                               |
+| [Presentation and navigation](https://www.shoalrun.com/styling/themes.md)              | Configure themes, layouts, branding, and navigation. Switch publications through a grouped dropdown, with language labels hidden automatically for single-language editions.                                                                                                                     |
+| [Publishing and measurement](https://www.shoalrun.com/publish.md)                      | Publish static output or use Node and Vercel serving options. Add analytics through optional adapters.                                                                                                                                                                                           |
 
 ## Before you choose Shoalrun
 
-Configuration and output contracts can change as Shoalrun develops. OpenAPI and JSON Schema support is partial. Arbitrary executable MDX and a live API request explorer aren't supported.
+Pin releases and review upgrade notes before deploying. OpenAPI and JSON Schema support is partial. Arbitrary executable MDX and a live API request explorer aren't supported.
 
 You supply hosting, reader authentication, authored translations, and any optional model or analytics services. Reader views change browsing convenience; they don't restrict access to published files. The hosted public MCP endpoint serves one configured publication, and profiled Vercel chat builds aren't supported.
 

package/agent-docs/provenance.json

@@ -2,15 +2,15 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "e3d0124ef8866a0cd2080cd8b3822909d5b4e288ef0c642b1ebcaebe2591c305",
-    "buildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f"
+    "configDigest": "0816f26a7b49559d3e41c19a7b88f59249d5d7a6e55c151c8e793586addb27c0",
+    "buildId": "ead78e4f9fa835d4189aade2c8d34a51b43400308304d415029ae2320db07da4"
   },
-  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw==",
+  "packageIntegrity": "sha512-oZG3QJeXiQYa/b0Vf6j13lFj/grebtzaeLsRkL+QbLqxGjcmnR/Gs5q/nQDai358sJcDh0XUUAcMFarbPLooHQ==",
   "compilerPackage": {
     "kind": "reviewed-local-artifact",
     "name": "@shoalrun/cli",
-    "version": "0.1.0-beta.1",
-    "integrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
+    "version": "1.1.0",
+    "integrity": "sha512-oZG3QJeXiQYa/b0Vf6j13lFj/grebtzaeLsRkL+QbLqxGjcmnR/Gs5q/nQDai358sJcDh0XUUAcMFarbPLooHQ=="
   },
-  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132"
+  "manifestDigest": "16d07fdeb5b061d6838131d603e76c475f85fcde040d5625d65516fdc19be7f8"
 }

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

@@ -17,12 +17,14 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 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'll 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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:

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Author the reference page
 
 Create `content/create-note.mdx`:

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Build and verify the output
 
 ```sh

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Next steps
 
 ### Publish several versions

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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.

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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:

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Register the operation
 
 Add this top-level entry to your existing `docs.config.yaml`:

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -25,6 +25,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## Related reading
 
 ### Next steps

package/agent-docs/publish/api-references.sections/review-imported-content-before-publishing.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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:

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -31,6 +31,8 @@ Add one authored API reference to the project created in the [quickstart](https:
 
 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.
 
+For Python libraries and SDKs, use [code API references](https://www.shoalrun.com/api-docs/code-references.md). They describe source-code interfaces rather than HTTP operations.
+
 ## 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 don't imply a live API or tested requests.

package/agent-docs/publish/content-export.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
@@ -66,6 +66,8 @@ The `documents` configuration selector remains shorthand for whole pages. Use [r
 
    Optional `contentFilter` uses configured reader facets. Every selected facet must match; choices within a facet are alternatives. Pages missing a selected facet are excluded. An explicitly requested ID that's absent, private, unavailable in the publication, or excluded by the export filter fails with a diagnostic.
 
+   The export's filter also evaluates [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) sections, including isolated snippet resources. Unmarked sections remain included. With no export filter, all valid ForFacet blocks are retained.
+
    Export selection is independent of the website's `site.contentFilter` and navigation. Changing a website menu doesn't change the app's help collection. See [separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) for website selection.
 
    Since 0.1.0-alpha.18

package/agent-docs/publish/content-export.sections/assets-downloads-and-notices.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/check-the-result.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/inspect-the-manifest.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/prerequisites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/review-exported-api-material.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/try-the-help-drawer-example.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/what-the-representations-retain.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/pdf.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 
@@ -54,7 +54,7 @@ If several publications are enabled, select one explicitly. These product and ve
 npx --no-install shoalrun export docs.config.yaml --format pdf --product core --channel production --version v2 --language en --out pdf/core-v2
 ```
 
-Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails.
+Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails. The effective filter also selects [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) sections before PDF rendering; unmarked sections remain included.
 
 Publication chapters follow navigation order. Eligible pages outside navigation are appended in stable document-ID order and reported in diagnostics. A named export target can supply an explicit document order:
 

package/agent-docs/publish/pdf.sections/apply-print-styling.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/check-the-result.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/export-a-page-or-publication.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 
@@ -44,7 +44,7 @@ If several publications are enabled, select one explicitly. These product and ve
 npx --no-install shoalrun export docs.config.yaml --format pdf --product core --channel production --version v2 --language en --out pdf/core-v2
 ```
 
-Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails.
+Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails. The effective filter also selects [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) sections before PDF rendering; unmarked sections remain included.
 
 Publication chapters follow navigation order. Eligible pages outside navigation are appended in stable document-ID order and reported in diagnostics. A named export target can supply an explicit document order:
 

package/agent-docs/publish/pdf.sections/html-markdown-and-agents.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/offer-browser-page-printing.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/offer-direct-downloads-through-a-node-server.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/prerequisites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/pdf.sections/publish-an-optional-manual-download.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 0.1.0-beta.1.**
 

package/agent-docs/publish/single-source-sites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Build separate sites from shared content
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 You can keep one content directory and build separate sites for any configured facet: audience, product, area, subarea, or a custom facet such as region. Each entry config can have its own origin, base path, branding, navigation, and output directory. A developer portal is one example; the same workflow applies to an operations site, a product site, or regional resources.
 
@@ -129,6 +129,24 @@ Every selected facet must match. Choices within one facet are alternatives: `{ a
 
 The selector doesn't rewrite publication metadata. Public access, enabled publications, and language still determine eligibility. Keep explicit navigation and page links within the selected set; missing targets fail validation rather than copying excluded pages into the output. Separate entry configs can replace inherited navigation lists.
 
+## Include additional sections in a build
+
+Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional instructions inside a shared page. The component uses the same resolved build filter, with no profile file:
+
+```mdx
+<ForFacet audience="operator">
+
+## Operational checks
+
+Record the job identifier before replaying a failed job.
+
+</ForFacet>
+```
+
+The developer build omits this block. The unfiltered main build includes it. A build that only filters region also includes it because audience isn't selected. Use whitespace-separated alternatives, such as `audience="developer operator"`; multiple facet attributes must all match.
+
+**Unmarked sections remain included. Pages without a mark for a selected facet are excluded.** Mark the containing page for every intended audience. Section selection adds information; an unfiltered build includes every valid block rather than choosing one replacement variant.
+
 ## Build and check each output
 
 From `resources/`, build each site into its own directory:
@@ -143,12 +161,16 @@ Check each output's `documents.json` for its page IDs and routes. The main site
 
 Deploy each output separately to its configured host. Building one site doesn't update the others. After editing shared content, rebuild and deploy every affected site. Keep output directories separate from sources and from one another because a successful build replaces its output directory.
 
-Selection applies to whole authored and generated pages before rendering. A selected page retains its complete body, including reader-marked sections in HTML and Markdown. Browser reader controls can't restore excluded pages. Section variants can use [publication blocks](https://www.shoalrun.com/publish/publications.md) where the sites also have distinct publications.
+Page selection applies to authored and generated pages before rendering. ForFacet then selects sections within retained pages, before headings and dependencies expand. ReaderSection remains a browser visibility control: its content stays in HTML and Markdown. Browser controls can't restore excluded pages or ForFacet sections. Use [publication blocks](https://www.shoalrun.com/publish/publications.md) when a section belongs to particular publications.
 
 Configure API sources and operation selection separately. A published OpenAPI source may contain operations beyond the selected reference pages. Generated references use their resolved facet marks, including `readerFilters.typeDefaults`. This setting is a page publication selector, not authorization for private content; protect private deployments at the host.
 
 For a help drawer or another application surface, [export the shared content](https://www.shoalrun.com/publish/content-export.md) instead of building another website. Export targets choose their own documents and produce portable content without the website shell.
 
+## HTML, Markdown, and agents
+
+Each site's selected pages and sections determine its HTML, Markdown, search, and discovery content. Agents reading that artifact receive the selected instructions; browser reader controls don't change the published files. Inspect `.shoalrun/content-selection.json` for the latest artifact's effective filter, section decisions, and warnings. Portable exports use their own target filters; PDF exports inherit the site's filter unless overridden. Check each artifact before distributing it.
+
 ## Related reading
 
 ### Next steps
@@ -161,6 +183,8 @@ For a help drawer or another application surface, [export the shared content](ht
 
 - [Reader views](https://www.shoalrun.com/author/reader-views.md) — Define the page facets used to select each site's content.
 
+- [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) — Look up section matching, export behavior, and selection reports.
+
 ### Related topics
 
 - [Share pages across products and documentation versions](https://www.shoalrun.com/publish/publications.md) — Publish separate sites from one content source using facet selections.