@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Tooltips
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Tooltip>` for brief supporting text beside a term. The text appears when readers hover over or focus the label. Use [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) for click-to-expand explanations, or a [callout](https://www.shoalrun.com/author/components/callout.md) for warnings and instructions that belong in the reading path.
 
@@ -47,7 +47,7 @@ With JavaScript, the label becomes a button linked to its explanation through `a
 
 The popup contains no focusable controls. Use an ordinary link or disclosure when readers need to interact with the explanation. Keep tooltips supplementary; essential warnings, choices, and instructions belong in visible page content.
 
-Without JavaScript, the label and explanation remain visible together in the page. Markdown includes the label and full explanation as ordinary text, so agents do not need hover, focus, or browser scripts. For the inline example above, the Markdown twin reads:
+Without JavaScript, the label and explanation remain visible together in the page. Markdown includes the label and full explanation as ordinary text, so agents don't need hover, focus, or browser scripts. For the inline example above, the Markdown twin reads:
 
 ```md
 Compare the build digest (A fingerprint of the published build's content.) before refreshing your cache.

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
 
@@ -303,7 +303,7 @@ navigation:
 
 ### Step 1: Name the site
 
-`site.title` appears in the header and in every page title. It is the only required site setting.
+`site.title` appears in the header and in every page title. It's the only required site setting.
 
 Lines 4–5:
 

package/agent-docs/author/components/walkthroughs.sections/attributes.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components/walkthroughs.sections/build-up-code.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components/walkthroughs.sections/choose-a-layout.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 
@@ -81,7 +81,7 @@ navigation:
 
 ### Step 1: Name the site
 
-`site.title` appears in the header and in every page title. It is the only required site setting.
+`site.title` appears in the header and in every page title. It's the only required site setting.
 
 Lines 4–5:
 

package/agent-docs/author/components/walkthroughs.sections/explain-one-file.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components/walkthroughs.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components/walkthroughs.sections/syntax.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components/walkthroughs.sections/take-code-from-a-file.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/components/walkthroughs.md)
 

package/agent-docs/author/components.md

@@ -16,9 +16,9 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components are not available.
+Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components aren't available.
 
 [Custom components](https://www.shoalrun.com/author/components/custom.md) let trusted project plugins lower into the shared content pipeline.
 

package/agent-docs/author/content.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Content and stable IDs
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Author pages as `.md` or `.mdx` under the content directory, `site.contentDir` (default `content`, relative to `docs.config.yaml`). The build parses and validates every `.md` and `.mdx` file there, drafts included, so a stray README without frontmatter fails the build. The `id` identifies a document independently of its filename, title, slug, and navigation position. A page's `slug` sets its public route. The compiler rejects route collisions and duplicate IDs within a publication variant.
 
@@ -35,11 +35,11 @@ access: { policy: public }
 ---
 ```
 
