@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.18

package/agent-docs/author/search.sections/turn-search-off.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) > Search, chat, and agent access > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Verified: 2026-10-01.**
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/author/search.md)
 
 - [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
 
-Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+Site search returns links to pages and sections. It's enabled by default and matches words in the browser, with no provider account or server required.
 
 Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
 
@@ -43,4 +43,4 @@ outputs:
       provider: none
 ```
 
-This removes both the reader search box and its index, so the local search command has nothing to query. Markdown twins, `/llms.txt`, and `/documents.json` do not change with the provider. Agents can still discover and fetch pages, but `shoalrun search` cannot query a missing `search-index.json`. The passage index and semantic endpoint are independent of this browser setting. Changing it does not remove those artifacts or disable a deployed endpoint.
+This removes both the reader search box and its index, so the local search command has nothing to query. Markdown twins, `/llms.txt`, and `/documents.json` don't change with the provider. Agents can still discover and fetch pages, but `shoalrun search` can't query a missing `search-index.json`. The passage index and semantic endpoint are independent of this browser setting. Changing it doesn't remove those artifacts or disable a deployed endpoint.

package/agent-docs/author/search.sections/use-the-search-box.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) > Search, chat, and agent access > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Verified: 2026-10-01.**
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/author/search.md)
 
 - [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
 
-Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+Site search returns links to pages and sections. It's enabled by default and matches words in the browser, with no provider account or server required.
 
 Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
 

package/agent-docs/author/search.sections/write-a-custom-provider.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) > Search, chat, and agent access > Site search
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Verified: 2026-10-01.**
 
@@ -28,7 +28,7 @@ Parent page: [Full Markdown page](/author/search.md)
 
 - [Preview semantic search in this checkout](https://www.shoalrun.com/recipes/preview-hybrid-search.md) — Build the passage index and verify hybrid search and lexical fallback in this checkout.
 
-Site search returns links to pages and sections. It is enabled by default and matches words in the browser, with no provider account or server required.
+Site search returns links to pages and sections. It's enabled by default and matches words in the browser, with no provider account or server required.
 
 Shoalrun supplies the search box and keyboard controls. A **search provider** supplies results; you can replace the built-in provider with your own module. [Search and chat](https://www.shoalrun.com/search-and-chat.md) explains when to add semantic search or cited answers.
 
@@ -69,14 +69,14 @@ The `module` path resolves from the config file that declares it. The module is
 
 The search box passes a context object to both functions.
 
-| Field             | Value                                                                                                                                                     |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`         | The page's channel, version, and language, joined by `\|`, such as `production\|current\|en`.                                                             |
-| `language`        | The page's `lang` value.                                                                                                                                  |
-| `indexUrl`        | The base-path-prefixed `/search-index.json` URL. The file exists only when the build writes an index.                                                     |
-| `limit`           | The maximum number of results the box shows.                                                                                                              |
-| `signal`          | An `AbortSignal`, passed to `search` only. It aborts when the reader types again.                                                                         |
-| `readerSelection` | The active reader view as facet IDs mapped to arrays of choice IDs. An empty object means show all. Custom providers must use it to filter their results. |
+| Field             | Value                                                                                                                                                                                                                                                       |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`         | The page’s publication key. Productless keys stay `channel\|version\|language`, such as `production\|current\|en`. Product publication keys append the product, such as `production\|v3\|en\|payments`. Forward this key unchanged; don't drop its product. |
+| `language`        | The page's `lang` value.                                                                                                                                                                                                                                    |
+| `indexUrl`        | The base-path-prefixed `/search-index.json` URL. The file exists only when the build writes an index.                                                                                                                                                       |
+| `limit`           | The maximum number of results the box shows.                                                                                                                                                                                                                |
+| `signal`          | An `AbortSignal`, passed to `search` only. It aborts when the reader types again.                                                                                                                                                                           |
+| `readerSelection` | The active reader view as facet IDs mapped to arrays of choice IDs. An empty object means show all. Custom providers must use it to filter their results.                                                                                                   |
 
 Pass `signal` to `fetch` so stale requests stop. The box ignores results from an aborted search.
 
@@ -95,4 +95,4 @@ The box drops results without a valid `url` and `title`, and it keeps the first
 
 ### Module limits
 
-The build copies one file. It does not copy files that the module imports with relative paths. Bundle the provider into one file, or import dependencies from absolute URLs.
+The build copies one file. It doesn't copy files that the module imports with relative paths. Bundle the provider into one file, or import dependencies from absolute URLs.

package/agent-docs/author/snippets.md

@@ -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 > Reusable snippets
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template does not change existing pages.
+A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template doesn't change existing pages.
 
 ## Register a snippet
 
@@ -101,7 +101,7 @@ For this slice, snippets use inline `<Var />` in prose. Code blocks are never ch
 | `<Snippet>` | `values`  | No       | Literal mapping of invocation values. |
 | `<Var>`     | `name`    | Yes      | Variable declared for that snippet.   |
 
-The included Markdown and supported MDX components render in both HTML and Markdown. Nested snippets work, but recursive includes fail. API embeds need page-level headings and cannot be placed inside snippets. Keep headings in the page, and use absolute or `doc:` links in snippets.
+The included Markdown and supported MDX components render in both HTML and Markdown. Nested snippets work, but recursive includes fail. API embeds need page-level headings and can't be placed inside snippets. Keep headings in the page, and use absolute or `doc:` links in snippets.
 
 ## Check the shared text
 

package/agent-docs/author/taxonomy.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Design and enforce a page taxonomy
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 Use `area` and `subarea` to describe a page's subject independently of its place in navigation. The same subject can appear in guides, reference pages, recipes, and change notes.
 
@@ -55,7 +55,7 @@ frontmatter:
 
 `required` makes the selected fields mandatory after defaults and enforced values are resolved. `requireExplicit` also requires those fields in authored source, including drafts. Generated API reference pages can inherit their categories from global frontmatter defaults.
 
-Each subarea belongs to its declared parent area. IDs do not need to share a prefix. A subarea ID must be unique across the taxonomy.
+Each subarea belongs to its declared parent area. IDs don't need to share a prefix. A subarea ID must be unique across the taxonomy.
 
 ## Classify pages by subject
 
@@ -66,7 +66,7 @@ area: components
 subarea: api-embeds
 ```
 
-The build rejects unknown categories, missing required tags, and subareas that do not belong to the selected area. It applies the checks to authored pages and resolved generated references. The generated frontmatter schema exposes the same vocabulary and pair constraints for editors.
+The build rejects unknown categories, missing required tags, and subareas that don't belong to the selected area. It applies the checks to authored pages and resolved generated references. The generated frontmatter schema exposes the same vocabulary and pair constraints for editors.
 
 Shoalrun publishes the definitions in `documents.json` under `taxonomy`. Individual page records and search indexes carry their resolved categories. To expose category IDs in Markdown frontmatter, add `area: frontmatter.area` and `subarea: frontmatter.subarea` to `outputs.markdown.metadata.fields`.
 

package/agent-docs/author/templates.md

@@ -18,11 +18,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Built-in templates
 
@@ -60,7 +60,7 @@ A recipe can be written directly; ingredients and composition specs are optional
 
 ## Project-added templates
 
-Project templates are named entries under `templates` in config. They are available only in projects that register them; installing the CLI does not provide these names. Use a custom name to add an outline, or a built-in name to override its starting content.
+Project templates are named entries under `templates` in config. They're available only in projects that register them; installing the CLI doesn't provide these names. Use a custom name to add an outline, or a built-in name to override its starting content.
 
 A project template with the same name as a built-in takes precedence. For example, registering `how-to` replaces its starting outline in that project. Use a distinct name to add a choice instead. Neither registration nor overriding rewrites existing pages.
 
@@ -82,7 +82,7 @@ These boundaries are based on Diátaxis's guidance for [tutorials](https://diata
 The primary Diátaxis templates use these authoring conventions; workflow templates keep the sections useful to their role:
 
 - **Commented frontmatter.** Comments explain fields and give examples where useful. Fields you must fill in hold a placeholder. Optional fields are commented out, each with the case where it applies.
-- **A short introduction.** One paragraph of 150 words or fewer sits under the title with no heading. It says what the page is for and who it is for.
+- **A short introduction.** One paragraph of 150 words or fewer sits under the title with no heading. It says what the page is for and who it's for.
 - **Optional sections.** Sections such as Prerequisites and Considerations are marked optional. Keep the ones that apply and delete the rest, heading and text.
 - **Structure for the reader need.** Tutorials guide an exercise, how-tos put actions and verification first, references organize facts for lookup, and explanations develop context and reasoning.
 - **HTML, Markdown, and agents.** Keep this section when the page uses a component or describes behavior that differs between HTML and Markdown or affects what an agent reads. State what HTML shows, what the Markdown twin contains, and what an agent receives. Delete it otherwise.
@@ -137,15 +137,17 @@ Three rules keep the output valid:
 
 - Quote placeholder values in the frontmatter. An unquoted value that starts with two square brackets is read as a YAML list.
 - Use only placeholder values that pass validation in every project. Comment out fields such as `audiences`, `readerFilters`, and `subjectLifecycle`, because a wrong value fails the draft build.
-- Keep nested fields in flow style, such as `card: { icon: book-open }`. A comment block after a nested block mapping is indented with it and cannot be uncommented in place.
+- Keep nested fields in flow style, such as `card: { icon: book-open }`. A comment block after a nested block mapping is indented with it and can't be uncommented in place.
 
-Frontmatter comments do not reach the published page, so they never appear in the Markdown twin.
+Frontmatter comments don't reach the published page, so they never appear in the Markdown twin.
 
 ### Write the body
 
-Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Don't use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
 
-Fenced code blocks can teach the placeholder syntax without blocking publication. Available since `0.1.0-alpha.13`. For example, this code is preserved literally in HTML and Markdown:
+Since 0.1.0-alpha.13
+
+Fenced code blocks can teach the placeholder syntax without blocking publication. For example, this code is preserved literally in HTML and Markdown:
 
 ```md
 [[TODO: Explain the task and how to check the result.]]
@@ -161,13 +163,13 @@ Set the page's frontmatter `updated` to the current date in `YYYY-MM-DD` format
 
 ## Choose formatting enforcement for your project
 
-A template supplies a starting outline. It does not impose that outline on completed pages. Project overrides replace the scaffold; they do not silently change your lint policy.
+A template supplies a starting outline. It doesn't impose that outline on completed pages. Project overrides replace the scaffold; they don't silently change your lint policy.
 
-This repository checks authored page formatting with `npm run docs:format`. Its `.vale-format.ini` enables project-owned `DocShape` rules. Errors cover title and summary lengths, body headings, introductions, and `updated` dates. Type-boundary warnings flag possible digressions for editorial review. A passing check does not prove a page serves its reader's need.
+This repository checks authored page formatting with `npm run docs:format`. Its `.vale-format.ini` enables project-owned `DocShape` rules. Errors cover title and summary lengths, body headings, introductions, and `updated` dates. Type-boundary warnings flag possible digressions for editorial review. A passing check doesn't prove a page serves its reader's need.
 
-The structural rules use [Vale's embedded Tengo scripting language](https://docs.vale.sh/checks/script) to read source frontmatter and headings. Tengo runs inside Vale during linting; it needs no separate installation and is not part of the published site. The scripts live under `.vale/styles/config/scripts/` in this repository.
+The structural rules use [Vale's embedded Tengo scripting language](https://docs.vale.sh/checks/script) to read source frontmatter and headings. Tengo runs inside Vale during linting; it needs no separate installation and isn't part of the published site. The scripts live under `.vale/styles/config/scripts/` in this repository.
 
-`DocShape.RecipeShape` requires nonempty setup, action, and final success-check sections. It accepts directly authored recipes without an Ingredients list and assembled recipes with task-specific action headings. `DocShape.IngredientShape` accepts either Inputs, Action, Output, and Check it worked sections or a compact body with `workflow` handoff metadata and a declared `check`. These are this repository's conventions. `recipe draft` validates YAML values and handoff order; Vale checks structure and does not run the instructions or prove the stated outcome.
+`DocShape.RecipeShape` requires nonempty setup, action, and final success-check sections. It accepts directly authored recipes without an Ingredients list and assembled recipes with task-specific action headings. `DocShape.IngredientShape` accepts either Inputs, Action, Output, and Check it worked sections or a compact body with `workflow` handoff metadata and a declared `check`. These are this repository's conventions. `recipe draft` validates YAML values and handoff order; Vale checks structure and doesn't run the instructions or prove the stated outcome.
 
 Both scripts ignore headings inside fenced code examples. Setup headings can be Before you start, Before you begin, Prerequisites, or What you need. Success headings can be Check it worked, Check the outcome, Check the result, Verify the outcome, or Verify the result. Alternate outlines and YAML forms may need a project-adapted script. Keep compact workflow declarations as ordinary block or flow mappings for this policy.
 
@@ -193,7 +195,7 @@ audit:
       run: [vale, --config=../.vale-format.ini, content]
 ```
 
-Vale must be installed when you configure that command. The CLI does not require Vale for other projects or derive rules from template text. Compiler checks for valid source, links, and unresolved public draft prompts still apply independently. See [audit settings](https://www.shoalrun.com/publish/audit.md) and [writing guides](https://www.shoalrun.com/author/design-writing-guides.md).
+Vale must be installed when you configure that command. The CLI doesn't require Vale for other projects or derive rules from template text. Compiler checks for valid source, links, and unresolved public draft prompts still apply independently. See [audit settings](https://www.shoalrun.com/publish/audit.md) and [writing guides](https://www.shoalrun.com/author/design-writing-guides.md).
 
 ## Short CLI and derived values
 
@@ -212,7 +214,7 @@ The CLI discovers `docs.config.yaml` in the current directory or a parent. It de
 | `summary` | `Draft guide for retry payments. Replace this summary before publication.` |
 | `slug`    | `/guides/retry-payments`                                                   |
 
-The derived summary counts as a placeholder, so the page cannot be published until you replace it. Override any value with `--id`, `--title`, `--summary`, or `--slug`. Other options are `--config FILE`, `--channel`, `--version`, and `--language` (defaults come from `publications.defaults`), and `--operation ID`, which can repeat. `--new` is the long form of `-n`. The [CLI reference](https://www.shoalrun.com/cli.md) lists every rule.
+The derived summary counts as a placeholder, so the page can't be published until you replace it. Override any value with `--id`, `--title`, `--summary`, or `--slug`. Other options are `--config FILE`, `--channel`, `--version`, and `--language` (defaults come from `publications.defaults`), and `--operation ID`, which can repeat. `--new` is the long form of `-n`. The [CLI reference](https://www.shoalrun.com/cli.md) lists every rule.
 
 If the target path begins with the selected publication's route prefix, the short form omits that prefix from the derived slug. For example, with version `v2` configured at `/v2`, `content/v2/check-payment.mdx` gets slug `/check-payment` and route `/v2/check-payment`. The stable ID still derives from the complete content path; use `--id` if several versions represent the same document.
 

package/agent-docs/author/templates.sections/built-in-feature-templates.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Built-in feature templates
 

package/agent-docs/author/templates.sections/built-in-templates.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Built-in templates
 

package/agent-docs/author/templates.sections/choose-formatting-enforcement-for-your-project.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,17 +30,17 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Choose formatting enforcement for your project
 
-A template supplies a starting outline. It does not impose that outline on completed pages. Project overrides replace the scaffold; they do not silently change your lint policy.
+A template supplies a starting outline. It doesn't impose that outline on completed pages. Project overrides replace the scaffold; they don't silently change your lint policy.
 
-This repository checks authored page formatting with `npm run docs:format`. Its `.vale-format.ini` enables project-owned `DocShape` rules. Errors cover title and summary lengths, body headings, introductions, and `updated` dates. Type-boundary warnings flag possible digressions for editorial review. A passing check does not prove a page serves its reader's need.
+This repository checks authored page formatting with `npm run docs:format`. Its `.vale-format.ini` enables project-owned `DocShape` rules. Errors cover title and summary lengths, body headings, introductions, and `updated` dates. Type-boundary warnings flag possible digressions for editorial review. A passing check doesn't prove a page serves its reader's need.
 
-The structural rules use [Vale's embedded Tengo scripting language](https://docs.vale.sh/checks/script) to read source frontmatter and headings. Tengo runs inside Vale during linting; it needs no separate installation and is not part of the published site. The scripts live under `.vale/styles/config/scripts/` in this repository.
+The structural rules use [Vale's embedded Tengo scripting language](https://docs.vale.sh/checks/script) to read source frontmatter and headings. Tengo runs inside Vale during linting; it needs no separate installation and isn't part of the published site. The scripts live under `.vale/styles/config/scripts/` in this repository.
 
-`DocShape.RecipeShape` requires nonempty setup, action, and final success-check sections. It accepts directly authored recipes without an Ingredients list and assembled recipes with task-specific action headings. `DocShape.IngredientShape` accepts either Inputs, Action, Output, and Check it worked sections or a compact body with `workflow` handoff metadata and a declared `check`. These are this repository's conventions. `recipe draft` validates YAML values and handoff order; Vale checks structure and does not run the instructions or prove the stated outcome.
+`DocShape.RecipeShape` requires nonempty setup, action, and final success-check sections. It accepts directly authored recipes without an Ingredients list and assembled recipes with task-specific action headings. `DocShape.IngredientShape` accepts either Inputs, Action, Output, and Check it worked sections or a compact body with `workflow` handoff metadata and a declared `check`. These are this repository's conventions. `recipe draft` validates YAML values and handoff order; Vale checks structure and doesn't run the instructions or prove the stated outcome.
 
 Both scripts ignore headings inside fenced code examples. Setup headings can be Before you start, Before you begin, Prerequisites, or What you need. Success headings can be Check it worked, Check the outcome, Check the result, Verify the outcome, or Verify the result. Alternate outlines and YAML forms may need a project-adapted script. Keep compact workflow declarations as ordinary block or flow mappings for this policy.
 
@@ -66,4 +66,4 @@ audit:
       run: [vale, --config=../.vale-format.ini, content]
 ```
 
-Vale must be installed when you configure that command. The CLI does not require Vale for other projects or derive rules from template text. Compiler checks for valid source, links, and unresolved public draft prompts still apply independently. See [audit settings](https://www.shoalrun.com/publish/audit.md) and [writing guides](https://www.shoalrun.com/author/design-writing-guides.md).
+Vale must be installed when you configure that command. The CLI doesn't require Vale for other projects or derive rules from template text. Compiler checks for valid source, links, and unresolved public draft prompts still apply independently. See [audit settings](https://www.shoalrun.com/publish/audit.md) and [writing guides](https://www.shoalrun.com/author/design-writing-guides.md).

package/agent-docs/author/templates.sections/create-or-edit-a-project-template.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Create or edit a project template
 
@@ -61,15 +61,17 @@ Three rules keep the output valid:
 
 - Quote placeholder values in the frontmatter. An unquoted value that starts with two square brackets is read as a YAML list.
 - Use only placeholder values that pass validation in every project. Comment out fields such as `audiences`, `readerFilters`, and `subjectLifecycle`, because a wrong value fails the draft build.
-- Keep nested fields in flow style, such as `card: { icon: book-open }`. A comment block after a nested block mapping is indented with it and cannot be uncommented in place.
+- Keep nested fields in flow style, such as `card: { icon: book-open }`. A comment block after a nested block mapping is indented with it and can't be uncommented in place.
 
-Frontmatter comments do not reach the published page, so they never appear in the Markdown twin.
+Frontmatter comments don't reach the published page, so they never appear in the Markdown twin.
 
 ### Write the body
 
-Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Don't use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
 
-Fenced code blocks can teach the placeholder syntax without blocking publication. Available since `0.1.0-alpha.13`. For example, this code is preserved literally in HTML and Markdown:
+Since 0.1.0-alpha.13
+
+Fenced code blocks can teach the placeholder syntax without blocking publication. For example, this code is preserved literally in HTML and Markdown:
 
 ```md
 [[TODO: Explain the task and how to check the result.]]

package/agent-docs/author/templates.sections/keep-the-four-shapes-distinct.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Keep the four shapes distinct
 

package/agent-docs/author/templates.sections/project-added-templates.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,10 +30,10 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Project-added templates
 
-Project templates are named entries under `templates` in config. They are available only in projects that register them; installing the CLI does not provide these names. Use a custom name to add an outline, or a built-in name to override its starting content.
+Project templates are named entries under `templates` in config. They're available only in projects that register them; installing the CLI doesn't provide these names. Use a custom name to add an outline, or a built-in name to override its starting content.
 
 A project template with the same name as a built-in takes precedence. For example, registering `how-to` replaces its starting outline in that project. Use a distinct name to add a choice instead. Neither registration nor overriding rewrites existing pages.

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

@@ -18,13 +18,13 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Related reading
 

package/agent-docs/author/templates.sections/scaffold-a-page.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Scaffold a page
 

package/agent-docs/author/templates.sections/short-cli-and-derived-values.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,7 +30,7 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## Short CLI and derived values
 
@@ -49,7 +49,7 @@ The CLI discovers `docs.config.yaml` in the current directory or a parent. It de
 | `summary` | `Draft guide for retry payments. Replace this summary before publication.` |
 | `slug`    | `/guides/retry-payments`                                                   |
 
-The derived summary counts as a placeholder, so the page cannot be published until you replace it. Override any value with `--id`, `--title`, `--summary`, or `--slug`. Other options are `--config FILE`, `--channel`, `--version`, and `--language` (defaults come from `publications.defaults`), and `--operation ID`, which can repeat. `--new` is the long form of `-n`. The [CLI reference](https://www.shoalrun.com/cli.md) lists every rule.
+The derived summary counts as a placeholder, so the page can't be published until you replace it. Override any value with `--id`, `--title`, `--summary`, or `--slug`. Other options are `--config FILE`, `--channel`, `--version`, and `--language` (defaults come from `publications.defaults`), and `--operation ID`, which can repeat. `--new` is the long form of `-n`. The [CLI reference](https://www.shoalrun.com/cli.md) lists every rule.
 
 If the target path begins with the selected publication's route prefix, the short form omits that prefix from the derived slug. For example, with version `v2` configured at `/v2`, `content/v2/check-payment.mdx` gets slug `/check-payment` and route `/v2/check-payment`. The stable ID still derives from the complete content path; use `--id` if several versions represent the same document.
 

package/agent-docs/author/templates.sections/what-every-template-gives-you.md

@@ -18,7 +18,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -30,14 +30,14 @@ Parent page: [Full Markdown page](/author/templates.md)
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
-Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they do not enforce a permanent page structure.
+Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose must stay shared across several pages. Templates guide the initial draft; they don't enforce a permanent page structure.
 
 ## What every template gives you
 
 The primary Diátaxis templates use these authoring conventions; workflow templates keep the sections useful to their role:
 
 - **Commented frontmatter.** Comments explain fields and give examples where useful. Fields you must fill in hold a placeholder. Optional fields are commented out, each with the case where it applies.
-- **A short introduction.** One paragraph of 150 words or fewer sits under the title with no heading. It says what the page is for and who it is for.
+- **A short introduction.** One paragraph of 150 words or fewer sits under the title with no heading. It says what the page is for and who it's for.
 - **Optional sections.** Sections such as Prerequisites and Considerations are marked optional. Keep the ones that apply and delete the rest, heading and text.
 - **Structure for the reader need.** Tutorials guide an exercise, how-tos put actions and verification first, references organize facts for lookup, and explanations develop context and reasoning.
 - **HTML, Markdown, and agents.** Keep this section when the page uses a component or describes behavior that differs between HTML and Markdown or affects what an agent reads. State what HTML shows, what the Markdown twin contains, and what an agent receives. Delete it otherwise.

package/agent-docs/author/workspace/commands.md

@@ -20,7 +20,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Commands
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -57,7 +57,7 @@ Baselines and validation artifacts must be outside the project or inside its exc
 
 Declare sibling files and directories needed by a configured check in [`audit.tests[].inputs`](https://www.shoalrun.com/config.md). Paths are relative to the project configuration directory and must remain within its parent. Snapshot builds resolve revision dates without writing freshness history. A configured check that changes captured source or history still fails validation.
 
-Configured Node checks receive Shoalrun's installed dependency search paths through `NODE_PATH` for CommonJS resolution. Consumer dependencies are not copied into the snapshot; missing modules produce an unavailable check. ESM imports do not use `NODE_PATH`.
+Configured Node checks receive Shoalrun's installed dependency search paths through `NODE_PATH` for CommonJS resolution. Consumer dependencies aren't copied into the snapshot; missing modules produce an unavailable check. ESM imports don't use `NODE_PATH`.
 
 Validation statuses include `ok`, `failed`, `incomplete`, `unavailable`, and `stale`. Read findings and coverage alongside status. These commands always return JSON. Snapshot validation requires affected page IDs to match `[A-Za-z0-9][A-Za-z0-9._-]*`.
 
@@ -75,11 +75,11 @@ Use these commands to inspect proposed changes and their rendered output.
 
 Preview binds only to `127.0.0.1`; the default port is 8771. Use port 0 to allocate a free port. Its JSON startup record contains the snapshot ID, origin, and review/status URLs. It also includes affected HTML/Markdown URLs, serving-copy directory, validation review, and lifecycle instructions. The process stays running. Ctrl-C or SIGTERM closes it, removes its private copy, and emits a stopped record. Validation artifacts remain. No browser is opened automatically.
 
-The review identifies the baseline, changed-file operations and digests, dependencies, and current freshness. It includes checks, findings and source/reference locations, coverage, and affected-page artifacts. Earlier file contents are not retained in a baseline; the report explains why it cannot generate a task diff. Evidence gathering remains with the harness. Reviewer results and author dispositions are explicitly empty; no semantic reviewer ran.
+The review identifies the baseline, changed-file operations and digests, dependencies, and current freshness. It includes checks, findings and source/reference locations, coverage, and affected-page artifacts. Earlier file contents aren't retained in a baseline; the report explains why it can't generate a task diff. Evidence gathering remains with the harness. Reviewer results and author dispositions are explicitly empty; no semantic reviewer ran.
 
 Configuration, dependency, and deletion changes conservatively list every rendered page, including generated API operations. Authored-only changes list their affected pages. Each page reports its authored or generated origin.
 
-A stale working tree can still be previewed as a clearly labelled historical snapshot. Modified or missing validation artifacts prevent startup. A missing site after a failed compile is reviewable through `docs review`, but cannot be served. A built site with failed or skipped checks can be previewed with its actual status. A running preview detects changed artifacts and refuses page serving; replacing the report never switches it to another snapshot.
+A stale working tree can still be previewed as a clearly labelled historical snapshot. Modified or missing validation artifacts prevent startup. A missing site after a failed compile is reviewable through `docs review`, but can't be served. A built site with failed or skipped checks can be previewed with its actual status. A running preview detects changed artifacts and refuses page serving; replacing the report never switches it to another snapshot.
 
 HTML pages show a freshness banner that refreshes every two seconds while open. Markdown stays the captured output; read its snapshot ID from the HTTP `X-Shoalrun-Snapshot` header and consult the status URL. After edits, revalidate and restart with the new report. Copies are limited to 20,000 regular files and 512 MiB; symlinks are rejected. A forced kill can leave the serving copy, whose path is returned at startup. Remove that directory only after the process has stopped.
 

package/agent-docs/author/workspace.md

@@ -20,11 +20,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Check edits
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
-Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the alpha package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key are not required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
+Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the alpha package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key aren't required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
 
 Framework contributors can instead build the source checkout and run `node framework/dist/cli.js <command>` from its root. The examples below use the installed package.
 
@@ -62,13 +62,13 @@ For an existing edit without a baseline, declare its scope explicitly:
 npx --no-install shoalrun docs validate --file content/install.mdx --config docs.config.yaml
 ```
 
-Validation compiles a separate capture. Read the returned status, coverage, findings, skipped checks, and artifact paths. A failure needs correction and another validation. An incomplete or unavailable result needs investigation; it is not a passing result. Configured shell checks require explicit `--run-checks` and your harness's execution authorization.
+Validation compiles a separate capture. Read the returned status, coverage, findings, skipped checks, and artifact paths. A failure needs correction and another validation. An incomplete or unavailable result needs investigation; it isn't a passing result. Configured shell checks require explicit `--run-checks` and your harness's execution authorization.
 
 ### Inspect authoring suggestions
 
-Available since `0.1.0-alpha.13`.
+Since 0.1.0-alpha.13
 
-Project discovery and validation can report `authoring.related-reading` when a “Related reading” or “Related material” section contains document links. This is a nonblocking suggestion to inspect [native relationships](https://www.shoalrun.com/author/related-reading.md) and [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md). It does not create relationships or change your source. Choose each connection's purpose and reason yourself; keep manual links when they fit better. Pages already using `RelatedReading` do not receive this hint.
+Project discovery and validation can report `authoring.related-reading` when a “Related reading” or “Related material” section contains document links. This is a nonblocking suggestion to inspect [native relationships](https://www.shoalrun.com/author/related-reading.md) and [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md). It doesn't create relationships or change your source. Choose each connection's purpose and reason yourself; keep manual links when they fit better. Pages already using `RelatedReading` don't receive this hint.
 
 ## Confirm the result still applies
 
@@ -85,9 +85,9 @@ npx --no-install shoalrun docs review /path/from/result/report.json --format mar
 npx --no-install shoalrun docs preview /path/from/result/report.json --port 8771
 ```
 
-The preview command stays running and returns a local review URL plus HTML and Markdown URLs for every affected page that rendered. Open the review URL in your browser. It shows the task baseline, changed files, checks, findings, dependencies, and artifacts. Previewing a failed or incomplete result does not make it pass. A failed compile can leave no site to preview; read its findings with `docs review` first.
+The preview command stays running and returns a local review URL plus HTML and Markdown URLs for every affected page that rendered. Open the review URL in your browser. It shows the task baseline, changed files, checks, findings, dependencies, and artifacts. Previewing a failed or incomplete result doesn't make it pass. A failed compile can leave no site to preview; read its findings with `docs review` first.
 
-The server uses a private copy of the captured build. Each HTML page shows the snapshot status and a link back to the review. Source changes make that preview stale; the displayed content remains the captured version. A baseline contains digests rather than earlier file contents, so retain the task diff with your harness. The report does not attribute all dirty files to your task.
+The server uses a private copy of the captured build. Each HTML page shows the snapshot status and a link back to the review. Source changes make that preview stale; the displayed content remains the captured version. A baseline contains digests rather than earlier file contents, so retain the task diff with your harness. The report doesn't attribute all dirty files to your task.
 
 After a revision, stop the preview with Ctrl-C, validate again, and start a preview using the new report path. The server never watches or rebuilds source. Ctrl-C or SIGTERM removes its private serving copy; the validation artifacts remain. Remove only the reported validation artifact directory when finished. A forced process kill can leave the serving copy behind; its path is in the startup result.