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

package/agent-docs/chat/settings.sections/send-extra-request-fields.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -39,4 +39,4 @@ chat:
 
 The fields can add to a request but can't replace what Shoalrun sets, which is `model`, `messages`, `max_tokens`, `temperature`, and `stream`. Use `chat.model`, `chat.maxTokens`, and `chat.temperature` for those. A field whose name looks like a secret, such as a key, token, or password, fails validation, because the config never holds a key. Each fallback and escalation model inherits `body` and can replace it with its own. An empty `body: {}` clears it. Another service may reject a field it doesn't know, so check what yours accepts.
 
-Service-specific fields can affect latency, cost, and quality. Test them with your own questions and model; support and effects vary by service. Shoalrun does not interpret those extra fields.
+Service-specific fields can affect latency, cost, and quality. Test them with your own questions and model; support and effects vary by service. Shoalrun doesn't interpret those extra fields.

package/agent-docs/chat/settings.sections/use-more-than-one-model.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
@@ -59,4 +59,4 @@ The main model answers first, and the checks run. If one of the `when` reasons a
 
 Without `when`, the reasons are `unsupported-code` and `uncited`, plus `unsupported-claim` when `verify` is set. The code check is a heuristic that can misjudge a valid example. A second answer from a thinking model adds seconds. So many sites limit `when` to `unsupported-claim` and `uncited`. A declined answer or a direct excerpt is never escalated. If the escalation model fails, the first answer is shown with a note. `--no-escalate` on `ask` turns it off for one run.
 
-Choose an escalation model using reviewed questions that your primary model handles poorly. A larger model is not automatically a better fit.
+Choose an escalation model using reviewed questions that your primary model handles poorly. A larger model isn't automatically a better fit.

package/agent-docs/chat/settings.sections/when-the-scorer-is-down.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Retrieval and chat > Retrieval and chat settings
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 

package/agent-docs/chat/setup.md

@@ -18,13 +18,13 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Documentation chat > Set up locally
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
 Set up a local chat panel, then check that its answers cite the right documentation. Start in the root of a Shoalrun project that already builds, with the CLI available in your terminal.
 
-You need a chat-service account and its API key. Meaning-based retrieval also needs an embedding provider and key. These commands make provider requests; they do not deploy your site.
+You need a chat-service account and its API key. Meaning-based retrieval also needs an embedding provider and key. These commands make provider requests; they don't deploy your site.
 
 For keyword-only retrieval, omit `retrieval` from the example below and omit `--embed` from the indexing command. You still need the passage index and a chat service.
 

package/agent-docs/chat.md

@@ -18,11 +18,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Documentation chat > How answers work
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 **Status: Experimental.**
 
-Documentation chat reads a site you have already built. It is optional: a normal `shoalrun build` does not call the retrieval or chat providers.
+Documentation chat reads a site you have already built. It's optional: a normal `shoalrun build` doesn't call the retrieval or chat providers.
 
 Chat first finds relevant passages, then uses them to produce a cited answer. A passage is a short part of a built Markdown page with a link back to its source. Some configurations can return an existing answer or an excerpt instead of generating new text.
 
@@ -34,7 +34,7 @@ Each layer adds a retrieval or answer capability and has its own prerequisites.
 
 | Layer            | What it adds                                                                                                                                                               | It needs                                       |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| Keyword matching | Finds the most relevant passages by their words. It is what the chat uses when there are no vectors, or the embedding service is unavailable.                              | The passage index. No key.                     |
+| Keyword matching | Finds the most relevant passages by their words. It's what the chat uses when there are no vectors, or the embedding service is unavailable.                               | The passage index. No key.                     |
 | Semantic search  | Finds passages by meaning, so a question matches even when it shares no words with the page.                                                                               | An embedding service and key.                  |
 | Relevance scorer | Reorders the results and declines a question the docs don't cover. It checks each sentence of an answer, and shows a passage word for word when one is clearly the answer. | A scorer service that speaks the Jev protocol. |
 | Chat model       | Writes a cited answer from the best passages.                                                                                                                              | A chat service and key.                        |

package/agent-docs/cli.md

@@ -16,13 +16,17 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Node.js 22.12 or newer. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm, then run commands as `npx --no-install shoalrun <command>`. Framework contributors can build the source checkout and run `node framework/dist/cli.js <command>` from its root.
 
 Commands that return data print JSON to standard output. On an error, the CLI prints `{"status":"error","message":"..."}` to standard error and exits with code 1. A config argument defaults to `docs.config.yaml` in the current directory unless noted.
 
