@shoalrun/cli 1.0.0 → 1.1.0

package/agent-docs/config/site.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Configure the site identity, header, footer, agent guidance, colors, and fonts. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
 
@@ -24,22 +24,22 @@ Configure the site identity, header, footer, agent guidance, colors, and fonts.
 
 Required.
 
-| Key                                | Default                                  | Meaning                                                                                                                                                                                                                                                                                                                              |
-| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `title`                            | None                                     | Site name in the masthead and the heading of `/llms.txt`.                                                                                                                                                                                                                                                                            |
-| `contentDir`                       | `content`                                | Page directory, relative to the root config file. Every `.md` and `.mdx` file in it's read.                                                                                                                                                                                                                                          |
-| `contentFilter`                    | None                                     | Build-time whole-page selection by configured reader facets. All selected facets must match; any listed choice within a facet matches. Unmarked pages are excluded. Unknown or empty selectors and selections with no pages fail. See [separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md). |
-| `basePath`                         | `""`                                     | Mount point for public pages and resources, such as `/docs`. Use URL path segments without escapes or dot segments. Build tools keep internal manifests at the output root; the public site is also complete inside the `docs/` output subtree.                                                                                      |
-| `origin`                           | None                                     | The site's HTTPS origin, such as `https://docs.example.com`, with no path or trailing slash. Required to publish the API catalog, and makes link-preview URLs absolute.                                                                                                                                                              |
-| `indexing`                         | `true`                                   | Set `false` on previews to add noindex to pages, disallow crawling in `robots.txt`, and omit the XML sitemap.                                                                                                                                                                                                                        |
-| `updated`                          | None                                     | Optional YYYY-MM-DD fallback for sitemap `lastmod`, especially on generated API pages. Page `updated` overrides it.                                                                                                                                                                                                                  |
-| `favicon`                          | A mark drawn from the preset and palette | A local `.svg` or `.png` file. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).                                                                                                                                                                                                                     |
-| `customCss`                        | None                                     | A local `.css` file linked after the framework styles. See [CSS](https://www.shoalrun.com/author/css.md).                                                                                                                                                                                                                            |
-| `editionBadge`                     | `auto`                                   | Legacy productless masthead label: `auto` shows only differing publication values; `always` or `never`. Product catalogs use the publication dropdown described below.                                                                                                                                                               |
-| `publicationSelector.showLanguage` | Automatic                                | Since 0.1.0-alpha.18 Show language labels in the product publication dropdown only when the rendered edition has multiple languages. A boolean forces display on or off.                                                                                                                                                             |
-| `header.links`                     | None                                     | Masthead links. See [header](https://www.shoalrun.com/styling/header.md).                                                                                                                                                                                                                                                            |
-| `agentDiscovery`                   | Visually hidden until focused            | HTML agent guidance, visual presentation, and link labels. See `site.agentDiscovery` below.                                                                                                                                                                                                                                          |
-| `footer`                           | None                                     | Footer `columns`, bottom-row `links`, and a `text` line. See [site footer](https://www.shoalrun.com/styling/footer.md).                                                                                                                                                                                                              |
+| Key                                | Default                                  | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`                            | None                                     | Site name in the masthead and the heading of `/llms.txt`.                                                                                                                                                                                                                                                                                                                                                                      |
+| `contentDir`                       | `content`                                | Page directory, relative to the root config file. Every `.md` and `.mdx` file in it's read.                                                                                                                                                                                                                                                                                                                                    |
+| `contentFilter`                    | None                                     | Build-time page selection by configured reader facets, also evaluated by [ForFacet](https://www.shoalrun.com/author/components/for-facet.md) sections. All selected facets must match; any listed choice within a facet matches. Unmarked pages are excluded. Unknown or empty selectors and selections with no pages fail. See [separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md). |
+| `basePath`                         | `""`                                     | Mount point for public pages and resources, such as `/docs`. Use URL path segments without escapes or dot segments. Build tools keep internal manifests at the output root; the public site is also complete inside the `docs/` output subtree.                                                                                                                                                                                |
+| `origin`                           | None                                     | The site's HTTPS origin, such as `https://docs.example.com`, with no path or trailing slash. Required to publish the API catalog, and makes link-preview URLs absolute.                                                                                                                                                                                                                                                        |
+| `indexing`                         | `true`                                   | Set `false` on previews to add noindex to pages, disallow crawling in `robots.txt`, and omit the XML sitemap.                                                                                                                                                                                                                                                                                                                  |
+| `updated`                          | None                                     | Optional YYYY-MM-DD fallback for sitemap `lastmod`, especially on generated API pages. Page `updated` overrides it.                                                                                                                                                                                                                                                                                                            |
+| `favicon`                          | A mark drawn from the preset and palette | A local `.svg` or `.png` file. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).                                                                                                                                                                                                                                                                                                               |
+| `customCss`                        | None                                     | A local `.css` file linked after the framework styles. See [CSS](https://www.shoalrun.com/author/css.md).                                                                                                                                                                                                                                                                                                                      |
+| `editionBadge`                     | `auto`                                   | Legacy productless masthead label: `auto` shows only differing publication values; `always` or `never`. Product catalogs use the publication dropdown described below.                                                                                                                                                                                                                                                         |
+| `publicationSelector.showLanguage` | Automatic                                | Since 0.1.0-alpha.18 Show language labels in the product publication dropdown only when the rendered edition has multiple languages. A boolean forces display on or off.                                                                                                                                                                                                                                                       |
+| `header.links`                     | None                                     | Masthead links. See [header](https://www.shoalrun.com/styling/header.md).                                                                                                                                                                                                                                                                                                                                                      |
+| `agentDiscovery`                   | Visually hidden until focused            | HTML agent guidance, visual presentation, and link labels. See `site.agentDiscovery` below.                                                                                                                                                                                                                                                                                                                                    |
+| `footer`                           | None                                     | Footer `columns`, bottom-row `links`, and a `text` line. See [site footer](https://www.shoalrun.com/styling/footer.md).                                                                                                                                                                                                                                                                                                        |
 
 A minimal site needs only a title:
 

package/agent-docs/config/site.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/site.md)
 

package/agent-docs/config/site.sections/theme.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/config/site.md)
 

package/agent-docs/configuration.md

@@ -59,7 +59,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 ```
 

package/agent-docs/configuration.sections/start-with-one-working-file.md

@@ -40,7 +40,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@1.0.0
+npm install --save-exact @shoalrun/cli@1.1.0
 npx --no-install shoalrun init . --starter minimal
 ```
 

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

@@ -15,14 +15,18 @@ canonical: /content-delivery/api
 
 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 > Content client API
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Client behavior
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 **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.
 
+## 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 source
 
 ```ts
@@ -136,6 +140,10 @@ The same typed reference selects either available representation. HTML mounting
 
 - [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.

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

@@ -0,0 +1,52 @@
+---
+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.
+
+## Errors
+
+Use `ContentDeliveryError.code` to distinguish these failures.
+
+| Code                 | Meaning                                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `invalid_manifest`   | Invalid source URL, options, inventory, manifest shape, digest, or review metadata                                                     |
+| `not_found`          | Missing manifest, unknown resource reference, or REST `404`                                                                            |
+| `unsupported_format` | Unavailable representation, REST `406`, or non-HTML input passed to `mountContent`                                                     |
+| `stale_revision`     | Content bytes differ from the opened revision, a static representation file is missing, or REST returns `409`                          |
+| `network_error`      | Failed or interrupted request; REST `400`, `405`, or `500`; or HTTP failures outside the REST contract, such as `401`, `429`, or `503` |
+| `invalid_content`    | Wrong response media type, invalid UTF-8, exceeded response limit, malformed REST error, or invalid mount content                      |
+| `disposed`           | Reading a disposed snapshot or a read aborted by disposal                                                                              |
+
+The static client maps a missing representation file to `stale_revision`; the REST client preserves `404` as `not_found`. Opening a REST inventory with a different requested revision also produces `stale_revision`.
+
+Defined REST error statuses must carry the documented JSON envelope. A malformed envelope produces `invalid_content`; other HTTP failure statuses produce `network_error` regardless of response body format.
+
+Cancellation can propagate the signal's abort reason instead of a `ContentDeliveryError`. Treat messages as diagnostics rather than parsing them for program logic.

package/agent-docs/content-delivery/api.sections/generated-typescript-reference.md

@@ -0,0 +1,36 @@
+---
+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.
+
+## 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.

package/agent-docs/content-delivery/api.sections/html-markdown-and-agents.md

@@ -0,0 +1,36 @@
+---
+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.
+
+## 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 don't establish that an unknown publisher's content is trustworthy.

package/agent-docs/content-delivery/api.sections/mount-html.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)
+
+**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.
+
+## Mount HTML
+
+```ts
+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 doesn't remove content. Call `unmount()` to remove only nodes still owned by that mount.

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.