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

package/agent-docs/content-delivery/agents.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 > Content delivery and agents
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Content delivery and documentation discovery serve different reading tasks. Delivery gives an application a reviewed collection of resources. Discovery helps an agent find and read documentation across a published site or installed snapshot.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Content delivery and documentation discovery serve different reading tasks. Delivery gives an application a reviewed collection of resources. Discovery helps an agent find and read documentation across a published site or installed snapshot.
 
 ## Choose the reading contract
 
@@ -34,7 +34,7 @@ Match the interface to the task and the context it must retain.
 | Find documentation by a question or topic     | Existing documentation search and discovery indexes |
 | Read a page or contextual section through MCP | Existing documentation MCP tools                    |
 
-An export does not automatically create a search service or MCP server. The content client lists and reads resources; it does not rank them or generate answers. For an HTTP integration, use the [REST resource routes](https://www.shoalrun.com/content-delivery/http-api.md) or `openRestContentSource` with the same snapshot reading methods.
+An export doesn't automatically create a search service or MCP server. The content client lists and reads resources; it doesn't rank them or generate answers. For an HTTP integration, use the [REST resource routes](https://www.shoalrun.com/content-delivery/http-api.md) or `openRestContentSource` with the same snapshot reading methods.
 
 ## Read Markdown for an agent
 
@@ -61,7 +61,7 @@ In Node.js, use an absolute URL. Browser integrations must serve the export from
 
 ## Keep context explicit
 
-Application section fragments use `{ id, context: section }` approval and explicit export selection. They contain the section slice plus required notices and referenced definitions. They can exist on short pages where no heuristic discovery section is generated. An application fragment is not a replacement for the MCP section's context contract.
+Application section fragments use `{ id, context: section }` approval and explicit export selection. They contain the section slice plus required notices and referenced definitions. They can exist on short pages where no heuristic discovery section is generated. An application fragment isn't a replacement for the MCP section's context contract.
 
 Discovery sections can include the page introduction, nested subsections, and reading-path context. Their generation also depends on page and section size. Existing title-string approvals retain that behavior; see [compatibility guidance](https://www.shoalrun.com/content-delivery/sections.md) before changing them.
 
@@ -69,7 +69,7 @@ Discovery sections can include the page introduction, nested subsections, and re
 
 Use the resource's typed reference and publication. Section IDs can be derived from headings or fixed by an explicit marker. A marker stays out of Markdown prose; metadata carries the identity. Follow the returned representation URL or use `snapshot.get` rather than constructing a Markdown anchor from the ID.
 
-A full-page fallback can help when a fragment does not answer the question. It must refer to an eligible published destination or an exported page; it is not permission to read drafts or private source files.
+A full-page fallback can help when a fragment doesn't answer the question. It must refer to an eligible published destination or an exported page; it isn't permission to read drafts or private source files.
 
 ## HTML, Markdown, and agents
 

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

@@ -17,11 +17,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content client API
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Import the browser-safe delivery API from `@shoalrun/cli/content`. It reads exports and mounts trusted HTML without loading the compiler. Browser use requires HTTPS or localhost for Web Crypto.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Import the browser-safe delivery API from `@shoalrun/cli/content`. It reads exports and mounts trusted HTML without loading the compiler. Browser use requires HTTPS or localhost for Web Crypto.
 
 ## Open a source
 
@@ -50,19 +50,32 @@ openRestContentSource(options): Promise<ContentSnapshot>
 
 `RestContentSourceOptions` accepts `baseUrl`, a required `{ channel, version, language }` publication, and an optional `revision`. It also accepts the same `fetch`, `signal`, and `limits` options as the manifest source. `limits.manifestBytes` bounds the JSON inventory response. Opening fetches that inventory and pins subsequent reads to its revision.
 
-Browser URLs must share the application's origin. Outside a browser, provide an absolute HTTP(S) URL. The base URL must omit credentials, query strings, and fragments. `contentResourceKey(ref)` returns a REST resource key; it is distinct from the local comparison key returned by `contentRefKey(ref)`. See the [HTTP reference](https://www.shoalrun.com/content-delivery/http-api.md) for routes and response types.
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+For a product-scoped source, pass `{ product, channel, version, language }` as `publication`. The client sends `product` on inventory and resource requests and rejects responses for a different product. Productless responses use envelope `schemaVersion: 1`; product responses use `schemaVersion: 2`. Both use the `/content/v1` protocol path.
+
+```ts
+const snapshot = await openRestContentSource({
+  baseUrl: '/content/v1',
+  publication: { product: 'payments', channel: 'production', version: 'v3', language: 'en' },
+});
+```
+
+Browser URLs must share the application's origin. Outside a browser, provide an absolute HTTP(S) URL. The base URL must omit credentials, query strings, and fragments. `contentResourceKey(ref)` returns a REST resource key; it's distinct from the local comparison key returned by `contentRefKey(ref)`. See the [HTTP reference](https://www.shoalrun.com/content-delivery/http-api.md) for routes and response types.
 
 ## Read a snapshot
 
 A snapshot exposes the following members for one opened revision.
 
-| Member                          | Contract                                            |
-| ------------------------------- | --------------------------------------------------- |
-| `revision`                      | Opened manifest digest                              |
-| `publication`                   | Channel, version, and language                      |
-| `list()`                        | Read-only resource metadata for this revision       |
-| `get(ref, { format, signal? })` | Promise for a checked HTML or Markdown result       |
-| `dispose()`                     | Cancel the snapshot lifetime and refuse later reads |
+| Member                          | Contract                                                                        |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| `revision`                      | Opened manifest digest                                                          |
+| `publication`                   | Channel, version, and language; product-scoped snapshots also include `product` |
+| `list()`                        | Read-only resource metadata for this revision                                   |
+| `get(ref, { format, signal? })` | Promise for a checked HTML or Markdown result                                   |
+| `dispose()`                     | Cancel the snapshot lifetime and refuse later reads                             |
 
 ```ts
 type ContentRef =
@@ -71,9 +84,9 @@ type ContentRef =
   | { kind: 'snippet'; id: string };
 ```
 
-`list()` is synchronous because opening a source loads and freezes its metadata. Each `get()` fetches and checks UTF-8, media type, byte count, and SHA-256 against that revision; the client does not cache response bodies. `dispose()` is idempotent, aborts active reads, and makes later `list()` and `get()` calls fail. The opening signal affects only opening; use the per-read signal or `dispose()` for subsequent reads.
+`list()` is synchronous because opening a source loads and freezes its metadata. Each `get()` fetches and checks UTF-8, media type, byte count, and SHA-256 against that revision; the client doesn't cache response bodies. `dispose()` is idempotent, aborts active reads, and makes later `list()` and `get()` calls fail. The opening signal affects only opening; use the per-read signal or `dispose()` for subsequent reads.
 
-A `ContentResult` contains `resource`, `representation`, `format`, `content`, and `revision`. `contentRefKey(ref)` returns a key for comparing typed references. It is not a URL or authorization decision.
+A `ContentResult` contains `resource`, `representation`, `format`, `content`, and `revision`. `contentRefKey(ref)` returns a key for comparing typed references. It isn't a URL or authorization decision.
 
 ## Validate a manifest
 
@@ -81,7 +94,7 @@ A `ContentResult` contains `resource`, `representation`, `format`, `content`, an
 validateContentManifest(value, maxResources = 10_000, maxResourceBytes = 8_000_000): asserts value is ContentManifest
 ```
 
-This exported helper checks structure, inventory limits, and approved review metadata. It does not fetch files or verify the manifest digest. Use `openManifestContentSource` for the complete loading and integrity checks. See the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md) for `ContentResource`, `ContentRepresentation`, `ContentAnchor`, and `ContentLink` fields.
+This exported helper checks structure, inventory limits, and approved review metadata. It doesn't fetch files or verify the manifest digest. Use `openManifestContentSource` for the complete loading and integrity checks. See the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md) for `ContentResource`, `ContentRepresentation`, `ContentAnchor`, and `ContentLink` fields.
 
 ## Mount HTML
 
@@ -91,7 +104,7 @@ mountContent(container, result, { instanceId?, signal? })
 
 The result must be HTML from a trusted export. Mounting replaces the container's children, assigns instance-specific DOM IDs, and rewrites local ID references. The returned `ContentMount` contains `anchors`, `links`, and `unmount()`. See [render content](https://www.shoalrun.com/content-delivery/render.md) for ownership and routing.
 
-`instanceId` is optional; the default uses a random UUID. A supplied ID must start with an ASCII letter and contain at most 128 letters, numbers, underscores, or hyphens. Use a different ID for each simultaneous mount. `anchors` maps original anchor IDs to mounted DOM IDs, while `links` carries routing metadata. `signal` cancels before insertion; aborting it after mounting does not remove content. Call `unmount()` to remove only nodes still owned by that mount.
+`instanceId` is optional; the default uses a random UUID. A supplied ID must start with an ASCII letter and contain at most 128 letters, numbers, underscores, or hyphens. Use a different ID for each simultaneous mount. `anchors` maps original anchor IDs to mounted DOM IDs, while `links` carries routing metadata. `signal` cancels before insertion; aborting it after mounting doesn't remove content. Call `unmount()` to remove only nodes still owned by that mount.
 
 ## Errors
 
@@ -115,7 +128,7 @@ Cancellation can propagate the signal's abort reason instead of a `ContentDelive
 
 ## HTML, Markdown, and agents
 
-The same typed reference selects either available representation. HTML mounting is optional and separate from retrieval. Agents can read Markdown and metadata through the client without a DOM. Digests detect mismatched bytes; they do not establish that an unknown publisher's content is trustworthy.
+The same typed reference selects either available representation. HTML mounting is optional and separate from retrieval. Agents can read Markdown and metadata through the client without a DOM. Digests detect mismatched bytes; they don't establish that an unknown publisher's content is trustworthy.
 
 ## Related reading
 

package/agent-docs/content-delivery/client.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 > Read content with a client
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
 
-Use the content client in an application to read a static export. Serve the bundle from the application's origin and use your normal JavaScript build tooling to import `@shoalrun/cli/content`.
+**Available since: 0.1.0-alpha.13.**
 
-Available since `0.1.0-alpha.13`.
+Use the content client in an application to read a static export. Serve the bundle from the application's origin and use your normal JavaScript build tooling to import `@shoalrun/cli/content`.
 
 ## Open a revision
 
@@ -33,11 +33,17 @@ const snapshot = await openManifestContentSource({
 });
 ```
 
-Use an absolute HTTP(S) URL outside a browser. In a browser, the manifest must share the application's origin. Its location must match the export's `publicBase`. The client does not accept URL credentials, query parameters, or fragments in the manifest URL.
+Use an absolute HTTP(S) URL outside a browser. In a browser, the manifest must share the application's origin. Its location must match the export's `publicBase`. The client doesn't accept URL credentials, query parameters, or fragments in the manifest URL.
 
 Browser use requires HTTPS or localhost because integrity checks use Web Crypto.
 
-Opening fetches and validates the manifest once. `snapshot.revision` identifies that opened revision; it does not track a moving latest pointer.
+Opening fetches and validates the manifest once. `snapshot.revision` identifies that opened revision; it doesn't track a moving latest pointer.
+
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+The content client accepts productless v1 manifests and product-scoped v2 manifests. A v2 manifest declares `{ product, channel, version, language }`; the client checks that every resource belongs to that same publication. Read `snapshot.publication` when retaining a resource reference. Open separate snapshots for different product releases, even when their document IDs match.
 
 ## Read a resource
 
@@ -50,15 +56,15 @@ const result = await snapshot.get(
 console.log(result.content);
 ```
 
-A result includes resource metadata, representation metadata, format, content, and revision. The client verifies representation size and SHA-256 digest before returning content. It does not evaluate MDX, interpolate variables, or run components in the browser.
+A result includes resource metadata, representation metadata, format, content, and revision. The client verifies representation size and SHA-256 digest before returning content. It doesn't evaluate MDX, interpolate variables, or run components in the browser.
 
 ## Handle changes and cancellation
 
 Pass an `AbortSignal` to an individual `get` to cancel obsolete navigation. Call `snapshot.dispose()` when the application stops using the revision. A disposed snapshot refuses further reads.
 
-If a representation is missing or differs from the opened manifest, the client reports `stale_revision`. Keep the current display, open a complete replacement revision, and retry deliberately. Do not combine resource lists from one revision with files from another.
+If a representation is missing or differs from the opened manifest, the client reports `stale_revision`. Keep the current display, open a complete replacement revision, and retry deliberately. Don't combine resource lists from one revision with files from another.
 
-A custom `fetch` function can integrate the application's request handling. It does not bypass same-origin, content-type, size, or digest checks. Use [openRestContentSource](https://www.shoalrun.com/content-delivery/rest.md) for the same `ContentSnapshot` contract over HTTP.
+A custom `fetch` function can integrate the application's request handling. It doesn't bypass same-origin, content-type, size, or digest checks. Use [openRestContentSource](https://www.shoalrun.com/content-delivery/rest.md) for the same `ContentSnapshot` contract over HTTP.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/content-delivery/http-api/operations/get-content-representation-fa1d2e3f.md

@@ -16,11 +16,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content REST API > Other > Read HTML or Markdown
 
-**Updated: 2026-09-27.**
+**Updated: 2026-11-05.**
 
 This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
 
-OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-getcontentrepresentation-63a66b7a4eae1e1befb0ade4fd57d8346e3a5548cb933c1718acc72a9ab3ceed.json).
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-getcontentrepresentation-5f3ded6e0382f20faab3224a94d604d8a7d0f129f9faad445649d00ec643752c.json).
 
 ## GET /resources/{key}/representations/{format}
 
@@ -64,6 +64,14 @@ string; minLength: 1; maxLength: 2048
 
 **Default example**: `"en"`
 
+#### product (query)
+
+Optional
+
+Exact product ID. Required for product-scoped publications; omitted selects only a legacy productless publication. No cross-product fallback.
+
+string; minLength: 1; maxLength: 2048
+
 #### revision (query)
 
 Required

package/agent-docs/content-delivery/http-api/operations/get-content-representation-head-4052375c.md

@@ -16,11 +16,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content REST API > Other > Read HTML or Markdown headers
 
-**Updated: 2026-10-28.**
+**Updated: 2026-11-05.**
 
 This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
 
-OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-getcontentrepresentationhead-6325b1c205226b5695592ad06bf1bdc1e1da03febe3b6645866d4910f500491b.json).
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-getcontentrepresentationhead-411643fba63a7f592d35aa2e6e534ecf56ef8ddbd901d5f8648b9b8a2ca2d403.json).
 
 ## HEAD /resources/{key}/representations/{format}
 
@@ -64,6 +64,14 @@ string; minLength: 1; maxLength: 2048
 
 **Default example**: `"en"`
 
+#### product (query)
+
+Optional
+
+Exact product ID. Required for product-scoped publications; omitted selects only a legacy productless publication. No cross-product fallback.
+
+string; minLength: 1; maxLength: 2048
+
 #### revision (query)
 
 Required