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

package/agent-docs/content-delivery/manifest.md

@@ -17,11 +17,33 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content manifest
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-`manifest.json` is the entry point for a content export. The resource-aware implementation uses `kind: shoalrun-content-export`, `schemaVersion: 1`, and a `resources` array. Earlier whole-page exports use a `documents` array; rebuild those exports before opening them with the resource client.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+`manifest.json` is the entry point for a content export. Resource exports use `kind: shoalrun-content-export` and a `resources` array. Productless exports use `schemaVersion: 1`. Earlier whole-page exports use a `documents` array; rebuild those exports before opening them with the resource client.
+
+## Product-scoped manifests
+
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+Shoalrun preserves v1 for publications without products and emits `schemaVersion: 2` for product-scoped publications. A v2 manifest requires `product` alongside `channel`, `version`, and `language`. Its resources must have that same complete publication; a resource from another product is invalid.
+
+```json
+{
+  "schemaVersion": 2,
+  "publication": {
+    "product": "payments",
+    "channel": "production",
+    "version": "v3",
+    "language": "en"
+  }
+}
+```
+
+This excerpt shows the version and publication fields, not a complete manifest. A legacy v1 client rejects v2, so update custom validators and use the new client before distributing product bundles.
 
 ## Bundle fields
 
@@ -31,14 +53,14 @@ These fields describe the complete export and its publication.
 | ------------- | -------------------------------------------------------------------- |
 | `digest`      | Revision digest for the bundle manifest                              |
 | `publicBase`  | Root-relative serving mount with a trailing slash                    |
-| `publication` | One channel, version, and language                                   |
+| `publication` | One channel, version, and language; v2 also requires a product       |
 | `review`      | API source-review status and digests                                 |
 | `resources`   | Selected pages, sections, and snippet instances                      |
 | `assets`      | Local asset records                                                  |
 | `files`       | Exported file paths, sizes, and digests                              |
 | `diagnostics` | Export findings such as external images or static interaction output |
 
-A review status of `required` identifies a review candidate. Do not serve it as an approved content release.
+A review status of `required` identifies a review candidate. Don't serve it as an approved content release.
 
 ## Resource fields
 
@@ -52,17 +74,17 @@ Each resource has `ref`, `publication`, `title`, `summary`, `type`, `representat
 }
 ```
 
-This is a section's `ref`, not a complete manifest. Page references use `kind` and `documentId`; snippet-instance references use `kind` and `id`. Identity is scoped to the publication. A title or generated filename is not a resource reference.
+This is a section's `ref`, not a complete manifest. Page references use `kind` and `documentId`; snippet-instance references use `kind` and `id`. Identity is scoped to the complete publication, including the product in v2. The same page or section ID in another product is a different resource. A title or generated filename isn't a resource reference.
 
 ## Representations and links
 
 Each available `html` or `markdown` representation declares `path`, `mediaType`, `bytes`, `digest`, `anchors`, and `links`. Paths point to files under the export mount. Anchors map source IDs to exported DOM IDs. Link records distinguish `resource`, `canonical`, `external`, and `asset` targets; resource links include a typed reference.
 
-A resource's asset list names local dependencies. `externalDependencies` identifies remote images that were not copied. Distribute `NOTICES.txt` and any required attribution with the content.
+A resource's asset list names local dependencies. `externalDependencies` identifies remote images that weren't copied. Distribute `NOTICES.txt` and any required attribution with the content.
 
 ## Validate a consumer
 
-Use the content client or validate the manifest before fetching its declared paths. Unknown references and unavailable formats are errors. Check representation bytes and digest against the opened revision. Do not assume that a valid digest makes an untrusted host or its HTML safe.
+Use the content client or validate the manifest before fetching its declared paths. Unknown references and unavailable formats are errors. Check representation bytes and digest against the opened revision. Don't assume that a valid digest makes an untrusted host or its HTML safe.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/content-delivery/publish.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Publish and update content
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Publish a complete export as one revision. The manifest and representation files must agree; replacing only the manifest or only an article can leave a running application with mismatched content.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Publish a complete export as one revision. The manifest and representation files must agree; replacing only the manifest or only an article can leave a running application with mismatched content.
 
 ## Build a revision
 
