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

package/agent-docs/author/reader-views.sections/configure-the-choices.md

@@ -0,0 +1,65 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Configure the choices
+
+Define the available reader choices once in `readerFilters.facets` in `docs.config.yaml`. The facet names and choices are yours; Shoalrun has no fixed list of reader types. Each facet and choice has a stable lowercase ID and a label for readers. Pages and sections refer to these IDs, and unknown IDs fail the build. `typeDefaults` is optional; it is useful when generated API references should start in the Developer view without marking every operation separately.
+
+```yaml title="docs.config.yaml"
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options:
+        ui: Use the UI
+        developer: Build with the API
+    product:
+      label: Product
+      options:
+        payments: Payments
+        reports: Reports
+    area:
+      label: Area
+      options:
+        reporting: Reporting
+        setup: Setup
+    subarea:
+      label: Subarea
+      options:
+        settlements: Settlements
+        exports: Exports
+  typeDefaults:
+    api-reference:
+      audience: [developer]
+  controls:
+    sidebar: false
+    header: { facet: audience, display: select, label: Reader }
+```
+
+Nothing is selected by default, so every page and section is visible. Readers can select more than one choice within a facet: a page marked for either selected choice appears. Different facets combine: a page marked `audience: [ui]` and `product: [payments]` appears when both selections match. A page with no mark for a facet is shared across that facet.

package/agent-docs/author/reader-views.sections/connect-your-own-control.md

@@ -0,0 +1,59 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Connect your own control
+
+Set `readerFilters.module` to a local `.js` or `.mjs` file. The build copies that file into the site and calls its `mountReaderViews(api)` export after the reader view is ready. This is useful for a custom header, a host application, or a login-based starting view.
+
+```yaml title="docs.config.yaml"
+readerFilters:
+  facets:
+    audience:
+      label: Reader
+      options: { ui: Use the UI, developer: Build with the API }
+  controls: { sidebar: false }
+  module: ./reader-view.js
+```
+
+```js title="reader-view.js"
+export function mountReaderViews(api) {
+  const picker = document.querySelector('#my-reader-picker');
+  if (!picker) return;
+  picker.addEventListener('change', () => {
+    api.setSelection({ audience: picker.value ? [picker.value] : [] }, { merge: true });
+  });
+  api.subscribe(selection => { picker.value = selection.audience?.[0] ?? ''; });
+}
+```
+
+The API provides `facets`, `getSelection()`, `setSelection(selection, { merge? })`, `reset()`, `subscribe(listener)`, and `shareUrl()` for the site view. For the current page it provides `getPageSelection()`, `setPageSelection(selection, { merge? })`, `resetPage()`, `inheritSiteView()`, and `subscribePage(listener)`. `setSelection` and `setPageSelection` validate facet and choice IDs; they replace their respective selection unless `merge: true` is supplied. Subscribers are called immediately and return an unsubscribe function. The API is also available as `window.shoalrunReaderViews`; the page dispatches `reader-views-ready`, `reader-view-change`, and `reader-page-view-change` events. The module is copied as one file, so bundle relative imports before publishing it.
+
+**Copy view link** includes the current choice in the URL; a shared URL overrides the recipient's saved choice. A host can use the API to supply a reader's initial view, but reader filters are presentation controls. Protect private content at the host or build layer.
+
+The built-in browser search provider excludes pages and section text outside the current site view. A custom search provider receives `context.readerSelection` and must apply the same rules if it wants matching behavior. Reader views are a reading aid, not access control. Use `access.policy` to keep a page out of a public build.

package/agent-docs/author/reader-views.sections/how-it-works-for-agents.md

