@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.17

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.0-alpha.17 — 2026-11-04
+
+- Package hosted Ask and Search without importing source configuration or its
+  component compiler, icon, syntax-highlighting, math-rendering, and esbuild
+  dependencies. Hosted functions consume resolved settings; local commands
+  retain source-config loading.
+- Build Search from its own dependency closure and private retrieval files,
+  without chat generation, answer cards, or third-party runtime packages.
+  Preserve existing hosted metadata and deep imports for compatibility.
+- Keep prepared search scoring and snippets separate from Markdown preparation,
+  and retain runtime and dependency licenses in function packages.
+- Test isolated function imports and requests, enforce per-runtime file/byte
+  budgets, and reject build-only dependencies in hosted runtime packages.
+
+No configuration migration is required. Upgrade the CLI and rebuild the hosted
+bundle to apply the smaller function packages; existing deployments are unchanged.
+
 ## 0.1.0-alpha.16 — 2026-11-04
 
 - Set `outputs.html.search.provider: semantic` to connect the search box to

package/README.md

@@ -9,13 +9,13 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.15
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.17
 ```
 
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.15 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.17 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
@@ -69,7 +69,7 @@ npx --no-install shoalrun docs search "Steps" --json
 npx --no-install shoalrun docs read guide.component.steps --json
 ```
 
-Alpha.12 includes the reviewed documentation refresh: clearer organization, installed-package workflows, and consistent explanations of HTML, Markdown, and agent behavior. The bundled snapshot stays fixed until you upgrade the package.
+The bundled documentation is a reviewed, pinned snapshot. Its provenance lives in `agent-docs/SNAPSHOT.json`; it does not automatically follow the live site.
 
 See the [authoring command reference](AUTHORING.md) for project inspection, validation, report schemas, and the public authoring API. Visit [shoalrun.com](https://www.shoalrun.com) for the full documentation; it may describe changes newer than your installed package.
 

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "52c055cc160abbcb931bacbd8fcd209ce834cb26",
-  "siteBuildId": "c8c2a551d388148cf830e85bea3a58118a3a935dc91fa043ab2cd2a178ff9c6c",
-  "manifestDigest": "3c6af9a8161232cd4e824e72a427fb2b2a21963939a761a5f0f3557415dba580",
-  "indexDigest": "a6153f8a9a12541db3a6d1608c33da30ad329a6ad1653324f308dbd824bd9c10",
-  "packageIntegrity": "sha512-2Of7hhwylA4zWfoWIISM+0E63RzMhK9yI/NErSoNaUhquYQSD8iED1AWiUzqabnE0hg9rdtxCt82ws5+R9D3bQ=="
+  "sourceCommit": "8102004b610ce6f6ea772d7c185809618c660f90",
+  "siteBuildId": "60f6dc0eaa4cc7c73333e0bdfdf837bdd83c1636d96a92e98e93b28bbdfcb773",
+  "manifestDigest": "79a5524ecf5a8dfc44207e1d72b7558805cc6545b9178d2b6facdde584e43d37",
+  "indexDigest": "640a2d074122ba753fd3f5ab9bd7200809db7e5c25e0af02927f5b58aafd67c3",
+  "packageIntegrity": "sha512-5N/QcKQJaX3YZ3EUBPWAaBmvIR+bphIJnijgQtIKpYd22MrMGU+gtmB1Ke9Cpw9KgNCtImQsnNKt5gTUID8Mvw=="
 }

package/agent-docs/author/frontmatter-reference.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
@@ -43,16 +43,18 @@ Use the page ID for links and cards that should survive a URL change. The slug s
 
 The project enables specific channel/version/language combinations. A page is built only for combinations matching its resolved values. `audiences` and `readerFilters` select reader views when the site config enables them; `access.policy` determines whether the page enters this public build. A draft page is excluded.
 
-| Field           | Type   | Needed      | What it changes                                                                                                                |
-| --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `channel`       | string | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                         |
-| `version`       | string | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                       |
-| `language`      | string | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                     |
-| `locale`        | string | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page. |
-| `access`        | object | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                             |
-| `access.policy` | string | With access | Use public to publish this page; draft pages are excluded from the built site.                                                 |
-| `audiences`     | array  | Optional    | Readers this page is intended for; does not control who can access it.                                                         |
-| `readerFilters` | object | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                     |
+| Field           | Type    | Needed      | What it changes                                                                                                                                                                                                  |
+| --------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel`       | string  | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                                                                                                           |
+| `version`       | string  | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                                                                                                         |
+| `language`      | string  | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                                                                                                       |
+| `locale`        | string  | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page.                                                                                   |
+| `access`        | object  | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                                                                                                               |
+| `access.policy` | string  | With access | Use public to publish this page; draft pages are excluded from the built site.                                                                                                                                   |
+| `shared`        | boolean | Optional    | Explicitly classify this page as shared across customer editions. Page-specific; cannot combine with requires. Sections may still use ForFeature.                                                                |
+| `requires`      | object  | Optional    | Build-time feature requirements from the shared SKU manifest. Both clauses must pass when present; omitted means shared within existing publication/access eligibility. Requires an explicit deployment profile. |
+| `audiences`     | array   | Optional    | Readers this page is intended for; does not control who can access it.                                                                                                                                           |
+| `readerFilters` | object  | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                                                                                                       |
 
 Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.
 
@@ -88,6 +90,8 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.
 
+With `profiles.requireClassification: true`, every public source page in the shared enabled publications needs an explicit `shared: true` or `requires` declaration before customer selection. Defaults do not count. Shared pages may contain feature-specific sections wrapped in `<ForFeature>`; unwrapped text remains shared.
+
 ## Control output details
 
 `seo` changes the browser title or HTML meta description. `displayText` overrides the text chosen for one output surface on this page. `variables` supplies values to registered snippets before they expand into the page body. `markdownMetadata` selects or overrides the YAML preamble of the generated Markdown twin—the machine-readable copy of this page. That generated preamble is separate from the source frontmatter shown above.

package/agent-docs/author/frontmatter-reference.sections/choose-a-publication-and-visibility.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -32,15 +32,17 @@ For section exports, declare `standaloneSections` with `{ id, context: section }
 
 The project enables specific channel/version/language combinations. A page is built only for combinations matching its resolved values. `audiences` and `readerFilters` select reader views when the site config enables them; `access.policy` determines whether the page enters this public build. A draft page is excluded.
 
