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

package/agent-docs/author/css.sections/page-transitions.md

@@ -0,0 +1,60 @@
+---
+id: guide.css
+title: CSS and theme reference
+summary: Customize colors, typography, layout, navigation, code, and component
+  styles with one project stylesheet.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /author/css
+---
+
+# CSS and theme reference
+
+> 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 > CSS and theme reference
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/css.md)
+
+The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  customCss: ./styles/project.css
+```
+
+```css title="styles/project.css"
+:root {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --color-accent: #2458a6;
+  --color-link: #2458a6;
+  --width-site: 92rem;
+}
+.page-head h1 { letter-spacing: -.02em; }
+```
+
+Pages link these stylesheets in order, and later files win: `/assets/site.css` (which imports `tokens.css` and `header.css`), a preset's `/assets/theme.css`, the generated `/assets/palette.css`, the generated `/assets/fonts.css`, then `/assets/project.css`. [Themes](https://www.shoalrun.com/styling/themes.md) lists when each one is present.
+
+To use your own font files, set [`theme.fonts`](https://www.shoalrun.com/styling/themes.md) instead of writing `@font-face` rules here. The build then copies the files, preloads the body font, and sets `--font-body`, `--font-heading`, and `--font-code` for you.
+
+Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or `@import` files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.
+
+Before writing CSS, check whether a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), or [color mode](https://www.shoalrun.com/styling/color-modes.md) already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.
+
+Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--color-field-surface`, `--color-ink`, and `--color-border` for `neutral`; `info`, `success`, `warning`, and `new` use the matching callout note, tip, warning, and important tokens. Register a color in `badges.variants` to add or override a variant with checked light and dark text contrast. The generated `/assets/badges.css` loads after palette CSS and before project CSS.
+
+## Page transitions
+
+In browsers that support cross-document view transitions, the reading column fades between pages while the masthead and sidebar stay in place. Other browsers load pages as usual. The fade is off when the reader's system asks for reduced motion. To turn it off for every reader, add this rule to project CSS:
+
+```css title="styles/project.css"
+@view-transition { navigation: none; }
+```
+
+The publication label adjusts automatically. A single channel, version, and language leaves the top-right spot empty. When one dimension varies, only that dimension appears. Set `site.editionBadge: always` to show all three values or `site.editionBadge: never` to hide the label. `auto` is the default.

package/agent-docs/author/css.sections/responsive-behavior.md

@@ -0,0 +1,58 @@
+---
+id: guide.css
+title: CSS and theme reference
+summary: Customize colors, typography, layout, navigation, code, and component
+  styles with one project stylesheet.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /author/css
+---
+
+# CSS and theme reference
+
+> 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 > CSS and theme reference
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/css.md)
+
+The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  customCss: ./styles/project.css
+```
+
+```css title="styles/project.css"
+:root {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --color-accent: #2458a6;
+  --color-link: #2458a6;
+  --width-site: 92rem;
+}
+.page-head h1 { letter-spacing: -.02em; }
+```
+
+Pages link these stylesheets in order, and later files win: `/assets/site.css` (which imports `tokens.css` and `header.css`), a preset's `/assets/theme.css`, the generated `/assets/palette.css`, the generated `/assets/fonts.css`, then `/assets/project.css`. [Themes](https://www.shoalrun.com/styling/themes.md) lists when each one is present.
+
+To use your own font files, set [`theme.fonts`](https://www.shoalrun.com/styling/themes.md) instead of writing `@font-face` rules here. The build then copies the files, preloads the body font, and sets `--font-body`, `--font-heading`, and `--font-code` for you.
+
+Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or `@import` files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.
+
+Before writing CSS, check whether a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), or [color mode](https://www.shoalrun.com/styling/color-modes.md) already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.
+
+Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--color-field-surface`, `--color-ink`, and `--color-border` for `neutral`; `info`, `success`, `warning`, and `new` use the matching callout note, tip, warning, and important tokens. Register a color in `badges.variants` to add or override a variant with checked light and dark text contrast. The generated `/assets/badges.css` loads after palette CSS and before project CSS.
+
+## Responsive behavior
+
+Above `72rem`, every page reserves the same right column so the article stays in place when moving between pages with and without a ToC. A ToC appears there as a sticky outline, and the API data panel shares that rail. At `72rem` and below, the rail moves below the article column. At `48rem` and below, the navigation and the outline become two compact buttons, **Menu** and **On this page**, side by side above the article. Each opens to the full width, and both start closed so the page title is on the first screen. The page's `tocDepth` frontmatter controls which headings appear in the outline, and `0` hides it. See the [frontmatter guide](https://www.shoalrun.com/author/frontmatter.md) for examples.
+
+As the reader scrolls, the outline marks the current section with `aria-current="location"`. Style it with `.page-toc a[aria-current]`.
+
+The reader script adds a link icon beside each article heading from level two to four. Selecting it copies the section URL and puts it in the address bar. Without clipboard access, the icon works as an ordinary link. The icon isn't part of the page source, so it doesn't appear in Markdown twins or search results.

