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

package/agent-docs/author/markdown-metadata.md

@@ -0,0 +1,207 @@
+---
+id: guide.markdown-metadata
+title: Markdown metadata
+summary: Public field projection, source paths, profiles, precedence, and
+  required values.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/markdown-metadata
+---
+
+# Markdown metadata
+
+> 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) > Metadata > Markdown metadata
+
+**Updated: 2026-10-26.**
+
+The build publishes [the page metadata guide as Markdown](https://www.shoalrun.com/author/frontmatter.md) alongside its HTML page. That `.md` file starts with a YAML header containing selected values from the source page header. Source headers can grow long and contain review notes or other details that do not help an agent read the page. Selecting a small set of useful fields keeps the agent's context focused and avoids exposing internal metadata in that header. Compare the two custom values in that guide's source:
+
+```yaml title="docs/content/frontmatter.mdx"
+agent:
+  intent: Help authors understand and configure page metadata.
+editorial:
+  reviewNote: Check the frontmatter examples before release.
+```
+
+The generated `.md` header includes `agent.intent` but leaves out `editorial.reviewNote`:
+
+```yaml title="docs/dist/author/frontmatter.md"
+---
+id: guide.frontmatter
+title: Page metadata
+summary: Set page identity, publication, and presentation fields before publishing.
+description: Learn how page metadata, project defaults, and publication choices
+  shape the site and its Markdown output.
+type: reference
+audiences:
+  - authors
+  - maintainers
+canonical: /author/frontmatter
+agent:
+  intent: Help authors understand and configure page metadata.
+---
+```
+
+The `agent.intent` value appears because this site's `docs/docs.config.yaml` selects it for `reference` pages. The relevant settings are:
+
+```yaml title="docs/docs.config.yaml"
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields:
+        id: frontmatter.id
+        title: frontmatter.title
+        summary: frontmatter.summary
+        description: frontmatter.description
+        type: frontmatter.type
+        audiences: frontmatter.audiences
+        subjectLifecycle: frontmatter.subjectLifecycle
+        canonical: publication.canonicalUrl
+      omitNull: true
+      byType:
+        reference:
+          addFields:
+            agent.intent: frontmatter.agent.intent
+```
+
+Each entry under `fields` names an output key on the left and its source on the right. Here `summary` and `description` stay separate, while `audiences` comes from the page's intended-reader labels. The `byType.reference` rule adds `agent.intent` only for pages whose `type` is `reference`. `subjectLifecycle` is absent from the example output because that guide has no subjectLifecycle value and `omitNull` is true.
+
+The review note is absent because its declaration sets `public: false` and the output config does not select it. This controls only the generated YAML header: text written in the page body still appears in the published Markdown and HTML.
+
+Keep this header short. Include the fields an agent needs for the page, and leave out long descriptions or notes that take up its context.
+
+### Projection settings
+
+`format` must be `yaml-frontmatter` to write a header. It defaults to `none`, so a projection with `fields` but no `format` writes no header and reports no error. `format: none` removes the header while leaving the full page body in Markdown.
+
+A field source is either `frontmatter.<path>` or one of these publication values:
+
+| Source                     | Value                                                                                    |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `publication.channel`      | The page's publication channel.                                                          |
+| `publication.version`      | The page's publication version.                                                          |
+| `publication.language`     | The page's language.                                                                     |
+| `publication.canonicalUrl` | The page route, such as `/author/frontmatter`. It is site-relative, not an absolute URL. |
+
+Built-in public fields can be selected directly. A custom field needs a declaration with `public: true`. The protected roots `access`, `seo`, `markdownMetadata`, `variables`, `tocDepth`, `private`, `internal`, `card`, and `displayText` cannot be selected under any name. With `omitNull: false`, a missing value fails the build instead of being skipped.
+
+Layers apply in order. The base settings come first, then `byType.<type>`, then a named profile, then the page's own override. Each layer accepts `format`, `fields`, `addFields`, `removeFields`, and `omitNull`. `fields` replaces the inherited fields; `addFields` merges into them; `removeFields` drops output names and fails if a name is missing.
+
+Define named profiles under `profiles`, then select one from a page:
+
+```yaml title="docs.config.yaml"
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields: { id: frontmatter.id, title: frontmatter.title }
+      profiles:
+        minimal:
+          removeFields: [title]
+```
+
+```yaml title="A page's frontmatter"
+markdownMetadata: minimal
+```
+
+A page can also write the override as a mapping, such as `markdownMetadata: { profile: minimal, addFields: { language: publication.language } }`. The example API project under `framework/example/` uses the same declaration and projection pattern.
+
+See [the generated frontmatter reference](https://www.shoalrun.com/author/frontmatter-reference.md) for the local project field inventory. See [cards and collections](https://www.shoalrun.com/author/components/cards.md) for card inheritance and collection filters, and [related reading](https://www.shoalrun.com/author/related-reading.md) for authored reading paths.
+
+### Put a field on every page
+
+List the field under `fields` at the top level of `outputs.markdown.metadata`. Top-level `fields` apply to every page. A `byType` rule adds fields only for pages of that type, so use it for extras and not for a field that every page needs.
+
+To require the value as well, declare the field with `required: true`. A page that lacks it then fails the build, and the error names the file:
+
+```yaml title="docs.config.yaml"
+frontmatter:
+  fields:
+    agent.intent:
+      type: string
+      description: The reader task this page helps an agent complete.
+      public: true
+      required: true
+
+outputs:
+  markdown:
+    metadata:
+      format: yaml-frontmatter
+      fields:
+        id: frontmatter.id
+        title: frontmatter.title
+        summary: frontmatter.summary
+        type: frontmatter.type
+        canonical: publication.canonicalUrl
+        agent.intent: frontmatter.agent.intent
+```
+
+Each page then writes its own value:
+
+```yaml title="A page's frontmatter"
+agent:
+  intent: Help a reader install Acme.
+```
+
+Every Markdown copy carries the field, one copy for each publication the page is in. Without `required: true`, a page that lacks the value is skipped when `omitNull` is true and fails the build when it is false. A shared default from `frontmatter.defaults` also satisfies `required: true`.
+
+## Published Markdown size
+
+Each page record in `documents.json` and `search-index.min.json` includes `markdownBytes`, `markdownTokens`, and `markdownTokenEncoding`. Bytes count the complete published `.md` file as UTF-8, including its metadata, navigation links, reader labels, and final newline. Tokens count that same text using `cl100k_base`; special-token spellings are treated as ordinary text. This count is specific to that encoding, not a universal model budget.
+
+Use the record's `markdownUrl` and publication coordinates to select the file. The manifest's `digest` remains the SHA-256 of those exact Markdown bytes. Counts live outside the Markdown itself, avoiding a self-referential size field. The compact index still omits article text and reader segments.
+
+## Declare sections that can be read alone
+
+Search recommends a section only when its heading uniquely matches the query and the author has listed that exact heading text in the page's `standaloneSections` frontmatter:
+
+```yaml
+standaloneSections:
+  - Try the page controls
+```
+
+Review the section together with the introduction that every section file repeats. All required setup, definitions, warnings, and steps for the section's stated purpose must be present there. A procedure that depends on configuration elsewhere in the page should use a full-page read. For example, the reader-views section about marking content needs facet configuration from another section, so this site leaves it undeclared.
+
+This field is page-specific; site defaults and enforced values cannot set it. Each value must match exactly one top-level level-two heading's text, including case. Missing or duplicate headings fail the build, even on short pages. The compiler checks identity and size eligibility; it cannot verify the author's claim about completeness. Re-review declarations when the content or its prerequisites change. Do not mark every section merely to obtain smaller reads.
+
+Omitting the list, using an empty list, or reading an older search index makes search use full pages for those headings. Size eligibility still applies to declared headings. Undeclared resources remain available through outlines and explicit section reads for callers that already have the context. Fetch-only consumers should require `standalone: true` before automatically choosing a section. A declaration does not guarantee relevance to every question; use the full-page fallback for broader tasks.
+
+## Fetch one section
+
+Each page record in `documents.json` now includes a `sections` outline. Entries describe top-level level-two headings in the normalized content tree. A section includes its nested headings and components through the next top-level heading of the same or higher level. Headings inside tabs, reader sections, lists, or disclosures do not become separate resources. Section files are generated only when the full page has at least 2,000 `cl100k_base` tokens and the complete section, including repeated context, uses at most half the page’s bytes and tokens. Other pages and sections use the full Markdown page; their outlines can be empty.
+
+Fetch the entry's `markdownUrl` for a complete section file. For example, the agent-friendliness page has a section at `/publish/agent-friendliness.sections/try-the-page-controls.md`. These are real static resources: adding `#heading` to the full page URL does not make an HTTP request smaller. The compact search index includes eligible section titles, URLs, sizes, and standalone declarations, so fetch-only agents can select them without downloading the full manifest. The short `llms.min.txt` index lists full pages and nests only author-declared standalone section links, with exact sizes and a **Full page** fallback. A fetch-only agent can use those text links without reading JSON or calling a search tool.
+
+Each file repeats the parent's projected metadata, title, publication dates, navigation, introductory content, and fictional-content notice when present. It then includes the selected section with all nested reader labels and code fences. Top-level current-page `RelatedReading` prerequisites and next steps omitted by the section boundary are included as a labeled **Page reading path**, without duplicating links already in the selected content. Nested or other-page relationship views remain in their original scope; see [reading paths](https://www.shoalrun.com/author/related-reading.md). Shared reference definitions are retained. Local fragment links point back to the full parent Markdown page. Section files are complete representations, not byte slices of the parent.
+
+| Outline field                                              | Meaning                                                                                                                    |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `standalone`                                               | Present as `true` only when the author declares the section self-contained. Absence means search recommends the full page. |
+| `id`, `title`, `depth`                                     | Generated section ID, heading text, and level two.                                                                         |
+| `markdownUrl`                                              | Fetch URL and citation for the section resource.                                                                           |
+| `parentMarkdownUrl`, `parentDigest`                        | Full page URL and SHA-256 digest of its published Markdown.                                                                |
+| `digest`                                                   | SHA-256 of the complete section file.                                                                                      |
+| `markdownBytes`, `markdownTokens`, `markdownTokenEncoding` | Exact section size, using the same UTF-8 and `cl100k_base` rules as page metadata.                                         |
+
+Section IDs use normalized lowercase title text, ASCII letters and digits, and hyphens, limited to an 80-character stem. A title with no usable characters uses `section`. Collisions receive suffixes beginning with `-2` in document order. These IDs are not permanent: renaming, inserting, or reordering headings can change them. Cite the stable page ID, publication coordinates, section ID, section URL, and both digests. The surrounding manifest supplies the page identity, publication, and build ID.
+
+From the repository root, inspect and read the agent-friendliness example's sections with the local CLI:
+
+```sh
+node framework/dist/cli.js docs outline guide.agent-friendliness --site docs/dist --max-tokens 10000
+node framework/dist/cli.js docs section guide.agent-friendliness try-the-page-controls --site docs/dist --max-tokens 10000
+```
+
+For ordinary retrieval, start with `docs search` and follow the result’s `read` instruction; the outline command is optional. Search returns a recommended `markdownUrl` and a `pageMarkdownUrl` fallback. Both commands above return JSON. Select `--channel`, `--version`, and `--language` when a page has multiple publications. The outline and section must fit the requested token budget in full; increase `--max-tokens` when they do not. Section reads verify the file digest and its link to the parent record. [MCP clients](https://www.shoalrun.com/publish/mcp.md) can use `get_outline` and `get_section` for the same operations. Rebuild older sites to add section resources.
+
+## Related reading
+
+### Reference while working
+
+- [Frontmatter field reference](https://www.shoalrun.com/author/frontmatter-reference.md) — Check native fields and the current project declarations.

package/agent-docs/author/navigation.md

@@ -0,0 +1,269 @@
+---
+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.**
+
+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.
+
+## Arrange authored pages
+
+```yaml
+- id: overview
+  doc: guide.overview
+- id: learn
+  label: Learn
+  items:
+    - id: first-steps
+      doc: guide.first-steps
+      label: First steps
+    - id: core-concepts
+      doc: concept.core
+- id: tasks
+  label: Tasks
+  items:
+    - id: create-payment
+      doc: guide.create-payment
+    - id: handle-errors
+      doc: guide.handle-errors
+```
+
+Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout does not control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
+
+Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting does not add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators cannot have `search`.
+
+## 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.
+
+## 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.
+
+## Hide group page counts
+
+Navigation groups show their page counts by default. To omit the counts from the HTML menu, set `outputs.html.navigation.showCounts` to `false`:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    navigation:
+      showCounts: false
+```
+
+The setting applies to every group, including nested groups and API navigation. The menu filter still finds pages and hides empty groups. Set `showCounts: true`, or omit it, to show counts again. This setting does not change Markdown output.
+
+## 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.
+
+## 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.
+
+## 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`.
+
+## Fill an API tag group
+
+Set `api` and `tag` on a group, then add `generated: remaining` inside `items`:
+
+```yaml
+- id: reports-tools
+  label: Reports tools
+  api: payments
+  tag: Reports
+  items:
+    - id: reports-rest
+      generated: remaining
+```
+
+The build rejects unknown operation IDs, duplicate placements, and duplicate tag generators.
+
+## 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.
+
+## 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.
+
+## 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/arrange-authored-pages.md

@@ -0,0 +1,58 @@
+---
+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.
+
+## Arrange authored pages
+
+```yaml
+- id: overview
+  doc: guide.overview
+- id: learn
+  label: Learn
+  items:
+    - id: first-steps
+      doc: guide.first-steps
+      label: First steps
+    - id: core-concepts
+      doc: concept.core
+- id: tasks
+  label: Tasks
+  items:
+    - id: create-payment
+      doc: guide.create-payment
+    - id: handle-errors
+      doc: guide.handle-errors
+```
+
+Each `doc` value must match a page's frontmatter ID. Groups can contain other groups, so a larger site can place task guides under a product area. Use a structure that matches the reader's tasks; the source directory layout does not control the menu. The build rejects missing document IDs and malformed groups. For a publication where a page has no matching channel, version, or language, its menu entry is omitted. An empty group is omitted too.
+
+Use `search` on an individual page or operation node to add terms to the reader's **sidebar menu filter**. The filter also matches the page label and its group labels. For example, `search: refunds returns` helps readers find a page whose title uses different words. This setting does not add terms to the site-wide search index; [site search](https://www.shoalrun.com/author/search.md) uses page content and search metadata. Groups and generators cannot have `search`.

package/agent-docs/author/navigation.sections/fill-an-api-tag-group.md

@@ -0,0 +1,48 @@
+---
+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.
+
+## Fill an API tag group
+
+Set `api` and `tag` on a group, then add `generated: remaining` inside `items`:
+
+```yaml
+- id: reports-tools
+  label: Reports tools
+  api: payments
+  tag: Reports
+  items:
+    - id: reports-rest
+      generated: remaining
+```
+
+The build rejects unknown operation IDs, duplicate placements, and duplicate tag generators.

package/agent-docs/author/navigation.sections/hide-group-page-counts.md

@@ -0,0 +1,45 @@
+---
+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.
+
+## Hide group page counts
+
+Navigation groups show their page counts by default. To omit the counts from the HTML menu, set `outputs.html.navigation.showCounts` to `false`:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    navigation:
+      showCounts: false
+```
+
+The setting applies to every group, including nested groups and API navigation. The menu filter still finds pages and hides empty groups. Set `showCounts: true`, or omit it, to show counts again. This setting does not change Markdown output.