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 toExperimental

Apply a checked edit plan

Find a page's sources, review an edit, and apply it through Shoalrun checks.

Updated
ForAuthors
Read as Markdown

Use this optional workflow when your agent needs a digest-checked replacement plan before writing files. Your agent gathers evidence and writes the candidate; Shoalrun validates and applies the exact plan. For ordinary working-tree editing, follow Check working-tree documentation edits instead.

Prepare and apply an update

  1. Read the page and its owners

    shoalrun docs context guide.welcome --config docs.config.yaml

    Read the returned source files and the project's writing guide. Capture the source digest before drafting. Give your agent the requested change and supporting sources; those can include other repositories, specifications, or links it can inspect with its own tools.

  2. Write and review a candidate

    Have the agent save a complete replacement file separately from the source. Preserve stable IDs, routes, publication fields, and access policy. Update the edit date. Ask for a diff, the evidence supporting changed claims, and any unresolved questions. Run the project's Vale rules and verify code examples.

  3. Create an exact edit plan

    Create edit-request.json with full replacement text and the digest of the source used to draft it:

    {
  "edits": [
    {
      "file": "content/welcome.mdx",
      "baseDigest": "<SHA-256 digest of the original source>",
      "content": "<complete replacement file>"
    }
  ]
}

    The placeholders above must be replaced with actual values. Paths are relative to the project configuration directory.

    shoalrun docs plan --request-file edit-request.json --out edit-plan.json --config docs.config.yaml
shoalrun docs apply edit-plan.json --config docs.config.yaml --check

    The check builds a temporary copy and leaves source files unchanged. A stale source or failed build stops the edit. Plans support existing authored Markdown files and YAML files loaded by the configuration; use scaffolding for new files.

  4. Apply the reviewed plan

    shoalrun docs apply edit-plan.json --config docs.config.yaml
shoalrun audit docs.config.yaml

    Applying repeats freshness and build checks before writing. Inspect the resulting HTML and Markdown. The plan does not run configured audit tests, commit changes, or deploy; those are separate steps.

What checks establish

Compiler checks catch problems such as broken document links and invalid components. Vale checks the rules your team configures. Neither establishes factual accuracy or whether a procedure works. Ask your agent to explain what it verified and what still needs review.

Ordinary public builds exclude draft pages. Use the separate working-tree docs validate interface to render affected drafts in isolation without changing their authored access policy. This does not change the checked plan/apply contract described above.

Read first

  • Templates — Scaffold a draft page before an agent writes its content.

Reference while working