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

package/agent-docs/author/navigation.sections/html-markdown-and-agents.md

@@ -0,0 +1,40 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## HTML, Markdown, and agents
+
+The build resolves the navigation list before publishing either format. HTML documentation pages show the current tab's hierarchy and shared navigation as links inside expandable groups. Without tabs, the sidebar shows the full hierarchy. The active page is marked `aria-current="page"`. JavaScript adds the sidebar filter; the links and groups remain usable without it. A page's breadcrumb trail also follows its navigation position.
+
+The Markdown twin does **not** repeat the full sidebar on every page. It puts that page's breadcrumb path near the title—for example, `Write documentation > Components > Callouts`. The [document manifest](https://www.shoalrun.com/documents.json) records the same ordered path as a `breadcrumbs` array with labels and URLs where a level has a page. `/llms.txt` lists every published page with a link to its Markdown twin, including pages omitted from the sidebar.
+
+An agent can use `/llms.txt` to discover pages and `/documents.json` to recover their hierarchy, then read the Markdown pages. Changing only how YAML files are split leaves the rendered navigation and breadcrumb paths unchanged; the manifest still records the included files as build dependencies. Moving or relabeling a page changes its HTML navigation, Markdown breadcrumb, and manifest path. The node's `search` words help only the HTML sidebar filter; they do not affect Markdown or agent search.

package/agent-docs/author/navigation.sections/local-api-preview.md

@@ -0,0 +1,47 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Local API preview
+
+The local API preview creates one page per source operation through the same compiler. With `--nav layout.yaml`, its layout can use source operation IDs; the preview converts them to stable IDs in its generated config:
+
+```yaml
+navigation:
+  - id: featured
+    label: Featured endpoints
+    items:
+      - operation: createPayment
+  - generated: tags
+```
+
+The preview layout must cover every selected operation directly or through `generated: tags`. An authored project may intentionally omit pages from navigation.

package/agent-docs/author/navigation.sections/mix-guides-and-api-references.md

@@ -0,0 +1,65 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Mix guides and API references
+
+An API reference is a document too, so `doc: reference.create-payment` works beside a task guide. Use `operation` when you want to place the reference by its stable operation ID instead. That ID is independent of the OpenAPI `operationId`, HTTP path, and page slug.
+
+```yaml
+- id: payments
+  label: Payments
+  items:
+    - id: payment-guide
+      doc: guide.create-payment
+    - id: payment-api
+      operation: payments.create
+    - id: other-payment-api
+      api: payments
+      generated: tags
+```
+
+`generated: tags` groups the remaining endpoints by their first OpenAPI tag. Declared tag order and source operation order are retained **only for those remaining endpoints**. To override the position of a generated reference, add its stable operation ID as an explicit `operation:` entry at the desired point in this YAML list. You do not need to create an MDX page. An explicit `doc` or `operation` placement wins regardless of where the generator appears, so the same endpoint appears once. Leave out the generator when you want to choose every menu entry yourself. Navigation resolves separately for each channel, version, and language.
+
+An API might tag every `/Query/` route as `Query`, while readers look for `GET /Query/widgets` under **Widgets**. Place its stable operation ID among the widget operations:
+
+```yaml
+- id: widgets
+  label: Widgets
+  items:
+    - { id: get-widget, operation: widgets.getWidget }
+    - { id: query-widgets, operation: widgets.queryWidgets }
+    - { id: create-widget, operation: widgets.createWidget }
+    - { id: other-widgets, api: widgets, generated: tags }
+```
+
+The menu shows Get widget, Query widgets, then Create widget in that order, regardless of the OpenAPI tag or source order. The `id` values name menu entries; the `operation` values select reference pages. The tag generator fills only endpoints not already placed. This works whether the reference is generated at build time or comes from an authored MDX page. For complete control, list every operation or document and omit `generated: tags`.

package/agent-docs/author/navigation.sections/optionally-split-a-large-menu-into-files.md

