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

package/agent-docs/author/recipe-drafts.sections/2-list-the-steps-for-one-complete-goal.md

@@ -0,0 +1,60 @@
+---
+id: guide.recipe-drafts
+title: Compose and maintain recipes
+summary: Use Shoalrun ingredient files and a recipe spec to produce a complete,
+  reviewable task page.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipe-drafts
+---
+
+# Compose and maintain recipes
+
+> 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 > Recipes and cookbooks > Compose and maintain recipes
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipe-drafts.md)
+
+Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
+
+If you only need one task page, you can write a `type: recipe` page directly. Ingredients and the draft assembler are optional. Start with [how the pieces fit](https://www.shoalrun.com/author/recipes.md) for the distinction between authoring a recipe and choosing one in a cookbook.
+
+The built-in `recipe`, `ingredient`, and `cookbook` scaffolds are available in any project without registering templates. For example:
+
+```sh
+shoalrun scaffold ingredient -n content/lookup-parcel.mdx
+shoalrun scaffold recipe -n content/track-parcel.mdx
+```
+
+See [templates](https://www.shoalrun.com/author/templates.md) for their outlines and project overrides.
+
+## 2. List the steps for one complete goal
+
+The recipe spec chooses the ingredients and their order. A shortened version of `docs/recipe-specs/audit-docs.yaml` is:
+
+```yaml title="docs/recipe-specs/audit-docs.yaml"
+schemaVersion: 1
+id: recipe.audit-docs
+title: Build and audit this documentation site
+summary: Build current documentation and run the configured audits.
+slug: /recipes/audit-docs
+inputs:
+  repositoryCheckout: A local Shoalrun checkout with dependencies installed.
+  DOC_ID: Set the stable ID of the page you want to check.
+ingredients:
+  - ../content/ingredient-compile-framework.mdx
+  - ../content/ingredient-build-site.mdx
+  - ../content/ingredient-inspect-build.mdx
+  - ../content/ingredient-audit-site.mdx
+outcome: The build succeeds, both page formats exist, and configured audits pass.
+```
+
+Paths are relative to this spec file. The initial `inputs` are available before the first ingredient. The compile ingredient produces `frameworkCli`; the build ingredient requires it and produces `builtSite`; the artifact-check ingredient requires that build and `DOC_ID`.
+
+The assembler rejects a missing input, repeated output name, repeated ingredient ID, or publication mismatch. It does not choose an order for you or verify that an output has the described value. The `outcome` is the final check for the complete recipe; omitting it leaves a prompt for the author to complete.

package/agent-docs/author/recipe-drafts.sections/3-generate-a-draft-and-review-it.md

@@ -0,0 +1,55 @@
+---
+id: guide.recipe-drafts
+title: Compose and maintain recipes
+summary: Use Shoalrun ingredient files and a recipe spec to produce a complete,
+  reviewable task page.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipe-drafts
+---
+
+# Compose and maintain recipes
+
+> 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 > Recipes and cookbooks > Compose and maintain recipes
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipe-drafts.md)
+
+Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
+
+If you only need one task page, you can write a `type: recipe` page directly. Ingredients and the draft assembler are optional. Start with [how the pieces fit](https://www.shoalrun.com/author/recipes.md) for the distinction between authoring a recipe and choosing one in a cookbook.
+
+The built-in `recipe`, `ingredient`, and `cookbook` scaffolds are available in any project without registering templates. For example:
+
+```sh
+shoalrun scaffold ingredient -n content/lookup-parcel.mdx
+shoalrun scaffold recipe -n content/track-parcel.mdx
+```
+
+See [templates](https://www.shoalrun.com/author/templates.md) for their outlines and project overrides.
+
+## 3. Generate a draft and review it
+
+From this repository's root, compile the CLI and preview the draft using the existing spec:
+
+```sh
+npm --prefix framework run build
+node framework/dist/cli.js recipe draft \
+  --config docs/docs.config.yaml \
+  --spec docs/recipe-specs/audit-docs.yaml \
+  --out /tmp/shoalrun-audit-recipe.mdx --check
+```
+
+`--check` prints the proposed content and reports `would-create`, `unchanged`, or `would-change`. Remove `--check` to create the file. The write command refuses to overwrite an existing file; choose a new output path for a new candidate.
+
+The output is a complete MDX **draft** with setup, ordered ingredient bodies, handoff descriptions, per-step checks, and the final outcome. It also contains a draft notice and a review checklist. No model or API is called, and none of the recipe's commands are executed during generation.
+
+Read the complete draft and follow its instructions in a suitable environment. Check that the handoffs describe real outputs, that failures have useful guidance, and that the final check proves the stated goal. Remove the draft notice and review checklist once that work is complete.
+
+For your own project, place the reviewed recipe in its content directory, change `access.policy` to `public`, and build the site. The recipe then works as a standalone page. A [cookbook](https://www.shoalrun.com/author/cookbooks.md) can offer it as a choice by its document ID.

package/agent-docs/author/recipe-drafts.sections/4-maintain-shoalrun-s-published-recipe-snapshots.md

@@ -0,0 +1,66 @@
+---
+id: guide.recipe-drafts
+title: Compose and maintain recipes
+summary: Use Shoalrun ingredient files and a recipe spec to produce a complete,
+  reviewable task page.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipe-drafts
+---
+
+# Compose and maintain recipes
+
+> 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 > Recipes and cookbooks > Compose and maintain recipes
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipe-drafts.md)
+
+Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
+
+If you only need one task page, you can write a `type: recipe` page directly. Ingredients and the draft assembler are optional. Start with [how the pieces fit](https://www.shoalrun.com/author/recipes.md) for the distinction between authoring a recipe and choosing one in a cookbook.
+
+The built-in `recipe`, `ingredient`, and `cookbook` scaffolds are available in any project without registering templates. For example:
+
+```sh
+shoalrun scaffold ingredient -n content/lookup-parcel.mdx
+shoalrun scaffold recipe -n content/track-parcel.mdx
+```
+
+See [templates](https://www.shoalrun.com/author/templates.md) for their outlines and project overrides.
+
+## 4. Maintain Shoalrun's published recipe snapshots
+
+This repository maintains five recipes from specs under `docs/recipe-specs/`. Their published pages are `docs/content/recipe-*.mdx`. The repository maintenance script regenerates these existing pages while preserving their publication IDs, routes, and card metadata.
+
+| Change you want                                   | File to edit                                            |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| Change a command or explanation shared by recipes | The corresponding `docs/content/ingredient-*.mdx` file. |
+| Add, remove, or reorder a recipe step             | That recipe's YAML spec under `docs/recipe-specs/`.     |
+| Change a recipe's starting inputs or final goal   | The spec's `inputs` or `outcome`.                       |
+| Change the choices or labels shown in a cookbook  | `docs/config/cookbooks.yaml`.                           |
+| Change a cookbook's introduction                  | Its `docs/content/cookbook-*.mdx` page.                 |
+
+After reviewing ingredient or spec changes, run:
+
+```sh
+node framework/scripts/build-shoalrun-recipes.mjs --write
+git diff -- docs/content/recipe-*.mdx
+npm run docs:build
+npm run agent-docs:build
+```
+
+The script replaces the five recipe bodies with their compositions and related-reading sections. Direct edits to those generated bodies are replaced on regeneration. Review the diff before treating the recipes as current.
+
+To check freshness without changing files:
+
+```sh
+node framework/scripts/build-shoalrun-recipes.mjs --check
+```
+
+The test suite runs that check too. General `recipe draft` output has no automatic synchronization: it is an editable snapshot. The maintenance script above is this repository's explicit workflow for keeping its published recipes in sync.

package/agent-docs/author/recipe-drafts.sections/related-reading.md

@@ -0,0 +1,45 @@
+---
+id: guide.recipe-drafts
+title: Compose and maintain recipes
+summary: Use Shoalrun ingredient files and a recipe spec to produce a complete,
+  reviewable task page.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipe-drafts
+---
+
+# Compose and maintain recipes
+
+> 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 > Recipes and cookbooks > Compose and maintain recipes
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipe-drafts.md)
+
+Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
+
+If you only need one task page, you can write a `type: recipe` page directly. Ingredients and the draft assembler are optional. Start with [how the pieces fit](https://www.shoalrun.com/author/recipes.md) for the distinction between authoring a recipe and choosing one in a cookbook.
+
+The built-in `recipe`, `ingredient`, and `cookbook` scaffolds are available in any project without registering templates. For example:
+
+```sh
+shoalrun scaffold ingredient -n content/lookup-parcel.mdx
+shoalrun scaffold recipe -n content/track-parcel.mdx
+```
+
+See [templates](https://www.shoalrun.com/author/templates.md) for their outlines and project overrides.
+
+## Related reading
+
+### Related topics
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md) — Configure the stable operation ID and review the OpenAPI source used by an API ingredient draft.
+
+- [CookbookChooser](https://www.shoalrun.com/author/components/cookbook-chooser.md) — Let readers assemble reviewed recipes into a path in a cookbook.
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Use a project template when an API example is not the right starting point.

package/agent-docs/author/recipe-drafts.sections/start-an-ingredient-from-an-api-example.md

@@ -0,0 +1,50 @@
+---
+id: guide.recipe-drafts
+title: Compose and maintain recipes
+summary: Use Shoalrun ingredient files and a recipe spec to produce a complete,
+  reviewable task page.
+type: how-to
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipe-drafts
+---
+
+# Compose and maintain recipes
+
+> 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 > Recipes and cookbooks > Compose and maintain recipes
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipe-drafts.md)
+
+Use ingredients when several recipes share instructions you want to maintain in one place. This guide follows Shoalrun's **Build and audit this documentation site** recipe from its source files to its published page.
+
+If you only need one task page, you can write a `type: recipe` page directly. Ingredients and the draft assembler are optional. Start with [how the pieces fit](https://www.shoalrun.com/author/recipes.md) for the distinction between authoring a recipe and choosing one in a cookbook.
+
+The built-in `recipe`, `ingredient`, and `cookbook` scaffolds are available in any project without registering templates. For example:
+
+```sh
+shoalrun scaffold ingredient -n content/lookup-parcel.mdx
+shoalrun scaffold recipe -n content/track-parcel.mdx
+```
+
+See [templates](https://www.shoalrun.com/author/templates.md) for their outlines and project overrides.
+
+## Start an ingredient from an API example
+
+`ingredient draft` creates starting material from one configured outgoing API operation and a named request example. For the included notification fixture:
+
+```sh
+node framework/dist/cli.js ingredient draft \
+  --config framework/example-configs/notifications/docs.config.yaml \
+  --spec framework/example-configs/notifications/ingredient-specs/queue-welcome-email.yaml \
+  --out /tmp/shoalrun-email-ingredient.mdx --check
+```
+
+Its YAML spec supplies `schemaVersion: 1`, the page's `id`, `title`, `summary`, and `slug`, plus `operation` and `requestExample`. An optional `workflow` mapping is copied into frontmatter. The command copies the generated cURL request and first inline 2xx response example, links the configured reference, and records a source digest. It supports the default publication and outgoing requests with generated cURL. Webhook receiver flows need authored instructions.
+
+The generated file still needs setup, failure guidance, and a verified success check. An example response is not evidence that a live request worked. The [email cookbook](https://www.shoalrun.com/cookbooks/welcome-email.md) shows a completed workflow against the local simulator.

package/agent-docs/author/recipes.md

@@ -0,0 +1,127 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## Use recipes for task-oriented how-tos
+
+Use the built-in `how-to` template for a task page, or `recipe` when the page should participate in Shoalrun's recipe and cookbook features. Both take a reader from a known starting state to a verifiable result. Give it prerequisites, ordered actions, failure guidance, and a final success check. A recipe can be a short, directly authored page; it does not require ingredients, a YAML composition spec, or a cookbook.
+
+Use the built-in `explanation` template to explain a concept or help readers understand a system. Use a reference page to describe fields, commands, or API behavior. Existing how-tos can keep their current type, stable ID, and route until a deliberate content revision calls for a change. A page's type does not prove its instructions have been tested.
+
+| Writing task                                             | Starting format                          |
+| -------------------------------------------------------- | ---------------------------------------- |
+| Build this site and verify its output                    | A recipe.                                |
+| Explain how the compiler produces HTML and Markdown      | An explanation page.                     |
+| Look up CLI flags or configuration fields                | A reference page.                        |
+| Reuse the same build instructions across several recipes | An ingredient included by those recipes. |
+| Help a reader choose build, audit, or preview            | A cookbook pointing to complete recipes. |
+
+The bundled `shoalrun-recipes` skill follows these choices. See [use the agent skills](https://www.shoalrun.com/contribute/agent-skills.md) for a copyable authoring request.
+
+## One example from Shoalrun
+
+Suppose you need two sets of instructions:
+
+- **Build and check a page.** Compile the CLI, build the docs, and check the HTML and Markdown files.
+- **Build and audit the site.** Do those same three steps, then run the project audits.
+
+Both recipes need the same build instructions. We keep those instructions in ingredient files and use them in both recipe specs:
+
+**Two recipes reuse the same source instructions**
+
+The compile, build, and artifact-check ingredients are used in both recipes. The build-and-audit recipe also includes the audit ingredient. These arrows describe authoring reuse; they do not run commands.
+
+[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-62592d6197a75626c36a-light.svg)
+
+```mermaid
+flowchart TD
+ shared["Shared ingredients<br/>Compile CLI → Build docs → Check artifacts"]
+ audit["Audit ingredient<br/>Run project audits"]
+ build_recipe["Recipe page<br/>Build and check a page"]
+ audit_recipe["Recipe page<br/>Build and audit the site"]
+ shared -->|"copied into draft"| build_recipe
+ shared -->|"copied into draft"| audit_recipe
+ audit -->|"added to draft"| audit_recipe
+```
+
+The [Site workflows cookbook](https://www.shoalrun.com/cookbooks/site-workflows.md) offers these two finished recipes. Choosing the audit path displays all four steps. The reader does not have to find or assemble the ingredients.
+
+## What each file does
+
+These are real files in this checkout:
+
+| File                                       | What the author puts there                                                              | What it contributes                                                                   |
+| ------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `docs/content/ingredient-build-site.mdx`   | The build command, explanation, required inputs, expected outputs, and a success check. | Reusable source instructions for one step.                                            |
+| `docs/recipe-specs/audit-docs.yaml`        | An ordered list of ingredient files, starting inputs, and the final goal.               | Instructions to the recipe assembler about which steps to copy and how to order them. |
+| `docs/content/recipe-audit-docs.mdx`       | The assembled, reviewed recipe.                                                         | The complete page a person or agent follows.                                          |
+| `docs/config/cookbooks.yaml`               | Choice labels and the published recipe ID for each option.                              | The chooser's options and descriptions.                                               |
+| `docs/content/cookbook-site-workflows.mdx` | An introduction and `<CookbookChooser id="site-checks" />`.                             | The page where readers choose their task.                                             |
+
+## What happens, and when
+
+1. **An author prepares ingredients and a recipe spec.** Ingredients contain prose and commands. Their optional `workflow` metadata names the values or artifacts each step needs and produces.
+2. **The author runs `recipe draft`.** The assembler copies ingredient bodies into a new MDX draft, combines identical prerequisites, and writes the declared handoffs and checks. It checks that each named input is available from setup or an earlier step.
+3. **The author reviews and tests the recipe, then publishes it.** A normal site build turns the recipe page into HTML and Markdown. It also builds the cookbook page and its choice list.
+4. **A reader chooses a recipe in the cookbook.** The browser fetches the already-published recipe and displays its instructions. The reader or their agent runs the commands and checks the results.
+
+**Selecting a cookbook option does not assemble ingredients or run a task.** It loads finished recipe content. The cookbook's own introduction and choice descriptions come from its page and configuration.
+
+## What changing an ingredient updates
+
+A generated recipe is a snapshot of its ingredients. Editing an ingredient does not immediately change a published recipe. Regenerate the affected recipe, review the changes, and rebuild the site.
+
+Shoalrun's five repository recipes have a maintenance script that updates their snapshots together and a test that detects stale snapshots. The [composition guide](https://www.shoalrun.com/author/recipe-drafts.md) shows that workflow. Other projects can keep generated recipes as drafts and edit them independently.
+
+For example, if the docs build command changes, update the build ingredient once and regenerate the recipes that use it. The cookbook continues pointing to the same published recipe IDs.
+
+## How agents use this
+
+Give an agent the source material that matches its task and the outcome you want.
+
+| Agent task                      | What to give it                                                 | What these files help it do                                                             |
+| ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Write or maintain documentation | Ingredient source files, the recipe spec, and project evidence. | Reuse instructions and prepare consistent recipe drafts.                                |
+| Complete a task                 | The finished recipe's Markdown.                                 | Follow the commands, pass values between steps, and evaluate the stated success checks. |
+| Choose a task                   | The cookbook's Markdown.                                        | Read each option's purpose and follow the appropriate recipe link.                      |
+
+The recipe assembler does not call a model. It does not execute commands, validate data types, or prove that a task succeeded. A declared output such as `builtSite` is a name and description; it does not create a directory or a shell variable. The recipe's commands produce the actual result.
+
+A recipe's **Read as Markdown** link contains its complete published instructions. A cookbook's Markdown lists the choices and recipe links. The browser selection has no separate published Markdown endpoint. **Download Markdown** saves the selected recipes' instructions in a file you can give to an agent.
+
+## Try a complete workflow
+
+Use the [Authoring workflows cookbook](https://www.shoalrun.com/cookbooks/authoring.md) to add a guide, preview a change, or refresh the agent bundle in this repository. Each choice is a complete recipe with its own setup and final check.
+
+The [email example](https://www.shoalrun.com/cookbooks/welcome-email.md) demonstrates passing a returned message ID into a delivery check. It runs against a local simulator and sends no email.
+
+## Related reading
+
+### Next steps
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.

package/agent-docs/author/recipes.sections/how-agents-use-this.md

@@ -0,0 +1,50 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## How agents use this
+
+Give an agent the source material that matches its task and the outcome you want.
+
+| Agent task                      | What to give it                                                 | What these files help it do                                                             |
+| ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Write or maintain documentation | Ingredient source files, the recipe spec, and project evidence. | Reuse instructions and prepare consistent recipe drafts.                                |
+| Complete a task                 | The finished recipe's Markdown.                                 | Follow the commands, pass values between steps, and evaluate the stated success checks. |
+| Choose a task                   | The cookbook's Markdown.                                        | Read each option's purpose and follow the appropriate recipe link.                      |
+
+The recipe assembler does not call a model. It does not execute commands, validate data types, or prove that a task succeeded. A declared output such as `builtSite` is a name and description; it does not create a directory or a shell variable. The recipe's commands produce the actual result.
+
+A recipe's **Read as Markdown** link contains its complete published instructions. A cookbook's Markdown lists the choices and recipe links. The browser selection has no separate published Markdown endpoint. **Download Markdown** saves the selected recipes' instructions in a file you can give to an agent.

package/agent-docs/author/recipes.sections/one-example-from-shoalrun.md

@@ -0,0 +1,64 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## One example from Shoalrun
+
+Suppose you need two sets of instructions:
+
+- **Build and check a page.** Compile the CLI, build the docs, and check the HTML and Markdown files.
+- **Build and audit the site.** Do those same three steps, then run the project audits.
+
+Both recipes need the same build instructions. We keep those instructions in ingredient files and use them in both recipe specs:
+
+**Two recipes reuse the same source instructions**
+
+The compile, build, and artifact-check ingredients are used in both recipes. The build-and-audit recipe also includes the audit ingredient. These arrows describe authoring reuse; they do not run commands.
+
+[View Two recipes reuse the same source instructions diagram](https://www.shoalrun.com/assets/diagrams/mermaid-62592d6197a75626c36a-light.svg)
+
+```mermaid
+flowchart TD
+ shared["Shared ingredients<br/>Compile CLI → Build docs → Check artifacts"]
+ audit["Audit ingredient<br/>Run project audits"]
+ build_recipe["Recipe page<br/>Build and check a page"]
+ audit_recipe["Recipe page<br/>Build and audit the site"]
+ shared -->|"copied into draft"| build_recipe
+ shared -->|"copied into draft"| audit_recipe
+ audit -->|"added to draft"| audit_recipe
+```
+
+The [Site workflows cookbook](https://www.shoalrun.com/cookbooks/site-workflows.md) offers these two finished recipes. Choosing the audit path displays all four steps. The reader does not have to find or assemble the ingredients.

package/agent-docs/author/recipes.sections/related-reading.md

@@ -0,0 +1,36 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## Related reading
+
+### Next steps
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.

package/agent-docs/author/recipes.sections/try-a-complete-workflow.md

@@ -0,0 +1,42 @@
+---
+id: guide.recipes-overview
+title: Understand ingredients, recipes, and cookbooks
+summary: See how reusable source instructions become complete recipe pages that
+  a cookbook helps readers choose.
+type: explanation
+area: authoring
+subarea: authoring-composition
+canonical: /author/recipes
+---
+
+# Understand ingredients, recipes, and cookbooks
+
+> 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 > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/author/recipes.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) — Follow the actual ingredient files and spec that produce Shoalrun's audit recipe.
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Use complete workflows for Shoalrun documentation work.
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Try an acceptance check or follow a message ID through delivery and failure handling.
+
+A **recipe** is the complete page someone follows to finish a task. An **ingredient** is a reusable piece of source documentation used to write that page. A **cookbook** is a page that helps readers choose a recipe.
+
+Readers can open a recipe directly. Ingredients help authors maintain instructions shared by several recipes. A cookbook becomes useful when readers need help choosing which complete task to follow.
+
+## Try a complete workflow
+
+Use the [Authoring workflows cookbook](https://www.shoalrun.com/cookbooks/authoring.md) to add a guide, preview a change, or refresh the agent bundle in this repository. Each choice is a complete recipe with its own setup and final check.
+
+The [email example](https://www.shoalrun.com/cookbooks/welcome-email.md) demonstrates passing a returned message ID into a delivery check. It runs against a local simulator and sends no email.