@shoalrun/cli 1.0.0 → 1.1.0

package/agent-docs/author/components/for-facet.md

@@ -0,0 +1,127 @@
+---
+id: guide.component.for-facet
+title: ForFacet
+summary: Include additional sections in selected builds using configured reader facets.
+type: reference
+area: components
+subarea: components-prose
+canonical: /author/components/for-facet
+---
+
+# ForFacet
+
+> 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) > Components > ForFacet
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.1.0.**
+
+`ForFacet` selects sections during a build using the same facets as `contentFilter`. It matches any facet declared in `readerFilters.facets` and its configured choices. A shared customer page with additional internal instructions is one example. You don't need a customer profile or feature manifest. **Unmarked sections remain included. Pages without a mark for a selected facet are excluded.** A section guard can't restore an excluded page.
+
+## Syntax
+
+Declare the choices in your project config:
+
+```yaml
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { customer: Customers, internal: Internal, partner: Partners }
+    region:
+      label: Region
+      options: { eu: Europe, us: United States }
+site:
+  contentFilter: { audience: [customer] }
+```
+
+Give a shared page all applicable page-level marks, then wrap only the additional content:
+
+```mdx
+---
+id: guide.billing
+title: Billing
+summary: Understand billing and operational checks.
+type: guide
+slug: /billing
+audiences: [customer, internal]
+---
+
+Everyone receives these billing instructions.
+
+<ForFacet audience="internal">
+
+## Operational checks
+
+Check whether the original request completed before replaying a failed job.
+
+</ForFacet>
+
+Everyone receives these support instructions.
+```
+
+The customer build omits **Operational checks** and its instructions. A build with `audience: [internal]` includes them. A build without `contentFilter` includes all valid blocks and all otherwise eligible pages.
+
+## Attributes
+
+Each attribute names a facet declared in `readerFilters.facets`. Its required value is a nonempty literal string of configured choice IDs separated by whitespace. The block needs at least one facet attribute and body content. Unknown facets or choices, duplicate attributes or choices, empty values, expressions, and spread attributes fail validation, even inside an excluded ancestor.
+
+| Rule                          | Example                                            | Result                          |
+| ----------------------------- | -------------------------------------------------- | ------------------------------- |
+| Alternatives within one facet | `audience="internal partner"`                      | Either selected choice matches. |
+| Every facet must match        | `audience="internal" region="eu"`                  | Both conditions must pass.      |
+| Unselected facet              | `region="eu"` when the build only selects audience | The region condition passes.    |
+| No build filter               | Any valid block                                    | The block is included.          |
+| Nested guards                 | A ForFacet inside another ForFacet or ForFeature   | Every ancestor must pass.       |
+
+A build selecting `audience: [customer, internal]` includes either audience's blocks. This feature adds information to selected builds; it doesn't replace one version with another. An unfiltered build includes both a customer block and an internal block. Exclusion attributes and arbitrary expressions aren't supported.
+
+## Choose the right section component
+
+Choose according to whether the content must be omitted from the build or hidden in a browser view.
+
+| Component       | Purpose                                   | Content in published files                       |
+| --------------- | ----------------------------------------- | ------------------------------------------------ |
+| `ForFacet`      | Build-time selection by configured facets | Unmatched blocks are omitted.                    |
+| `ReaderSection` | Browser reader-view convenience           | All blocks remain published, including Markdown. |
+| `ForFeature`    | Feature grants from a customer profile    | Unmatched blocks are omitted under that profile. |
+
+`ForFacet` uses whitespace-separated choices. `ReaderSection` uses comma-separated choices. A retained ReaderSection that mentions a build-selected facet produces the warning `reader-section-build-facet`. Review that warning when content should be omitted from the artifact.
+
+## Exports and private selection reports
+
+A portable [content export](https://www.shoalrun.com/publish/content-export.md) uses its own target's `contentFilter`, independently of the website. Set that filter explicitly when an application export must omit internal sections. When section filters differ, canonical fragment fallback fails. The export tree can't prove that the website publishes the same anchor. Include the target resource in the export or link to its page URL without a fragment. [PDF exports](https://www.shoalrun.com/publish/pdf.md) use the target's filter or inherit the site's filter when the target doesn't specify one.
+
+After a successful build or export, `.shoalrun/content-selection.json` identifies the artifact, effective selection, section decisions, and warnings. Its `receipt` field points to the artifact-specific copy in `.shoalrun/content-selection/`. A later build replaces the latest receipt, including when it has no filter. These reports contain source locations and conditions, not section prose; keep them outside served output.
+
+## HTML, Markdown, and agents
+
+Selection happens before headings, anchors, tables of contents, dependency expansion, and rendering. An excluded block contributes no body, heading, snippet expansion, API embed, or referenced image to that artifact. Its text doesn't appear in the site's HTML, Markdown twins, search and passage indexes, or discovery content. Retained content renders normally; ForFacet adds no browser control or JavaScript requirement. Application clients receive the selected export's rendered content.
+
+Globally configured snippet files and component plugins still load and validate. Facet choice catalogs remain public configuration. A separately published OpenAPI contract isn't redacted by removing an API embed. Protect a private deployment with host authentication, and review each separately generated artifact's selection before distributing it.
+
+## Check both builds
+
+Build filtered and unfiltered outputs into separate directories. Check HTML and Markdown for the added instructions, and search the customer output for a distinctive phrase from the excluded section. Check application exports separately. The packaged `example-configs/facet-sections` example provides a complete page and two entry configs for this comparison.
+
+### Test for content crossing builds
+
+Use a small fixture with unique text, heading, snippet, image, and API-example markers inside guarded sections. Confirm each marker appears in a build that includes it, then scan every file in the excluded output for it. Checking both presence and absence prevents a broken fixture from producing a false pass.
+
+Cover the outputs you distribute: HTML and Markdown, search and discovery data, MCP runtime copies, application exports, and PDF preparation. Decode base64 asset payloads and extract text from generated PDFs; a plain text scan can't inspect compressed or encoded content. Check each export target's own selection explicitly.
+
+Interleave builds for different audiences and products in one process. Rebuild a previously broader output with a narrower filter in a temporary directory to check stale-file removal. Confirm sibling output directories remain unchanged and shared document/snippet IDs retain the correct publication scope. Keep production output directories separate, and stop deployment when any build or isolation check fails.
+
+## Related reading
+
+### Next steps
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Build separate sites with page and section selection from shared source.
+
+### Reference while working
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) — Compare build-time omission with browser visibility controls.

