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

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

@@ -0,0 +1,53 @@
+---
+id: guide.templates
+title: Templates
+summary: Create and edit page starting points, then scaffold drafts from them.
+type: reference
+area: authoring
+subarea: authoring-templates
+audiences:
+  - authors
+canonical: /author/templates
+---
+
+# Templates
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/templates.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Know which fields a new page needs before you pre-fill them.
+
+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.
+
+## Scaffold a page
+
+Use a built-in template, or a template registered by your project. From the project directory, with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md):
+
+```sh
+npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx
+```
+
+Follow [create a page](https://www.shoalrun.com/author/add-page.md) to complete the draft, review it, set public access, and add it to navigation. Register a custom template only when your project needs a different starting structure.
+
+The built-in `api-reference` template needs `--operation`. To scaffold from it, run this form from your documentation project after [registering the operation](https://www.shoalrun.com/publish/api-references.md):
+
+```sh
+npx --no-install shoalrun scaffold api-reference docs.config.yaml content/new-operation.mdx \
+  --id reference.new --title 'New operation' --summary 'Create a thing.' --slug /reference/new \
+  --operation notes.create
+```
+
+Both forms write explicit channel, version, language, and draft access, and refuse to overwrite a file. The [API generation guide](https://www.shoalrun.com/api-docs/generate.md) explains reference templates that avoid duplicating spec facts.

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

@@ -0,0 +1,56 @@
+---
+id: guide.templates
+title: Templates
+summary: Create and edit page starting points, then scaffold drafts from them.
+type: reference
+area: authoring
+subarea: authoring-templates
+audiences:
+  - authors
+canonical: /author/templates
+---
+
+# Templates
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/templates.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Know which fields a new page needs before you pre-fill them.
+
+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.
+
+## Short CLI and derived values
+
+From a project directory, use the package's `shoalrun` command after installing it locally:
+
+```sh
+shoalrun scaffold how-to -n /path/to/project/content/track-parcel.mdx
+```
+
+The CLI discovers `docs.config.yaml` in the current directory or a parent. It derives draft values from the target path relative to the content directory. For `content/guides/retry-payments.mdx` with `guide`:
+
+| Field     | Derived value                                                              |
+| --------- | -------------------------------------------------------------------------- |
+| `id`      | `guide.guides.retry-payments`                                              |
+| `title`   | `Retry Payments`                                                           |
+| `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.
+
+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.
+
+Every new page is a draft. Its detailed placeholders remain visible for author and AI edits, and an unresolved placeholder fails the public build. This guard catches unfinished sections; a human still needs to check technical claims and example behavior before publication.

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

@@ -0,0 +1,44 @@
+---
+id: guide.templates
+title: Templates
+summary: Create and edit page starting points, then scaffold drafts from them.
+type: reference
+area: authoring
+subarea: authoring-templates
+audiences:
+  - authors
+canonical: /author/templates
+---
+
+# Templates
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/templates.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Know which fields a new page needs before you pre-fill them.
+
+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.
+
+## 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.
+- **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.
+- **Related reading.** A `RelatedReading` block ends the page. Declare the relationships in config, or delete the section if no page relates to this one. The `api-reference` template has no such block, because the build adds related lists after the generated details.

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

@@ -0,0 +1,92 @@
+---
+id: reference.authoring-workspace
+title: Authoring tools commands
+summary: Look up provider-free project discovery, reference reads, baselines,
+  and snapshot validation.
+type: reference
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/workspace/commands
+---
+
+# Authoring tools commands
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Commands
+
+**Updated: 2026-10-27.**
+
+**Status: Experimental.**
+
+These commands are available through the Shoalrun CLI. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm. They make no authoring provider calls.
+
+## Discovery and references
+
+Use these commands to find the project and retrieve the references needed for an edit.
+
+| Command                    | Result                                                            |
+| -------------------------- | ----------------------------------------------------------------- |
+| `docs project`             | Project-wide JSON discovery, without requiring a page selector.   |
+| `docs source FILE`         | Bounded project-relative source passage with a whole-file digest. |
+| `docs search QUERY --json` | Search bundled framework documentation.                           |
+| `docs read ID --json`      | Read a bundled reference by stable ID.                            |
+
+Project commands accept `--config FILE`; otherwise they find the nearest `docs.config.yaml` in the current directory or its ancestors. Project sections are `pages`, `guidance`, `configuration`, `navigation`, `relationships`, `templates`, and `findings`. Choose a section with `--section`. Pages, navigation, and relationships accept one of `--id`, `--file`, or `--query`.
+
+Project pagination uses `--offset` and `--limit` (default 20, maximum 100). Follow the returned `pagination.nextOffset`. `--max-tokens` bounds the response (default 8192). Source reads use Unicode code-point offsets and default to 4096 tokens; follow `nextOffset` and verify the digest between reads. Paths must resolve inside the project. Use your harness's tools and permissions for external implementation sources.
+
+## Validation
+
+Use these checks to find source and publication problems before reviewing the result.
+
+| Command                         | Result                                                                               |
+| ------------------------------- | ------------------------------------------------------------------------------------ |
+| `docs baseline --out FILE`      | Record the current working tree without running checks. The destination must be new. |
+| `docs validate --baseline FILE` | Validate changes since a task baseline in a separate capture.                        |
+| `docs validate --file FILE`     | Validate declared file changes; repeat the selector for more files.                  |
+| `docs validate --id ID`         | Validate declared pages; repeat the selector for more IDs.                           |
+| `docs validation-status REPORT` | Check whether a retained report still applies to current inputs.                     |
+
+Baselines and validation artifacts must be outside the project or inside its excluded `.shoalrun` directory. `--artifacts DIRECTORY` selects a new artifact directory; otherwise validation retains a temporary directory. Results contain actual report, capture, and site locations. `--run-checks` opts into configured trusted shell checks under the harness's permissions; evaluator hooks remain skipped.
+
+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`.
+
+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._-]*`.
+
+## Review and preview
+
+Use these commands to inspect proposed changes and their rendered output.
+
+| Command                                | Result                                                                    |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `docs review REPORT`                   | JSON review for a retained validation report.                             |
+| `docs review REPORT --format markdown` | A readable report for the same snapshot and task scope.                   |
+| `docs preview REPORT --port PORT`      | Foreground local preview of that exact build, with a browser review page. |
+
+`REPORT` is the validation report path returned by `docs validate`. Review accepts `--format json` or `--format markdown`; JSON is the default. It exits 0 only for a current `ok` result. An error returns the existing JSON failure envelope, even when Markdown was requested.
+
+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.
+
+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.
+
+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.
+
+## Existing checked edits
+
+`docs context`, `docs plan`, and `docs apply` remain supported. They preserve source freshness, collision, validation, and rollback protections. See [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) for that procedure. Working-tree editing is the default for the new tools. The portable authoring skill uses this working-tree workflow.
+
+## Related reading
+
+No matching documents.

package/agent-docs/author/workspace.md

@@ -0,0 +1,104 @@
+---
+id: guide.authoring-workspace
+title: Check working-tree documentation edits
+summary: Discover a project, capture a baseline, edit files, and validate an
+  isolated copy.
+type: how-to
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/workspace
+---
+
+# Check working-tree documentation edits
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Check edits
+
+**Updated: 2026-10-27.**
+
+**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.
+
+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.
+
+## Read project guidance
+
+```sh
+npx --no-install shoalrun docs project --section guidance --config docs.config.yaml
+npx --no-install shoalrun docs project --query "installation" --config docs.config.yaml
+npx --no-install shoalrun docs source AGENTS.md --config docs.config.yaml
+npx --no-install shoalrun docs search "page metadata" --json
+npx --no-install shoalrun docs read guide.frontmatter --json
+```
+
+Read applicable instructions and reviewed examples before editing. Discovery works without a selected page. Inspect the findings section when discovery reports findings; follow pagination when a section exceeds its response budget.
+
+## Record the starting files
+
+```sh
+npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json --config docs.config.yaml
+```
+
+Choose a new baseline filename for each task. The baseline includes earlier local edits and untracked files; it compares later changes with this starting state rather than Git HEAD. It runs no checks.
+
+## Edit and validate
+
+Edit ordinary MDX and configuration files using your agent's file tools. Preserve unrelated edits and review changes to identity, navigation, relationships, and publication metadata.
+
+```sh
+npx --no-install shoalrun docs validate --baseline .shoalrun/task-baseline.json --config docs.config.yaml
+```
+
+For an existing edit without a baseline, declare its scope explicitly:
+
+```sh
+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.
+
+## Confirm the result still applies
+
+```sh
+npx --no-install shoalrun docs validation-status /path/from/result/report.json
+```
+
+Use the actual report path returned by validation. A stale result requires another validation.
+
+## Review and preview the snapshot
+
+```sh
+npx --no-install shoalrun docs review /path/from/result/report.json --format markdown
+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 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.
+
+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.
+
+Review facts, examples, supporting sources, and the task diff before accepting the edit. Use your normal review and publication process afterward.
+
+## Related reading
+
+### Read first
+
+- [Authoring tools for your coding agent](https://www.shoalrun.com/author/agent-overview.md) — Understand how your coding agent uses Shoalrun tools and human review. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Look up discovery and snapshot validation commands. (Status: experimental.)
+
+- [Example writing guide](https://www.shoalrun.com/author/writing-style.md) — Review the example guidance before approving a writing plan.
+
+### Related topics
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Use the checked edit commands with your existing coding agent. (Status: experimental.)

package/agent-docs/author/writing-style.md

@@ -0,0 +1,147 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Adapt this example
+
+Save your team's writing guide in the project and give your agent its path in project instructions. Include reviewed examples appropriate to the page type. Configure your own Vale rules for automated checks. [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) explains how to choose useful rules and examples.
+
+## Example audience and scope
+
+Write for someone trying to understand or complete a task in Shoalrun. Assume they can edit a text file; introduce framework-specific concepts before relying on them. State prerequisites when a task needs terminal, Git, API, or deployment knowledge.
+
+## Page purpose and structure
+
+Choose the page type by the reader's goal and the actual content. Keep one primary purpose per page. Split substantial conceptual discussion from a procedure and connect the pages with related reading.
+
+| Page type       | Reader goal                                    | Useful structure                                                                                                                                                                        |
+| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tutorial        | Learn through a guided exercise.               | Outcome, prerequisites, one reliable path with sample values, visible results, and a final check. Explain only what the exercise needs; link to deeper discussion.                      |
+| How-to          | Complete a specific task.                      | Starting state, necessary prerequisites, actions in execution order, success check, and likely failures. Put decisions before the steps they affect.                                    |
+| Reference       | Look up an exact fact.                         | When the feature applies, syntax or fields, defaults, constraints, examples, and errors. Organize facts for lookup.                                                                     |
+| Explanation     | Understand a concept or design.                | The question being explained, definitions, a concrete example, reasons and tradeoffs, and links to practical tasks.                                                                     |
+| Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
+| Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
+| Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
+| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+
+Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
+
+Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and agents** for predictable lookup. Document required values, defaults, accepted types, and constraints in Attributes; say when a component takes no attributes. Keep feature-specific examples and errors under descriptive headings. Fenced-code options and configured site features can use their own precise labels. Preserve old fragment IDs when changing a heading.
+
+Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
+
+Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
+
+These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
+
+## Voice and explanations
+
+Address the reader as “you.” Use active voice and concrete verbs. Start a paragraph with its main point, then supply the reason or example needed to understand it. Keep sentences short enough to follow without breaking every thought into a separate paragraph.
+
+Name the action and its result. Replace claims such as “powerful,” “seamless,” and “easy” with behavior the reader can observe. Avoid inflated words, ceremonial introductions, repeated summaries, and invented terminology.
+
+| Before                                                            | Better                                                                                                                    | Reason                                       |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `Utilize the configuration to leverage publication capabilities.` | “Set the channel and version in the page's frontmatter.”                                                                  | Names the fields and action.                 |
+| `It is important to note that a Markdown twin is generated.`      | “The build creates a Markdown copy of each published page.”                                                               | Identifies the actor and defines the result. |
+| “Run CI to validate it.”                                          | “Run the project's automated checks. Continuous integration (CI) runs those checks when code changes.”                    | Explains the acronym and mechanism.          |
+| “Hybrid improves relevance.”                                      | “Hybrid search combines word matching and vector rankings. Whether it helps depends on the queries and ranking settings.” | Defines the term and limits the claim.       |
+
+Define an unfamiliar term at its first useful appearance, even when the glossary also defines it. Explain acronyms before using them repeatedly. Prefer one small example to a chain of new terms. Preserve exact command, field, model, and component names in code formatting.
+
+## Procedures and examples
+
+Show the starting directory, required inputs, and expected result when a command depends on them. Say which values readers must replace. Keep commands supported by source or verified behavior; do not invent flags to make an example look complete.
+
+Give each procedure step one purpose. Put the explanation beside the action it supports. Include a check that readers can perform and describe what success looks like. Troubleshooting should identify a symptom, likely cause, and concrete next action.
+
+Examples demonstrate the feature under discussion. Use the smallest example that still shows the important behavior. Preserve required fields, defaults, constraints, and meaningful errors during a rewrite. An example copied from a different page is not evidence that it applies to this task.
+
+## Ingredients, recipes, and cookbooks
+
+Use a recipe for a task that should participate in the recipe and cookbook features. A recipe can be authored directly; ingredients and a composition spec are optional. Use ingredients when multiple recipes share instructions you want to maintain once. Use a cookbook when readers need help choosing a complete path. See [how these page types fit together](https://www.shoalrun.com/author/recipes.md).
+
+For an ingredient, name what must already be available and what success makes available to the next step. When using `workflow` metadata, keep `inputs` and `outputs` consistent across the recipe and include the required `check`. State a check the reader can perform, such as “the build reports success and both output files exist,” rather than “make sure it works.” Metadata declares handoffs; it does not run commands or verify their results. Keep essential instructions in the body.
+
+For a recipe, choose the order deliberately and explain how to recover from a failed step. The published recipe must contain the complete instructions; readers should not need to assemble ingredients themselves. Review assembled drafts before publication. Do not describe passing assembly checks as proof that the procedure succeeds. [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) explains the authoring workflow.
+
+For a cookbook, describe each choice's starting state and outcome. Use single selection for alternative or overlapping paths, such as build versus build-and-audit. Offer multiple selection only when the recipes make sense together. A chooser displays published recipes; it does not deduplicate their steps, connect dependencies, or execute them. If a combined task needs shared setup and explicit handoffs, write one complete recipe for it. [Configure a cookbook](https://www.shoalrun.com/author/cookbooks.md) explains the options.
+
+Check each ingredient's instructions and each recipe's full outcome. Inspect the cookbook's HTML choices and Markdown recipe links. Keep prerequisites, failure guidance, and success checks readable in both formats.
+
+## Choose components by reader need
+
+Choose the structure that helps readers use the information or complete the task.
+
+| Need                                                          | Choice                                                                                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| A short ordered sequence without titled steps                 | An ordinary Markdown numbered list.                                                                                        |
+| A procedure with a title and supporting content for each step | [Steps](https://www.shoalrun.com/author/components/steps.md).                                                              |
+| Code that changes across steps with synchronized explanations | [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md).                                                 |
+| A prerequisite, caution, or consequence that needs emphasis   | [Callout](https://www.shoalrun.com/author/components/callout.md), with a specific label.                                   |
+| Parallel facts such as fields, defaults, or alternatives      | A table with concise cells.                                                                                                |
+| A choice between complete task paths                          | [CookbookChooser](https://www.shoalrun.com/author/components/cookbook-chooser.md), or recipe cards for a simple directory. |
+| Recommended next pages                                        | [Related reading](https://www.shoalrun.com/author/related-reading.md), backed by configured relationships.                 |
+
+Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
+
+Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+
+A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
+
+## Evidence and uncertainty
+
+Distinguish implemented behavior, measured observations, and planned work. State a benchmark's inputs and scoring rule before drawing conclusions. A result from one task or model does not establish general reliability.
+
+When evidence does not specify a fact, say what is missing. An undocumented policy is not proof that no policy exists. Keep a visible TODO in an unpublished draft and record the missing fact for review. Do not remove uncertainty just to clear a style check. Resolve it with evidence before publication.
+
+Preserve stable IDs, routes, publication metadata, and access policy during a prose edit. Use stable document links. Set the edit date without changing an entry's original change date. Report changes to identity, scope, or technical claims explicitly for review.
+
+## Reviewed writing examples
+
+These pages illustrate specific editorial choices. Copy their approach, then verify the facts for the page being written.
+
+| Example                                                                                                      | What to learn from it                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| [Getting started](https://www.shoalrun.com/start.md)                                                         | One guided exercise, explicit prerequisites, working-directory context, and observable preview results.                |
+| [Add a page](https://www.shoalrun.com/author/add-page.md)                                                    | A practical starting state, actions in order, and checks before publication.                                           |
+| [Steps reference](https://www.shoalrun.com/author/components/steps.md)                                       | Syntax beside live examples, exact attributes and defaults, and complete output behavior.                              |
+| [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md)                       | Definitions, reasons for the design, concrete discovery paths, and limits. Match its reasoning rather than its length. |
+| [Build-site ingredient](https://www.shoalrun.com/ingredients/build-site.md)                                  | Named inputs and outputs, a focused action, and an observable handoff check.                                           |
+| [Build-and-audit recipe](https://www.shoalrun.com/recipes/audit-docs.md)                                     | Complete ordered instructions with prerequisites and a final task outcome.                                             |
+| [Site workflows cookbook](https://www.shoalrun.com/cookbooks/site-workflows.md)                              | Clear choices between overlapping complete paths and links to their recipes.                                           |
+| [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) | Reader-visible behavior, precise scope, and an explicit private-prototype qualification.                               |
+
+## Review a draft
+
+Check purpose, organization, definitions, factual support, examples, and the success check. Compare technical details with the original source. Run the compiler and Vale, then inspect HTML and Markdown. This site's Vale configuration enables Voices, Direct, and Shoalrun; those rules catch detectable wording and structure problems. Passing them does not establish factual accuracy or usefulness.
+
+Give your agent this guide and an example appropriate to the page's purpose. Examples guide structure and tone; verify technical claims against the relevant sources.
+
+## Related reading
+
+### Reference while working
+
+- [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) — Adapt editorial rules to your own readers.
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Look up page types, starter structures, and formatting checks.

package/agent-docs/author/writing-style.sections/adapt-this-example.md

@@ -0,0 +1,28 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Adapt this example
+
+Save your team's writing guide in the project and give your agent its path in project instructions. Include reviewed examples appropriate to the page type. Configure your own Vale rules for automated checks. [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) explains how to choose useful rules and examples.

package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md

@@ -0,0 +1,44 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Choose components by reader need
+
+Choose the structure that helps readers use the information or complete the task.
+
+| Need                                                          | Choice                                                                                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| A short ordered sequence without titled steps                 | An ordinary Markdown numbered list.                                                                                        |
+| A procedure with a title and supporting content for each step | [Steps](https://www.shoalrun.com/author/components/steps.md).                                                              |
+| Code that changes across steps with synchronized explanations | [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md).                                                 |
+| A prerequisite, caution, or consequence that needs emphasis   | [Callout](https://www.shoalrun.com/author/components/callout.md), with a specific label.                                   |
+| Parallel facts such as fields, defaults, or alternatives      | A table with concise cells.                                                                                                |
+| A choice between complete task paths                          | [CookbookChooser](https://www.shoalrun.com/author/components/cookbook-chooser.md), or recipe cards for a simple directory. |
+| Recommended next pages                                        | [Related reading](https://www.shoalrun.com/author/related-reading.md), backed by configured relationships.                 |
+
+Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
+
+Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+
+A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.

package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md

@@ -0,0 +1,32 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Evidence and uncertainty
+
+Distinguish implemented behavior, measured observations, and planned work. State a benchmark's inputs and scoring rule before drawing conclusions. A result from one task or model does not establish general reliability.
+
+When evidence does not specify a fact, say what is missing. An undocumented policy is not proof that no policy exists. Keep a visible TODO in an unpublished draft and record the missing fact for review. Do not remove uncertainty just to clear a style check. Resolve it with evidence before publication.
+
+Preserve stable IDs, routes, publication metadata, and access policy during a prose edit. Use stable document links. Set the edit date without changing an entry's original change date. Report changes to identity, scope, or technical claims explicitly for review.