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

package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md

@@ -0,0 +1,41 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Read a search result with an agent
+
+CLI and MCP search results include a ready-to-use `read` instruction: call `read.tool` with `read.arguments`. This selects `get_section` only when one eligible, author-declared standalone section heading matches the query after common English request wording and page-title context are removed. CLI/MCP ranking favors complete multiword matches to eligible section headings over incidental page-title words. Broad, ambiguous, cross-section, or undeclared-section queries select `get_page`. No outline request is needed first.
+
+The result's `markdownUrl` points to the recommended section or page, with its byte/token size when available. `pageMarkdownUrl` always points to the full page. Use that fallback when more context is needed. This is a lexical recommendation, not proof that the selected content answers the question. Page reads can still truncate at the maximum budget; inspect their budget metadata.
+
+Section resources exist only for pages of at least 2,000 `cl100k_base` tokens and only when they halve both bytes and tokens, including repeated context. Both search indexes include eligible section titles, URLs, sizes, and any `standalone: true` declaration without duplicating section bodies. Fetch-only agents should start with `/llms.min.txt`, which links to full pages and declared standalone sections, directly or through topic indexes. Each compact index is limited to 2,000 `cl100k_base` tokens; growing topics split automatically. Standalone links retain sizes and full-page fallbacks. The larger compact JSON index is optional when more headings are needed. The human search box continues to open HTML page or heading links. See [Markdown section resources](https://www.shoalrun.com/author/markdown-metadata.md).

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

@@ -0,0 +1,45 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Related reading
+
+### Next steps
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Query a built site's search index without a server.
+
+### Related topics
+
+- [Header links](https://www.shoalrun.com/styling/header.md) — The search box sits in the site header, before your header links.
+
+- [How documentation answers work](https://www.shoalrun.com/chat.md) — Use retrieved passages to produce cited answers instead of page links. (Status: experimental.)
+
+- [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — Configure semantic search and lexical fallback.

package/agent-docs/author/search.sections/reuse-the-lexical-index.md

@@ -0,0 +1,81 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Reuse the lexical index
+
+Set `index: true` to build `/search-index.json` for a custom provider. Use it to load the pages into a client-side library such as MiniSearch or FlexSearch:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: custom
+      module: ./search/minisearch.js
+      index: true
+```
+
+The generated index contains one record for each published page:
+
+```json title="search-index.json"
+{
+  "schemaVersion": 1,
+  "documents": [
+    {
+      "id": "guide.snippets",
+      "url": "/author/snippets",
+      "markdownUrl": "/author/snippets.md",
+      "title": "Reuse prose across pages",
+      "summary": "Share validated prose across pages with typed variables.",
+      "type": "how-to",
+      "variant": "production|current|en",
+      "headings": [{ "id": "register-a-snippet", "title": "Register a snippet" }],
+      "text": "A snippet is a shared Markdown or MDX fragment…"
+    }
+  ]
+}
+```
+
+The index fields have these limits:
+
+- `headings` covers levels 2 through 4, including headings later in the article.
+- `text` holds the first 5,000 characters of the HTML article as plain text. Body words beyond that limit are not searchable through this field.
+- Titles and the selected summary are indexed separately from body text.
+- A section result links to a heading; it does not mean the section's full body was indexed.
+- `id` and `markdownUrl` let local tools cite the matching page.
+
+When reader views are enabled, `readerFilters` holds page marks and `readerSegments` holds shared and marked text. A custom provider must apply those marks to respect the selected view. The full text remains in the index; reader views do not restrict access to published files.
+
+The browser index comes from the HTML article, including HTML-only blocks and excluding Markdown-only blocks written with [Only](https://www.shoalrun.com/author/components/only.md). It excludes the surrounding header, navigation, and search UI. Marked sections stay in the stored index; the built-in browser provider filters their text when a view is active. Each `readerSegments` text value is capped at 5,000 characters.
+
+The `summary` field uses `outputs.text.search`, or a page’s `displayText.search` override. Without a configured selection, it uses the frontmatter summary. This site selects description before summary. The lexical provider uses the selected text for ranking and result snippets.

package/agent-docs/author/search.sections/turn-search-off.md

@@ -0,0 +1,46 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Turn search off
+
+Set the provider to `none` to remove the browser search box and its page index:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: none
+```
+
+This removes both the reader search box and its index, so the local search command has nothing to query. Markdown twins, `/llms.txt`, and `/documents.json` do not change with the provider. Agents can still discover and fetch pages, but `shoalrun search` cannot query a missing `search-index.json`. The passage index and semantic endpoint are independent of this browser setting. Changing it does not remove those artifacts or disable a deployed endpoint.

package/agent-docs/author/search.sections/use-the-search-box.md

@@ -0,0 +1,39 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Use the search box
+
+Press `/` or `Ctrl`+`K` (`⌘`+`K` on macOS) to focus the box. Use the arrow keys to move through results, Enter to open one, and Escape to close the list. When a match falls inside a section, the result names the section and links to its heading.
+
+The box needs JavaScript. Without it, both the search box and sidebar filter stay hidden; the published navigation links still work.

package/agent-docs/author/search.sections/write-a-custom-provider.md

@@ -0,0 +1,98 @@
+---
+id: guide.search
+title: Site search
+summary: Search settings, keyboard behavior, provider interfaces, and index fields.
+type: reference
+area: discovery
+subarea: discovery-search
+canonical: /author/search
+---
+
+# Site search
+
+> 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) > Search, chat, and agent access > Site search
+
+**Updated: 2026-10-26.**
+
+**Verified: 2026-10-01.**
+
+Parent page: [Full Markdown page](/author/search.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
+
+Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+
+Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
+
+## Write a custom provider
+
+A provider is one ES module. It must export `search`, and it can export `prepare`:
+
+```js title="search/hosted.js"
+const endpoint = 'https://search.example.com/query';
+
+// Optional. Runs when the reader first focuses the box.
+export async function prepare({ language }) {
+  await fetch(`${endpoint}/warm?language=${language}`);
+}
+
+export async function search(query, { language, limit, signal }) {
+  const params = new URLSearchParams({ q: query, language, limit: String(limit) });
+  const response = await fetch(`${endpoint}?${params}`, { signal });
+  if (!response.ok) throw new Error(`Search failed: ${response.status}`);
+  const { hits } = await response.json();
+  return hits.map(hit => ({ url: hit.path, title: hit.title, summary: hit.snippet }));
+}
+```
+
+Register the module in the config:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    search:
+      provider: custom
+      module: ./search/hosted.js
+```
+
+The `module` path resolves from the config file that declares it. The module is a build dependency, so a rebuild picks up changes.
+
+### Search context
+
+The search box passes a context object to both functions.
+
+| Field             | Value                                                                                                                                                     |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`         | The page's channel, version, and language, joined by `\|`, such as `production\|current\|en`.                                                             |
+| `language`        | The page's `lang` value.                                                                                                                                  |
+| `indexUrl`        | The base-path-prefixed `/search-index.json` URL. The file exists only when the build writes an index.                                                     |
+| `limit`           | The maximum number of results the box shows.                                                                                                              |
+| `signal`          | An `AbortSignal`, passed to `search` only. It aborts when the reader types again.                                                                         |
+| `readerSelection` | The active reader view as facet IDs mapped to arrays of choice IDs. An empty object means show all. Custom providers must use it to filter their results. |
+
+Pass `signal` to `fetch` so stale requests stop. The box ignores results from an aborted search.
+
+### Search results
+
+`search` returns an array, or a promise of one. Each result is an object:
+
+| Field     | Required | Value                                                                      |
+| --------- | -------- | -------------------------------------------------------------------------- |
+| `url`     | Yes      | A site-root path or `http(s)` URL. Add `#heading-id` to link to a section. |
+| `title`   | Yes      | The page title.                                                            |
+| `summary` | No       | One line of supporting text.                                               |
+| `section` | No       | A section title, shown after the page title.                               |
+
+The box drops results without a valid `url` and `title`, and it keeps the first `limit` results. It escapes all text and highlights query terms itself. If `search` throws, the box shows "Search is unavailable right now."
+
+### Module limits
+
+The build copies one file. It does not copy files that the module imports with relative paths. Bundle the provider into one file, or import dependencies from absolute URLs.

package/agent-docs/author/snippets.md

@@ -0,0 +1,122 @@
+---
+id: guide.snippets
+title: Reuse prose across pages
+summary: Share validated prose across pages with typed variables.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/snippets
+---
+
+# Reuse prose across pages
+
+> 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 > Reusable snippets
+
+**Updated: 2026-10-27.**
+
+A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template does not change existing pages.
+
+## Register a snippet
+
+Import a `snippets` mapping in project config. Snippet IDs are dot-separated names, such as `authoring.build-check`. Each entry points to a plain `.md` or `.mdx` file and declares its variables:
+
+```yaml filename="docs/config/snippets.yaml"
+authoring.build-check:
+  file: ../snippets/build-check.mdx
+  variables:
+    command: { type: string, required: true }
+```
+
+The snippet file uses `<Var name="command" />` in prose:
+
+```mdx filename="docs/snippets/build-check.mdx"
+<Callout label="Check the result">Run <Var name="command" /> after editing. Confirm the HTML page and Markdown twin contain the same resolved snippet text.</Callout>
+```
+
+A page includes it with literal values:
+
+```mdx filename="docs/content/snippets.mdx"
+<Snippet id="authoring.build-check" values={{ command: "npm test" }} />
+```
+
+## See a variable resolve
+
+The example project has a second snippet with two variables:
+
+```yaml filename="example/config/snippets.yaml"
+payment.request-prep:
+  file: ../snippets/request-prep.mdx
+  variables:
+    product: { type: string, required: true }
+    header: { type: string, default: Idempotency-Key }
+```
+
+Its source file contains ordinary MDX prose:
+
+```mdx filename="example/snippets/request-prep.mdx"
+For <Var name="product" /> requests, choose a unique
+<Var name="header" /> and provide the amount in minor currency units.
+```
+
+The guide supplies `product` and leaves `header` at its declared default:
+
+```mdx filename="example/content/create-payment-guide.mdx"
+<Snippet id="payment.request-prep" values={{ product: "Payments" }} />
+```
+
+Readers and agents get resolved text in their respective page formats:
+
+> For Payments requests, choose a unique Idempotency-Key and provide the amount in minor currency units.
+
+The real snippet also includes a nested retry note. It inherits `product` from the outer snippet. See `example/snippets/request-prep.mdx` and `example/content/create-payment-guide.mdx` in the repository.
+
+This page uses that snippet below, so the published HTML and Markdown exercise the same expansion.
+
+> **Check the result:** Run npm test after editing. Confirm the HTML page and Markdown twin contain the same resolved snippet text.
+
+Values can be strings, numbers, or booleans. A variable can also list allowed values with `enum`, such as `tier: { type: string, enum: [free, pro] }`; its `default` must be one of them.
+
+Snippet defaults, project variables, page variables, and invocation values apply in that order. Set project variables in the top-level `variables` mapping of `docs.config.yaml`, and page variables in a page's `variables` frontmatter:
+
+```yaml title="docs.config.yaml"
+variables:
+  product: Payments
+```
+
+Unknown names, missing required values, wrong types, and recursive includes stop the build. The document manifest lists snippet IDs used by each page.
+
+For this slice, snippets use inline `<Var />` in prose. Code blocks are never changed by string replacement. Put headings in the page, and use absolute or `doc:` links inside snippets. These limits avoid ambiguous anchors and broken relative links until their adapters are built.
+
+## Component attributes
+
+`<Snippet>` is a standalone empty element in a page or registered snippet. `<Var>` is an inline empty element inside a snippet file; using it directly in a page fails the build.
+
+| Element     | Attribute | Required | Meaning                               |
+| ----------- | --------- | -------- | ------------------------------------- |
+| `<Snippet>` | `id`      | Yes      | Registered snippet ID.                |
+| `<Snippet>` | `values`  | No       | Literal mapping of invocation values. |
+| `<Var>`     | `name`    | Yes      | Variable declared for that snippet.   |
+
+The included Markdown and supported MDX components render in both HTML and Markdown. Nested snippets work, but recursive includes fail. API embeds need page-level headings and cannot be placed inside snippets. Keep headings in the page, and use absolute or `doc:` links in snippets.
+
+## Check the shared text
+
+Build your project and open each page that includes the snippet. Confirm that HTML and Markdown both contain the resolved text and that no variable tags remain. Change the snippet source and rebuild; every including page should receive that change. If validation fails, correct the named variable, include, or type before publishing.
+
+## HTML, Markdown, and agents
+
+The build expands snippets and variables into the containing page before rendering HTML and Markdown. Agents read the resolved text, not a `Snippet` or `Var` instruction to execute. Components inside a snippet retain their own output behavior; for example, an interactive control can become ordinary text in Markdown. Verify the including page in both formats after changing shared content.
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up the snippets and variables settings.
+
+### Often confused with
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — A template is copied into a new page once; a snippet is shared prose that stays in sync on every page that includes it.

package/agent-docs/author/taxonomy.md

@@ -0,0 +1,121 @@
+---
+id: guide.page-taxonomy
+title: Design and enforce a page taxonomy
+summary: Define page categories, validate allowed values, and enforce your
+  project's area and subarea rules.
+type: how-to
+area: authoring
+subarea: authoring-metadata
+canonical: /author/taxonomy
+---
+
+# Design and enforce a page taxonomy
+
+> 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 > Design and enforce a page taxonomy
+
+**Updated: 2026-10-25.**
+
+Use `area` and `subarea` to describe a page's subject independently of its place in navigation. The same subject can appear in guides, reference pages, recipes, and change notes.
+
+> Built-in taxonomy enforcement requires `@shoalrun/cli@0.1.0-alpha.3` or later.
+
+Start with an existing Shoalrun project. You need access to its configuration, authored pages, and build command.
+
+## Define allowed categories
+
+Choose areas that readers recognize and subareas for distinct subjects within them. Keep category IDs stable when changing display labels.
+
+Store the definitions and enforcement options in one file:
+
+```yaml title="config/taxonomy.yaml"
+required: [area, subarea]
+requireExplicit: [area, subarea]
+areas:
+  components:
+    label: Content components
+    subareas:
+      api-embeds: API examples and schemas
+      diagrams: Diagrams
+  api:
+    label: API documentation
+    subareas:
+      contracts: Contracts
+```
+
+Load the file as the project's taxonomy:
+
+```yaml title="docs.config.yaml"
+frontmatter:
+  taxonomy: { $include: ./config/taxonomy.yaml }
+```
+
+`required` makes the selected fields mandatory after defaults and enforced values are resolved. `requireExplicit` also requires those fields in authored source, including drafts. Generated API reference pages can inherit their categories from global frontmatter defaults.
+
+Each subarea belongs to its declared parent area. IDs do not need to share a prefix. A subarea ID must be unique across the taxonomy.
+
+## Classify pages by subject
+
+Add the category IDs to a page's frontmatter:
+
+```yaml
+area: components
+subarea: api-embeds
+```
+
+The build rejects unknown categories, missing required tags, and subareas that do not belong to the selected area. It applies the checks to authored pages and resolved generated references. The generated frontmatter schema exposes the same vocabulary and pair constraints for editors.
+
+Shoalrun publishes the definitions in `documents.json` under `taxonomy`. Individual page records and search indexes carry their resolved categories. To expose category IDs in Markdown frontmatter, add `area: frontmatter.area` and `subarea: frontmatter.subarea` to `outputs.markdown.metadata.fields`.
+
+## Allow multiple areas when needed
+
+A site permits one area and one subarea per page by default. Enable lists only for the fields your project needs:
+
+```yaml title="config/taxonomy.yaml"
+required: [area, subarea]
+requireExplicit: [area, subarea]
+multiple: [area, subarea]
+areas:
+  components:
+    label: Content components
+    subareas:
+      api-embeds: API examples and schemas
+  api:
+    label: API documentation
+    subareas:
+      contracts: Contracts
+```
+
+A page can then belong to both subjects:
+
+```yaml
+area: [components, api]
+subarea: [api-embeds, contracts]
+```
+
+Lists must be nonempty and contain unique IDs. Every subarea must belong to at least one selected area. Scalar values remain valid when multiple values are enabled. Use `multiple: [area]` if only areas may have several values; subareas then remain single-valued.
+
+A matching configured reader facet receives all selected values. See [reader views](https://www.shoalrun.com/author/reader-views.md) for facet controls and matching. Category enforcement works without configuring reader facets.
+
+## Choose the enforcement level
+
+Omit `required` to validate categories only where supplied. Omit `requireExplicit` to let authored pages inherit categories. Omit `multiple` to keep both fields single-valued.
+
+Omit `frontmatter.taxonomy` or set it to `false` to leave category fields optional with their existing behavior. Configured reader facets continue to validate their own choices.
+
+Run the ordinary build after editing the definitions or page tags:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml dist
+```
+
+Verify that missing required fields, unknown IDs, wrong parent pairs, and disallowed lists fail. Restore valid tags and inspect a generated page and the published taxonomy. When renaming or removing a category, update the definitions and affected pages together.
+
+## Related reading
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) describes the native category fields.
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) explains how category values become facets.
+- [Custom metadata](https://www.shoalrun.com/author/custom-metadata.md) covers defaults and additional fields.