@@ -47,7 +47,7 @@ npx --no-install shoalrun export docs.config.yaml \
 
 The comparison reports added and removed typed references within their publication. A title or body edit changes content without changing an explicit identity. A renamed derived section ID can remove a reference. Strict removal checking fails before replacing the previous output; without a baseline, removal checking is reported as unavailable.
 
-Review intentional removals with the applications that consume them. Keep old revisions available while deployed applications still need them. Comparison does not create redirects or aliases.
+Review intentional removals with the applications that consume them. Keep old revisions available while deployed applications still need them. Comparison doesn't create redirects or aliases.
 
 ## Serve and switch
 
@@ -57,7 +57,7 @@ The application chooses which manifest URL to open. An already-open snapshot sta
 
 ## HTML, Markdown, and agents
 
-Publish both representations together when both are selected. Agents and applications can record the manifest revision with a resource reference to explain which content they read. A digest verifies that bytes match the declared revision; it is not a signature or proof of factual accuracy. Remote images remain external dependencies and need separate availability planning.
+Publish both representations together when both are selected. Agents and applications can record the manifest revision with a resource reference to explain which content they read. A digest verifies that bytes match the declared revision; it isn't a signature or proof of factual accuracy. Remote images remain external dependencies and need separate availability planning.
 
 ## Related reading
 

