@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/agent-docs/content-delivery/api.sections/open-a-rest-source.md

@@ -0,0 +1,55 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
+
+**Updated: 2026-11-07.**
+
+**Available since: 0.1.0-alpha.13.**
+
+Parent page: [Full Markdown page](/content-delivery/api.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+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 REST source
+
+```ts
+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.
+
+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.

package/agent-docs/content-delivery/api.sections/open-a-source.md

@@ -0,0 +1,51 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
+
+**Updated: 2026-11-07.**
+
+**Available since: 0.1.0-alpha.13.**
+
+Parent page: [Full Markdown page](/content-delivery/api.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+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
+
+```ts
+openManifestContentSource(options): Promise<ContentSnapshot>
+```
+
+| Option                 | Meaning                                                      | Default        |
+| ---------------------- | ------------------------------------------------------------ | -------------- |
+| `manifestUrl`          | HTTP(S) manifest URL; relative URLs use the browser location | Required       |
+| `fetch`                | Application-provided fetch implementation                    | Global `fetch` |
+| `signal`               | Cancellation signal for opening the manifest                 | None           |
+| `limits.manifestBytes` | Maximum manifest response bytes                              | 5,000,000      |
+| `limits.resourceBytes` | Maximum representation response bytes                        | 8,000,000      |
+| `limits.resources`     | Maximum resources in a manifest                              | 10,000         |
+
+`manifestUrl` accepts a string or `URL`. Outside a browser, supply an absolute URL. URLs must omit credentials, query strings, and fragments; the manifest must sit within its declared `publicBase`.
+
+Limits must be positive safe integers. The browser client requires the application origin and refuses redirects. The server must send `application/json` for the manifest and the declared content type for representations.

package/agent-docs/content-delivery/api.sections/read-a-snapshot.md

@@ -0,0 +1,55 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
+
+**Updated: 2026-11-07.**
+
+**Available since: 0.1.0-alpha.13.**
+
+Parent page: [Full Markdown page](/content-delivery/api.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+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.
+
+## Read a snapshot
+
+A snapshot exposes the following members for one opened revision.
+
+| 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 =
+  | { kind: 'page'; documentId: string }
+  | { kind: 'section'; documentId: string; sectionId: string }
+  | { 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 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 isn't a URL or authorization decision.

package/agent-docs/content-delivery/api.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
+
+**Updated: 2026-11-07.**
+
+**Available since: 0.1.0-alpha.13.**
+
+Parent page: [Full Markdown page](/content-delivery/api.md)
+
+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.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Reference while working
+
+- [ContentSnapshot](https://www.shoalrun.com/content-delivery/sdk/content-snapshot.md) — Inspect the source-derived snapshot methods and their typed parameters.
+
+### Related topics
+
+- [Read content with a client](https://www.shoalrun.com/content-delivery/client.md) — Look up client methods, limits, and errors.
+
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) — Use the shared snapshot methods and client limits.

package/agent-docs/content-delivery/api.sections/validate-a-manifest.md

@@ -0,0 +1,40 @@
+---
+id: reference.content-client
+title: Content client API
+summary: Look up the content client entry point, snapshot methods, limits,
+  results, and errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/api
+---
+
+# Content client API
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
+
+**Updated: 2026-11-07.**
+
+**Available since: 0.1.0-alpha.13.**
+
+Parent page: [Full Markdown page](/content-delivery/api.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+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.
+
+## Validate a manifest
+
+```ts
+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 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.

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

@@ -17,12 +17,16 @@ 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-11-05.**
+**Updated: 2026-11-07.**
 
 **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`.
 
+## Generated TypeScript reference
+
+Use the [generated content client reference](https://www.shoalrun.com/content-delivery/sdk/all.md) to browse public exports from `@shoalrun/cli/content`. It follows the source declarations and JSDoc, including [snapshot methods](https://www.shoalrun.com/content-delivery/sdk/content-snapshot.md), [source options](https://www.shoalrun.com/content-delivery/sdk/manifest-content-source-options.md), [results](https://www.shoalrun.com/content-delivery/sdk/content-result.md), and [delivery errors](https://www.shoalrun.com/content-delivery/sdk/content-delivery-error.md). The guide and behavior reference explain how to use those interfaces and where their trust boundaries apply.
+
 ## Open a revision
 
 ```ts
@@ -76,6 +80,10 @@ Request HTML for [application rendering](https://www.shoalrun.com/content-delive
 
 - [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
 
+### Reference while working
+
+- [Complete content client reference](https://www.shoalrun.com/content-delivery/sdk/all.md) — Look up the public functions and types while integrating a content source.
+
 ### Related topics
 
 - [Select content resources](https://www.shoalrun.com/content-delivery/select.md) — Read a reviewed export from an application.