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

package/agent-docs/content-delivery/http-api/operations/list-content-resources-8e977ec7.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 > List resource metadata
 
-**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-listcontentresources-b664cb30bd0fc4c2a4b13ada9e7591355af7d9f084fa9def4c21b785fece1861.json).
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-listcontentresources-6cd53f1112313a9e12ab865afaf4544035bfe61a87fb1c592ef68ae43d004a87.json).
 
 ## GET /resources
 
@@ -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)
 
 Optional
@@ -119,6 +127,12 @@ Serialization: simple; explode: false.
 
 string
 
+The response has exactly one of these shapes:
+
+**Shape 1** · 4 properties
+
+object
+
 4 properties
 
 - `schemaVersion` `number` **always present** 
@@ -165,7 +179,7 @@ string
 
     - `publication` `object` **always present** 
 
-      3 properties
+      4 properties
 
       - `channel` `string` **always present** 
 
@@ -179,6 +193,534 @@ string
 
         minLength: 1
 
+      - `product` `string` **may be absent** 
+
+        minLength: 1
+
+      Additional properties: not allowed.
+
+    - `title` `string` **always present** 
+
+    - `summary` `string` **always present** 
+
+    - `type` `string` **always present** 
+
+    - `canonicalUrl` `string` **may be absent** 
+
+      format: uri
+
+    - `representations` `object` **always present** 
+
+      minProperties: 1
+
+      2 properties
+
+      - `html` `object` **may be absent** 
+
+        6 properties
+
+        - `path` `string` **always present** 
+
+          pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+        - `bytes` `integer` **always present** 
+
+          minimum: 0
+
+        - `digest` `string` **always present** 
+
+          pattern: ^\[a-f0-9]{64}$
+
+        - `mediaType` `string` **always present** 
+
+        - `anchors` `list of object` **always present** 
+
+          Array items:
+
+          object
+
+          3 properties
+
+          - `id` `string` **always present** 
+
+          - `exportedId` `string` **always present** 
+
+          - `title` `string` **may be absent** 
+
+          Additional properties: not allowed.
+
+        - `links` `list of one of several types` **always present** 
+
+          Array items:
+
+          The response has exactly one of these shapes:
+
+          **Shape 1** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present** 
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"resource"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `ref` `one of several types` **always present**&#x20;
+
+            The response has exactly one of these shapes:
+
+            **Shape 1** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "page"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            Additional properties: not allowed.
+
+            **Shape 2** · 3 properties
+
+            object
+
+            3 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "section"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            - `sectionId` `string` **always present**&#x20;
+
+              pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+            Additional properties: not allowed.
+
+            **Shape 3** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "snippet"
+
+            - `id` `string` **always present**&#x20;
+
+              pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+            Additional properties: not allowed.
+
+          Additional properties: not allowed.
+
+          **Shape 2** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"asset"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `asset` `string` **always present**&#x20;
+
+            pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+          Additional properties: not allowed.
+
+          **Shape 3** · 5 properties
+
+          object
+
+          5 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"canonical"`, `"external"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        Additional properties: not allowed.
+
+      - `markdown` `object` **may be absent**&#x20;
+
+        6 properties
+
+        - `path` `string` **always present**&#x20;
+
+          pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+        - `bytes` `integer` **always present**&#x20;
+
+          minimum: 0
+
+        - `digest` `string` **always present**&#x20;
+
+          pattern: ^\[a-f0-9]{64}$
+
+        - `mediaType` `string` **always present**&#x20;
+
+        - `anchors` `list of object` **always present**&#x20;
+
+          Array items:
+
+          object
+
+          3 properties
+
+          - `id` `string` **always present**&#x20;
+
+          - `exportedId` `string` **always present**&#x20;
+
+          - `title` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        - `links` `list of one of several types` **always present**&#x20;
+
+          Array items:
+
+          The response has exactly one of these shapes:
+
+          **Shape 1** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"resource"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `ref` `one of several types` **always present**&#x20;
+
+            The response has exactly one of these shapes:
+
+            **Shape 1** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "page"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            Additional properties: not allowed.
+
+            **Shape 2** · 3 properties
+
+            object
+
+            3 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "section"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            - `sectionId` `string` **always present**&#x20;
+
+              pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+            Additional properties: not allowed.
+
+            **Shape 3** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "snippet"
+
+            - `id` `string` **always present**&#x20;
+
+              pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+            Additional properties: not allowed.
+
+          Additional properties: not allowed.
+
+          **Shape 2** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"asset"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `asset` `string` **always present**&#x20;
+
+            pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+          Additional properties: not allowed.
+
+          **Shape 3** · 5 properties
+
+          object
+
+          5 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"canonical"`, `"external"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        Additional properties: not allowed.
+
+      Additional properties: not allowed.
+
+    - `assets` `list of string` **always present**&#x20;
+
+      uniqueItems: true
+
+      Array items:
+
+      string; pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+    - `externalDependencies` `list of object` **always present**&#x20;
+
+      Array items:
+
+      object
+
+      2 properties
+
+      - `url` `string` **always present**&#x20;
+
+        format: uri
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "image"
+
+      Additional properties: not allowed.
+
+    - `ref` `one of several types` **always present**&#x20;
+
+      The response has exactly one of these shapes:
+
+      **Shape 1** · 2 properties
+
+      object
+
+      2 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "page"
+
+      - `documentId` `string` **always present**&#x20;
+
+        minLength: 1
+
+      Additional properties: not allowed.
+
+      **Shape 2** · 3 properties
+
+      object
+
+      3 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "section"
+
+      - `documentId` `string` **always present**&#x20;
+
+        minLength: 1
+
+      - `sectionId` `string` **always present**&#x20;
+
+        pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+      Additional properties: not allowed.
+
+      **Shape 3** · 2 properties
+
+      object
+
+      2 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "snippet"
+
+      - `id` `string` **always present**&#x20;
+
+        pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+      Additional properties: not allowed.
+
+    - `source` `object` **may be absent**&#x20;
+
+      minProperties: 1
+
+      3 properties
+
+      - `documentId` `string` **may be absent**&#x20;
+
+        minLength: 1
+
+      - `snippetId` `string` **may be absent**&#x20;
+
+        minLength: 1
+
+      - `valuesDigest` `string` **may be absent**&#x20;
+
+        pattern: ^\[a-f0-9]{64}$
+
+      Additional properties: not allowed.
+
+    Additional properties: not allowed.
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+**Shape 2** · 4 properties
+
+object
+
+4 properties
+
+- `schemaVersion` `number` **always present**&#x20;
+
+  const: 2
+
+- `revision` `string` **always present**&#x20;
+
+  pattern: ^\[a-f0-9]{64}$
+
+- `publication` `object` **always present**&#x20;
+
+  4 properties
+
+  - `channel` `string` **always present**&#x20;
+
+    minLength: 1
+
+  - `version` `string` **always present**&#x20;
+
+    minLength: 1
+
+  - `language` `string` **always present**&#x20;
+
+    minLength: 1
+
+  - `product` `string` **always present**&#x20;
+
+    minLength: 1
+
+  Additional properties: not allowed.
+
+- `resources` `list of object` **always present**&#x20;
+
+  Array items:
+
+  2 properties
+
+  - `key` `string` **always present**&#x20;
+
+    Opaque stable typed-reference key. Use the returned key. It is k\_ followed by unpadded base64url of UTF-8 JSON for \["page",documentId], \["section",documentId,sectionId], or \["snippet",id]. Publication and revision are separate selectors.
+
+    pattern: ^k\_\[A-Za-z0-9\_-]+$
+
+  - `resource` `object` **always present**&#x20;
+
+    10 properties
+
+    - `publication` `object` **always present**&#x20;
+
+      4 properties
+
+      - `channel` `string` **always present**&#x20;
+
+        minLength: 1
+
+      - `version` `string` **always present**&#x20;
+
+        minLength: 1
+
+      - `language` `string` **always present**&#x20;
+
+        minLength: 1
+
+      - `product` `string` **may be absent**&#x20;
+
+        minLength: 1
+
       Additional properties: not allowed.
 
     - `title` `string` **always present**&#x20;

