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

package/agent-docs/configuration.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Related reading
+
+### Next steps
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+### Reference while working
+
+- [Frontmatter field reference](https://www.shoalrun.com/author/frontmatter-reference.md) — Inspect generated native and project-defined page fields.
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up individual settings and their defaults.
+
+### Related topics
+
+- [Example configs](https://www.shoalrun.com/config/examples.md) — Explore complete projects using composition, versions, and languages.

package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.md

@@ -0,0 +1,54 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Separate config inheritance from page metadata
+
+The loader first combines all configured `frontmatter` sections using the config merge rules. It then resolves each page using:
+
+```text
+frontmatter.defaults → page frontmatter → frontmatter.enforced
+```
+
+Mappings merge recursively and lists replace at this stage too. Config directives such as `$include`, `$concat`, and `$remove` are not page-frontmatter inheritance instructions.
+
+For example, `frontmatter.defaults.access.policy: public` lets a page set itself to `draft`. Setting `frontmatter.enforced.access.policy: public` overrides that draft choice. Use defaults when authors should control publication access.
+
+`frontmatter.fields` declares field types and requirements; it does not fill in missing values. A metadata provider is an additional advanced input to page resolution. See [page metadata](https://www.shoalrun.com/author/frontmatter.md) and the [configuration reference](https://www.shoalrun.com/config.md) before adding one.
+
+### Publication defaults serve a different purpose
+
+`publications.defaults` identifies default publication choices, including which channel and version receive an API's top-level source. It also supplies defaults for scaffolding and API selection. The default language supplies a page language when one is missing.
+
+Existing authored pages still need resolved channel and version fields. The starter provides these through `frontmatter.defaults`. Do not assume that changing `publications.defaults.version` also changes every page's metadata.
+
+`publications.enabled` selects combinations to build; it does not clone pages into those combinations. Navigation and `doc:` links resolve against the selected publication. See [versions and languages](https://www.shoalrun.com/publish/publications.md) for complete variant and route examples.

package/agent-docs/configuration.sections/share-defaults-through-extends.md

@@ -0,0 +1,121 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Share defaults through `extends`
+
+Use `extends` when several projects should inherit shared settings. Presets are ordinary YAML mappings and can extend other presets. Each file's `extends` list is processed in order; later presets override earlier ones, and the local file overrides them all.
+
+Create a shared directory beside the site:
+
+```sh
+mkdir -p ../shared
+```
+
+Create the following preset:
+
+```yaml title="../shared/base.yaml"
+schemaVersion: 1
+site:
+  title: Company handbook
+  customCss: ./brand.css
+  header:
+    links:
+      - { label: Support, href: "https://support.example.com" }
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+variables:
+  company: Acme
+  legacyLabel: Old handbook
+```
+
+Add its stylesheet:
+
+```css title="../shared/brand.css"
+.content h2 {
+  text-underline-offset: 0.2em;
+}
+```
+
+Now replace `docs.config.yaml` with this smaller entry file:
+
+```yaml title="docs.config.yaml"
+schemaVersion: 1
+extends: [../shared/base.yaml]
+site:
+  title: Parcel handbook
+navigation: { $include: ./config/nav.yaml }
+```
+
+The project inherits publications, page defaults, the stylesheet, variables, and header links. Its title replaces the shared title. The content directory remains `site/content/`, beside the entry config.
+
+Check the final values and build:
+
+```sh
+npx --no-install shoalrun config explain site.title docs.config.yaml
+npx --no-install shoalrun config explain site.header.links docs.config.yaml
+npx --no-install shoalrun config explain site.customCss docs.config.yaml
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
+```
+
+`site.title` comes from the local file, with the preset in its replacement history. `site.customCss` comes from `shared/base.yaml`, so `./brand.css` resolves beside that preset.
+
+### Predict a merge before you make it
+
+When a config extends another file, the overlay value determines how each inherited value changes.
+
+| Overlay value            | Result                                                                     |
+| ------------------------ | -------------------------------------------------------------------------- |
+| Mapping over a mapping   | Merge recursively by key. Unchanged keys survive.                          |
+| List                     | Replace the entire inherited list. Items do not merge by ID.               |
+| Scalar, including `null` | Replace the inherited value. The receiving setting must accept that value. |
+| `$concat`                | Append to an inherited list, or create a list if none exists.              |
+| `$remove`                | Remove inherited mapping keys or list entries by `id`.                     |
+
+This also applies after resolving an include. An included mapping can merge with an inherited mapping at the same location; inclusion itself supplies the overlay value.
+
+To layer a second preset, use `extends: [../shared/base.yaml, ../shared/brand.yaml]`. Only settings in `brand.yaml` override the base; the project's local settings still win.
+
+`extends` is recognized at the top level of each loaded YAML file, including files loaded through `$include`. Avoid using a top-level `extends` key as unrelated data in a fragment. An `extends` nested inside an ordinary mapping is not an inheritance instruction.

package/agent-docs/configuration.sections/start-with-one-working-file.md

@@ -0,0 +1,83 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Start with one working file
+
+The examples use a separate project so you can replace its configuration as you follow along. Install the same pinned package used in [getting started](https://www.shoalrun.com/start.md):
+
+```sh
+CONFIG_DEMO="$(mktemp -d)"
+mkdir "$CONFIG_DEMO/site"
+cd "$CONFIG_DEMO/site"
+npm init -y
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npx --no-install shoalrun init . --starter minimal
+```
+
+The starter has two pages and this basic configuration structure:
+
+```yaml title="docs.config.yaml"
+schemaVersion: 1
+site:
+  title: Acme handbook
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+navigation:
+  - id: welcome
+    doc: guide.welcome
+  - id: setup
+    label: Setup
+    items:
+      - id: install
+        doc: guide.install
+```
+
+Build once before reorganizing:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml dist
+```
+
+This produces the same two pages after each reorganization below. Keep `dist/` separate from content and configuration inputs.

package/agent-docs/configuration.sections/understand-the-three-stages.md

@@ -0,0 +1,59 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Understand the three stages
+
+Configuration takes effect in three stages:
+
+1. **Resolve configuration.** Read the entry file, load presets and includes, and merge them into one value. Track which file supplied each setting.
+2. **Resolve pages.** Apply configured frontmatter defaults, the page's own metadata, and enforced metadata. Validate the resulting page fields.
+3. **Build publications.** Select public pages for enabled channel/version/language combinations, resolve links and APIs, then produce HTML, Markdown, and discovery files.
+
+A preset changes configuration. A page default changes metadata. An enabled publication selects an edition to build. These mechanisms have separate rules; changing one does not automatically create pages or translations.
+
+### Find the section you need
+
+Start with the configuration sections that control the behavior you want to change.
+
+| Goal                                           | Configuration sections                              |
+| ---------------------------------------------- | --------------------------------------------------- |
+| Name the site and locate content               | `site`                                              |
+| Choose editions and routes                     | `publications`, `redirects`                         |
+| Organize pages and related reading             | `navigation`, `relationships`                       |
+| Define page metadata and authoring conventions | `frontmatter`, `metadata`, `templates`, `authoring` |
+| Reuse text and semantic content                | `variables`, `snippets`, `callouts`, `badges`       |
+| Register local OpenAPI sources and operations  | `apis`                                              |
+| Style the site and configure rendering         | `theme`, `outputs`                                  |
+| Configure reader views and project checks      | `readerFilters`, `audit`                            |
+
+Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate YAML keys and unknown top-level settings fail. Nested settings are not all checked for unknown keys, so verify spelling against the reference.

package/agent-docs/configuration.sections/understand-where-paths-point.md

@@ -0,0 +1,53 @@
+---
+id: guide.configuration
+title: Organize project configuration
+summary: Learn how Shoalrun resolves config files, layers presets, tracks path
+  origins, and applies page defaults before building publications.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /configuration
+---
+
+# Organize project configuration
+
+> 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) > Configure and customize > Configure your project
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/configuration.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse shared configuration and content for separately selected sites.
+
+`docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
+
+Use the [configuration reference](https://www.shoalrun.com/config.md) to look up individual fields. Use [example projects](https://www.shoalrun.com/config/examples.md) for complete configurations you can copy.
+
+## Understand where paths point
+
+Resolution records a source file for every configuration value. Relative paths often use that source rather than the entry file or your shell's current directory.
+
+| Path                                   | Base directory                                    |
+| -------------------------------------- | ------------------------------------------------- |
+| `extends` and `$include`               | The YAML file containing the directive            |
+| `site.contentDir`                      | The entry config's directory, even when inherited |
+| `site.customCss`, `site.favicon`       | The file supplying that path value                |
+| API `source.path`                      | The file supplying that path value                |
+| Snippet `file`, custom template `body` | The file supplying that path value                |
+| Page frontmatter `image`               | The page file's directory                         |
+
+In the running example, `site.customCss: ./brand.css` still finds `shared/brand.css` after the project overrides `site.title`. The two keys keep separate origins.
+
+Moving a path into `config/api.yaml` may require changing `./apis/service.yaml` to `../apis/service.yaml`. Inspect the exact path key with `config explain` after moving it. `config resolve` retains relative strings; it does not rewrite every file path into an absolute path.
+
+Some grouped settings use the origin of their containing block: custom search uses `outputs.html.search`, fonts use `theme.fonts`, and share images use `outputs.html.shareImages`. Overriding part of such a block can change its path base. Keep a block's relative paths and related overrides together, and inspect that block's source when debugging.
+
+CLI output arguments have their own meaning. In these examples, `dist` is relative to the working directory where you run `build`.

package/agent-docs/connect/mcp.md

@@ -0,0 +1,85 @@
+---
+id: guide.site-mcp
+title: Use this site's MCP
+summary: Connect your agent to Shoalrun's public documentation and ask it to
+  search, read pages, or fetch sections.
+type: how-to
+area: discovery
+subarea: discovery-mcp
+canonical: /connect/mcp
+---
+
+# Use this site's MCP
+
+> 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) > Search, chat, and agent access > MCP > Use this site's MCP
+
+**Updated: 2026-10-26.**
+
+Connect an MCP client to Shoalrun's live documentation at **`https://www.shoalrun.com/mcp`**. You need an agent application that supports remote HTTP MCP servers. No Shoalrun account, API key, custom header, or local installation is required.
+
+This endpoint reads Shoalrun's public documentation. To host an endpoint for your own documentation, use the separate [MCP hosting guide](https://www.shoalrun.com/publish/mcp.md).
+
+## Connect and ask a question
+
+The setting names vary by client. Use its remote MCP server connection settings:
+
+1. ### Add the documentation server
+
+   Create a remote server connection named `shoalrun-docs`. Choose HTTP or Streamable HTTP when your client asks for the transport. Enter this server URL:
+
+   ```text
+   https://www.shoalrun.com/mcp
+   ```
+
+   Leave authentication and custom headers unset. The URL is an MCP endpoint, not a web page; opening it directly in a browser may show a method error.
+
+2. ### Connect and discover the tools
+
+   Save the connection and enable it. Restart or reconnect the client if it does not refresh its tools automatically.
+
+   Look for `search_docs`, `get_page`, `get_outline`, and `get_section` under the connection. Your client may prefix their names with `shoalrun-docs`.
+
+3. ### Ask the agent to use the documentation
+
+   Try this request in your agent:
+
+   > Use the Shoalrun docs MCP to find how to configure analytics. Read the relevant documentation and give me the answer with source links.
+
+   Inspect the agent's tool activity. It should call `search_docs` and follow a returned read instruction. Answers and links alone do not prove that it used MCP.
+
+## What the tools do
+
+These tools only read published documentation. They cannot edit your files, change a project, or deploy a site.
+
+| Tool          | Use                                                  |
+| ------------- | ---------------------------------------------------- |
+| `search_docs` | Find relevant pages and suggested read instructions. |
+| `get_page`    | Read a Markdown page by its stable document ID.      |
+| `get_outline` | List a page's sections and their exact IDs.          |
+| `get_section` | Read one section by page ID and section ID.          |
+
+Use IDs returned by the tools rather than guessing them from a page title or URL. When a tool says the result does not fit its token budget, retry with the recommended `maxTokens` value. Do not treat an incomplete response as the complete documentation.
+
+## If the connection fails
+
+Check that your client supports remote HTTP MCP and that the URL ends in `/mcp`. A client that only launches local stdio commands cannot connect directly to this URL.
+
+If tools are missing after saving, reconnect the server or restart the client. If the client insists on an API key or OAuth login, check that you selected an unauthenticated remote connection. This endpoint does not provide an OAuth login.
+
+This site's MCP analytics measures tool usage, available harness/model labels, and fixed intent categories. It excludes raw queries, free-text intent, returned content, and request headers. Session grouping uses pseudonymous IDs. Hosting access logs are separate; see the [analytics safeguards](https://www.shoalrun.com/publish/mcp-analytics.md).
+
+No private test settings are needed to use the tools or supply supported metadata. Missing or unrecognized labels remain absent; the server does not guess them.
+
+## Related reading
+
+### Next steps
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Host the same documentation tools for your own project.
+
+### Related topics
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Understand the Markdown and discovery outputs behind the tools.

package/agent-docs/contribute/agent-skills.md

@@ -0,0 +1,72 @@
+---
+id: guide.agent-skills
+title: Use the bundled agent skills
+summary: Give an agent the setup and authoring workflows that ship with Shoalrun.
+type: how-to
+area: authoring
+subarea: authoring-agent-workflows
+canonical: /contribute/agent-skills
+---
+
+# Use the bundled agent skills
+
+> 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 > Use the bundled agent skills
+
+**Updated: 2026-10-26.**
+
+Give an agent a bundled skill when you want it to follow Shoalrun's setup, authoring, recipe, component, or walkthrough workflow. You need an agent that can read the skill file and run commands, plus a Shoalrun checkout or installed CLI.
+
+## Choose the skill for your task
+
+Use `shoalrun-setup` to start a site, `shoalrun-author` to add or revise pages, `shoalrun-recipes` to write a complete task recipe, or `shoalrun-walkthrough` to explain code in steps. Use `shoalrun-component-author` to create trusted custom components. The [skill reference](https://www.shoalrun.com/reference/agent-skills.md) lists their locations and behavior.
+
+## Make the instructions available
+
+Install the complete folder in your agent's skill directory using that agent's installation process. If it supports reading repository files directly, point it at the entry file instead. For a recipe task, use `framework/skills/shoalrun-recipes/SKILL.md`.
+
+In an installed package, skill folders live under `node_modules/@shoalrun/cli/skills/`. These files are portable instructions; the CLI does not install them into your agent automatically.
+
+Give your agent the installed `shoalrun-author/SKILL.md` path and the consumer project's `docs.config.yaml` path. Use the existing harness's file, terminal, and browser tools. No separate authoring service or model configuration is required.
+
+Ask the agent to read the skill before beginning. If it cannot discover installed skills, include the file path. If it cannot read files or run a CLI, follow the [page creation workflow](https://www.shoalrun.com/author/add-page.md) yourself.
+
+## Give the agent a bounded request
+
+Name the task, documentation project, relevant source files, and result to check. For example:
+
+```text
+Read framework/skills/shoalrun-recipes/SKILL.md and use its workflow.
+Write a complete recipe for previewing a Shoalrun documentation change.
+Work in this checkout's docs project. Include setup, commands, failure
+guidance, and a final success check. Reuse existing ingredients where
+instructions are shared. Preserve IDs and routes when updating pages,
+and set updated to today's date. Show the diff and verification results.
+```
+
+For a page edit, name the stable document ID and the facts that must stay unchanged. [Use a coding agent with Shoalrun](https://www.shoalrun.com/author/coding-agent.md) explains native editing and checks. [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) covers baselines, validation, and matching previews.
+
+## Check the result
+
+Ask the agent to show the changed files, rendered HTML and Markdown, and results from the project's checks. Read the diff and verify technical claims against the source or API contract. For an existing page, confirm its ID and route are preserved and `updated` records the edit date.
+
+If the agent lacks product guidance, have it run `shoalrun docs search` and `shoalrun docs read` using the [offline documentation commands](https://www.shoalrun.com/reference/agent-skills.md). If a build or audit fails, ask it to fix the reported issue and rerun the check. A passing check covers the implemented rules; review the task instructions and factual claims before committing or publishing.
+
+## Related reading
+
+### Reference while working
+
+- [Bundled agent skills](https://www.shoalrun.com/reference/agent-skills.md) — Look up shipped skill names, locations, workflows, and offline documentation behavior.
+
+### Related topics
+
+- [Frontmatter field reference](https://www.shoalrun.com/author/frontmatter-reference.md) — Point agents at the local inventory of page fields this project accepts.
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Let an agent run the same draft, check, and apply loop. (Status: experimental.)
+
+- [Getting started](https://www.shoalrun.com/start.md) — Give an agent the same setup and authoring workflow as a bundled skill.
+
+- [Use your coding agent](https://www.shoalrun.com/author/coding-agent.md) — Give your coding agent the bundled Shoalrun workflow instructions.

package/agent-docs/cookbooks/authoring.md

@@ -0,0 +1,72 @@
+---
+id: cookbook.authoring
+title: Authoring workflows
+summary: Choose a complete Shoalrun workflow for adding a guide, previewing a
+  change, or refreshing agent docs.
+type: cookbook
+area: authoring
+subarea: authoring-composition
+canonical: /cookbooks/authoring
+---
+
+# Authoring workflows
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Authoring workflows
+
+**Updated: 2026-10-27.**
+
+Choose the outcome you need for Shoalrun's own documentation. Each recipe includes setup, ordered work, handoffs, and an observable final check.
+
+## Choose your task
+
+What are you working on?. Choose one recipe.
+
+- [Add a new guide — Add a page to this documentation site](https://www.shoalrun.com/recipes/add-page.md)
+
+  Use when: A task needs a new page with navigation and current agent documentation.
+
+  You need: A topic, a stable page ID, and time to write and review the actual instructions.
+
+  You will have: A local public page, passing checks, and a refreshed agent bundle ready for review.
+
+- [Preview an existing change — Preview a documentation change locally](https://www.shoalrun.com/recipes/preview-page.md)
+
+  Use when: You want to inspect the current page in a browser and as Markdown.
+
+  You need: An edited checkout and a free local port.
+
+  You will have: A local HTTP preview with the changed page verified in both formats.
+
+- [Refresh the agent bundle — Refresh Shoalrun's bundled agent docs](https://www.shoalrun.com/recipes/refresh-agent-docs.md)
+
+  Use when: Authored documentation changed and the CLI needs the updated offline content.
+
+  You need: Completed source edits and the stable ID of a page to check.
+
+  You will have: Current CLI search and page lookup, a reviewed generated diff, and passing audits.
+
+Adding a guide includes manual writing and review. The recipe then builds and audits the page and refreshes the agent bundle. Previewing an existing change starts a local server; refreshing the bundle verifies what the CLI can search and read. Choose one task at a time so shared setup runs once within that recipe.
+
+Use **Link to this path** to share the selected instructions, **Download Markdown** to work from a saved copy, or **Print this path** for a checklist. These workflows prepare local changes for review; they do not commit or deploy them.
+
+## HTML, Markdown, and agents
+
+In HTML, the chooser loads and displays the selected published recipes. Without JavaScript, readers can follow the recipe links. This page's Markdown lists the choices and their destinations; it does not contain the selected recipes' full instructions. Give an agent a recipe's Markdown page or the chooser's **Download Markdown** file to follow the complete task.
+
+## Related reading
+
+### Go deeper
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — See how these workflows are composed from checked-in ingredient files.
+
+### Related topics
+
+- [Add a page to this documentation site](https://www.shoalrun.com/recipes/add-page.md) — Choose a related Shoalrun workflow.
+
+- [Preview a documentation change locally](https://www.shoalrun.com/recipes/preview-page.md) — Choose a related Shoalrun workflow.
+
+- [Refresh Shoalrun's bundled agent docs](https://www.shoalrun.com/recipes/refresh-agent-docs.md) — Choose a related Shoalrun workflow.