-[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs do not need it.
+[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs don't need it.
+
+Since 0.1.0-alpha.18
+
+Product selectors, `dev --profile`, and `get_publications` discovery add product-aware workflows. Existing productless commands keep their publication scope.
 
 ## Start a project
 
@@ -32,17 +36,17 @@ Commands that return data print JSON to standard output. On an error, the CLI pr
 shoalrun init [directory] [--starter minimal|api-docs|showcase]
 ```
 
-Copies a bundled starter into `directory` (default `.`). `minimal` is the default; `api-docs` includes the fictional Cedar Parcel API, an overview and quickstart, a local OpenAPI file, generated references, search, and a color-mode toggle. The `showcase` starter adds a component handbook, diagrams, code walkthroughs, reader views, a landing page, and a local-workflow cookbook to that API example. All three build without provider credentials. The API and showcase README files explain customization. Existing unrelated files stay in place, but any destination file collision stops the command before it copies anything. Existing destination directories must be real directories, not symlinks or files. The command prints JSON with the starter, absolute directory, copied files, and the next validate and build commands. Run those commands from the created directory, then replace fixture content and example domains. `init` does not install packages or deploy the site.
+Copies a bundled starter into `directory` (default `.`). `minimal` is the default; `api-docs` includes the fictional Cedar Parcel API, an overview and quickstart, a local OpenAPI file, generated references, search, and a color-mode toggle. The `showcase` starter adds a component handbook, diagrams, code walkthroughs, reader views, a landing page, and a local-workflow cookbook to that API example. All three build without provider credentials. The API and showcase README files explain customization. Existing unrelated files stay in place, but any destination file collision stops the command before it copies anything. Existing destination directories must be real directories, not symlinks or files. The command prints JSON with the starter, absolute directory, copied files, and the next validate and build commands. Run those commands from the created directory, then replace fixture content and example domains. `init` doesn't install packages or deploy the site.
 
 ## Build and serve
 
 ### `build`
 
 ```sh
-shoalrun build [config] [output] [--source-commit SHA] [--release-label LABEL]
+shoalrun build [config] [output] [--profile FILE] [--source-commit SHA] [--release-label LABEL]
 ```
 
-Compiles the site. `output` defaults to `site-dist`. Prints `{ "status": "ok", "documents": <count>, "operations": <count> }`.
+Compiles the site. `--profile FILE` selects the customer edition, including its feature grants and enabled product releases. See [customer deployment profiles](https://www.shoalrun.com/publish/deployment-profiles.md). `output` defaults to `site-dist`. Prints `{ "status": "ok", "documents": <count>, "operations": <count> }`.
 
 The build writes to a temporary directory, then **deletes `output` and replaces it**. Don't point it at a directory with other files. The build stops before deleting anything if `output` contains the project or content directory, sits inside the content directory, or holds a file the build reads. It also writes the [frontmatter reference](https://www.shoalrun.com/author/frontmatter-reference.md) to `.shoalrun/` beside the config; add `.shoalrun/` to `.gitignore`.
 
@@ -53,12 +57,12 @@ Every build writes `/build-info.json` with the build ID and resolved config dige
 ```sh
 shoalrun export [config] --out DIRECTORY [--target NAME]
   [--format markdown|html|both] [--document ID]...
-  [--channel C --version V --language L] [--public-base /help/] [--review]
+  [--product P --channel C --version V --language L] [--profile FILE] [--public-base /help/] [--review]
 ```
 
-Exports whole public pages from source as resolved Markdown and passive HTML fragments, with a versioned manifest, referenced assets, and notices. No navigation, facets, website theme, or prior website build is required. `--out` is required. Without `--target`, the command exports all eligible pages in one enabled publication; select all three publication coordinates when more than one is enabled. `--document` can be repeated. Command options override the named target's formats, document selection, publication, and public base.
+Exports whole public pages from source as resolved Markdown and passive HTML fragments, with a versioned manifest, referenced assets, and notices. No navigation, facets, website theme, or prior website build is required. `--out` is required. Without `--target`, the command exports all eligible pages in one enabled publication. When several are enabled, select the product when applicable and the remaining publication coordinates. `--document` can be repeated. Command options override the named target's formats, document selection, publication, and public base.
 
-Named targets live under `exports` in the project config. Their optional page-facet filter is independent of `site.contentFilter` and navigation. Public access, enabled publication, and language still determine eligibility. Invalid selections and missing link or asset dependencies fail before a previous export is replaced. An unrelated nonempty destination or a source directory cannot be replaced.
+Named targets live under `exports` in the project config. Their optional page-facet filter is independent of `site.contentFilter` and navigation. Public access, enabled publication, and language still determine eligibility. Invalid selections and missing link or asset dependencies fail before a previous export is replaced. An unrelated nonempty destination or a source directory can't be replaced.
 
 The command prints JSON with status, absolute output directory, publication, formats, document count and IDs, asset count, bundle digest, API review digests, and diagnostics. `--review` can write a candidate with `status: needs-review` and exit code 2. Pin the reviewed digests and repeat the normal command before distributing it. See [export content into an application](https://www.shoalrun.com/publish/content-export.md) for target fields, output contracts, and the help-drawer example.
 
@@ -68,7 +72,7 @@ The command prints JSON with status, absolute output directory, publication, for
 shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SNAPSHOT
 ```
 
-Compares two local `documents.sync.json` files and prints JSON with build IDs, `buildChanged`, `metadataChanged`, and `added`, `changed`, and `removed` page records. Page identity includes its publication variant. The command validates both snapshots and rejects unsupported schema versions, invalid records, and duplicate identities. It reads files only; it does not fetch pages or modify a cache. Keep saved snapshots outside the replaced build directory. See [incremental sync](https://www.shoalrun.com/publish/output.md).
+Compares two local `documents.sync.json` files and prints JSON with build IDs, `buildChanged`, `metadataChanged`, and `added`, `changed`, and `removed` page records. Page identity includes its publication variant. The command validates both snapshots and rejects unsupported schema versions, invalid records, and duplicate identities. It reads files only; it doesn't fetch pages or modify a cache. Keep saved snapshots outside the replaced build directory. See [incremental sync](https://www.shoalrun.com/publish/output.md).
 
 ### `serve`
 
@@ -88,15 +92,23 @@ It serves plain HTTP with no compression or cache headers. To host it publicly,
 ### `dev`
 
 ```sh
-shoalrun dev [config] [output] [--port PORT]
+shoalrun dev [config] [output] [--profile FILE] [--port PORT]
+```
+
+Builds the project, serves it at `127.0.0.1:8765` by default, and refreshes open pages after a successful rebuild. `output` defaults to `site-dist`; `--port` overrides `PORT`. It watches the config directory and declared external dependencies. Restart after changing framework TypeScript, a `metadata.provider` module, or a custom highlighting module, because Node loads each module once.
+
+Use `--profile FILE` to preview one customer edition with the same publication selection and feature pruning as `build --profile`. For example:
+
+```sh
+npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/acme.yaml --port 8770
 ```
 
-Builds the project, serves it at `127.0.0.1:8765` by default, watches the directory containing the config, and refreshes open pages after a successful rebuild. `output` defaults to `site-dist`; `--port` overrides `PORT`. A failed rebuild prints its error and keeps serving the last successful build. Fix the source to trigger another build. Restart the command after changing framework TypeScript or files outside the config directory. Also restart after editing a `metadata.provider` module or a custom highlighting module, because Node loads each module once.
+Changes to the profile, SKU manifest, or declared assets rebuild the edition, including external files. A successful build replaces the output and removes excluded pages, assets, navigation, and search records. If the current page disappears, the browser opens the new edition’s landing page. A failure keeps the last successful edition and displays its identity and a failure notice, including on newly opened pages. Fixing a newly declared missing asset can trigger recovery without another profile edit. Reader views don't substitute for this compiled customer selection. See [deployment profiles](https://www.shoalrun.com/publish/deployment-profiles.md).
 
 ### `search`
 
 ```sh
-shoalrun search <site-directory> <query> [--channel C] [--version V] [--language L] [--limit N]
+shoalrun search <site-directory> <query> [--product P] [--channel C] [--version V] [--language L] [--limit N]
 ```
 
 Searches a built site's `search-index.json` without a server. Quote queries with spaces. It returns JSON with the selected publication, total matches, and up to eight ranked results by default. Each result includes a page ID, HTML URL, Markdown URL, title, summary, type, score, and a short body excerpt. A section match links to its heading in the HTML URL.
@@ -105,7 +117,7 @@ Searches a built site's `search-index.json` without a server. Quote queries with
 shoalrun search docs/dist "nullable response" --limit 5
 ```
 
-If the index contains multiple publications, select one with `--channel`, `--version`, and `--language`. The CLI refuses to mix them. `--limit` accepts 1 through 100. Build with the default lexical search provider, or enable `index: true` for a custom provider. The command reports a missing index instead of rebuilding the site.
+If the index contains multiple publications, select one with `--product` when applicable, plus `--channel`, `--version`, and `--language`. The CLI refuses to mix them. `--limit` accepts 1 through 100. Build with the default lexical search provider, or enable `index: true` for a custom provider. The command reports a missing index instead of rebuilding the site.
 
 ### `docs search` and `docs read`
 
@@ -115,7 +127,7 @@ shoalrun docs read guide.navigation-lifecycle --json --max-tokens 4096
 shoalrun docs search "search provider" --site docs/dist --limit 5
 ```
 
-These commands use Shoalrun's bundled documentation by default. Pass `--site DIRECTORY` to search or read a built site's own documentation instead. `docs search` prints JSON results with document IDs and excerpts; `docs read` prints generated Markdown, or structured page data with `--json`. Both accept `--max-tokens` (default 4096; range 256–100000) and publication selectors `--channel`, `--version`, and `--language`. Search also accepts `--limit` (default 8; range 1–100). JSON results include `budget` metadata; plain Markdown reads report truncation on standard error. Increase the budget when a page is truncated. They need no project config, site build, browser, network, or agent-specific protocol. An agent can search for a task, read the matching page, and then run the ordinary project commands. The bundled docs are generated from this site's sources and checked against the self-doc build in the test suite.
+These commands use Shoalrun's bundled documentation by default. Pass `--site DIRECTORY` to search or read a built site's own documentation instead. `docs search` prints JSON results with document IDs and excerpts; `docs read` prints generated Markdown, or structured page data with `--json`. Both accept `--max-tokens` (default 4096; range 256–100000) and publication selectors `--product`, `--channel`, `--version`, and `--language`. Search also accepts `--limit` (default 8; range 1–100). JSON results include `budget` metadata; plain Markdown reads report truncation on standard error. Increase the budget when a page is truncated. They need no project config, site build, browser, network, or agent-specific protocol. An agent can search for a task, read the matching page, and then run the ordinary project commands. The bundled docs are generated from this site's sources and checked against the self-doc build in the test suite.
 
 ### `docs mcp`
 
@@ -124,7 +136,7 @@ shoalrun docs mcp
 shoalrun docs mcp --site docs/dist
 ```
 
-Starts a read-only MCP server over stdio. The default source is the bundled Shoalrun docs; `--site` selects a built site. The server exposes `search_docs`, `get_page`, `get_outline`, and `get_section`. They share the search/read core and token budgets with the CLI. Standard output is reserved for protocol messages. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md).
+Starts a read-only MCP server over stdio. The default source is the bundled Shoalrun docs; `--site` selects a built site. The server exposes `search_docs`, `get_page`, `get_outline`, and `get_section`. It also exposes `get_publications`, a compact, paginated list of available product/channel/version/language coordinates; follow its `nextOffset` before choosing a scope. They share the search/read core and token budgets with the CLI. Standard output is reserved for protocol messages. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md).
 
 Documentation search/read errors use `{ "status": "error", "error": { "code": "...", "message": "..." } }`. Codes distinguish `invalid_input`, `unknown_page`, `missing_index`, and `internal_error`. JSON mode sends errors to standard output and exits 1; plain reads send errors to standard error. Other commands retain the general CLI error shape described above.
 
@@ -137,19 +149,19 @@ shoalrun eval snapshot <site-directory> > SNAPSHOT.json
 shoalrun eval compare CURRENT.json --since PREVIOUS.json
 ```
 
-`prepare` reads a YAML or JSON task file and writes a JSON report template for the built documentation. All tasks start skipped, runner details are unrecorded, and review is null. Existing report files are never overwritten. The command does not execute tasks or grade answers.
+`prepare` reads a YAML or JSON task file and writes a JSON report template for the built documentation. All tasks start skipped, runner details are unrecorded, and review is null. Existing report files are never overwritten. The command doesn't execute tasks or grade answers.
 
-`check` validates a completed report against the current task definitions and built output. It prints JSON findings and outcomes, and exits 1 for stale reports, malformed data, invalid citations, incomplete judgments, or required tasks that did not pass. A missing report is a reported failure. Invalid tasks or an unreadable site fail before a report can be produced. See [evaluate agent tasks](https://www.shoalrun.com/publish/evals.md) for the schemas and audit hook.
+`check` validates a completed report against the current task definitions and built output. It prints JSON findings and outcomes, and exits 1 for stale reports, malformed data, invalid citations, incomplete judgments, or required tasks that didn't pass. A missing report is a reported failure. Invalid tasks or an unreadable site fail before a report can be produced. See [evaluate agent tasks](https://www.shoalrun.com/publish/evals.md) for the schemas and audit hook.
 
 `snapshot` prints a JSON file inventory and exact-output digest. `compare` validates two inventories and lists added, changed, and removed paths; it exits 1 when builds differ or inputs are invalid. These commands diagnose freshness without running or approving an evaluation. New report templates also include the inventory, so a stale report can show file differences in `details.buildChanges`.
 
 ### `vercel build`
 
 ```sh
-shoalrun vercel build [config] [output] [--source-commit SHA] [--release-label LABEL] [--chat]
+shoalrun vercel build [config] [output] [--profile FILE] [--source-commit SHA] [--release-label LABEL] [--chat]
 ```
 
-Writes a Vercel Build Output API directory. `output` defaults to `.vercel/output`. It accepts the same public build provenance flags as `build` and includes `/build-info.json` in the static output. `--chat` adds the optional hosted chat function; the build fails if you request it and the function cannot be added. See [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) and [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).
+Writes a Vercel Build Output API directory. `output` defaults to `.vercel/output`. It accepts `--profile` for a selected static customer edition; profiled builds don't support `--chat`. It accepts the same public build provenance flags as `build` and includes `/build-info.json` in the static output. `--chat` adds the optional hosted chat function; the build fails if you request it and the function can't be added. See [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) and [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).
 
 ## Author pages
 
@@ -171,12 +183,12 @@ shoalrun scaffold <template> <config> <target-file> --id ID --title TITLE --summ
 
 The short form finds `docs.config.yaml` in the current directory or a parent, and derives the ID, title, summary, and slug from the target path. `--new` is the same as `-n`.
 
-| Option                                   | Meaning                                                                                                                                  |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `--config FILE`                          | Config file to use (short form only).                                                                                                    |
-| `--id`, `--title`, `--summary`, `--slug` | Page values. Required in the explicit form; they override derived values in the short form.                                              |
-| `--channel`, `--version`, `--language`   | Publication. Defaults come from `publications.defaults`; the combination must be enabled.                                                |
-| `--operation ID`                         | A stable operation ID for the page. Repeat it for several. It must be an operation declared in `apis.*.operations`, not a generated one. |
+| Option                                              | Meaning                                                                                                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--config FILE`                                     | Config file to use (short form only).                                                                                                                  |
+| `--id`, `--title`, `--summary`, `--slug`            | Page values. Required in the explicit form; they override derived values in the short form.                                                            |
+| `--product`, `--channel`, `--version`, `--language` | Publication. A selected product uses its own default version; productless defaults come from `publications.defaults`. The combination must be enabled. |
+| `--operation ID`                                    | A stable operation ID for the page. Repeat it for several. It must be an operation declared in `apis.*.operations`, not a generated one.               |
 
 The target must be a `.md` or `.mdx` file inside the content directory, and must not exist yet. The slug must start with `/`. The new page has draft access. Prints the template, page ID, file path, publication, and access. See [templates](https://www.shoalrun.com/author/templates.md) for how values are derived.
 
@@ -191,7 +203,7 @@ shoalrun docs apply edit-plan.json [--config docs.config.yaml] --check
 shoalrun docs apply edit-plan.json [--config docs.config.yaml]
 ```
 
-`docs context` reports a stable page ID's authored sources and digests, navigation placements, relationships, and configuration owners. It also returns configured authoring directives and guide and exemplar paths. It does not return a generated API reference as an authored page.
+`docs context` reports a stable page ID's authored sources and digests, navigation placements, relationships, and configuration owners. It also returns configured authoring directives and guide and exemplar paths. It doesn't return a generated API reference as an authored page.
 
 The request file contains full replacement text for each existing file, relative to the project config directory:
 
@@ -205,7 +217,7 @@ The request file contains full replacement text for each existing file, relative
 
 `docs plan` records the exact replacements and a SHA-256 digest of each original file. Each request edit can also include `baseDigest`, the lowercase SHA-256 digest of the UTF-8 source text used to write the candidate. If the current source differs, planning fails. Include this digest from the source your agent read before drafting. It refuses to overwrite an existing plan. The plan can be reviewed as JSON or with a diff tool. Edits can replace existing `.md`/`.mdx` files in the content directory and YAML files loaded by the config. Symlink targets and paths outside the project are rejected.
 
-`docs apply --check` verifies the original digests, copies the project to a temporary directory, inserts the proposed text, and builds the candidate site. It reports affected published document IDs and routes without changing the source. Run `docs apply` without `--check` to repeat validation and write the files. A stale digest or failed build stops the write. The command does not run configured `audit.tests`, commit, deploy, or establish that technical claims are correct. Run `shoalrun audit` and review the rendered pages before publication.
+`docs apply --check` verifies the original digests, copies the project to a temporary directory, inserts the proposed text, and builds the candidate site. It reports affected published document IDs and routes without changing the source. Run `docs apply` without `--check` to repeat validation and write the files. A stale digest or failed build stops the write. The command doesn't run configured `audit.tests`, commit, deploy, or establish that technical claims are correct. Run `shoalrun audit` and review the rendered pages before publication.
 
 ### `ingredient draft` and `recipe draft`
 
@@ -214,21 +226,21 @@ shoalrun ingredient draft --spec FILE --out FILE [--config FILE] [--check]
 shoalrun recipe draft --spec FILE --out FILE [--config FILE] [--check]
 ```
 
-`ingredient draft` takes a spec naming one explicitly configured API operation and a named inline request example. It copies the generated cURL request and first inline 2xx response example into a draft `type: ingredient` page. It supports outgoing requests in the default publication. `recipe draft` takes a project-owned spec with ordered ingredient file paths and assembles a draft `type: recipe` page for a customer goal. It rejects duplicate ingredient IDs and publication mismatches. Ingredients can declare `workflow.inputs`, `workflow.outputs`, `workflow.prerequisites`, and `workflow.check`; recipe specs can declare initial `inputs` and a final `outcome`. The assembler checks handoffs, rejects missing inputs and duplicate output names, and includes shared prerequisites once. Neither command executes a request or uses a model. See [assemble recipes from ingredients](https://www.shoalrun.com/author/recipe-drafts.md) for YAML fields and review workflow.
+`ingredient draft` takes a spec naming one explicitly configured API operation and a named inline request example. It copies the generated cURL request and first inline 2xx response example into a draft `type: ingredient` page. It supports outgoing requests in a selected publication. Ingredient and recipe specs can declare `publication: { product: payments, channel: production, version: v3, language: en }`; omitted product versions use that product’s default. Productless specs retain the legacy defaults. A products-only project needs an explicit product selection rather than an arbitrary first product. `recipe draft` takes a project-owned spec with ordered ingredient file paths and assembles a draft `type: recipe` page for a customer goal. It rejects duplicate ingredient IDs and publication mismatches. Ingredients can declare `workflow.inputs`, `workflow.outputs`, `workflow.prerequisites`, and `workflow.check`; recipe specs can declare initial `inputs` and a final `outcome`. The assembler checks handoffs, rejects missing inputs and duplicate output names, and includes shared prerequisites once. Neither command executes a request or uses a model. See [assemble recipes from ingredients](https://www.shoalrun.com/author/recipe-drafts.md) for YAML fields and review workflow.
 
-With `--check`, either command prints the proposed MDX and reports `would-create`, `unchanged`, or `would-change`; it writes nothing and does not build a preview. Without it, the command creates the output file and refuses to overwrite an existing one. A person or agent finishes and verifies the complete recipe before publication.
+With `--check`, either command prints the proposed MDX and reports `would-create`, `unchanged`, or `would-change`; it writes nothing and doesn't build a preview. Without it, the command creates the output file and refuses to overwrite an existing one. A person or agent finishes and verifies the complete recipe before publication.
 
 ## Inspect config and operations
 
 These commands print configuration and API operation details for inspection.
 
-| Command                                                                               | Prints                                                                                                                                                                                       |
-| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `shoalrun config validate [config]`                                                   | `status`, the config `digest`, the number of files read, and a `contrast` result for the palette and modes the site shows. Fails with the build's contrast messages when a color pair fails. |
-| `shoalrun config resolve [config]`                                                    | The fully merged config `value`, its `digest`, and the list of files read.                                                                                                                   |
-| `shoalrun config graph [config]`                                                      | The root file and every file it includes or extends.                                                                                                                                         |
-| `shoalrun config explain <key> [config]`                                              | The value at a dotted key, such as `site.title` or `navigation.0.id`, the file that set it, and the files it overrode.                                                                       |
-| `shoalrun operation inspect <id> [config] [--channel C] [--version V] [--language L]` | Each publication where a stable operation ID has a reference page.                                                                                                                           |
+| Command                                                                                             | Prints                                                                                                                                                                                       |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shoalrun config validate [config]`                                                                 | `status`, the config `digest`, the number of files read, and a `contrast` result for the palette and modes the site shows. Fails with the build's contrast messages when a color pair fails. |
+| `shoalrun config resolve [config]`                                                                  | The fully merged config `value`, its `digest`, and the list of files read.                                                                                                                   |
+| `shoalrun config graph [config]`                                                                    | The root file and every file it includes or extends.                                                                                                                                         |
+| `shoalrun config explain <key> [config]`                                                            | The value at a dotted key, such as `site.title` or `navigation.0.id`, the file that set it, and the files it overrode.                                                                       |
+| `shoalrun operation inspect <id> [config] [--product P] [--channel C] [--version V] [--language L]` | Each publication where a stable operation ID has a reference page.                                                                                                                           |
 
 `operation inspect` compiles the whole project without writing a site. When the operation isn't found in the selected publications, it prints `"status": "missing-variant"` and still exits with code 0. Put flags after the optional config path. An unknown or repeated flag fails before the project is compiled.
 
@@ -248,7 +260,7 @@ Run before pushing. Prints a readable PASS/FAIL summary; `--json` prints the str
 shoalrun audit [config]
 ```
 
-Runs the configured project audit, including enabled reference checks, focused contracts, test commands, and evaluation reports. Prints JSON and exits with code 1 when the audit fails. It does not call an authoring model or judge prose claims. See [audit settings](https://www.shoalrun.com/publish/audit.md).
+Runs the configured project audit, including enabled reference checks, focused contracts, test commands, and evaluation reports. Prints JSON and exits with code 1 when the audit fails. It doesn't call an authoring model or judge prose claims. See [audit settings](https://www.shoalrun.com/publish/audit.md).
 
 ### `api audit`
 
@@ -294,22 +306,22 @@ Builds a local candidate without requiring the current `publicReview.digest`. It
 ### `api materialize`
 
 ```sh
-shoalrun api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]
+shoalrun api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory] [--product P --channel C --version V --language L]
 ```
 
-Writes one-time draft MDX references from a registered local OpenAPI source. Repeat `--operation` and `--route` to select several endpoints; `--all` selects every endpoint and cannot be combined with selectors. `--route` uses an exact uppercase method and OpenAPI path. The default output is `content/api/<api-id>/`, and a custom output must stay inside the configured content directory. The JSON result lists written and skipped files. Existing matching pages are left untouched; conflicting files or unknown selectors stop the command. It does not alter config or navigation. See [Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) for the review and publishing workflow.
+Writes one-time draft MDX references from a registered local OpenAPI source. Repeat `--operation` and `--route` to select several endpoints; `--all` selects every endpoint and can't be combined with selectors. `--route` uses an exact uppercase method and OpenAPI path. Productless publications default to `content/api/<api-id>/`; product publications default to `content/api/<product>/<version>/<api-id>/`. A custom output must stay inside the configured content directory. The JSON result lists written and skipped files. Existing matching pages are left untouched; conflicting files or unknown selectors stop the command. It doesn't alter config or navigation. See [Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) for the review and publishing workflow.
 
 ### `api select`
 
 ```sh
-shoalrun api select <api-id> <config> --output <selection-file>
+shoalrun api select <api-id> <config> --output <selection-file> [--product P --channel C --version V --language L]
 ```
 
-Walks the default publication's OpenAPI operations and asks whether to generate a reference page for each. Answer `y` or `yes`, `n` or `no`, or press Enter to keep the current choice. `q` or `quit` cancels. Any other answer, or the end of input, cancels without writing. When every choice is made, it writes `pathPrefix` and an `include` list to the output file. See [generate and select API pages](https://www.shoalrun.com/api-docs/generate.md).
+Walks the selected publication’s OpenAPI operations and asks whether to generate a reference page for each. Answer `y` or `yes`, `n` or `no`, or press Enter to keep the current choice. `q` or `quit` cancels. Any other answer, or the end of input, cancels without writing. When every choice is made, it writes `pathPrefix` and an `include` list to the output file. See [generate and select API pages](https://www.shoalrun.com/api-docs/generate.md).
 
 ## npm scripts in this repository
 
-These scripts belong to Shoalrun's docs repository. Installing `@shoalrun/cli` in another project provides the `shoalrun` command; it does not add these npm scripts. Run the scripts below from the docs repository root.
+These scripts belong to Shoalrun's docs repository. Installing `@shoalrun/cli` in another project provides the `shoalrun` command; it doesn't add these npm scripts. Run the scripts below from the docs repository root.
 
 | Script                             | What it does                                                                                                         |
 | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
@@ -357,14 +369,14 @@ See [Passage index](https://www.shoalrun.com/chat/passage-index.md) for the chun
 shoalrun serve <site-directory> --search --config docs.config.yaml [--port PORT]
 ```
 
-Optional local preview for a custom browser search provider. Run `shoalrun build` and `shoalrun index` first. The server adds `/__shoalrun/search`, which returns page and section links from lexical passage retrieval or combines it with semantic retrieval when current vectors exist. It reads query embedding settings from `retrieval.embeddings` and the key from the environment. It runs only on a loopback address and accepts same-origin JSON requests. It does not add the chat panel or call a chat model. A site needs a [custom provider](https://www.shoalrun.com/author/search.md) to call the endpoint; the built-in search provider continues to use `/search-index.json`.
+Optional local preview for the included semantic browser search provider or a custom provider. Run `shoalrun build` and `shoalrun index` first. The server adds `/__shoalrun/search`, which returns page and section links from vector retrieval when current embeddings are available, with lexical fallback otherwise. It reads query embedding settings from `retrieval.embeddings` and the key from the environment. It runs only on a loopback address and accepts same-origin JSON requests. It doesn't add the chat panel or call a chat model. Set `outputs.html.search.provider: semantic` to use the included endpoint integration. The lexical browser provider continues to use `/search-index.json`; a [custom provider](https://www.shoalrun.com/author/search.md) can also call the endpoint.
 
 The local `serve --search` command is a preview server. The optional Vercel `--chat` build packages the same search handler as `/__shoalrun/search`, alongside `/__shoalrun/ask`, with shared rate and embedding budgets.
 
 ### `ask`
 
 ```sh
-shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]
+shoalrun ask <site-directory> "<question>" [--config FILE] [--model MODEL] [--passages N] [--reader-view FACET=CHOICE[,CHOICE]]... [--product P --channel C --version V --language L] [--no-rerank] [--no-direct] [--no-escalate] [--no-cards] [--json]
 ```
 
 Optional. It answers one question from your built docs, with citations. It needs a site that you have run [`shoalrun index`](#index) on, and a [`chat`](https://www.shoalrun.com/chat/settings.md) section in your config. The build doesn't need any of this, and skipping it changes nothing about your site. Quote the question.
@@ -373,27 +385,29 @@ The command searches the passages, using vector search too when the site has vec
 
 Standard error also shows how the answer was made: the search mode, the decision, the Jev score, the model, the tokens, and the time. Any layer that failed, such as Jev or the query embedding, is listed as a note, and the answer falls back to plain search. `--json` prints the full result as JSON instead, including every passage the model saw and the support score of every checked sentence.
 
-| Option                                 | Value                                                                                        |
-| -------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `--config`                             | The config to read. The default is `docs.config.yaml` in the current directory or a parent.  |
-| `--model`                              | Overrides `chat.model`.                                                                      |
-| `--passages`                           | Overrides `chat.passages`.                                                                   |
-| `--reader-view`                        | Overrides `chat.readerView`, as `facet=choice[,choice]`. Repeat it for more than one filter. |
-| `--channel`, `--version`, `--language` | The publication to search. Needed only when the site has more than one.                      |
-| `--no-rerank`                          | Skips Jev even when `chat.rerank` is set.                                                    |
-| `--no-direct`                          | Always uses the model, even when `chat.direct` would show an excerpt.                        |
-| `--no-escalate`                        | Skips the escalation model even when `chat.escalate` is set.                                 |
-| `--no-cards`                           | Skips answer cards even when `chat.cards` is set.                                            |
-| `--json`                               | Prints the result as JSON.                                                                   |
+| Option                                              | Value                                                                                                                                  |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `--config`                                          | The config to read. The default is `docs.config.yaml` in the current directory or a parent.                                            |
+| `--model`                                           | Overrides `chat.model`.                                                                                                                |
+| `--passages`                                        | Overrides `chat.passages`.                                                                                                             |
+| `--reader-view`                                     | Overrides `chat.readerView`, as `facet=choice[,choice]`. Repeat it for more than one filter.                                           |
+| `--product`, `--channel`, `--version`, `--language` | The publication to search. Needed when the built index doesn't identify one matching publication. Product versions remain independent. |
+| `--no-rerank`                                       | Skips Jev even when `chat.rerank` is set.                                                                                              |
+| `--no-direct`                                       | Always uses the model, even when `chat.direct` would show an excerpt.                                                                  |
+| `--no-escalate`                                     | Skips the escalation model even when `chat.escalate` is set.                                                                           |
+| `--no-cards`                                        | Skips answer cards even when `chat.cards` is set.                                                                                      |
+| `--json`                                            | Prints the result as JSON.                                                                                                             |
 
 The command answers one question at a time. It reads `OPENAI_API_KEY`, or the variable that `chat.keyEnv` names, and `JEV_API_KEY`, or the variable that `chat.rerank.keyEnv` names, when you use a scorer. It fails with a clear message when the chat section, the chat key, or `ai/chunks.json` is missing. Without the scorer's key, the scorer counts as down, as [chat settings](https://www.shoalrun.com/chat/settings.md) explain.
 
 ### `answers`
 
 ```sh
-shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--reader-view FACET=CHOICE[,CHOICE]]...
+shoalrun answers <site-directory> --questions FILE [--config FILE] [--model MODEL] [--product P --channel C --version V --language L] [--reader-view FACET=CHOICE[,CHOICE]]...
 ```
 
+Use the publication selectors to build cards for one product release. The command rejects ambiguous multi-product indexes; it doesn't combine products or infer a customer edition from a reader view.
+
 Optional. It builds [answer cards](https://www.shoalrun.com/chat/prepared-answers.md) from a list of questions and writes `ai/answers.json`. The list is YAML or JSON: plain strings, or mappings with `question` and `aliases`. It needs a site that you have indexed with `--embed`, and the same `chat` config as `ask`. This build step uses embeddings and the configured scorer. It calls the chat model for questions that pass the coverage gate. It never reuses a direct excerpt or another card. It embeds kept questions and aliases, then keeps only answers that passed every check. It prints JSON with the number of cards, the questions it skipped and why, and the output path. It replaces any earlier file, so keep the question list in your repository and rerun it after the docs change.
 
 ### `ask-log`
@@ -425,7 +439,7 @@ Optional. It serves a built and indexed site with a local chat panel, so you can
 This is a local preview and nothing more:
 
 - It runs only on a loopback address (`127.0.0.1`, `localhost`, or `::1`), because every question spends your API credits. It refuses `--host 0.0.0.0` and any other address.
-- `serve --ask` adds the panel and the `/__shoalrun/ask` endpoint for local preview. `shoalrun vercel build --chat` adds the hosted panel and function. Ordinary `build` and `dev` do not add chat.
+- `serve --ask` adds the panel and the `/__shoalrun/ask` endpoint for local preview. `shoalrun vercel build --chat` adds the hosted panel and function. Ordinary `build` and `dev` don't add chat.
 - The endpoint refuses requests from other web sites and from unknown host names, requires JSON, caps the request size, and allows 20 questions a minute.
 
 It reads the same `chat` and `retrieval` config as `ask`, and the keys from the environment. Stop it with the usual interrupt.
@@ -434,7 +448,7 @@ It reads the same `chat` and `retrieval` config as `ask`, and the keys from the
 
 `docs project` discovers pages, guidance, configuration, navigation, relationships, templates, and findings without selecting a page. `docs source FILE` reads bounded project-relative source passages. Both return JSON and accept `--config FILE`.
 
-`docs baseline --out FILE` records the current working tree. `docs validate` checks a separate capture using a baseline or explicit file/page selectors. `docs validation-status REPORT` checks whether a retained result still applies. `docs review REPORT` presents that snapshot as JSON or Markdown. `docs preview REPORT` serves its exact build locally and returns a browser review URL plus affected HTML/Markdown URLs. These tools make no authoring provider calls and do not apply or publish edits.
+`docs baseline --out FILE` records the current working tree. `docs validate` checks a separate capture using a baseline or explicit file/page selectors. `docs validation-status REPORT` checks whether a retained result still applies. `docs review REPORT` presents that snapshot as JSON or Markdown. `docs preview REPORT` serves its exact build locally and returns a browser review URL plus affected HTML/Markdown URLs. These tools make no authoring provider calls and don't apply or publish edits.
 
 See [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) for selectors, budgets, artifact paths, statuses, and check execution limits. Follow [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) for a complete procedure. Existing context/plan/apply commands remain supported.
 

package/agent-docs/cli.sections/audit-a-project-and-api-sources.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/cli.md)
 
@@ -24,7 +24,11 @@ The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Nod
 
 Commands that return data print JSON to standard output. On an error, the CLI prints `{"status":"error","message":"..."}` to standard error and exits with code 1. A config argument defaults to `docs.config.yaml` in the current directory unless noted.
 
-[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs do not need it.
+[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs don't need it.
+
+Since 0.1.0-alpha.18
+
+Product selectors, `dev --profile`, and `get_publications` discovery add product-aware workflows. Existing productless commands keep their publication scope.
 
 ## Audit a project and API sources
 
@@ -42,7 +46,7 @@ Run before pushing. Prints a readable PASS/FAIL summary; `--json` prints the str
 shoalrun audit [config]
 ```
 
-Runs the configured project audit, including enabled reference checks, focused contracts, test commands, and evaluation reports. Prints JSON and exits with code 1 when the audit fails. It does not call an authoring model or judge prose claims. See [audit settings](https://www.shoalrun.com/publish/audit.md).
+Runs the configured project audit, including enabled reference checks, focused contracts, test commands, and evaluation reports. Prints JSON and exits with code 1 when the audit fails. It doesn't call an authoring model or judge prose claims. See [audit settings](https://www.shoalrun.com/publish/audit.md).
 
 ### `api audit`
 
@@ -88,15 +92,15 @@ Builds a local candidate without requiring the current `publicReview.digest`. It
 ### `api materialize`
 
 ```sh
-shoalrun api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory]
+shoalrun api materialize <api-id> <config> (--all | --operation ID | --route "METHOD /path")... [--output content/subdirectory] [--product P --channel C --version V --language L]
 ```
 
-Writes one-time draft MDX references from a registered local OpenAPI source. Repeat `--operation` and `--route` to select several endpoints; `--all` selects every endpoint and cannot be combined with selectors. `--route` uses an exact uppercase method and OpenAPI path. The default output is `content/api/<api-id>/`, and a custom output must stay inside the configured content directory. The JSON result lists written and skipped files. Existing matching pages are left untouched; conflicting files or unknown selectors stop the command. It does not alter config or navigation. See [Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) for the review and publishing workflow.
+Writes one-time draft MDX references from a registered local OpenAPI source. Repeat `--operation` and `--route` to select several endpoints; `--all` selects every endpoint and can't be combined with selectors. `--route` uses an exact uppercase method and OpenAPI path. Productless publications default to `content/api/<api-id>/`; product publications default to `content/api/<product>/<version>/<api-id>/`. A custom output must stay inside the configured content directory. The JSON result lists written and skipped files. Existing matching pages are left untouched; conflicting files or unknown selectors stop the command. It doesn't alter config or navigation. See [Generate and select API pages](https://www.shoalrun.com/api-docs/generate.md) for the review and publishing workflow.
 
 ### `api select`
 
 ```sh
-shoalrun api select <api-id> <config> --output <selection-file>
+shoalrun api select <api-id> <config> --output <selection-file> [--product P --channel C --version V --language L]
 ```
 
-Walks the default publication's OpenAPI operations and asks whether to generate a reference page for each. Answer `y` or `yes`, `n` or `no`, or press Enter to keep the current choice. `q` or `quit` cancels. Any other answer, or the end of input, cancels without writing. When every choice is made, it writes `pathPrefix` and an `include` list to the output file. See [generate and select API pages](https://www.shoalrun.com/api-docs/generate.md).
+Walks the selected publication’s OpenAPI operations and asks whether to generate a reference page for each. Answer `y` or `yes`, `n` or `no`, or press Enter to keep the current choice. `q` or `quit` cancels. Any other answer, or the end of input, cancels without writing. When every choice is made, it writes `pathPrefix` and an `include` list to the output file. See [generate and select API pages](https://www.shoalrun.com/api-docs/generate.md).

package/agent-docs/cli.sections/author-pages.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/cli.md)
 
@@ -24,7 +24,11 @@ The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Nod
 
 Commands that return data print JSON to standard output. On an error, the CLI prints `{"status":"error","message":"..."}` to standard error and exits with code 1. A config argument defaults to `docs.config.yaml` in the current directory unless noted.
 
-[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs do not need it.
+[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs don't need it.
+
+Since 0.1.0-alpha.18
+
+Product selectors, `dev --profile`, and `get_publications` discovery add product-aware workflows. Existing productless commands keep their publication scope.
 
 ## Author pages
 
@@ -46,12 +50,12 @@ shoalrun scaffold <template> <config> <target-file> --id ID --title TITLE --summ
 
 The short form finds `docs.config.yaml` in the current directory or a parent, and derives the ID, title, summary, and slug from the target path. `--new` is the same as `-n`.
 
-| Option                                   | Meaning                                                                                                                                  |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `--config FILE`                          | Config file to use (short form only).                                                                                                    |
-| `--id`, `--title`, `--summary`, `--slug` | Page values. Required in the explicit form; they override derived values in the short form.                                              |
-| `--channel`, `--version`, `--language`   | Publication. Defaults come from `publications.defaults`; the combination must be enabled.                                                |
-| `--operation ID`                         | A stable operation ID for the page. Repeat it for several. It must be an operation declared in `apis.*.operations`, not a generated one. |
+| Option                                              | Meaning                                                                                                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--config FILE`                                     | Config file to use (short form only).                                                                                                                  |
+| `--id`, `--title`, `--summary`, `--slug`            | Page values. Required in the explicit form; they override derived values in the short form.                                                            |
+| `--product`, `--channel`, `--version`, `--language` | Publication. A selected product uses its own default version; productless defaults come from `publications.defaults`. The combination must be enabled. |
+| `--operation ID`                                    | A stable operation ID for the page. Repeat it for several. It must be an operation declared in `apis.*.operations`, not a generated one.               |
 
 The target must be a `.md` or `.mdx` file inside the content directory, and must not exist yet. The slug must start with `/`. The new page has draft access. Prints the template, page ID, file path, publication, and access. See [templates](https://www.shoalrun.com/author/templates.md) for how values are derived.
 
@@ -66,7 +70,7 @@ shoalrun docs apply edit-plan.json [--config docs.config.yaml] --check
 shoalrun docs apply edit-plan.json [--config docs.config.yaml]
 ```
 
-`docs context` reports a stable page ID's authored sources and digests, navigation placements, relationships, and configuration owners. It also returns configured authoring directives and guide and exemplar paths. It does not return a generated API reference as an authored page.
+`docs context` reports a stable page ID's authored sources and digests, navigation placements, relationships, and configuration owners. It also returns configured authoring directives and guide and exemplar paths. It doesn't return a generated API reference as an authored page.
 
 The request file contains full replacement text for each existing file, relative to the project config directory:
 
@@ -80,7 +84,7 @@ The request file contains full replacement text for each existing file, relative
 
 `docs plan` records the exact replacements and a SHA-256 digest of each original file. Each request edit can also include `baseDigest`, the lowercase SHA-256 digest of the UTF-8 source text used to write the candidate. If the current source differs, planning fails. Include this digest from the source your agent read before drafting. It refuses to overwrite an existing plan. The plan can be reviewed as JSON or with a diff tool. Edits can replace existing `.md`/`.mdx` files in the content directory and YAML files loaded by the config. Symlink targets and paths outside the project are rejected.
 
-`docs apply --check` verifies the original digests, copies the project to a temporary directory, inserts the proposed text, and builds the candidate site. It reports affected published document IDs and routes without changing the source. Run `docs apply` without `--check` to repeat validation and write the files. A stale digest or failed build stops the write. The command does not run configured `audit.tests`, commit, deploy, or establish that technical claims are correct. Run `shoalrun audit` and review the rendered pages before publication.
+`docs apply --check` verifies the original digests, copies the project to a temporary directory, inserts the proposed text, and builds the candidate site. It reports affected published document IDs and routes without changing the source. Run `docs apply` without `--check` to repeat validation and write the files. A stale digest or failed build stops the write. The command doesn't run configured `audit.tests`, commit, deploy, or establish that technical claims are correct. Run `shoalrun audit` and review the rendered pages before publication.
 
 ### `ingredient draft` and `recipe draft`
 
@@ -89,6 +93,6 @@ shoalrun ingredient draft --spec FILE --out FILE [--config FILE] [--check]
 shoalrun recipe draft --spec FILE --out FILE [--config FILE] [--check]
 ```
 
-`ingredient draft` takes a spec naming one explicitly configured API operation and a named inline request example. It copies the generated cURL request and first inline 2xx response example into a draft `type: ingredient` page. It supports outgoing requests in the default publication. `recipe draft` takes a project-owned spec with ordered ingredient file paths and assembles a draft `type: recipe` page for a customer goal. It rejects duplicate ingredient IDs and publication mismatches. Ingredients can declare `workflow.inputs`, `workflow.outputs`, `workflow.prerequisites`, and `workflow.check`; recipe specs can declare initial `inputs` and a final `outcome`. The assembler checks handoffs, rejects missing inputs and duplicate output names, and includes shared prerequisites once. Neither command executes a request or uses a model. See [assemble recipes from ingredients](https://www.shoalrun.com/author/recipe-drafts.md) for YAML fields and review workflow.
+`ingredient draft` takes a spec naming one explicitly configured API operation and a named inline request example. It copies the generated cURL request and first inline 2xx response example into a draft `type: ingredient` page. It supports outgoing requests in a selected publication. Ingredient and recipe specs can declare `publication: { product: payments, channel: production, version: v3, language: en }`; omitted product versions use that product’s default. Productless specs retain the legacy defaults. A products-only project needs an explicit product selection rather than an arbitrary first product. `recipe draft` takes a project-owned spec with ordered ingredient file paths and assembles a draft `type: recipe` page for a customer goal. It rejects duplicate ingredient IDs and publication mismatches. Ingredients can declare `workflow.inputs`, `workflow.outputs`, `workflow.prerequisites`, and `workflow.check`; recipe specs can declare initial `inputs` and a final `outcome`. The assembler checks handoffs, rejects missing inputs and duplicate output names, and includes shared prerequisites once. Neither command executes a request or uses a model. See [assemble recipes from ingredients](https://www.shoalrun.com/author/recipe-drafts.md) for YAML fields and review workflow.
 
-With `--check`, either command prints the proposed MDX and reports `would-create`, `unchanged`, or `would-change`; it writes nothing and does not build a preview. Without it, the command creates the output file and refuses to overwrite an existing one. A person or agent finishes and verifies the complete recipe before publication.
+With `--check`, either command prints the proposed MDX and reports `would-create`, `unchanged`, or `would-change`; it writes nothing and doesn't build a preview. Without it, the command creates the output file and refuses to overwrite an existing one. A person or agent finishes and verifies the complete recipe before publication.