package/agent-docs/content-delivery/render.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Render content in an application
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Your application can display a resource in a panel, onboarding surface, article view, or help drawer. Fetch the resource through a [content snapshot](https://www.shoalrun.com/content-delivery/client.md), then mount its HTML in a container you own.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Your application can display a resource in a panel, onboarding surface, article view, or help drawer. Fetch the resource through a [content snapshot](https://www.shoalrun.com/content-delivery/client.md), then mount its HTML in a container you own.
 
 ## Mount the result
 
@@ -44,17 +44,17 @@ Mounting assigns a unique prefix to IDs and rewrites local fragments, footnote r
 
 ## Own the interface
 
-Apply your application's CSS to passive elements. The mount helper does not install the documentation theme or recreate interactive components. Preserve headings, link labels, image alternatives, and other semantic content when styling.
+Apply your application's CSS to passive elements. The mount helper doesn't install the documentation theme or recreate interactive components. Preserve headings, link labels, image alternatives, and other semantic content when styling.
 
 Your app owns loading and failure states, navigation history, focus management, close controls, keyboard behavior, and announcements when content changes. Preserve heading levels from the content; arrange the surrounding page so those levels make sense.
 
-The helper inserts trusted compiler output. It is not a sanitizer for arbitrary HTML from users or unknown publishers.
+The helper inserts trusted compiler output. It isn't a sanitizer for arbitrary HTML from users or unknown publishers.
 
 ## Route links and clean up
 
 `mounted.links` records each exported link's kind and target. Resource links include a typed `ref`; canonical and external links have ordinary URLs. Intercept a resource link only when the app can open that target and preserve its fragment or query. Other links should retain their normal destination.
 
-Use the returned `mounted.anchors` for instance-specific fragment targets. Do not guess DOM IDs from headings. When the view closes, call `mounted.unmount()` and dispose the snapshot when it is no longer shared by another view.
+Use the returned `mounted.anchors` for instance-specific fragment targets. Don't guess DOM IDs from headings. When the view closes, call `mounted.unmount()` and dispose the snapshot when it's no longer shared by another view.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/content-delivery/rest.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Serve content through REST
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Serve the same reviewed pages, sections, and snippet instances through the Content REST API. The reference adapter accepts already-open snapshots and exposes a Fetch-style request handler. Your host provides the HTTP listener, request routing, and any access controls.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Serve the same reviewed pages, sections, and snippet instances through the Content REST API. The reference adapter accepts already-open snapshots and exposes a Fetch-style request handler. Your host provides the HTTP listener, request routing, and any access controls.
 
 ## Prepare a snapshot
 
@@ -40,9 +40,15 @@ const handleContent = createContentRestHandler({ sources: [source] });
 const response = await handleContent(request);
 ```
 
-The host passes a standard `Request` and sends the returned `Response`. `createContentRestHandler` does not start a listener. Import its server entry point only in server code. Browser clients use the separate entry point shown below.
+The host passes a standard `Request` and sends the returned `Response`. `createContentRestHandler` doesn't start a listener. Import its server entry point only in server code. Browser clients use the separate entry point shown below.
+
+Supply at most one snapshot for each channel, version, and language combination. The handler retains those revisions for its lifetime. It doesn't reload manifests or keep an archive. Keep sources alive while requests use them, then dispose them during host shutdown.
 
-Supply at most one snapshot for each channel, version, and language combination. The handler retains those revisions for its lifetime. It does not reload manifests or keep an archive. Keep sources alive while requests use them, then dispose them during host shutdown.
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+For product-scoped snapshots, uniqueness includes the product: Payments v3 and Reporting v1 can share a handler, and each request selects one exact publication. Resource keys and document IDs alone don't select a product. Requests can't fall back to another product when a resource is missing.
 
 ## Read through the client
 
@@ -66,11 +72,13 @@ try {
 }
 ```
 
+To read a Payments v3 bundle, add `product: 'payments'` and set `version` to `'v3'` in the client publication above. The handler returns a v2 JSON envelope for that product, while the route remains `/content/v1`. Export that exact product publication first.
+
 Select `guide.billing` in the export before running this example. Outside a browser, provide an absolute HTTP(S) `baseUrl`. Opening loads the resource list and pins later reads to its revision. Pass `revision` when the caller already knows which revision it needs. The returned [ContentSnapshot](https://www.shoalrun.com/content-delivery/api.md) has the same `list`, `get`, and `dispose` methods as the manifest client.
 
 ## Try the local example
 
-Copy the package's `examples/content-delivery` directory into a project with the new implementation installed. From that copied directory, build the export and start its preview:
+Copy the package's `examples/content-delivery` directory into a project with Shoalrun installed. From that copied directory, build the export and start its preview:
 
 ```sh
 npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help/releases/demo
@@ -81,7 +89,7 @@ Open `http://127.0.0.1:8775/settings/billing?delivery=rest`. The example hosts i
 
 ## Keep assets and links available
 
-The adapter sends representation bytes unchanged. Images and links still point to the export's configured static locations; the REST endpoint does not replace that asset mount. Keep the complete bundle hosted alongside the API. Applications can also route typed resource links through their own interface.
+The adapter sends representation bytes unchanged. Images and links still point to the export's configured static locations; the REST endpoint doesn't replace that asset mount. Keep the complete bundle hosted alongside the API. Applications can also route typed resource links through their own interface.
 
 For a new release, open the new snapshot and replace the handler in your host. Clients pinned to an unavailable older revision receive `409 stale_revision`. Retaining historical revisions or routing between them requires host code beyond this adapter. See [publish and update content](https://www.shoalrun.com/content-delivery/publish.md).
 
@@ -89,7 +97,7 @@ For a new release, open the new snapshot and replace the handler in your host. C
 
 The [HTTP reference](https://www.shoalrun.com/content-delivery/http-api.md) describes REST contract v1. That protocol version is separate from the package release and the content publication's `version` value.
 
-The adapter lists and reads approved resources. It does not implement authentication, search, content editing, or an MCP service. Place authorization before the handler when required. Successful pinned responses use public immutable caching; a host protecting private content must override that cache policy before sending responses.
+The adapter lists and reads approved resources. It doesn't implement authentication, search, content editing, or an MCP service. Place authorization before the handler when required. Successful pinned responses use public immutable caching; a host protecting private content must override that cache policy before sending responses.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/content-delivery/sections.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Section identity and compatibility
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-A section is a heading and the content beneath it. For content delivery, Shoalrun selects sections beginning at a top-level `##` heading, including nested subsections, and ending before the next `##` or `#` heading. Exporting a section extracts that part of the page so an application can use it separately.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+A section is a heading and the content beneath it. For content delivery, Shoalrun selects sections beginning at a top-level `##` heading, including nested subsections, and ending before the next `##` or `#` heading. Exporting a section extracts that part of the page so an application can use it separately.
 
 ## Why a section needs a declaration
 
@@ -37,9 +37,9 @@ Run the reset command from Settings.
 
 Exporting only “Reset the database” would leave out the backup instruction and deletion warning. Before exporting this section, move those details into the section or export the whole page instead.
 
-A **standalone section** is one the author has reviewed and declared understandable without the rest of the page. Record that judgment in the page's `standaloneSections` frontmatter. This is what “approval” means here: a declaration in a source file, not a separate reviewer, permission request, or approval service. Shoalrun checks that the declaration exists and identifies a section; it cannot prove the content is complete.
+A **standalone section** is one the author has reviewed and declared understandable without the rest of the page. Record that judgment in the page's `standaloneSections` frontmatter. This is what “approval” means here: a declaration in a source file, not a separate reviewer, permission request, or approval service. Shoalrun checks that the declaration exists and identifies a section; it can't prove the content is complete.
 
-You need this declaration when exporting an individual section. You do not need it to write a page, link to a heading, or export a whole page. Declaring a section does not export it: the export target separately chooses which declared sections to include.
+You need this declaration when exporting an individual section. You don't need it to write a page, link to a heading, or export a whole page. Declaring a section doesn't export it: the export target separately chooses which declared sections to include.
 
 ## Identify the section
 
@@ -61,7 +61,7 @@ This heading derives `request-a-refund`. Derivation normalizes the heading text,
 
 The ID remains `refunds` if the title changes. The marker must be the single trailing element of a root H2, with one literal `id` and no children. IDs use 1–512 lowercase letters, numbers, or dashes, beginning with a letter or number. Duplicate IDs and collisions with another anchor fail. `Anchor` is a reserved built-in name.
 
-The marker cannot be placed inside emphasis, a link, a tab, a reader section, or a snippet. Code examples containing marker syntax remain ordinary code. Both `##` headings and Setext H2 headings are supported.
+The marker can't be placed inside emphasis, a link, a tab, a reader section, or a snippet. Code examples containing marker syntax remain ordinary code. Both `##` headings and Setext H2 headings are supported.
 
 ## Declare a section ready for separate use
 
@@ -85,19 +85,19 @@ standaloneSections:
   - Request a refund
 ```
 
-This form remains supported. It matches the exact heading text and approves a discovery read that includes page introduction and reading-path context. It does not approve a section-only export. Keep it when the section relies on that surrounding context.
+This form remains supported. It matches the exact heading text and approves a discovery read that includes page introduction and reading-path context. It doesn't approve a section-only export. Keep it when the section relies on that surrounding context.
 
-Do not mechanically replace a title string with `{ id, context: section }`. First review the section without the page introduction and include any missing prerequisites, definitions, or warnings. Then replace the title string with the ID-based object and select the section in the export target. A heading cannot be declared in both forms.
+Don't mechanically replace a title string with `{ id, context: section }`. First review the section without the page introduction and include any missing prerequisites, definitions, or warnings. Then replace the title string with the ID-based object and select the section in the export target. A heading can't be declared in both forms.
 
-The object form also marks the section as approved for contextual discovery when it meets discovery size requirements. Switching to the object does not remove context from existing discovery responses; it additionally approves the section-only export. See [section discovery](https://www.shoalrun.com/author/markdown-metadata.md) for those response rules.
+The object form also marks the section as approved for contextual discovery when it meets discovery size requirements. Switching to the object doesn't remove context from existing discovery responses; it additionally approves the section-only export. See [section discovery](https://www.shoalrun.com/author/markdown-metadata.md) for those response rules.
 
 ## Maintain references
 
-Renaming an explicit ID or removing an exported section removes a public content reference. Use `--previous-manifest` and `--fail-on-removed` when publishing an established collection. An unchanged ID with edited content receives a new digest; identity does not mean immutable wording.
+Renaming an explicit ID or removing an exported section removes a public content reference. Use `--previous-manifest` and `--fail-on-removed` when publishing an established collection. An unchanged ID with edited content receives a new digest; identity doesn't mean immutable wording.
 
 ## HTML, Markdown, and agents
 
-HTML preserves the existing heading-derived anchor and adds an explicit ID as an alias when it is distinct and available. Markdown keeps the clean heading text. Agents receive IDs through outlines or export metadata; they should follow the returned resource URL rather than invent a Markdown fragment URL. Existing contextual MCP section reads retain their page context and size heuristics; application fragments are a separate output.
+HTML preserves the existing heading-derived anchor and adds an explicit ID as an alias when it's distinct and available. Markdown keeps the clean heading text. Agents receive IDs through outlines or export metadata; they should follow the returned resource URL rather than invent a Markdown fragment URL. Existing contextual MCP section reads retain their page context and size heuristics; application fragments are a separate output.
 
 ## Related reading
 

package/agent-docs/content-delivery/select.md

@@ -17,14 +17,14 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Select content resources
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.13.**
 
 Use an export target to choose exactly which content an application receives. Work from a Shoalrun project with public pages in an enabled publication. Whole pages need no section declaration. To export just one section, first read it without the rest of its page. Check that it includes the context needed to understand or follow it. Record that review in the source page's `standaloneSections` frontmatter; [declare a section ready for separate use](https://www.shoalrun.com/content-delivery/sections.md) explains why and shows the syntax.
 
 The declaration says the section can be used on its own. The export target below says which content to include in this bundle. Both are required for a section export.
 
-Available since `0.1.0-alpha.13`.
-
 ## Define the target
 
 Add this target to `docs.config.yaml`. Replace the example IDs with your own:
@@ -48,7 +48,7 @@ exports:
 
 `resources` and the older `documents` selection are mutually exclusive. A page selector includes the complete page. A section selector includes its approved H2 and nested subsections, ending at the next H2 or H1. The export retains applicable notices and referenced definitions without copying ordinary page introduction text.
 
-A requested page must be public and available in the chosen publication. An export `contentFilter` can narrow eligible pages; it is independent of website navigation and `site.contentFilter`. Reader filters select content, not access permissions.
+A requested page must be public and available in the chosen publication. An export `contentFilter` can narrow eligible pages; it's independent of website navigation and `site.contentFilter`. Reader filters select content, not access permissions.
 
 ## Name snippet instances
 
@@ -68,7 +68,7 @@ The snippet file contains:
 Request a refund within <Var name="days" /> days.
 ```
 
-`snippetId` chooses that source; `id` names the exported instance. Multiple instances can use different literal values. The application reads `refund.standard`, not a runtime template. Instances have no containing page or page variables. Page-dependent components and headings are not supported in standalone snippets.
+`snippetId` chooses that source; `id` names the exported instance. Multiple instances can use different literal values. The application reads `refund.standard`, not a runtime template. Instances have no containing page or page variables. Page-dependent components and headings aren't supported in standalone snippets.
 
 ## Export and inspect
 
@@ -79,7 +79,7 @@ npx --no-install shoalrun export docs.config.yaml \
 
 Inspect `manifest.json`, each selected representation, and its referenced assets. Unknown references, missing approval, and unsupported content fail before replacing an existing export. Imported API material still follows the existing source-review gate.
 
-Links to fragments in unselected pages fail export because their anchors cannot be verified. Select the target page or section explicitly. Missing or ambiguous fragments also fail. A sliced section keeps its full-source heading identity. Links to sibling content can use a canonical page URL only when the source HTML anchor is verified.
+Links to fragments in unselected pages fail export because their anchors can't be verified. Select the target page or section explicitly. Missing or ambiguous fragments also fail. A sliced section keeps its full-source heading identity. Links to sibling content can use a canonical page URL only when the source HTML anchor is verified.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/content-delivery.md

@@ -17,7 +17,9 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.13.**
 
 Content delivery makes your documentation a reusable content source for applications, agents, services, and workflows. They can retrieve whole pages, individual sections, or reusable snippets in HTML or Markdown. You control how the content is displayed, combined, or processed; Shoalrun supplies the content and its metadata.
 
@@ -30,8 +32,6 @@ For example:
 
 These are starting points. The consuming system decides what to build with the content.
 
-Available since `0.1.0-alpha.13`.
-
 ## Choose a resource
 
 Choose the unit that matches the application surface.
@@ -58,7 +58,7 @@ Authored pages and snippets
   -> application interface
 ```
 
-Keep the application's content access behind the [ContentSnapshot interface](https://www.shoalrun.com/content-delivery/api.md). The [REST adapter](https://www.shoalrun.com/content-delivery/rest.md) exposes the same resources through HTTP, and its client returns that interface. The host supplies its listener and authorization. The adapter does not add search or live content editing.
+Keep the application's content access behind the [ContentSnapshot interface](https://www.shoalrun.com/content-delivery/api.md). The [REST adapter](https://www.shoalrun.com/content-delivery/rest.md) exposes the same resources through HTTP, and its client returns that interface. The host supplies its listener and authorization. The adapter doesn't add search or live content editing.
 
 ## Choose the next task
 

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

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Use the bundled agent skills
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Give an agent a bundled skill when you want it to follow Shoalrun's setup, authoring, recipe, component, or walkthrough workflow. You need an agent that can read the skill file and run commands, plus a Shoalrun checkout or installed CLI.
 
@@ -28,11 +28,11 @@ Use `shoalrun-setup` to start a site, `shoalrun-author` to add or revise pages,
 
 Install the complete folder in your agent's skill directory using that agent's installation process. If it supports reading repository files directly, point it at the entry file instead. For a recipe task, use `framework/skills/shoalrun-recipes/SKILL.md`.
 
-In an installed package, skill folders live under `node_modules/@shoalrun/cli/skills/`. These files are portable instructions; the CLI does not install them into your agent automatically.
+In an installed package, skill folders live under `node_modules/@shoalrun/cli/skills/`. These files are portable instructions; the CLI doesn't install them into your agent automatically.
 
 Give your agent the installed `shoalrun-author/SKILL.md` path and the consumer project's `docs.config.yaml` path. Use the existing harness's file, terminal, and browser tools. No separate authoring service or model configuration is required.
 
-Ask the agent to read the skill before beginning. If it cannot discover installed skills, include the file path. If it cannot read files or run a CLI, follow the [page creation workflow](https://www.shoalrun.com/author/add-page.md) yourself.
+Ask the agent to read the skill before beginning. If it can't discover installed skills, include the file path. If it can't read files or run a CLI, follow the [page creation workflow](https://www.shoalrun.com/author/add-page.md) yourself.
 
 ## Give the agent a bounded request
 

package/agent-docs/cookbooks/authoring.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Authoring workflows
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Choose the outcome you need for Shoalrun's own documentation. Each recipe includes setup, ordered work, handoffs, and an observable final check.
 
@@ -51,11 +51,11 @@ What are you working on?. Choose one recipe.
 
 Adding a guide includes manual writing and review. The recipe then builds and audits the page and refreshes the agent bundle. Previewing an existing change starts a local server; refreshing the bundle verifies what the CLI can search and read. Choose one task at a time so shared setup runs once within that recipe.
 
-Use **Link to this path** to share the selected instructions, **Download Markdown** to work from a saved copy, or **Print this path** for a checklist. These workflows prepare local changes for review; they do not commit or deploy them.
+Use **Link to this path** to share the selected instructions, **Download Markdown** to work from a saved copy, or **Print this path** for a checklist. These workflows prepare local changes for review; they don't commit or deploy them.
 
 ## HTML, Markdown, and agents
 
-In HTML, the chooser loads and displays the selected published recipes. Without JavaScript, readers can follow the recipe links. This page's Markdown lists the choices and their destinations; it does not contain the selected recipes' full instructions. Give an agent a recipe's Markdown page or the chooser's **Download Markdown** file to follow the complete task.
+In HTML, the chooser loads and displays the selected published recipes. Without JavaScript, readers can follow the recipe links. This page's Markdown lists the choices and their destinations; it doesn't contain the selected recipes' full instructions. Give an agent a recipe's Markdown page or the chooser's **Download Markdown** file to follow the complete task.
 
 ## Related reading
 

package/agent-docs/cookbooks/site-workflows.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Site workflows
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use these recipes on a local Shoalrun checkout after editing documentation. Choose the level of validation you need. The audit path already includes the build and artifact checks, so run one complete path.
 
@@ -44,7 +44,7 @@ These recipes use the same installation, build, and artifact-check ingredients.
 
 ## HTML, Markdown, and agents
 
-The HTML chooser displays the complete recipe you select; its recipe links also work without JavaScript. The cookbook's Markdown lists the build and audit choices with links to their recipe pages. It does not contain a browser-selected workflow. An agent should read the chosen recipe's Markdown or receive the file from **Download Markdown** before carrying out its steps.
+The HTML chooser displays the complete recipe you select; its recipe links also work without JavaScript. The cookbook's Markdown lists the build and audit choices with links to their recipe pages. It doesn't contain a browser-selected workflow. An agent should read the chosen recipe's Markdown or receive the file from **Download Markdown** before carrying out its steps.
 
 ## Related reading
 

package/agent-docs/cookbooks/welcome-email.md

@@ -1,28 +1,31 @@
 ---
 id: cookbook.welcome-email
-title: Welcome email workflows
-summary: Choose an acceptance check or follow the same message through delivery.
+title: Cookbook example
+summary: Compare recipe choices and see how a cookbook reuses instructions
+  across workflows.
 type: cookbook
-area: api
-subarea: api-examples
+area: authoring
+subarea: authoring-composition
 canonical: /cookbooks/welcome-email
 ---
 
-# Welcome email workflows
+# Cookbook example
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
 Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Email simulation > Email simulation
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Cookbook example > Cookbook example
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-An accepted request is the first checkpoint. Choose how far you want to follow the message. Both paths use a local simulation that sends no email.
+This worked example shows how a cookbook presents complete recipes and reuses instructions across them. Choose a short acceptance check or a longer delivery workflow; the delivery recipe includes the same queue step.
+
+Email is the sample task. Both recipes use a local simulator that sends no email. The reusable pattern is choosing an outcome, following the selected recipe, and carrying one step’s output into the next step.
 
 Each recipe includes the setup command, inputs, and success check. You need a Shoalrun checkout, cURL, and Node.js. The demo runs on your own computer at `127.0.0.1:8787`.
 
-## Choose your outcome
+## Choose a recipe
 
 What do you need to confirm?. Choose one recipe.
 
@@ -42,11 +45,11 @@ What do you need to confirm?. Choose one recipe.
 
   You will have: A delivery status tied to the message you queued, with a failure check.
 
-The delivery path includes the queue step, so choose one path. Use **Link to this path** to share your selection, **Download Markdown** to keep the instructions, or **Print this path** for a paper copy. Shared links contain your recipe choice only; they do not contain a message ID.
+The delivery path includes the queue step, so choose one path. Use **Link to this path** to share your selection, **Download Markdown** to keep the instructions, or **Print this path** for a paper copy. Shared links contain your recipe choice only; they don't contain a message ID.
 
 ## HTML, Markdown, and agents
 
-The HTML chooser loads the selected email recipes, while ordinary recipe links remain available without JavaScript. Markdown lists the choices and links rather than the browser-selected recipe bodies. An agent must follow those links or read the chooser's **Download Markdown** file for the complete simulator instructions. Selecting a recipe does not send an email or execute its commands.
+The HTML chooser loads the selected email recipes, while ordinary recipe links remain available without JavaScript. Markdown lists the choices and links rather than the browser-selected recipe bodies. An agent must follow those links or read the chooser's **Download Markdown** file for the complete simulator instructions. Selecting a recipe doesn't send an email or execute its commands.
 
 ## Related reading