Use this procedure from your documentation project directory, containing docs.config.yaml, with @shoalrun/cli installed. Getting started explains how to install the private alpha package from GitHub Packages. 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
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
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.
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:
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
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
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.