package/agent-docs/author/components/only.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Content for one format
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Use `<Only>` to author content for one output format. Shared material stays outside the blocks; a block can contain an instruction, explanation, example, or link that serves only one version:
 
@@ -56,6 +56,8 @@ An agent that fetches the direct `.md` URL, or requests this page with `Accept:
 This sentence appears only in the Markdown twin.
 ```
 
+HTML-only blocks are wrapped in an element marked `data-markdown-ignore`. Agent-parity checks can use that marker to tell intentional format-specific content from content that is missing by mistake.
+
 Keep facts, warnings, and task steps that both readers need outside `<Only>`, or provide suitable versions in both formats. You can add or suppress content in either output when that helps its intended reader. Check that each version remains accurate and usable for its task; see [Shoalrun's position on shared and format-specific content](https://www.shoalrun.com/publish/agent-friendliness.md). The browser search index uses the HTML output, so Markdown-only text isn't included in that search. See [publishing and agent representations](https://www.shoalrun.com/publish/output.md) for the full output contract.
 
 ## Related reading

package/agent-docs/author/components.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components aren't available.
 
@@ -60,6 +60,7 @@ Start with the reader's task, then open the linked reference before choosing syn
 - [Walkthroughs](https://www.shoalrun.com/author/components/walkthroughs.md) — code explained step by step beside a scrolling code pane.
 - [Hero](https://www.shoalrun.com/styling/layouts.md) — a landing page opener with a title, tagline, and action buttons.
 - [Section](https://www.shoalrun.com/styling/layouts.md) — a full-width band on a splash page.
+- [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) — include additional sections in selected builds using configured facets.
 - [ReaderSection, ReaderChoice, and ReaderFilter](https://www.shoalrun.com/author/reader-views.md) — marked sections, choice buttons, and in-page filter controls.
 - [FrontmatterReference](https://www.shoalrun.com/author/frontmatter-reference.md) — publish this project's built-in and declared page fields as a live reference.
 

package/agent-docs/author/reader-views.md

@@ -17,13 +17,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Try the controls here
 

package/agent-docs/author/reader-views.sections/configure-the-choices.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Configure the choices
 

package/agent-docs/author/reader-views.sections/connect-your-own-control.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Connect your own control
 

package/agent-docs/author/reader-views.sections/how-it-works-for-agents.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## How it works for agents
 

package/agent-docs/author/reader-views.sections/mark-pages.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Mark pages
 

package/agent-docs/author/reader-views.sections/mark-sections-and-add-an-entry-choice.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Mark sections and add an entry choice
 

package/agent-docs/author/reader-views.sections/place-filter-controls.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Place filter controls
 

package/agent-docs/author/reader-views.sections/try-the-controls-here.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) > Write documentation > Reader views
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/author/reader-views.md)
 
@@ -25,7 +25,7 @@ A reader view changes which pages appear in navigation and search. It also contr
 
 Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
 
-To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+To build separate sites from the same source using these facets, use [build-time selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. Use [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) for additional sections that should be omitted from particular builds; ReaderSection content remains published. A browser reader view continues to affect visibility within a published site.
 
 ## Try the controls here
 

package/agent-docs/changelog/facet-typescript.md

@@ -0,0 +1,54 @@
+---
+id: change.facet-typescript
+title: Build selection and TypeScript references
+summary: Select additional sections for each build, generate TypeScript SDK
+  references, and improve search queries written as questions.
+type: changelog-entry
+area:
+  - publishing
+  - api
+  - discovery
+  - project
+subarea:
+  - publishing-builds
+  - api-generation
+  - discovery-search
+  - project-releases
+canonical: /changelog/facet-typescript
+date: 2026-11-07
+releaseVersion: 1.1.0
+---
+
+# Build selection and TypeScript references
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > 1.1: Build selection and TypeScript
+
+**Published: 2026-11-07.**
+
+**Version: 1.1.0.**
+
+Upgrade to CLI `1.1.0` and rebuild your site and application exports.
+
+## [Choose sections for each build](https://www.shoalrun.com/author/components/for-facet.md)
+
+Choose which sections each build includes using any configured facet and its choices. `ForFacet` uses your existing `contentFilter` to omit unmatched sections from Markdown, search, and expanded resources. A shared customer page with additional internal notes is one example. It needs no customer profile. The authoring skill covers facet selection and checks for content crossing builds.
+
+## [Generate TypeScript SDK references](https://www.shoalrun.com/api-docs/typescript-references.md)
+
+Extract a public TypeScript entry point and JSDoc into native reference pages with overloads, linked types, optional methods, and readonly properties. Install `typescript@5.9.3` explicitly for extraction; normal site builds use the saved JSON. The authoring skill covers this workflow, and Shoalrun's [content client reference](https://www.shoalrun.com/content-delivery/sdk/all.md) provides a real example.
+
+## [Find docs with questions](https://www.shoalrun.com/author/search.md)
+
+Browser and CLI keyword search give content terms priority over filler words, so a focused page can match a question without repeating every word. Shoalrun's docs also recognize more common search vocabulary through configured synonyms.
+
+## [Check intentional format differences](https://www.shoalrun.com/author/components/only.md)
+
+HTML-only `Only` blocks carry `data-markdown-ignore` for compatible parity checks. Tooltip and info-hint content remains covered by the HTML/Markdown comparison.
+
+## [Load the right agent skill](https://www.shoalrun.com/contribute/agent-skills.md)
+
+Connect complete skill folders to your agent's discovery directory, use explicit loading instructions in the project, and follow a short checklist at the start of each bundled skill. CLI skill listing remains separate from native agent discovery.

package/agent-docs/changelog.md

@@ -22,6 +22,14 @@ Updates to Shoalrun and its documentation. Each entry identifies the affected ve
 
 ## Latest changes
 
+- 2026-11-07
+
+  Version 1.1.0
+
+  [Build selection and TypeScript references](https://www.shoalrun.com/changelog/facet-typescript.md)
+
+  Select additional sections for each build, generate TypeScript SDK references, and improve search queries written as questions.
+
 - 2026-11-06
 
   Version 1.0.0

package/agent-docs/config/examples.md

@@ -27,7 +27,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -52,7 +52,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/feature-showcase.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -54,7 +54,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/minimal-site.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/multilingual-help-center.md

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

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

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

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

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

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

@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/outputs.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 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.
 
@@ -62,17 +62,17 @@ Optional named targets for `shoalrun export`. They select portable application c
 
 Each target accepts these fields:
 
-| Field           | Default                                         | Meaning                                                                                                                                            |
-| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                |
-| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                    |
-| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                    |
-| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous. |
-| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't 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.                                                                              |
+| Field           | Default                                         | Meaning                                                                                                                                                                                                                     |
+| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                                                                                         |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                                                                                             |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                                                                                             |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous.                                                                          |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't match; unmarked sections remain. Also selects [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) blocks. |
+| `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:

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 
@@ -37,17 +37,17 @@ Optional named targets for `shoalrun export`. They select portable application c
 
 Each target accepts these fields:
 
-| Field           | Default                                         | Meaning                                                                                                                                            |
-| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                |
-| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                    |
-| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                    |
-| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous. |
-| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't 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.                                                                              |
+| Field           | Default                                         | Meaning                                                                                                                                                                                                                     |
+| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                                                                                                                         |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.                                                                                                             |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                                                                                                                             |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Product-scoped selection also requires `product`. Required when selection is ambiguous.                                                                          |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages don't match; unmarked sections remain. Also selects [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) blocks. |
+| `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:

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

package/agent-docs/config/outputs.sections/pdf-output.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/outputs.md)