package/agent-docs/author/css.sections/status-code-and-callout-tokens.md

@@ -0,0 +1,89 @@
+---
+id: guide.css
+title: CSS and theme reference
+summary: Customize colors, typography, layout, navigation, code, and component
+  styles with one project stylesheet.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /author/css
+---
+
+# CSS and theme reference
+
+> 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 > CSS and theme reference
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/css.md)
+
+The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  customCss: ./styles/project.css
+```
+
+```css title="styles/project.css"
+:root {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --color-accent: #2458a6;
+  --color-link: #2458a6;
+  --width-site: 92rem;
+}
+.page-head h1 { letter-spacing: -.02em; }
+```
+
+Pages link these stylesheets in order, and later files win: `/assets/site.css` (which imports `tokens.css` and `header.css`), a preset's `/assets/theme.css`, the generated `/assets/palette.css`, the generated `/assets/fonts.css`, then `/assets/project.css`. [Themes](https://www.shoalrun.com/styling/themes.md) lists when each one is present.
+
+To use your own font files, set [`theme.fonts`](https://www.shoalrun.com/styling/themes.md) instead of writing `@font-face` rules here. The build then copies the files, preloads the body font, and sets `--font-body`, `--font-heading`, and `--font-code` for you.
+
+Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or `@import` files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.
+
+Before writing CSS, check whether a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), or [color mode](https://www.shoalrun.com/styling/color-modes.md) already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.
+
+Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--color-field-surface`, `--color-ink`, and `--color-border` for `neutral`; `info`, `success`, `warning`, and `new` use the matching callout note, tip, warning, and important tokens. Register a color in `badges.variants` to add or override a variant with checked light and dark text contrast. The generated `/assets/badges.css` loads after palette CSS and before project CSS.
+
+## Status, code, and callout tokens
+
+Use these tokens to style status messages, code examples, and callouts.
+
+| Token                                                             | Controls                                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--color-presence-bg`, `--color-presence-text`                    | Required field badge.                                                                                                                                                                                                                                              |
+| `--color-optional-bg`, `--color-optional-text`                    | Optional field badge.                                                                                                                                                                                                                                              |
+| `--color-deprecated-bg`, `--color-deprecated-text`                | Deprecated subject lifecycle badge.                                                                                                                                                                                                                                |
+| `--color-beta-bg`, `--color-beta-text`                            | Beta subject lifecycle badge.                                                                                                                                                                                                                                      |
+| `--color-development-bg`, `--color-development-text`              | In-development subject lifecycle badge.                                                                                                                                                                                                                            |
+| `--color-experimental-bg`, `--color-experimental-text`            | Experimental subject lifecycle badge.                                                                                                                                                                                                                              |
+| `--color-code-bg`                                                 | Inline code background.                                                                                                                                                                                                                                            |
+| `--color-code-text`                                               | Plain code text on dark blocks.                                                                                                                                                                                                                                    |
+| `--color-code-muted`                                              | Code toolbar label.                                                                                                                                                                                                                                                |
+| `--color-code-border`                                             | Code toolbar and button border.                                                                                                                                                                                                                                    |
+| `--color-code-block`                                              | Code block background. It takes effect only when the build writes `palette.css`: any palette or mode other than the default `kelp` in light mode. Otherwise, code blocks use `--color-ink`; to change them there, style `.code-block` and `.content pre` directly. |
+| `--color-callout-line`                                            | Callout left rule.                                                                                                                                                                                                                                                 |
+| `--color-callout-bg`                                              | Callout background.                                                                                                                                                                                                                                                |
+| `--color-callout-{note,tip,important,warning,caution}-line`       | Left rule for each typed callout.                                                                                                                                                                                                                                  |
+| `--color-callout-{note,tip,important,warning,caution}-bg`         | Background for each typed callout.                                                                                                                                                                                                                                 |
+| `--color-callout-{note,tip,important,warning,caution}-text`       | Label text for each typed callout.                                                                                                                                                                                                                                 |
+| `--callout-dark-line`, `--callout-dark-bg`, `--callout-dark-text` | Dark-mode colors for a [custom callout tone](https://www.shoalrun.com/author/components/callout.md) with a `dark` block. The build sets them on the callout along with a `data-callout-dark` attribute.                                                            |
+
+### Preset-specific tokens
+
+Some [presets](https://www.shoalrun.com/styling/themes.md) define extra tokens in their own stylesheet. They apply only when that preset is active:
+
+| Preset   | Token            | Controls                                                |
+| -------- | ---------------- | ------------------------------------------------------- |
+| `ledger` | `--font-ui`      | Interface labels; defaults to `--font-code`.            |
+| `ledger` | `--font-heading` | Set to `--font-ui`, so headings use the monospace font. |
+| `vice`   | `--font-display` | Display type for the site title, headings, and labels.  |
+| `vice`   | `--font-heading` | Set to `--font-display`.                                |
+| `vice`   | `--sunset`       | The gradient used for accents.                          |
+| `reef`   | `--shadow-panel` | Panel and card shadow.                                  |
+
+The default `site` code theme colors code text with `--code-foreground` and tokens with `--code-token-keyword`, `--code-token-string`, `--code-token-string-expression`, `--code-token-constant`, `--code-token-function`, `--code-token-parameter`, `--code-token-link`, `--code-token-comment`, and `--code-token-punctuation`. Palettes set the token colors from their dark set; `--code-foreground` and the comment and punctuation colors follow `--color-code-text` and `--color-code-muted`. Project CSS can override any of them. A named Shiki theme puts its colors directly on highlighted tokens instead. A light Shiki theme also sets the code block background; a dark theme leaves it to `--color-code-block`. To change those colors, set `outputs.html.highlighting.theme` to another bundled theme or use a custom highlighting adapter. The [code highlighting guide](https://www.shoalrun.com/author/components/code-blocks.md) documents those settings.

package/agent-docs/author/css.sections/typography-shape-and-width-tokens.md

@@ -0,0 +1,71 @@
+---
+id: guide.css
+title: CSS and theme reference
+summary: Customize colors, typography, layout, navigation, code, and component
+  styles with one project stylesheet.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /author/css
+---
+
+# CSS and theme reference
+
+> 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 > CSS and theme reference
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/css.md)
+
+The built site loads `/assets/site.css`, which imports `/assets/tokens.css`. To customize a project, set `site.customCss` to a local stylesheet. The build copies it to `/assets/project.css` and links it after the framework CSS on every HTML page. Paths resolve from the config file that declares them, including imported config fragments. The stylesheet is a build dependency, so changes are picked up on rebuild.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Example documentation
+  customCss: ./styles/project.css
+```
+
+```css title="styles/project.css"
+:root {
+  --font-body: Inter, ui-sans-serif, system-ui, sans-serif;
+  --color-accent: #2458a6;
+  --color-link: #2458a6;
+  --width-site: 92rem;
+}
+.page-head h1 { letter-spacing: -.02em; }
+```
+
+Pages link these stylesheets in order, and later files win: `/assets/site.css` (which imports `tokens.css` and `header.css`), a preset's `/assets/theme.css`, the generated `/assets/palette.css`, the generated `/assets/fonts.css`, then `/assets/project.css`. [Themes](https://www.shoalrun.com/styling/themes.md) lists when each one is present.
+
+To use your own font files, set [`theme.fonts`](https://www.shoalrun.com/styling/themes.md) instead of writing `@font-face` rules here. The build then copies the files, preloads the body font, and sets `--font-body`, `--font-heading`, and `--font-code` for you.
+
+Use tokens for broad changes and the generated classes below for a particular region. The project stylesheet is copied as one file; relative images or `@import` files are not copied automatically. Use site-root URLs for separately hosted assets. Markdown twins contain content, not CSS.
+
+Before writing CSS, check whether a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), or [color mode](https://www.shoalrun.com/styling/color-modes.md) already covers the change. Project CSS loads after all three, so the tokens below override them. The build checks palette colors for contrast. It does not check colors set here.
+
+Inline [badges](https://www.shoalrun.com/author/components/badge.md) use `--color-field-surface`, `--color-ink`, and `--color-border` for `neutral`; `info`, `success`, `warning`, and `new` use the matching callout note, tip, warning, and important tokens. Register a color in `badges.variants` to add or override a variant with checked light and dark text contrast. The generated `/assets/badges.css` loads after palette CSS and before project CSS.
+
+## Typography, shape, and width tokens
+
+Use these tokens to adjust text, corner shapes, and content widths.
+
+| Token                                   | Controls                                                                                                                              |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `--font-body`                           | Body and interface font stack.                                                                                                        |
+| `--font-code`                           | Inline code, blocks, and small technical labels.                                                                                      |
+| `--font-heading`                        | Page titles and section headings. Defaults to `--font-body`.                                                                          |
+| `--radius-small`                        | Inputs, small panels, code, tabs, and disclosures.                                                                                    |
+| `--radius-panel`                        | Larger cards and example panels.                                                                                                      |
+| `--shadow-edge`                         | A faint outline and top highlight on code blocks and `reef` panels. Empty in light mode; palettes set it in dark mode.                |
+| `--width-site`                          | Maximum width of the page shell, whether or not a right rail is present.                                                              |
+| `--width-reference`                     | Maximum width of the masthead.                                                                                                        |
+| `--landing-width`                       | Maximum width of a `landing` page, a `splash` section, and their masthead. Defaults to `76rem`.                                       |
+| `--nav-item-height`, `--nav-item-pad-y` | Height and vertical padding of navigation rows. Rows are 44px tall for touch and 32px tall with a mouse or trackpad on wider screens. |
+
+Each preset's font stack starts with its bundled font, followed by a matching fallback face named after it, such as `"Inter Fallback"`. The fallback is a local system font resized to the bundled font's metrics, so text keeps its place while the font loads. `fonts.css` defines these faces; with `theme.fonts: system`, the build omits them and the stacks fall through to system fonts.
+
+The root text size is `16px` and line height is `1.65` in `site.css`. Override `:root` in the project stylesheet if the whole site needs different type scale. Article paragraphs, headings, and code blocks also have local sizes that can be overridden by their selectors.

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

@@ -0,0 +1,177 @@
+---
+id: guide.custom-metadata
+title: Metadata customization
+summary: Configure metadata defaults, enforcement, fields, and providers.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/custom-metadata
+---
+
+# Metadata customization
+
+> 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 > Metadata customization
+
+**Updated: 2026-10-26.**
+
+Use this guide when your project needs shared metadata rules or fields beyond the [native page metadata](https://www.shoalrun.com/author/frontmatter.md). To choose which values appear in published Markdown, see [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Global defaults and enforced values
+
+The project config is the root `docs.config.yaml` plus any imported fragments. Its `frontmatter` block supplies shared page values; this block does not appear inside an individual page's header. Configure it in the root file or an imported fragment:
+
+```yaml
+frontmatter:
+  locales: { en: en-US }
+  defaults:
+    type: guide
+    channel: production
+    version: v1
+    language: en
+    audiences: [developers]
+    access: { policy: draft }
+    seo:
+      description: Documentation for the example API.
+    variables:
+      product: Payments
+  enforced:
+    audiences: [partners]
+    editorial:
+      owner: API documentation
+  fields:
+    editorial.owner:
+      type: string
+      description: Team responsible for the documentation.
+```
+
+`defaults` fills in values that a page may replace. `enforced` sets values the page cannot replace. Precedence is **defaults → page frontmatter → enforced values**. Objects merge recursively, and arrays replace rather than concatenate. In this example, every page's effective audience is `partners`, even if its source lists another audience. A page can override the default SEO description, but cannot override the enforced editorial owner.
+
+The `id` and `slug` fields must stay on each page; they cannot be global defaults or enforced values. Other native and custom metadata can be inherited. Required fields and declared types are checked after merging, so an inherited `type`, `summary`, or required custom field satisfies validation. The generated JSON Schema omits inherited fields from its source-level required lists. Global values do not bypass public metadata projection rules.
+
+`access` follows the same precedence. A default public policy allows a page to remain an explicit draft. An enforced public policy replaces even an explicit draft policy, so use defaults if authors need to keep individual pages unpublished. Scaffolded files are still initially written with draft access.
+
+For language, a page uses the enforced language, its own language, the frontmatter default, `publications.defaults.language`, then `en`, in that order. Enabled publication entries that omit language use the enforced/default global language, then the publication default, then `en`. The current router leaves the default language unprefixed. Future translation URL conventions remain open.
+
+`frontmatter.locales` sets the usual formatting locale for each language. A page can override it with its own `locale`; `frontmatter.enforced.locale` takes precedence over both. The locale has no routing effect. A project with one language can instead use `frontmatter.defaults.locale` without a map.
+
+When updating an earlier prototype project, rename these settings:
+
+| Earlier name                                                              | Current name              | If left unchanged                                                                  |
+| ------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------- |
+| `publications.defaults.locale`, `publications.enabled[].locale`           | `language`                | The config loader fails with a migration message.                                  |
+| Page `locale` used to choose a publication                                | `language`                | The page uses the default language, and `locale` sets only formatting conventions. |
+| `redirects[].to.locale`                                                   | `redirects[].to.language` | The build fails because the redirect has no full target publication.               |
+| `publication.locale` in Markdown metadata sources                         | `publication.language`    | The build fails with an unknown metadata source.                                   |
+| Page `lifecycle: beta`, `in-development`, `experimental`, or `deprecated` | `subjectLifecycle`        | No status badge appears, and the build reports no error.                           |
+| `--locale` CLI option                                                     | `--language`              | The command fails with an unknown-option error.                                    |
+| `locale` in a custom search provider's context                            | `language`                | The value is `undefined`.                                                          |
+
+Review page `locale` values individually, because that name now means formatting conventions.
+
+Set nested global values with YAML mappings, as shown above. Dotted names such as `editorial.owner` belong in `fields` declarations and metadata projections. Global settings are applied in memory during the build; source pages are not rewritten. There are no directory-specific or document-type global policies yet.
+
+## Add a custom page field
+
+The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) uses the optional, project-defined `agent.intent` field to record the task it helps a reader complete. Shoalrun does not require or interpret that field. A custom field has two parts: a **declaration** in project config and a **value** in a page header. The declaration appears in the [published field reference](https://www.shoalrun.com/author/frontmatter-reference.md) and the local generated reference; the value belongs to that page.
+
+1. `docs/docs.config.yaml` loads the field declarations from a separate file:
+
+   ```yaml title="docs/docs.config.yaml"
+   frontmatter: { $include: ./config/frontmatter.yaml }
+   ```
+
+2. `docs/config/frontmatter.yaml` declares both fields used by that guide:
+
+   ```yaml title="docs/config/frontmatter.yaml"
+   fields:
+     agent.intent:
+       type: string
+       description: The reader task this page helps an agent complete.
+       public: true
+     editorial.reviewNote:
+       type: string
+       description: Internal note for documentation reviewers.
+       public: false
+   ```
+
+3. This page, `docs/content/frontmatter.mdx`, gives them these values:
+
+   ```yaml title="docs/content/frontmatter.mdx"
+   agent:
+     intent: Help authors understand and configure page metadata.
+   editorial:
+     reviewNote: Check the frontmatter examples before release.
+   ```
+
+The config key `agent.intent` is a path. On the page, write it as an `agent` object with an `intent` value. The declaration checks that the value is a string and adds its description to the generated reference. `public: true` makes it eligible for the Markdown preamble; it does not export the value by itself.
+
+Undeclared fields are allowed in source pages, but they have no project type check or export approval. Declarations cannot redefine built-in fields, `slug`, `channel`, `version`, or the [protected metadata roots](https://www.shoalrun.com/author/markdown-metadata.md). A dotted declaration such as `agent.intent` needs any declared parent, such as `agent`, to have type `object`. Declarations support `string`, `number`, `integer`, `boolean`, `object`, and `array`. They can also set `required`, `items` for arrays, or `enum` for scalar values.
+
+For conditional source rules, such as requiring a verification date and evidence note together, see [check editorial policies with Manni](https://www.shoalrun.com/publish/manni.md). This optional check complements the field declarations above.
+
+## Choose text for each surface
+
+`summary` and `description` are separate fields. The short `summary` is required by Shoalrun; the fuller `description` is optional. Project config chooses an ordered list of field paths for each surface. The first nonempty string wins:
+
+```yaml title="docs.config.yaml"
+outputs:
+  text:
+    card: [summary]
+    pageHeader: [summary]
+    search: [description, summary]
+    htmlDescription: [description, summary]
+    socialCard: [summary]
+```
+
+`socialCard` writes an Open Graph description tag when it finds text; it does not generate a card image. Without a `socialCard` rule or page override, Shoalrun writes no Open Graph description. The other surfaces default to `summary` if no rule is set. The search choice becomes the summary in `search-index.json`. A card's existing `card.description` and an HTML page's existing `seo.description` take precedence over these rules.
+
+Override one surface on a page with literal text:
+
+```yaml title="A page's frontmatter"
+displayText:
+  socialCard: A short introduction for link previews.
+```
+
+`displayText` is presentation control; it is not exported as Markdown metadata. A configured text rule can also select a custom or provider-supplied string field by path. Selecting it for public HTML or the search index is an explicit publication decision.
+
+## Read metadata from a project module
+
+A project can opt into a local build-time provider module. Shoalrun does not validate external vocabularies; projects run their own validation separately. A provider can adapt an external metadata manifest to Shoalrun's page model:
+
+```yaml title="docs.config.yaml"
+metadata:
+  provider:
+    module: ./metadata/provider.mjs
+```
+
+```js title="metadata/provider.mjs"
+export async function provideMetadata({ file, source, projectRoot }) {
+  const entry = await lookupById(source.id, projectRoot);
+  if (!entry) return;
+  return {
+    values: { owner: entry.owner },
+    ownedKeys: ['owner'],
+    dependencies: [entry.manifestFile]
+  };
+}
+```
+
+`lookupById` is project code in this example. The provider runs for each authored page before project defaults and normal frontmatter checks. Returned values can be used by Shoalrun's build features. Return nothing to leave a page unchanged. `ownedKeys` names top-level fields the provider owns, including fields with no value on a given page. Every key in `values` must be owned. If `ownedKeys` is omitted, the provider owns exactly the keys in `values`. If an owned field also appears in page frontmatter, the build fails. Providers cannot replace `id`, `slug`, publication selectors, or `access`. `dependencies` lists absolute paths of files the provider read so the build record includes them.
+
+Provider fields stay out of public metadata unless the project selects them. To put a custom provider field in the Markdown header, declare it under `frontmatter.fields` with `public: true`, then select it in `outputs.markdown.metadata.fields`. The project's explicit selection determines what is published.
+
+Next, [choose metadata for published Markdown](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Preview changes to metadata providers
+
+Restart local preview after editing a custom metadata provider module configured with `metadata.provider`. Node loads the module once, so a watched rebuild does not reload its implementation. Stop `shoalrun dev` and start it again to see changes to the provider code. Changes to ordinary documentation pages still trigger automatic rebuilds. See the [CLI reference](https://www.shoalrun.com/cli.md) for other changes that require a restart.
+
+## Related reading
+
+### Next steps
+
+- [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md) — Choose which eligible project fields to publish.

package/agent-docs/author/custom-metadata.sections/add-a-custom-page-field.md

@@ -0,0 +1,68 @@
+---
+id: guide.custom-metadata
+title: Metadata customization
+summary: Configure metadata defaults, enforcement, fields, and providers.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/custom-metadata
+---
+
+# Metadata customization
+
+> 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 > Metadata customization
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/custom-metadata.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md) — Choose which eligible project fields to publish.
+
+Use this guide when your project needs shared metadata rules or fields beyond the [native page metadata](https://www.shoalrun.com/author/frontmatter.md). To choose which values appear in published Markdown, see [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Add a custom page field
+
+The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) uses the optional, project-defined `agent.intent` field to record the task it helps a reader complete. Shoalrun does not require or interpret that field. A custom field has two parts: a **declaration** in project config and a **value** in a page header. The declaration appears in the [published field reference](https://www.shoalrun.com/author/frontmatter-reference.md) and the local generated reference; the value belongs to that page.
+
+1. `docs/docs.config.yaml` loads the field declarations from a separate file:
+
+   ```yaml title="docs/docs.config.yaml"
+   frontmatter: { $include: ./config/frontmatter.yaml }
+   ```
+
+2. `docs/config/frontmatter.yaml` declares both fields used by that guide:
+
+   ```yaml title="docs/config/frontmatter.yaml"
+   fields:
+     agent.intent:
+       type: string
+       description: The reader task this page helps an agent complete.
+       public: true
+     editorial.reviewNote:
+       type: string
+       description: Internal note for documentation reviewers.
+       public: false
+   ```
+
+3. This page, `docs/content/frontmatter.mdx`, gives them these values:
+
+   ```yaml title="docs/content/frontmatter.mdx"
+   agent:
+     intent: Help authors understand and configure page metadata.
+   editorial:
+     reviewNote: Check the frontmatter examples before release.
+   ```
+
+The config key `agent.intent` is a path. On the page, write it as an `agent` object with an `intent` value. The declaration checks that the value is a string and adds its description to the generated reference. `public: true` makes it eligible for the Markdown preamble; it does not export the value by itself.
+
+Undeclared fields are allowed in source pages, but they have no project type check or export approval. Declarations cannot redefine built-in fields, `slug`, `channel`, `version`, or the [protected metadata roots](https://www.shoalrun.com/author/markdown-metadata.md). A dotted declaration such as `agent.intent` needs any declared parent, such as `agent`, to have type `object`. Declarations support `string`, `number`, `integer`, `boolean`, `object`, and `array`. They can also set `required`, `items` for arrays, or `enum` for scalar values.
+
+For conditional source rules, such as requiring a verification date and evidence note together, see [check editorial policies with Manni](https://www.shoalrun.com/publish/manni.md). This optional check complements the field declarations above.

package/agent-docs/author/custom-metadata.sections/choose-text-for-each-surface.md

@@ -0,0 +1,54 @@
+---
+id: guide.custom-metadata
+title: Metadata customization
+summary: Configure metadata defaults, enforcement, fields, and providers.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/custom-metadata
+---
+
+# Metadata customization
+
+> 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 > Metadata customization
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/custom-metadata.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md) — Choose which eligible project fields to publish.
+
+Use this guide when your project needs shared metadata rules or fields beyond the [native page metadata](https://www.shoalrun.com/author/frontmatter.md). To choose which values appear in published Markdown, see [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Choose text for each surface
+
+`summary` and `description` are separate fields. The short `summary` is required by Shoalrun; the fuller `description` is optional. Project config chooses an ordered list of field paths for each surface. The first nonempty string wins:
+
+```yaml title="docs.config.yaml"
+outputs:
+  text:
+    card: [summary]
+    pageHeader: [summary]
+    search: [description, summary]
+    htmlDescription: [description, summary]
+    socialCard: [summary]
+```
+
+`socialCard` writes an Open Graph description tag when it finds text; it does not generate a card image. Without a `socialCard` rule or page override, Shoalrun writes no Open Graph description. The other surfaces default to `summary` if no rule is set. The search choice becomes the summary in `search-index.json`. A card's existing `card.description` and an HTML page's existing `seo.description` take precedence over these rules.
+
+Override one surface on a page with literal text:
+
+```yaml title="A page's frontmatter"
+displayText:
+  socialCard: A short introduction for link previews.
+```
+
+`displayText` is presentation control; it is not exported as Markdown metadata. A configured text rule can also select a custom or provider-supplied string field by path. Selecting it for public HTML or the search index is an explicit publication decision.

package/agent-docs/author/custom-metadata.sections/preview-changes-to-metadata-providers.md

@@ -0,0 +1,33 @@
+---
+id: guide.custom-metadata
+title: Metadata customization
+summary: Configure metadata defaults, enforcement, fields, and providers.
+type: reference
+area: authoring
+subarea: authoring-metadata
+canonical: /author/custom-metadata
+---
+
+# Metadata customization
+
+> 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 > Metadata customization
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/custom-metadata.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md) — Choose which eligible project fields to publish.
+
+Use this guide when your project needs shared metadata rules or fields beyond the [native page metadata](https://www.shoalrun.com/author/frontmatter.md). To choose which values appear in published Markdown, see [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md).
+
+## Preview changes to metadata providers
+
+Restart local preview after editing a custom metadata provider module configured with `metadata.provider`. Node loads the module once, so a watched rebuild does not reload its implementation. Stop `shoalrun dev` and start it again to see changes to the provider code. Changes to ordinary documentation pages still trigger automatic rebuilds. See the [CLI reference](https://www.shoalrun.com/cli.md) for other changes that require a restart.