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

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

@@ -0,0 +1,46 @@
+---
+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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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.
+
+## Keep the four shapes distinct
+
+Each template gives the page a different writing purpose and boundary.
+
+| Shape       | Writing boundary                                                                                                                                                                   |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tutorial    | Choose one reliable exercise and sample values. Show results early and at each step, offer repetition, and keep explanation brief. Link out for deeper reasoning and alternatives. |
+| How-to      | Address the reader's specific goal. Assume practical competence, allow conditional paths for real situations, and link out for background or complete reference facts.             |
+| Reference   | Organize facts to mirror the product, with consistent sections and neutral descriptions. Examples illustrate behavior without becoming task walkthroughs.                          |
+| Explanation | Develop a bounded topic through context, connections, design reasons, and perspectives. Discuss alternatives and tradeoffs without prescribing a task or cataloging fields.        |
+
+These boundaries are based on Diátaxis's guidance for [tutorials](https://diataxis.fr/tutorials/), [how-to guides](https://diataxis.fr/how-to-guides/), [reference](https://diataxis.fr/reference/), and [explanation](https://diataxis.fr/explanation/). The templates are editable starting points, not a claim that a page conforms merely because its type is set.

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

@@ -0,0 +1,39 @@
+---
+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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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.
+
+## 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.
+
+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

@@ -0,0 +1,47 @@
+---
+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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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.
+
+## Related reading
+
+### Read first
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Know which fields a new page needs before you pre-fill them.
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up the scaffold command's arguments and defaults.
+
+- [Design templates](https://www.shoalrun.com/author/design-templates.md) — Choose structures and prompts that serve the reader.
+
+### Related topics
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Use a project template when an API example is not the right starting point.
+
+### Often confused with
+
+- [Reuse prose across pages](https://www.shoalrun.com/author/snippets.md) — A template is copied into a new page once; a snippet is shared prose that stays in sync on every page that includes it.

package/agent-docs/author/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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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` set as in the [quickstart](https://www.shoalrun.com/start.md):
+
+```sh
+node "$SHOALRUN_CLI" 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 explicit form from the **repository root**:
+
+```sh
+node framework/dist/cli.js scaffold api-reference docs/docs.config.yaml docs/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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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: [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 > Templates
+
+**Updated: 2026-10-26.**
+
+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: [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 > Project tools > 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 > Project tools > 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.)