@@ -0,0 +1,97 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Optionally split a large menu into files
+
+You can keep the whole navigation in one file, as this site's `config/nav.yaml` does. When a menu becomes difficult to edit, an `items` list can include another YAML file. Shoalrun resolves each `$include` relative to the file that contains it, so groups can include smaller groups.
+
+One possible layout is:
+
+- config
+
+  - nav.yaml
+
+  - nav
+
+    - author.yaml
+
+    - components.yaml
+
+The files above could contain:
+
+```yaml title="docs.config.yaml"
+navigation: { $include: ./config/nav.yaml }
+```
+
+```yaml title="config/nav.yaml"
+- id: author
+  label: Write documentation
+  items: { $include: ./nav/author.yaml }
+```
+
+```yaml title="config/nav/author.yaml"
+- id: components
+  label: Components
+  items: { $include: ./components.yaml }
+- { id: first-page, doc: guide.first-page }
+```
+
+```yaml title="config/nav/components.yaml"
+- { id: component-index, doc: guide.components }
+- { id: component-callout, doc: guide.component.callout }
+```
+
+Each fragment contains the list for its `items`, without an extra `items:` wrapper. The order of included items is their order in the sidebar. The build tracks included files as dependencies and rejects cycles.
+
+To join two lists inside one group, replace the single include above with [`$concat`](https://www.shoalrun.com/config.md):
+
+```yaml title="config/nav/author.yaml"
+- id: components
+  label: Components
+  items:
+    $concat:
+      - { $include: ./components-basics.yaml }
+      - { $include: ./components-more.yaml }
+```
+
+```yaml title="config/nav/components-basics.yaml"
+- { id: component-index, doc: guide.components }
+- { id: component-callout, doc: guide.component.callout }
+```
+
+```yaml title="config/nav/components-more.yaml"
+- { id: component-tabs, doc: guide.component.tabs }
+- { id: component-fields, doc: guide.component.fields }
+```
+
+The Components group shows the two basics first, then Tabs and Fields. Each included file is a YAML list, and `$concat` joins them in the listed order. Splitting files changes authoring organization only; the rendered menu uses the resolved list.

package/agent-docs/author/navigation.sections/reach-navigation-while-reading.md

@@ -0,0 +1,38 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Reach navigation while reading
+
+Desktop pages keep the sidebar and page outline visible. Keyboard skip links appear on focus without adding a row above the article. The HTML places the article before the full site navigation.
+
+On smaller screens, the page outline moves into an **On this page** disclosure below the introduction. Selecting a heading closes the disclosure and focuses the heading. Escape closes the navigation drawer; when the navigation filter contains text, the first Escape clears it. Without JavaScript, the outline remains below the article and is reachable through a skip link.

package/agent-docs/author/navigation.sections/related-reading.md

@@ -0,0 +1,44 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up every field a navigation item accepts.
+
+### Related topics
+
+- [Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) — Generate the API reference pages that fill a tag group in the menu.
+
+- [Breadcrumbs](https://www.shoalrun.com/author/components/breadcrumbs.md) — Understand the breadcrumb trails generated from navigation groups.

package/agent-docs/author/navigation.sections/split-navigation-into-tabs.md

@@ -0,0 +1,67 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Split navigation into tabs
+
+Use navigation tabs for parallel sections such as Guides, API reference, and Recipes. Mark a top-level group with `tab: true` and name its landing page by stable document ID:
+
+```yaml title="config/nav.yaml"
+- id: guides
+  label: Guides
+  tab: true
+  landing: guide.overview
+  items:
+    - { id: overview, doc: guide.overview }
+    - { id: first-page, doc: guide.add-page }
+- id: api
+  label: API reference
+  tab: true
+  landing: guide.api-references
+  items:
+    - { id: api-intro, doc: guide.api-references }
+    - { id: generated, api: notes, generated: tags }
+```
+
+Replace the example IDs and API name with your project's values. A tab ID uses lowercase letters, digits, and hyphens and starts with a letter. Tabs require a label, nonempty items, and a landing document inside those items. Nested tabs fail the build. A published page can belong to only one tab, or to shared navigation; placing it in both fails the build. Tabs whose items have no pages in a publication are omitted. A nonempty tab whose landing page is unavailable in that publication fails the build.
+
+Each tab links to its landing page. The current page's URL selects its tab and sidebar on the server. Opening a direct link, following a search result, or navigating without JavaScript selects the same section. Groups outside tabs remain shared navigation. A page outside every tab shows the shared navigation with no tab selected. Existing navigation lists work without adding tabs. Tab placement does not change page URLs or publication routes.
+
+The section links appear below the masthead on docs and wide pages. Landing and splash pages hide them by default. Set `showNavigationTabs: true` or `false` in page frontmatter to override the layout default; see [page layouts](https://www.shoalrun.com/styling/layouts.md). On smaller screens, Menu opens a drawer containing these section links and the current sidebar. Closing the drawer restores focus and the article's scroll position. Without JavaScript, Menu links to navigation below the article and section links remain in a native disclosure. They inherit each theme's typography and colors. Site-wide search still includes all sections; the sidebar filter searches only the current sidebar. Reader views can filter that sidebar without changing tab membership or agent discovery.
+
+### Agent discovery across tabs
+
+Both `/llms.min.txt` and `/llms.txt` keep every published page and add links to a scoped text index for each tab and publication. Follow the published `indexUrl`; do not construct it from the page's URL. Each scoped index links to all of that tab's Markdown pages and back to the global index, which also includes shared pages and pages omitted from navigation.
+
+Each member page's Markdown identifies its navigation section, stable tab ID, and scoped index. Its breadcrumbs include the tab. `documents.json` publishes a `navigationTabs` catalog and a matching `navigationTab` record on each member page. Records contain `id`, `label`, `variant`, `url`, `markdownUrl`, and `indexUrl`. Both search indexes carry page membership too. The generated offline documentation bundle includes the scoped indexes.
+
+Tab selection never removes page content from Markdown, filters the published inventory, or requires browser state. Navigation tabs provide links between pages; the [Tabs component](https://www.shoalrun.com/author/components/tabs.md) groups content inside one page. Neither replaces access policy or host authorization.

package/agent-docs/author/navigation.sections/subject-lifecycle-labels.md

@@ -0,0 +1,42 @@
+---
+id: guide.navigation-lifecycle
+title: Organize site navigation
+summary: Arrange guides, reference pages, and other documents into a clear site menu.
+type: how-to
+area: appearance
+subarea: appearance-navigation
+canonical: /author/navigation
+---
+
+# Organize site navigation
+
+> 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) > Customize > Navigation > Overview
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/navigation.md)
+
+The `navigation` setting controls the site's left menu. It can be a list in `docs.config.yaml` or import a separate YAML file. Add guides, tutorials, concepts, and reference pages by their stable document IDs. Nodes appear in the order you write them.
+
+Each node has a stable `id` for the menu entry. It needs exactly one of these targets:
+
+- `doc` places any page, including a guide or API reference, by its stable document ID.
+- `label` with `items` makes a group of pages or nested groups.
+- `operation` places an API reference by stable operation ID.
+- `generated` fills in API references from the registered OpenAPI source.
+
+The menu follows document IDs rather than file paths or slugs. Moving a source file or changing a page URL does not require a navigation edit. A `doc` node uses the page title by default; set `label` when the menu needs a shorter name. Pages omitted from navigation can still be built and linked from other pages.
+
+## Subject lifecycle labels
+
+Set `subjectLifecycle` to `beta`, `in-development`, `experimental`, or `deprecated` in page frontmatter. Navigation and page headers show a text badge. Markdown and the document manifest carry the same status.
+
+OpenAPI `deprecated: true` marks an endpoint as deprecated and cannot be overridden by an editorial label. The preview layout can also assign a label by source operation ID. Labels communicate maturity; they do not control access.
+
+For a deprecated subject, add [deprecation guidance](https://www.shoalrun.com/author/frontmatter.md) with optional dates, replacement, and migration references. These details appear in the article and Markdown resources; navigation keeps its concise status badge.
+
+See [current limitations](https://www.shoalrun.com/status.md) for the remaining navigation and authoring work.

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

@@ -0,0 +1,200 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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) > Write documentation > Reader views
+
+**Updated: 2026-10-25.**
+
+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.
+
+## Try the controls here
+
+### Filter the navigation
+
+This site's **Focus** dropdown changes navigation, search, and document cards. The same control appears in the header on every page. Your choice persists across visits and can be shared in the URL.
+
+- Choose **Write documentation** to bring forward pages about metadata, authoring, components, and API documentation. Pages about styling and deployment leave the navigation and search results.
+- Choose **Configure & publish** to bring forward styling, search, chat, hosting, and deployment. Authoring-specific pages leave the navigation and search results.
+- Choose **All** to see both paths. Foundational pages, such as [How Shoalrun works](https://www.shoalrun.com/concepts.md), stay in every view.
+
+All published pages still work at their direct URLs. A focus choice is a reading aid, not an access rule.
+
+This site's `focus` facet has `write` and `configure` choices. Generated API references use a `typeDefaults` mark of `write`. It also retains an internal `audience` facet for the hosted chat's author view and a `persona` facet for the page-only examples below. The header shows only Focus. These machine IDs contain no spaces; the longer labels are only shown to readers.
+
+### Filter examples on this page
+
+The controls below use a separate `persona` facet and `scope="page"`. They change the examples below without changing this site's navigation or search. Choose a reader to see one example, or use the controls to show both.
+
+[Show UI example](https://www.shoalrun.com/author/reader-views?pageView=persona%3Aui)
+
+[Show developer example](https://www.shoalrun.com/author/reader-views?pageView=persona%3Adeveloper)
+
+**For Reader: UI reader.**
+
+**UI example**
+
+In a dashboard guide, show the menu names and screen actions a reader needs. This section appears when **UI reader** is selected.
+
+**For Reader: Developer.**
+
+**Developer example**
+
+In an API guide, show the request, required fields, and expected response. This section appears when **Developer** is selected.
+
+**Show all** in the multi-select keeps both sections visible on this page. **Follow site view** removes the page-only choice and returns to the site's current reader view. The page-only choice is shareable with **Copy view link** and is not saved across visits.
+
+## Configure the choices
+
+Define the available reader choices once in `readerFilters.facets` in `docs.config.yaml`. The facet names and choices are yours; Shoalrun has no fixed list of reader types. Each facet and choice has a stable lowercase ID and a label for readers. Pages and sections refer to these IDs, and unknown IDs fail the build. `typeDefaults` is optional; it is useful when generated API references should start in the Developer view without marking every operation separately.
+
+```yaml title="docs.config.yaml"
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options:
+        ui: Use the UI
+        developer: Build with the API
+    product:
+      label: Product
+      options:
+        payments: Payments
+        reports: Reports
+    area:
+      label: Area
+      options:
+        reporting: Reporting
+        setup: Setup
+    subarea:
+      label: Subarea
+      options:
+        settlements: Settlements
+        exports: Exports
+  typeDefaults:
+    api-reference:
+      audience: [developer]
+  controls:
+    sidebar: false
+    header: { facet: audience, display: select, label: Reader }
+```
+
+Nothing is selected by default, so every page and section is visible. Readers can select more than one choice within a facet: a page marked for either selected choice appears. Different facets combine: a page marked `audience: [ui]` and `product: [payments]` appears when both selections match. A page with no mark for a facet is shared across that facet.
+
+## Mark pages
+
+Use the existing `audiences` field for the `audience` facet. `product`, `area`, and `subarea` can each supply a single choice for a same-named facet. Use `readerFilters` for other facets or when a page needs multiple choices in one facet. All of these fields work with frontmatter defaults and enforced values.
+
+```yaml title="content/payments-dashboard.mdx"
+---
+id: guide.payments-dashboard
+title: Review payments in the dashboard
+type: guide
+slug: /payments/dashboard
+audiences: [ui]
+product: payments
+area: reporting
+subarea: settlements
+---
+```
+
+When a facet is configured, `audiences` and same-named category values must use its choice IDs. You can instead use `readerFilters.audience` or `readerFilters.product`, but do not put both forms for the same facet on one page. An explicit page value overrides a `typeDefaults` value for that facet. Categories without matching configured facets remain taxonomy metadata only. Pages with no marks remain visible in every view.
+
+The page marks control navigation, search, and cards that point to the page. They do not change its URL. A direct link to a page outside the current view opens the page in full. A notice offers actions to switch view or show all content.
+
+## Mark sections and add an entry choice
+
+Use `ReaderSection` for content that belongs to a narrower view within an otherwise shared page. Content outside these blocks stays visible to everyone. Sections can contain Markdown and supported MDX components, but reader sections cannot be nested.
+
+```mdx title="content/get-started.mdx"
+<ReaderChoice audience="ui" label="Use the dashboard" />
+<ReaderChoice audience="developer" label="Build with the API" />
+
+Everyone needs an account before starting.
+
+<ReaderSection audience="ui">
+Open **Settings** in the dashboard.
+</ReaderSection>
+
+<ReaderSection audience="developer" product="payments">
+Create an API token, then run the payment CLI.
+</ReaderSection>
+```
+
+`ReaderChoice` changes only the facets named on the button. It can set several facets at once, and comma-separated values select more than one choice within a facet.
+
+## Place filter controls
+
+The site config above puts a compact reader dropdown in the header and removes the sidebar control. `controls.sidebar` defaults to `true`; `controls.header` is optional. Both can be present, and they stay in sync. Each header control accepts `facet`, `display: select` or `checks`, and an optional `label`. Omit `facet` to show every configured facet.
+
+Authors can place the same controls inside a page:
+
+```mdx
+<ReaderFilter facet="audience" display="select" label="I use…" />
+<ReaderFilter facet="product" display="checks" />
+```
+
+`select` allows one choice per facet and includes **All**. `checks` allows multiple choices and includes **Show all** and **Copy view link**. `<ReaderFilter />` controls every facet. The component is interactive in HTML and omitted from the Markdown twin; marked content and `ReaderChoice` links remain in Markdown.
+
+Set `scope="page"` on an in-page `ReaderChoice` or `ReaderFilter` to control only marked sections and cards on the current page. The site-wide choice still controls navigation and search. Page-only choices use the `pageView` URL parameter for sharing; they do not enter local storage. With no page-only choice, the page follows the site view. A page-scoped multi-select includes **Follow site view** to return to that state. The default scope is `site`.
+
+## How it works for agents
+
+Reader views change the interactive HTML. They do not create separate agent publications or a personalized agent navigation tree. An agent can discover and read every **published** page regardless of a browser reader's saved choice or a shared `view` or `pageView` URL parameter. Draft and access-controlled source pages still follow the normal publication rules.
+
+| Agent-facing output   | Reader-view behavior                                                                                                                                                                                                                                                                                                         |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Markdown twin (`.md`) | Includes shared content and every `ReaderSection`, even sections hidden in HTML. Each marked section starts with a readable label such as `**For Reader: UI reader.**`. `<ReaderFilter />` controls are omitted. `ReaderChoice` becomes a link to the interactive HTML page with its `view` or `pageView` choice in the URL. |
+| `/llms.txt`           | Lists every published Markdown page. A selected browser view does not remove entries.                                                                                                                                                                                                                                        |
+| `/documents.json`     | Lists every published page. `readerFacets` defines the configured choices; each document's `readerFilters` contains its resolved page marks. An empty map means the page is shared. Optional `product`, `area`, and `subarea` categories also appear when set.                                                               |
+| `/search-index.json`  | Retains a search record for every published page, with page marks in `readerFilters` and indexed section text in `readerSegments`. The built-in **browser** search applies the site-wide choice when displaying results.                                                                                                     |
+
+For example, [this guide's Markdown twin](https://www.shoalrun.com/author/reader-views.md) contains both the UI and Developer example paragraphs with their reader labels. Choosing a page-only view above leaves those paragraphs in the twin. The page's Markdown YAML header includes reader marks only when `outputs.markdown.metadata` explicitly selects those frontmatter fields. The resolved marks are always available in `/documents.json` when reader views are configured. Reader views help people find relevant content; use `access.policy` to decide whether a page is published at all.
+
+## Connect your own control
+
+Set `readerFilters.module` to a local `.js` or `.mjs` file. The build copies that file into the site and calls its `mountReaderViews(api)` export after the reader view is ready. This is useful for a custom header, a host application, or a login-based starting view.
+
+```yaml title="docs.config.yaml"
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options: { ui: Use the UI, developer: Build with the API }
+  controls: { sidebar: false }
+  module: ./reader-view.js
+```
+
+```js title="reader-view.js"
+export function mountReaderViews(api) {
+  const picker = document.querySelector('#my-reader-picker');
+  if (!picker) return;
+  picker.addEventListener('change', () => {
+    api.setSelection({ audience: picker.value ? [picker.value] : [] }, { merge: true });
+  });
+  api.subscribe(selection => { picker.value = selection.audience?.[0] ?? ''; });
+}
+```
+
+The API provides `facets`, `getSelection()`, `setSelection(selection, { merge? })`, `reset()`, `subscribe(listener)`, and `shareUrl()` for the site view. For the current page it provides `getPageSelection()`, `setPageSelection(selection, { merge? })`, `resetPage()`, `inheritSiteView()`, and `subscribePage(listener)`. `setSelection` and `setPageSelection` validate facet and choice IDs; they replace their respective selection unless `merge: true` is supplied. Subscribers are called immediately and return an unsubscribe function. The API is also available as `window.shoalrunReaderViews`; the page dispatches `reader-views-ready`, `reader-view-change`, and `reader-page-view-change` events. The module is copied as one file, so bundle relative imports before publishing it.
+
+**Copy view link** includes the current choice in the URL; a shared URL overrides the recipient's saved choice. A host can use the API to supply a reader's initial view, but reader filters are presentation controls. Protect private content at the host or build layer.
+
+The built-in browser search provider excludes pages and section text outside the current site view. A custom search provider receives `context.readerSelection` and must apply the same rules if it wants matching behavior. Reader views are a reading aid, not access control. Use `access.policy` to keep a page out of a public build.