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

package/agent-docs/api-docs/generate.sections/use-a-template-for-editorial-context.md

@@ -0,0 +1,45 @@
+---
+id: guide.api-generation
+title: Generate and select API pages
+summary: Choose operations, generate reference pages, and add editorial context
+  to an API reference.
+type: how-to
+area: api
+subarea: api-generation
+canonical: /api-docs/generate
+---
+
+# Generate and select API pages
+
+> 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) > Document an API > Generate and select API pages
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/api-docs/generate.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Register and review an API source before generating its pages.
+
+**Next steps**
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Arrange selected operations in the site menu.
+
+Start with a registered local API from [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md). Use generation when you want references for many operations without writing an MDX page for each one. The commands below run in your documentation project with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md).
+
+## Use a template for editorial context
+
+Use the built-in `api-reference` template for details OpenAPI cannot supply, such as operational context, task links, prerequisites, and limitations. Keep method, path, field lists, and example values in the spec so generated references have one source for those facts.
+
+```sh
+shoalrun scaffold api-reference -n content/create-enrollment.mdx \
+  --id reference.create-enrollment --operation cedar.createEnrollment
+```
+
+No template registration is needed. The scaffold requires exactly one known stable operation ID. Check that the page ID matches that operation's `reference` entry in API config. A scaffold is a draft; replace every prompt and review the operation against the spec before publishing. The [Templates guide](https://www.shoalrun.com/author/templates.md) shows how to override the built-in outline for your project. Editing a template later affects new drafts, not existing pages.

package/agent-docs/api-docs/support.md