-Publication channel, API version, and language are separate axes. Published pages need channel and version, supplied on the page or through [global frontmatter](https://www.shoalrun.com/author/frontmatter.md). Language uses global frontmatter defaults/enforced values first, then `publications.defaults.language`, then `en`. An explicit page language overrides that default. Enabled publication entries can also omit language to inherit the same default; the project config declares supported combinations and route prefixes. Nonpublic pages are excluded before rendering. The prototype does not yet provide hosted role-based access control.
+Publication channel, API version, and language are separate axes. Published pages need channel and version, supplied on the page or through [global frontmatter](https://www.shoalrun.com/author/frontmatter.md). Language uses global frontmatter defaults/enforced values first, then `publications.defaults.language`, then `en`. An explicit page language overrides that default. Enabled publication entries can also omit language to inherit the same default; the project config declares supported combinations and route prefixes. Nonpublic pages are excluded before rendering. The prototype doesn't yet provide hosted role-based access control.
 
 Link to another document by ID with `[the guide](doc:guide.example)` or `<DocLink doc="guide.example">the guide</DocLink>`. These become the current route in HTML and the corresponding `.md` route in Markdown. A slug or filename change leaves ID-based links intact. Unknown IDs fail the build.
 
-The current MDX semantic adapters cover GitHub Flavored Markdown and the elements in the [component reference](https://www.shoalrun.com/author/components.md), including [diagrams](https://www.shoalrun.com/author/components/diagrams.md). Dynamic expressions and unknown components fail because they cannot yet be represented faithfully in both HTML and Markdown. See [published outputs](https://www.shoalrun.com/publish/output.md) for what an agent receives.
+The current MDX semantic adapters cover GitHub Flavored Markdown and the elements in the [component reference](https://www.shoalrun.com/author/components.md), including [diagrams](https://www.shoalrun.com/author/components/diagrams.md). Dynamic expressions and unknown components fail because they can't yet be represented faithfully in both HTML and Markdown. See [published outputs](https://www.shoalrun.com/publish/output.md) for what an agent receives.
 
 Set the root language once, for example:
 

package/agent-docs/author/cookbooks.md

@@ -16,9 +16,9 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Let readers choose recipes with a cookbook
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-A cookbook combines an authored introduction with a list or chooser of **published recipe pages**. It does not read ingredient files. Ingredients have already been copied into the recipes during authoring.
+A cookbook combines an authored introduction with a list or chooser of **published recipe pages**. It doesn't read ingredient files. Ingredients have already been copied into the recipes during authoring.
 
 This guide uses the [Site workflows cookbook](https://www.shoalrun.com/cookbooks/site-workflows.md). It offers a build check or a build-and-audit check. The audit recipe already includes the build, so the reader chooses one complete path.
 
@@ -51,7 +51,7 @@ site-checks:
       outcome: Checked page files and no failed configured audits.
 ```
 
-`doc` selects the recipe. `label` names the choice. The optional `when`, `needs`, and `outcome` fields explain the choice; they are descriptive text, not requirements the browser verifies. When `when` is omitted, the recipe's summary is shown.
+`doc` selects the recipe. `label` names the choice. The optional `when`, `needs`, and `outcome` fields explain the choice; they're descriptive text, not requirements the browser verifies. When `when` is omitted, the recipe's summary is shown.
 
 Load this mapping from the project configuration. Shoalrun already has this include:
 
@@ -69,11 +69,11 @@ Choose the level of validation you need. The audit path includes the build.
 <CookbookChooser id="site-checks" />
 ```
 
-The component's `id` is the configuration key `site-checks`. It is separate from the cookbook page's document ID, `cookbook.site-workflows`.
+The component's `id` is the configuration key `site-checks`. It's separate from the cookbook page's document ID, `cookbook.site-workflows`.
 
-A normal site build publishes the cookbook's own text and chooser. When a reader makes a selection, the browser fetches the selected recipe's HTML and shows the instructions under **Your path**. It does not call the recipe assembler, fetch ingredients, or execute commands.
+A normal site build publishes the cookbook's own text and chooser. When a reader makes a selection, the browser fetches the selected recipe's HTML and shows the instructions under **Your path**. It doesn't call the recipe assembler, fetch ingredients, or execute commands.
 
-For a simple directory of recipes, use [DocCards](https://www.shoalrun.com/author/components/cards.md) instead of a chooser. A page with `type: cookbook` does not require an interactive component.
+For a simple directory of recipes, use [DocCards](https://www.shoalrun.com/author/components/cards.md) instead of a chooser. A page with `type: cookbook` doesn't require an interactive component.
 
 ## Choose single or multiple selection deliberately
 
@@ -84,7 +84,7 @@ Choose the selection mode based on whether readers should follow one path or com
 | `mode: single`   | Choose one recipe with radio buttons.                                        | Alternative tasks or overlapping paths, such as build versus build-and-audit. |
 | `mode: multiple` | Select several recipes with checkboxes; display them in configuration order. | Recipes that the author has checked make sense together. This is the default. |
 
-Multiple selection displays whole recipe bodies, including any repeated setup. It does not deduplicate steps, connect outputs between recipes, or check their combined dependencies. If a combined task needs shared setup and explicit handoffs, compose it as one recipe and offer that recipe as a choice.
+Multiple selection displays whole recipe bodies, including any repeated setup. It doesn't deduplicate steps, connect outputs between recipes, or check their combined dependencies. If a combined task needs shared setup and explicit handoffs, compose it as one recipe and offer that recipe as a choice.
 
 ## What readers and agents receive
 
@@ -98,9 +98,9 @@ The published surfaces expose cookbook choices in different forms.
 | Recipe Markdown                | The complete published instructions for that one recipe.                |
 | Download Markdown              | A file containing the selected recipes' instructions.                   |
 
-**Link to this path** preserves the selection in the browser URL. It does not create a new published Markdown page. An agent reading the cookbook's Markdown can choose a recipe link. Give a task-performing agent the recipe's Markdown or the downloaded selection.
+**Link to this path** preserves the selection in the browser URL. It doesn't create a new published Markdown page. An agent reading the cookbook's Markdown can choose a recipe link. Give a task-performing agent the recipe's Markdown or the downloaded selection.
 
-**Print this path** prints the loaded instructions. If a recipe cannot load, its source link remains available. Markdown downloads fail as a whole rather than saving an incomplete selection. Without JavaScript, the visible recipe links still work.
+**Print this path** prints the loaded instructions. If a recipe can't load, its source link remains available. Markdown downloads fail as a whole rather than saving an incomplete selection. Without JavaScript, the visible recipe links still work.
 
 ## Check the result
 

package/agent-docs/author/css.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 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.
 
@@ -41,9 +41,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 
@@ -238,4 +238,4 @@ The publication label adjusts automatically. A single channel, version, and lang
 
 ## HTML, Markdown, and agents
 
-Project CSS changes the HTML presentation. It is not included in Markdown twins, and a text-reading agent does not apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS does not remove its content from the published Markdown or protect it from access.
+Project CSS changes the HTML presentation. It isn't included in Markdown twins, and a text-reading agent doesn't apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS doesn't remove its content from the published Markdown or protect it from access.

package/agent-docs/author/css.sections/borders-fields-and-navigation-tokens.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

package/agent-docs/author/css.sections/core-color-tokens.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,12 +43,12 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 
 ## HTML, Markdown, and agents
 
-Project CSS changes the HTML presentation. It is not included in Markdown twins, and a text-reading agent does not apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS does not remove its content from the published Markdown or protect it from access.
+Project CSS changes the HTML presentation. It isn't included in Markdown twins, and a text-reading agent doesn't apply selectors, pseudo-elements, or responsive rules. Put essential instructions and labels in authored content rather than CSS-generated text. Hiding an element with CSS doesn't remove its content from the published Markdown or protect it from access.

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Output and presentation > CSS and theme reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/css.md)
 
@@ -43,9 +43,9 @@ Pages link these stylesheets in order, and later files win: `/assets/site.css` (
 
 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.
+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 aren't 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.
+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 doesn't 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.
 

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

@@ -16,13 +16,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 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:
+The project config is the root `docs.config.yaml` plus any imported fragments. Its `frontmatter` block supplies shared page values; this block doesn't appear inside an individual page's header. Configure it in the root file or an imported fragment:
 
 ```yaml
 frontmatter:
@@ -48,9 +48,9 @@ frontmatter:
       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.
+`defaults` fills in values that a page may replace. `enforced` sets values the page can't 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 can't 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.
+The `id` and `slug` fields must stay on each page; they can't 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 don't 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.
 
@@ -72,11 +72,11 @@ When updating an earlier prototype project, rename these settings:
 
 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.
+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 aren't 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.
+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 doesn't 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:
 
@@ -107,9 +107,9 @@ The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) uses t
      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.
+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 doesn't 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.
+Undeclared fields are allowed in source pages, but they have no project type check or export approval. Declarations can't 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.
 
@@ -127,7 +127,7 @@ outputs:
     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.
+`socialCard` writes an Open Graph description tag when it finds text; it doesn't 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:
 
@@ -136,11 +136,11 @@ 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.
+`displayText` is presentation control; it isn't 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:
+A project can opt into a local build-time provider module. Shoalrun doesn't 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:
@@ -160,7 +160,7 @@ export async function provideMetadata({ file, source, projectRoot }) {
 }
 ```
 
-`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.
+`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 can't 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.
 
@@ -168,7 +168,7 @@ Next, [choose metadata for published Markdown](https://www.shoalrun.com/author/m
 
 ## 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.
+Restart local preview after editing a custom metadata provider module configured with `metadata.provider`. Node loads the module once, so a watched rebuild doesn't 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
 

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

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Metadata customization
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/custom-metadata.md)
 
@@ -30,7 +30,7 @@ Use this guide when your project needs shared metadata rules or fields beyond th
 
 ## 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.
+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 doesn't 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:
 
@@ -61,8 +61,8 @@ The [page metadata guide](https://www.shoalrun.com/author/frontmatter.md) uses t
      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.
+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 doesn't 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.
+Undeclared fields are allowed in source pages, but they have no project type check or export approval. Declarations can't 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.