Shoalrun documentation framework
For agents
Start with https://www.shoalrun.com/llms.txt for the documentation index, then read the Markdown pages it links. Skip to article. Documentation index. Read this page as Markdown.
How to

Use your coding agent

Give your agent project guidance and draft a new documentation page.

Updated
ForAuthors
Read as Markdown

Use an agent that can read project files and run commands. It writes with its own model; Shoalrun requires no additional authoring API key.

Prepare your agent

Install the portable authoring skill using your agent's supported skill setup. If it cannot load skills, give it the same project instructions and commands directly. Tell it where to find docs.config.yaml, your writing guide, and reviewed examples. The example writing guide is a starting point you can adapt.

The CLI's docs search and docs read commands read bundled Shoalrun guidance. The MCP server offers documentation search and reads for agents that support MCP; it does not write project files. Your agent uses its own file tools and the CLI for edits.

Give a working-tree task

Name the reader outcome and documentation project. Let the agent discover the relevant pages and required supporting changes from project policy. For example:

Read the installed shoalrun-author/SKILL.md and work in this documentation project.
Revise the authoring procedure so readers can write titled steps and inspect
both outputs. Read project policy and supporting evidence first, preserve earlier
local edits, capture a task baseline, edit files normally, and show the matching
validation report, preview, and task diff. Do not commit or publish.

This uses the harness's own writer and execution permissions. Required navigation, relationships, and changelog entries come from the project instructions rather than an automatic compiler rule. If evidence is missing or policies conflict, the agent should identify the question for review.

Draft a new page

  1. Define the reader's task

    Give your agent the audience, goal, intended page type, and supporting sources. Let it gather and evaluate evidence using its own tools. Ask it to identify missing facts rather than invent examples or behavior.

  2. Choose and scaffold a template

    Use the project's templates. Record the starting state before scaffolding:

    shoalrun docs baseline --out .shoalrun/task-baseline.json --config docs.config.yaml
shoalrun scaffold how-to -n content/publish-a-site.mdx --config docs.config.yaml

    The new file is a draft. Replace the prompts, preserve its identity and publication metadata, and add required companions from project policy.

  3. Check and review the page

    Run the project's style checker and configured checks. Read the draft, verify its examples, and review technical claims against the evidence.

    shoalrun docs validate --baseline .shoalrun/task-baseline.json --config docs.config.yaml
shoalrun docs review /path/from/result/report.json --format markdown
shoalrun docs preview /path/from/result/report.json --port 0

    Use the actual report path returned by validation. It renders affected drafts in a separate capture while preserving their authored access policy. Review findings, coverage, and skipped checks; use --run-checks only for applicable trusted commands under the harness's permissions. A stale, failed, incomplete, or unavailable result is not a pass. After edits, revalidate and restart the preview from the new report. Stop the foreground preview with Ctrl-C when finished.

  4. Prepare publication

    After the author approves publication, change the page's access policy to public and build to a dedicated output directory. Inspect its HTML, Markdown, navigation, and links before committing or deploying.

    shoalrun build docs.config.yaml preview-output