@@ -0,0 +1,41 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## How it works for agents
+
+Reader views change the interactive HTML. They do not create separate agent publications or a personalized agent navigation tree. An agent can discover and read every **published** page regardless of a browser reader's saved choice or a shared `view` or `pageView` URL parameter. Draft and access-controlled source pages still follow the normal publication rules.
+
+| Agent-facing output   | Reader-view behavior                                                                                                                                                                                                                                                                                                         |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Markdown twin (`.md`) | Includes shared content and every `ReaderSection`, even sections hidden in HTML. Each marked section starts with a readable label such as `**For Reader: UI reader.**`. `<ReaderFilter />` controls are omitted. `ReaderChoice` becomes a link to the interactive HTML page with its `view` or `pageView` choice in the URL. |
+| `/llms.txt`           | Lists every published Markdown page. A selected browser view does not remove entries.                                                                                                                                                                                                                                        |
+| `/documents.json`     | Lists every published page. `readerFacets` defines the configured choices; each document's `readerFilters` contains its resolved page marks. An empty map means the page is shared. Optional `product`, `area`, and `subarea` categories also appear when set.                                                               |
+| `/search-index.json`  | Retains a search record for every published page, with page marks in `readerFilters` and indexed section text in `readerSegments`. The built-in **browser** search applies the site-wide choice when displaying results.                                                                                                     |
+
+For example, [this guide's Markdown twin](https://www.shoalrun.com/author/reader-views.md) contains both the UI and Developer example paragraphs with their reader labels. Choosing a page-only view above leaves those paragraphs in the twin. The page's Markdown YAML header includes reader marks only when `outputs.markdown.metadata` explicitly selects those frontmatter fields. The resolved marks are always available in `/documents.json` when reader views are configured. Reader views help people find relevant content; use `access.policy` to decide whether a page is published at all.

package/agent-docs/author/reader-views.sections/mark-pages.md

@@ -0,0 +1,49 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Mark pages
+
+Use the existing `audiences` field for the `audience` facet. `product`, `area`, and `subarea` can each supply a single choice for a same-named facet. Use `readerFilters` for other facets or when a page needs multiple choices in one facet. All of these fields work with frontmatter defaults and enforced values.
+
+```yaml title="content/payments-dashboard.mdx"
+---
+id: guide.payments-dashboard
+title: Review payments in the dashboard
+type: guide
+slug: /payments/dashboard
+audiences: [ui]
+product: payments
+area: reporting
+subarea: settlements
+---
+```
+
+When a facet is configured, `audiences` and same-named category values must use its choice IDs. You can instead use `readerFilters.audience` or `readerFilters.product`, but do not put both forms for the same facet on one page. An explicit page value overrides a `typeDefaults` value for that facet. Categories without matching configured facets remain taxonomy metadata only. Pages with no marks remain visible in every view.
+
+The page marks control navigation, search, and cards that point to the page. They do not change its URL. A direct link to a page outside the current view opens the page in full. A notice offers actions to switch view or show all content.

package/agent-docs/author/reader-views.sections/mark-sections-and-add-an-entry-choice.md

@@ -0,0 +1,49 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Mark sections and add an entry choice
+
+Use `ReaderSection` for content that belongs to a narrower view within an otherwise shared page. Content outside these blocks stays visible to everyone. Sections can contain Markdown and supported MDX components, but reader sections cannot be nested.
+
+```mdx title="content/get-started.mdx"
+<ReaderChoice audience="ui" label="Use the dashboard" />
+<ReaderChoice audience="developer" label="Build with the API" />
+
+Everyone needs an account before starting.
+
+<ReaderSection audience="ui">
+Open **Settings** in the dashboard.
+</ReaderSection>
+
+<ReaderSection audience="developer" product="payments">
+Create an API token, then run the payment CLI.
+</ReaderSection>
+```
+
+`ReaderChoice` changes only the facets named on the button. It can set several facets at once, and comma-separated values select more than one choice within a facet.

package/agent-docs/author/reader-views.sections/place-filter-controls.md

@@ -0,0 +1,43 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Place filter controls
+
+The site config above puts a compact reader dropdown in the header and removes the sidebar control. `controls.sidebar` defaults to `true`; `controls.header` is optional. Both can be present, and they stay in sync. Each header control accepts `facet`, `display: select` or `checks`, and an optional `label`. Omit `facet` to show every configured facet.
+
+Authors can place the same controls inside a page:
+
+```mdx
+<ReaderFilter facet="audience" display="select" label="I use…" />
+<ReaderFilter facet="product" display="checks" />
+```
+
+`select` allows one choice per facet and includes **All**. `checks` allows multiple choices and includes **Show all** and **Copy view link**. `<ReaderFilter />` controls every facet. The component is interactive in HTML and omitted from the Markdown twin; marked content and `ReaderChoice` links remain in Markdown.
+
+Set `scope="page"` on an in-page `ReaderChoice` or `ReaderFilter` to control only marked sections and cards on the current page. The site-wide choice still controls navigation and search. Page-only choices use the `pageView` URL parameter for sharing; they do not enter local storage. With no page-only choice, the page follows the site view. A page-scoped multi-select includes **Follow site view** to return to that state. The default scope is `site`.

package/agent-docs/author/reader-views.sections/try-the-controls-here.md

@@ -0,0 +1,64 @@
+---
+id: guide.reader-filters
+title: Reader views
+summary: Reader-view configuration, page and section marks, controls, and
+  agent-facing behavior.
+type: reference
+area: discovery
+subarea: discovery-reader-views
+canonical: /author/reader-views
+---
+
+# Reader views
+
+> 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 > Reader views
+
+**Updated: 2026-10-25.**
+
+Parent page: [Full Markdown page](/author/reader-views.md)
+
+A reader view changes which pages appear in navigation and search. It also controls document cards and marked sections within pages. The site still publishes one URL for each page. A first-time visitor sees all content; a choice is saved in the browser and added to the URL so it can be shared.
+
+Reader views are visibility controls, not access controls. All published page and section content remains available in site files and Markdown twins. Use `access.policy` to exclude a page from a public build, and host-level authorization to protect private content.
+
+To build separate sites from the same source using these facets, use [build-time page selection](https://www.shoalrun.com/publish/single-source-sites.md) with `site.contentFilter`. That selector excludes unmatched pages from the output. A browser reader view continues to affect visibility within a published site.
+
+## Try the controls here
+
+### Filter the navigation
+
+This site's **Focus** dropdown changes navigation, search, and document cards. The same control appears in the header on every page. Your choice persists across visits and can be shared in the URL.
+
+- Choose **Write documentation** to bring forward pages about metadata, authoring, components, and API documentation. Pages about styling and deployment leave the navigation and search results.
+- Choose **Configure & publish** to bring forward styling, search, chat, hosting, and deployment. Authoring-specific pages leave the navigation and search results.
+- Choose **All** to see both paths. Foundational pages, such as [How Shoalrun works](https://www.shoalrun.com/concepts.md), stay in every view.
+
+All published pages still work at their direct URLs. A focus choice is a reading aid, not an access rule.
+
+This site's `focus` facet has `write` and `configure` choices. Generated API references use a `typeDefaults` mark of `write`. It also retains an internal `audience` facet for the hosted chat's author view and a `persona` facet for the page-only examples below. The header shows only Focus. These machine IDs contain no spaces; the longer labels are only shown to readers.
+
+### Filter examples on this page
+
+The controls below use a separate `persona` facet and `scope="page"`. They change the examples below without changing this site's navigation or search. Choose a reader to see one example, or use the controls to show both.
+
+[Show UI example](https://www.shoalrun.com/author/reader-views?pageView=persona%3Aui)
+
+[Show developer example](https://www.shoalrun.com/author/reader-views?pageView=persona%3Adeveloper)
+
+**For Reader: UI reader.**
+
+**UI example**
+
+In a dashboard guide, show the menu names and screen actions a reader needs. This section appears when **UI reader** is selected.
+
+**For Reader: Developer.**
+
+**Developer example**
+
+In an API guide, show the request, required fields, and expected response. This section appears when **Developer** is selected.
+
+**Show all** in the multi-select keeps both sections visible on this page. **Follow site view** removes the page-only choice and returns to the site's current reader view. The page-only choice is shareable with **Copy view link** and is not saved across visits.

package/agent-docs/author/recipe-drafts.md

@@ -0,0 +1,181 @@
+---
+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.**
+
+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.
+
+## 1. Write one reusable step
+
+An ingredient is an MDX file with `type: ingredient`. Its body contains the instructions to reuse. This is a shortened version of `docs/content/ingredient-build-site.mdx`:
+
+````mdx title="docs/content/ingredient-build-site.mdx"
+---
+id: ingredient.build-site
+title: Build the Shoalrun docs site
+summary: Compile authored documentation into local HTML and Markdown.
+type: ingredient
+slug: /ingredients/build-site
+channel: production
+version: current
+language: en
+access: { policy: public }
+workflow:
+  inputs:
+    frameworkCli: The CLI compiled from this checkout.
+  outputs:
+    builtSite: The successful site build at docs/dist.
+  prerequisites:
+    - Run commands from the Shoalrun repository root.
+  check: "The build reports status: ok."
+---
+
+Use the compiled CLI to build the documentation:
+
+```sh
+node framework/dist/cli.js build docs/docs.config.yaml docs/dist
+```
+
+If the build fails, fix the named source or configuration issue and rerun it.
+````
+
+The `workflow` fields describe the step:
+
+| Field           | Meaning                                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inputs`        | Names and descriptions of values or artifacts that must already be available. Here, an earlier step must provide `frameworkCli`.                   |
+| `outputs`       | Names and descriptions of what successful completion makes available to later steps. Here, `builtSite` means the successful output at `docs/dist`. |
+| `prerequisites` | Setup instructions. The assembler includes identical strings once across the recipe.                                                               |
+| `check`         | An observable condition for the reader to evaluate before continuing. Required whenever `workflow` is present.                                     |
+
+These declarations do not run the command or create variables. The body tells the reader or agent what to do. The check tells them what result to inspect. The assembler checks names and order, so a typo such as `builtDocs` where the next step expects `builtSite` fails during assembly.
+
+An ingredient can be private draft source for a recipe, or a published page readers can inspect. It must have a literal YAML header and match the recipe's default channel, version, and language. Without `workflow`, the assembler copies its body without checking handoffs.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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/1-write-one-reusable-step.md

@@ -0,0 +1,82 @@
+---
+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.
+
+## 1. Write one reusable step
+
+An ingredient is an MDX file with `type: ingredient`. Its body contains the instructions to reuse. This is a shortened version of `docs/content/ingredient-build-site.mdx`:
+
+````mdx title="docs/content/ingredient-build-site.mdx"
+---
+id: ingredient.build-site
+title: Build the Shoalrun docs site
+summary: Compile authored documentation into local HTML and Markdown.
+type: ingredient
+slug: /ingredients/build-site
+channel: production
+version: current
+language: en
+access: { policy: public }
+workflow:
+  inputs:
+    frameworkCli: The CLI compiled from this checkout.
+  outputs:
+    builtSite: The successful site build at docs/dist.
+  prerequisites:
+    - Run commands from the Shoalrun repository root.
+  check: "The build reports status: ok."
+---
+
+Use the compiled CLI to build the documentation:
+
+```sh
+node framework/dist/cli.js build docs/docs.config.yaml docs/dist
+```
+
+If the build fails, fix the named source or configuration issue and rerun it.
+````
+
+The `workflow` fields describe the step:
+
+| Field           | Meaning                                                                                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inputs`        | Names and descriptions of values or artifacts that must already be available. Here, an earlier step must provide `frameworkCli`.                   |
+| `outputs`       | Names and descriptions of what successful completion makes available to later steps. Here, `builtSite` means the successful output at `docs/dist`. |
+| `prerequisites` | Setup instructions. The assembler includes identical strings once across the recipe.                                                               |
+| `check`         | An observable condition for the reader to evaluate before continuing. Required whenever `workflow` is present.                                     |
+
+These declarations do not run the command or create variables. The body tells the reader or agent what to do. The check tells them what result to inspect. The assembler checks names and order, so a typo such as `builtDocs` where the next step expects `builtSite` fails during assembly.
+
+An ingredient can be private draft source for a recipe, or a published page readers can inspect. It must have a literal YAML header and match the recipe's default channel, version, and language. Without `workflow`, the assembler copies its body without checking handoffs.