package/agent-docs/content-delivery/http-api/operations/list-content-resources-head-b67cbad9.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 > List resource metadata 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-listcontentresourceshead-220a5fd6f9ff22577a0823f7f772b7f76e01c38aa0b24dd895d7a91ebbad4021.json).
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-listcontentresourceshead-7f2691e421949981a2360d004695c1bb499223180af5e2227052c3fc23d01a54.json).
 
 ## HEAD /resources
 
@@ -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)
 
 Optional

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

@@ -17,14 +17,14 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content REST API > Overview
 
-**Updated: 2026-10-29.**
+**Updated: 2026-11-05.**
+
+**Available since: 0.1.0-alpha.13.**
 
 Content REST contract v1 exposes one reviewed resource inventory per configured publication. The default base path is `/content/v1`. Protocol v1 is independent of the package release and publication version.
 
 The host application supplies the API origin. The relative server URL `/content/v1` describes a mount, not a live endpoint on this documentation site. Use the [local example](https://www.shoalrun.com/content-delivery/rest.md) to try requests.
 
-Available since `0.1.0-alpha.13`.
-
 ## Operations
 
 The following references are generated from the reviewed OpenAPI source. They contain each operation's parameters, response schemas, examples, and source download.
@@ -42,13 +42,27 @@ The following references are generated from the reviewed OpenAPI source. They co
 
 All routes require a channel, version, and language. Omit `revision` only to discover the current inventory; copy its returned revision into subsequent requests. There is no pagination, search query, or fallback to another publication.
 
-Treat the returned resource `key` as opaque. It identifies a page, section, or snippet instance independently of publication and revision. JavaScript integrations can use `contentResourceKey(ref)` from `@shoalrun/cli/content`. Do not substitute filenames, headings, or document IDs for the returned key.
+Since 0.1.0-alpha.18
+
+Upgrade the exporter and content client together to use product-scoped bundles.
+
+Product-scoped requests also require `product`, for example:
+
+```text
+/content/v1/resources?product=payments&channel=production&version=v3&language=en
+```
+
+Omitting `product` selects only a productless publication. When only matching product publications exist, the request returns `400 invalid_request`; the handler doesn't choose a product for you. An unknown product or complete publication returns `404 not_found`.
+
+Inventory and resource-metadata envelopes use `schemaVersion: 1` without a product, or `schemaVersion: 2` with one. A resource's publication must match the envelope, including `product`. Keep all returned coordinates and the revision together on later reads. The protocol path stays `/content/v1`; it isn't the envelope schema version.
+
+Treat the returned resource `key` as opaque. It identifies a page, section, or snippet instance independently of publication and revision. JavaScript integrations can use `contentResourceKey(ref)` from `@shoalrun/cli/content`. Don't substitute filenames, headings, or document IDs for the returned key.
 
 ## Caching and revisions
 
 Successful responses include a strong `ETag` containing the SHA-256 of their response bytes. `If-None-Match` can return `304` without a body. An inventory request without `revision` uses `Cache-Control: no-cache`. Successful revision-pinned requests use `public, max-age=31536000, immutable`.
 
-An unavailable revision returns `409`; the handler does not silently serve newer content. Errors use JSON with an `error.code` and `error.message`, and `Cache-Control: no-store`. `HEAD` returns the same status and headers without a body. The supplied browser client requests fresh responses and verifies representation bytes against the inventory; it does not maintain an HTTP response cache.
+An unavailable revision returns `409`; the handler doesn't silently serve newer content. Errors use JSON with an `error.code` and `error.message`, and `Cache-Control: no-store`. `HEAD` returns the same status and headers without a body. The supplied browser client requests fresh responses and verifies representation bytes against the inventory; it doesn't maintain an HTTP response cache.
 
 ## Host the reference handler
 
@@ -61,11 +75,11 @@ createContentRestHandler({ sources, basePath? }):
 
 `sources` is an array of already-open `ContentSnapshot` instances with distinct publications. `basePath` defaults to `/content/v1`; use an absolute path without a trailing slash. Segments accept ASCII letters, numbers, underscores, and hyphens. The caller owns the listener, routing, source disposal, and access policy. See [serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) for setup.
 
-The adapter sends representation bytes unchanged. Continue hosting the original export's static asset and link mount. It does not supply authentication, search, editing, or revision history.
+The adapter sends representation bytes unchanged. Continue hosting the original export's static asset and link mount. It doesn't supply authentication, search, editing, or revision history.
 
 ## HTML, Markdown, and agents
 
-Each native operation reference presents its source-backed request and response contract in HTML and Markdown. Agents can use those schemas and examples to list resources and request Markdown with the same publication and revision. HTML responses are passive content; the API does not supply application styling or browser behavior.
+Each native operation reference presents its source-backed request and response contract in HTML and Markdown. Agents can use those schemas and examples to list resources and request Markdown with the same publication and revision. HTML responses are passive content; the API doesn't supply application styling or browser behavior.
 
 ## Related reading