@@ -0,0 +1,97 @@
+---
+id: guide.openapi-support
+title: OpenAPI support and limits
+summary: Check supported OpenAPI operations, schema keywords, examples, and
+  source restrictions before importing a specification.
+type: reference
+area: api
+subarea: api-contracts
+canonical: /api-docs/support
+---
+
+# OpenAPI support and limits
+
+> 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) > API support > OpenAPI support and limits
+
+**Updated: 2026-10-27.**
+
+Shoalrun renders a defined subset of OpenAPI into HTML, Markdown, and focused contracts. Check these limits before importing a large specification. A supported OpenAPI version does not mean every feature in that version can be rendered.
+
+## Compatibility
+
+The supported behavior varies by OpenAPI feature and source structure.
+
+| Area               | Supported behavior                                                                                                                                                                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Source formats     | OpenAPI 3.0.x and 3.1.x in YAML or JSON. `kind: file` builds from local files; `api import` can create a pinned local snapshot from a public HTTPS URL.                                                                                                                                                                              |
+| Operations         | Method and path, server alternatives, CommonMark descriptions, security alternatives and credential details, path and operation parameter overrides, request body media types, responses, and named examples.                                                                                                                        |
+| Webhooks           | Top-level OpenAPI 3.1 `webhooks`, including a document without `paths`; authored and generated references describe the inbound request and acknowledgement, with no outbound cURL command. Focused contracts retain the `webhooks` location.                                                                                         |
+| Authentication     | API keys in headers, query strings, or cookies; HTTP schemes; OAuth2 flow names and scopes; OpenID Connect discovery; mutual TLS. These describe authentication; the site does not authenticate or execute requests.                                                                                                                 |
+| References         | Local `$ref` within the project or configured OpenAPI source directory, including multiple files. `api import` downloads same-origin relative references and rewrites them to local snapshot paths. Recursive schemas end with a named reference marker. Absolute file paths and references escaping those directories are rejected. |
+| Schemas            | Objects, arrays, titled variants, discriminators, enums, constants, required fields, defaults, examples, nullable values, supported constraints, additional properties, and read/write/deprecated labels. OpenAPI 3.1 boolean schemas are supported. The exact keyword list is below.                                                |
+| Named examples     | Parameter, request, and response `examples` maps; reusable `components.examples` references; names, summaries, descriptions, values, provenance, HTML selection and deep links. All examples appear in Markdown. HTTPS `externalValue` is an external link, not a fetched payload.                                                   |
+| Focused contracts  | One-operation JSON with transitive local components, named examples, security schemes, and internal recursive references. Enabled by `source.focused: true` or `source.publish: true`.                                                                                                                                               |
+| Reader layout      | Three columns at wide widths and a stacked order on narrow screens. JSON schemas supply type shapes even without named examples; shapes and named examples are distinct views.                                                                                                                                                       |
+| Extension metadata | Explicit mappings from operation-level `x-*` values to `subjectLifecycle`; OpenAPI `deprecated: true` takes precedence. Other extensions do not automatically become page metadata.                                                                                                                                                  |
+
+## Supported schema keywords
+
+The renderer accepts these schema keys, plus `x-*` extension keys:
+
+```text
+$ref, type, format, nullable, enum, const, default,
+minLength, maxLength, minimum, maximum, exclusiveMinimum,
+exclusiveMaximum, multipleOf,
+minItems, maxItems, uniqueItems, minProperties, maxProperties, pattern,
+readOnly, writeOnly, deprecated, description, example, examples,
+allOf, oneOf, anyOf, items, properties, required, additionalProperties,
+title, discriminator
+```
+
+Other schema keywords fail when encountered by the renderer. This includes valid OpenAPI or JSON Schema keywords outside this list. The compiler presents supported constraints; it is not a general validator for payloads or the entire OpenAPI specification.
+
+Exclusive bounds follow the entry document's version even when a schema lives in another local file. In OpenAPI 3.0, `exclusiveMinimum` and `exclusiveMaximum` are booleans that modify a numeric `minimum` or `maximum`. In OpenAPI 3.1, each exclusive bound is a number. The build rejects a value in the wrong form. OpenAPI 3.1 also accepts `true` and `false` as entire schemas, displayed as allowing any value or no value, and an `examples` array on a schema. OpenAPI 3.0 rejects boolean schemas and schema-level `examples`.
+
+## Features requiring adaptation
+
+These features have limits that may require adapting the source or authored documentation.
+
+| Feature                         | Current limit and recovery                                                                                                                                                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Remote `$ref` in a normal build | Fails with `Remote $ref requires a pinned snapshot`. Use `api import` for public HTTPS sources with same-origin relative references, then build from its local snapshot. Cross-origin references need a separately prepared local source. |
+| Local `externalValue`           | Fails with `local externalValue needs a pinned adapter`. Use a local inline example value, or an HTTPS external example link.                                                                                                             |
+| Callbacks                       | Operation callbacks fail with an unsupported feature diagnostic. Top-level 3.1 webhooks are supported separately.                                                                                                                         |
+| Response headers and links      | Fail with `Response headers or links need an adapter`. Prepare a supported documentation source while retaining the original contract separately.                                                                                         |
+| Parameter `content`             | Requires an adapter; use supported parameter schemas in the documentation source.                                                                                                                                                         |
+| Request media `encoding`        | Fails with `Request encoding needs an adapter`. Multipart binary fields have limited generated upload commands, but media encoding settings are not rendered.                                                                             |
+| Other schema keywords           | Fail with `Unsupported schema keyword`. Adapt the documentation source without claiming omitted constraints are represented.                                                                                                              |
+
+Avoid removing source semantics silently. If your API needs an unsupported feature, describe that limitation in the authored page and keep the authoritative contract available to readers where appropriate.
+
+## Check a source before adding pages
+
+With the CLI built as in the [quickstart](https://www.shoalrun.com/start.md), run:
+
+```sh
+npx --no-install shoalrun api audit apis/notes/openapi.yaml
+```
+
+The audit renders every operation in the supplied source and checks field anchors and named examples across HTML and Markdown. It reports every unsupported schema keyword it finds for each operation, with the source file and schema location, before the strict renderer runs. It can reveal unsupported features beyond the operations you initially plan to publish. It does not call a live API or establish complete semantic fidelity.
+
+After registering an API and authoring or selecting its pages, run `api review` and pin the reviewed digest before a normal public build. The [API tutorial](https://www.shoalrun.com/publish/api-references.md) gives the full sequence. `source.publish: true` publishes the entire source, even when only a subset has reference pages; use focused contracts when a full-source download is unnecessary.
+
+For existing site output, run `api focused-audit <site-directory>` to check focused contract scope, internal references, and Markdown links. [Project audits](https://www.shoalrun.com/publish/audit.md) combine these checks with the site build and configured external tests.
+
+## Related reading
+
+### Next steps
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Build a reference page from a supported local specification.
+
+### Reference while working
+
+- [Focused OpenAPI contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) — Check what a focused export keeps and drops.

package/agent-docs/author/add-page.md

@@ -0,0 +1,126 @@
+---
+id: guide.add-page
+title: Create a page
+summary: Create a page from a template, complete its scaffolded draft, and
+  publish it in navigation.
+type: how-to
+area: authoring
+subarea: authoring-pages
+canonical: /author/add-page
+---
+
+# Create a page
+
+> 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 > Create a page
+
+**Updated: 2026-10-27.**
+
+Create a page from a template with `scaffold`. Templates prompt you for the page's frontmatter, an introduction, the main content, and related pages before you publish. This is the recommended authoring workflow for new pages.
+
+## Before you begin
+
+Complete [getting started](https://www.shoalrun.com/start.md), then run the commands from `my-docs/`, where `@shoalrun/cli` is installed. You will create a page at `/track-parcel` and verify both published formats.
+
+## Choose a template
+
+Choose the template that matches what the reader needs to accomplish.
+
+| Template        | Use it for                                                                            |
+| --------------- | ------------------------------------------------------------------------------------- |
+| `tutorial`      | A reliable guided exercise for learning by doing.                                     |
+| `how-to`        | A specific task, with practical actions and a success check.                          |
+| `reference`     | Exact syntax, fields, options, examples, errors, and limits.                          |
+| `explanation`   | Concepts, context, reasons, and tradeoffs.                                            |
+| `api-reference` | Editorial context above generated operation details; requires one known operation ID. |
+| `recipe`        | A complete task used by recipe and cookbook workflows.                                |
+| `ingredient`    | One reusable action or check used in recipes.                                         |
+| `cookbook`      | A page that helps readers choose complete recipes.                                    |
+
+These templates ship with the CLI. `guide` and `troubleshooting` remain available for compatibility. Projects can register additional templates or override built-ins.
+
+The CLI includes a [`recipe` template](https://www.shoalrun.com/author/recipe-drafts.md) for a complete customer task, written directly or assembled from ingredients. Built-in `ingredient` and `cookbook` templates support reusable steps and workflow selection. The `ingredient draft` command can start one ingredient from an API example; `recipe draft` assembles an ordered set of ingredient files for review.
+
+Use the project's template for the document type when one exists. Project templates can also override the built-in names. See [templates](https://www.shoalrun.com/author/templates.md) to register or change one.
+
+## Scaffold the draft
+
+From the project directory:
+
+```sh
+npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx \
+  --id how-to.track-parcel --title 'Track a parcel'
+```
+
+The command finds `docs.config.yaml`, creates the file, and adds the template body and draft frontmatter. It refuses to overwrite an existing file. This example sets the stable ID and title explicitly; the CLI derives the slug `/track-parcel` from the target path.
+
+Without overrides, this path would produce ID `how-to.track-parcel` and title `Track Parcel`. The generated summary starts with `Draft guide for ` and must be replaced before publication. Publication fields come from your project configuration.
+
+## Complete the template
+
+Open `content/track-parcel.mdx` and work through its prompts:
+
+1. Read the comments in the frontmatter, fill in the placeholder fields, and delete the comment lines.
+2. Set `updated` to today's date in `YYYY-MM-DD` format. Write an introduction of 150 words or fewer and remove irrelevant optional sections.
+3. Follow the chosen shape. Write a guided exercise, practical task actions, organized reference facts, or conceptual discussion. For this how-to, write actions and checks.
+4. Keep the **HTML, Markdown, and agents** section when the page uses a component or behavior that changes either output or what an agent reads. Otherwise delete it.
+5. Add relationships for the page, or delete Related reading. Verify technical claims before you publish.
+
+Replace every TODO prompt enclosed in double square brackets. Adapt the sections to the task rather than leaving irrelevant prompts behind. Templates provide a starting structure; editing a template later does not rewrite this page. The [quickstart](https://www.shoalrun.com/start.md) shows a completed example.
+
+Keep the generated `access.policy: draft` while writing. Drafts are validated but omitted from the published site, even if the starter defaults to public access. Headings in the body begin at level 2 because Shoalrun renders the page title separately.
+
+## Publish the page
+
+After reviewing the content, change the generated access value to:
+
+```yaml
+access: { policy: public }
+```
+
+Keep the ID `how-to.track-parcel` and slug `/track-parcel` for this example. Check the channel, version, and language match an enabled publication. The build rejects public pages with unresolved template prompts or the generated draft summary. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for shared defaults and publication rules. The [generated frontmatter reference](https://www.shoalrun.com/author/frontmatter-reference.md) lists native fields and this site's project declarations.
+
+## Put it in navigation
+
+Append this item to the existing `navigation` list in `docs.config.yaml`:
+
+```yaml
+  - id: track-parcel
+    doc: how-to.track-parcel
+```
+
+Use the page's frontmatter ID for `doc`; the navigation item's own `id` identifies that menu entry. You can nest the item under a group's `items` list instead. Navigation uses the page title as its label unless you supply `label`.
+
+A public page can have a working URL without appearing in the sidebar. Adding this entry makes it discoverable there. See [organize navigation](https://www.shoalrun.com/author/navigation.md) for groups, includes, and links.
+
+## Verify HTML and Markdown
+
+From the project directory:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8765
+```
+
+Open `http://127.0.0.1:8765/track-parcel` and confirm that the page appears in navigation and that its links work. Then open `http://127.0.0.1:8765/track-parcel.md` and confirm that the same prose is available and internal links point to Markdown pages. Press **Ctrl+C** to stop the server.
+
+If you use another publication or a language prefix, inspect the built `documents.json` for the resolved URLs. To preview edits continuously, use `npx --no-install shoalrun dev docs.config.yaml site-dist --port 8765`.
+
+Next, [organize your navigation](https://www.shoalrun.com/author/navigation.md) as the site grows.
+
+## Related reading
+
+### Next steps
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Adapt the starting template for your team's next pages.
+
+### Reference while working
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Check the scaffolded page's publication and metadata fields.
+
+### Related topics
+
+- [Troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md) — Find why a page is missing or a build fails.

package/agent-docs/author/agent-overview.md

@@ -0,0 +1,59 @@
+---
+id: guide.authoring-agent-overview
+title: Authoring tools for your coding agent
+summary: Understand project discovery, working-tree editing, snapshot
+  validation, and human review.
+type: explanation
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/agent-overview
+---
+
+# Authoring tools for your coding agent
+
+> 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 > Tools overview
+
+**Updated: 2026-10-27.**
+
+**Status: Experimental.**
+
+Shoalrun supplies documentation tools for existing coding agents. Your agent supplies its model, file editing, repository exploration, and execution permissions. Shoalrun supplies canonical writing guidance, templates, project discovery, and checks. The tools make no authoring provider calls.
+
+## Discover before editing
+
+Project discovery works without selecting a page. It lists pages, configured guidance, templates, navigation, relationships, and findings. Topic searches help your agent find candidates across the project. Source reads return bounded passages and file digests. Bundled documentation search and reads explain framework behavior; your project's guidance governs local conventions.
+
+## Edit and check
+
+The default is to edit ordinary working-tree files using your agent's file tools. A baseline records the current files, including earlier local changes. Snapshot validation captures those files and compiles a separate copy, so checking a draft does not rewrite the project. Results identify affected pages, findings, skipped checks, and retained artifacts. A freshness check tells you whether those results still apply after further edits.
+
+Existing checked plan/apply commands remain available for clients that need them. Their digest checks and application protections are preserved.
+
+## Review and release
+
+Compiler checks establish structural validity. They do not establish factual accuracy, clear writing, or a successful reader task. Review the diff, supporting evidence, and rendered documentation before using your project's release process.
+
+Local previews serve the exact captured build and show its freshness. Review reports list task scope, affected HTML/Markdown, findings, checks, and dependencies. The portable authoring skill guides this working-tree workflow. Independent author trials remain separate from these checks. Install the alpha CLI through [Getting started](https://www.shoalrun.com/start.md).
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Discover the project and check a working-tree edit. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Look up discovery, baseline, validation, and freshness commands. (Status: experimental.)
+
+- [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) — Give both people and models useful project writing guidance.
+
+### Go deeper
+
+- [How snapshot validation works](https://www.shoalrun.com/author/agent-workflow.md) — Understand capture coverage, checks, artifacts, and freshness. (Status: experimental.)

package/agent-docs/author/agent-workflow.md

@@ -0,0 +1,65 @@
+---
+id: guide.authoring-agent-workflow
+title: How snapshot validation works
+summary: Understand captured files, affected-page coverage, freshness, and
+  validation limits.
+type: explanation
+area: authoring
+subarea: authoring-agent-workflows
+audiences:
+  - authors
+subjectLifecycle: experimental
+canonical: /author/agent-workflow
+---
+
+# How snapshot validation works
+
+> 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 > Snapshot validation
+
+**Updated: 2026-10-26.**
+
+**Status: Experimental.**
+
+Snapshot validation checks a captured working tree. Your existing coding agent edits files; Shoalrun records and checks the resulting state.
+
+## Baselines and captures
+
+A baseline records source paths, modes, and digests before a task. It includes preexisting dirty and untracked files. Validation compares with that baseline, or uses explicit file and page selectors, to identify affected pages. Configuration, dependency, and deletion changes can expand coverage to all authored pages.
+
+The capture excludes generated output, dependencies, repository metadata, credentials, and private archives. Files must fit capture limits. Symlinks and absolute dependency references are rejected. Declared sibling dependencies can be captured within the project's parent directory. Capture races produce a failure rather than an apparently current result.
+
+## Checks and artifacts
+
+The compiler renders affected drafts in the captured project while preserving their publication access metadata. It checks metadata, identities, routes, components, navigation, relationships, and document links. Local HTML and Markdown links and configured API contracts are checked in the captured output. External URLs are not requested.
+
+Configured shell checks are skipped by default. With `--run-checks`, trusted project commands run inside the capture under the harness's permissions. This is not an operating-system sandbox; scripts can still access absolute paths or services. Model evaluators are skipped. Executable metadata and highlighting extensions are currently unavailable to snapshot validation.
+
+The result retains the captured project, built site, and JSON report. Remove the reported artifact directory when finished. Compiler success does not replace factual and editorial review.
+
+## Freshness and scope
+
+The report identifies the snapshot and source digests. `docs validation-status` compares current inputs with the report and returns stale when they differ. A report only applies to its recorded coverage and checks. Review skipped and unavailable checks before accepting a result.
+
+Snapshot validation does not apply edits, start a preview server, commit, or publish. Existing checked plan/apply clients retain their own review and freshness protections.
+
+## Matching previews and review reports
+
+`docs review` reads a retained validation report as JSON or Markdown. It associates changed-file operations and digests with the declared baseline and exposes findings, check status, affected routes, dependencies, and artifacts. Baselines retain digests rather than earlier contents, so your harness must retain the task diff. Evidence, semantic review, and author decisions are not inferred by these tools.
+
+`docs preview` makes a separate private copy of the validated site and starts a foreground loopback server. Every affected rendered page has HTML and Markdown URLs. HTML pages link to a browser review and display freshness; the original Markdown output remains unchanged. Replacing source files does not replace the preview's content. Replacing the report makes its pinned preview stale. Artifact changes prevent startup or stop page serving.
+
+After editing, validate again and restart from the new report. Ctrl-C or SIGTERM closes the server and removes only its serving copy. Retained validation artifacts have a separate lifecycle. The preview starts no source watcher or provider requests.
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Capture a baseline and validate a working-tree edit. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Find commands for discovery and snapshot validation. (Status: experimental.)

package/agent-docs/author/agents.md

@@ -0,0 +1,53 @@
+---
+id: guide.write-with-agents
+title: Write with agents
+summary: Use your existing coding agent with project guidance, templates, and
+  provider-free documentation tools.
+type: explanation
+area: authoring
+subarea: authoring-writing
+audiences:
+  - authors
+canonical: /author/agents
+---
+
+# Write with agents
+
+> 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 > Overview
+
+**Updated: 2026-10-26.**
+
+Use your existing coding agent to write and revise Shoalrun documentation. Start with the workflow that matches your task.
+
+## Choose a writing task
+
+Each guide below describes a different starting point:
+
+| Task                                              | Start here                                                                             |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Draft a new page                                  | [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md)               |
+| Check edits in your working tree                  | [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) |
+| Apply a plan from an existing checked-plan client | [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md)        |
+| Give your agent the bundled workflow instructions | [Use agent skills](https://www.shoalrun.com/contribute/agent-skills.md)                |
+
+[Authoring tools for your coding agent](https://www.shoalrun.com/author/agent-overview.md) explains project discovery, isolated validation, and the division of work between Shoalrun and your agent. No additional authoring provider key is required.
+
+## Review the result
+
+Review the diff, supporting sources, and built HTML and Markdown before accepting an edit. For coverage, skipped checks, and result freshness, follow [snapshot validation](https://www.shoalrun.com/author/agent-workflow.md). You decide when the result is ready to publish.
+
+## Shared writing guidance
+
+[Design templates](https://www.shoalrun.com/author/design-templates.md) and [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) explain how to give your agent useful project conventions. The [example writing guide](https://www.shoalrun.com/author/writing-style.md) is a starting point to adapt.
+
+## Related reading
+
+### Related topics
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Start with the agent authoring workflow. (Status: experimental.)
+
+- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) — Choose the authoring workflow that fits how you work.