-| Field           | Type   | Needed      | What it changes                                                                                                                |
-| --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `channel`       | string | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                         |
-| `version`       | string | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                       |
-| `language`      | string | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                     |
-| `locale`        | string | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page. |
-| `access`        | object | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                             |
-| `access.policy` | string | With access | Use public to publish this page; draft pages are excluded from the built site.                                                 |
-| `audiences`     | array  | Optional    | Readers this page is intended for; does not control who can access it.                                                         |
-| `readerFilters` | object | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                     |
+| Field           | Type    | Needed      | What it changes                                                                                                                                                                                                  |
+| --------------- | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `channel`       | string  | Public page | Publication environment, such as sandbox or production; selects an enabled publication and API source.                                                                                                           |
+| `version`       | string  | Public page | API or documentation edition, such as v1; selects an enabled publication and API source.                                                                                                                         |
+| `language`      | string  | Optional    | Content language; uses frontmatter defaults/enforced values, then publications.defaults.language, then en.                                                                                                       |
+| `locale`        | string  | Optional    | Formatting conventions used in the content; can inherit a project locale for the page language and can be overridden per page.                                                                                   |
+| `access`        | object  | Public page | Controls whether the page enters a public build; this object is not exported to Markdown metadata.                                                                                                               |
+| `access.policy` | string  | With access | Use public to publish this page; draft pages are excluded from the built site.                                                                                                                                   |
+| `shared`        | boolean | Optional    | Explicitly classify this page as shared across customer editions. Page-specific; cannot combine with requires. Sections may still use ForFeature.                                                                |
+| `requires`      | object  | Optional    | Build-time feature requirements from the shared SKU manifest. Both clauses must pass when present; omitted means shared within existing publication/access eligibility. Requires an explicit deployment profile. |
+| `audiences`     | array   | Optional    | Readers this page is intended for; does not control who can access it.                                                                                                                                           |
+| `readerFilters` | object  | Optional    | Configured reader filter choices for this page. Missing facets are shared.                                                                                                                                       |
 
 Language is the content language and selects a publication. Locale describes formatting conventions in the content and does not select a publication. `frontmatter.locales` can set a project locale for each language; pages may override it.

package/agent-docs/author/frontmatter-reference.sections/control-output-details.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/global-defaults-and-enforced-values.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/html-markdown-and-agents.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/identify-and-route-a-page.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/point-agents-to-it.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/project-defined-fields.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/use-the-local-files-while-authoring.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

package/agent-docs/author/frontmatter-reference.sections/when-the-files-update.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 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.
 
@@ -168,7 +168,7 @@ npx --no-install shoalrun ingredient draft \
 
 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.
+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 [worked cookbook example](https://www.shoalrun.com/cookbooks/welcome-email.md) shows how complete recipes reuse a step and offer different outcomes against the local simulator.
 
 ## Related reading
 

package/agent-docs/author/recipe-drafts.sections/1-write-one-reusable-step.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Compose and maintain recipes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipe-drafts.md)
 
@@ -47,4 +47,4 @@ npx --no-install shoalrun ingredient draft \
 
 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.
+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 [worked cookbook example](https://www.shoalrun.com/cookbooks/welcome-email.md) shows how complete recipes reuse a step and offer different outcomes against the local simulator.

package/agent-docs/author/recipes.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 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.
 
@@ -114,7 +114,7 @@ A recipe's **Read as Markdown** link contains its complete published instruction
 
 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.
+The [worked cookbook example](https://www.shoalrun.com/cookbooks/welcome-email.md) demonstrates two recipe choices that reuse the same queue step. Its longer workflow passes a returned message ID into a delivery check. Email supplies the sample task; a local simulator runs both recipes without sending a message.
 
 ## Related reading
 
@@ -124,4 +124,4 @@ The [email example](https://www.shoalrun.com/cookbooks/welcome-email.md) demonst
 
 - [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.
+- [Cookbook example](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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -33,4 +33,4 @@ Readers can open a recipe directly. Ingredients help authors maintain instructio
 
 - [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.
+- [Cookbook example](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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 
@@ -39,4 +39,4 @@ Readers can open a recipe directly. Ingredients help authors maintain instructio
 
 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.
+The [worked cookbook example](https://www.shoalrun.com/cookbooks/welcome-email.md) demonstrates two recipe choices that reuse the same queue step. Its longer workflow passes a returned message ID into a delivery check. Email supplies the sample task; a local simulator runs both recipes without sending a message.

package/agent-docs/author/recipes.sections/use-recipes-for-task-oriented-how-tos.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 

package/agent-docs/author/recipes.sections/what-changing-an-ingredient-updates.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 

package/agent-docs/author/recipes.sections/what-each-file-does.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.
 

package/agent-docs/author/recipes.sections/what-happens-and-when.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Understand ingredients, recipes, and cookbooks
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/author/recipes.md)
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/author/recipes.md)
 
 - [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.
+- [Cookbook example](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.