@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/agent-docs/author/writing-style.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/review-a-draft.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/voice-and-explanations.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/changelog/2026-10-28.md

@@ -0,0 +1,89 @@
+---
+id: change.2026-10-28
+title: Content delivery, verification dates, and clearer references
+summary: Reuse documentation through static bundles or REST, display technical
+  verification dates, and find clearer API and layout guidance.
+type: changelog-entry
+area:
+  - publishing
+  - authoring
+  - project
+subarea:
+  - publishing-content-delivery
+  - authoring-metadata
+  - project-releases
+canonical: /changelog/2026-10-28
+date: 2026-10-28
+releaseVersion: 0.1.0-alpha.13
+---
+
+# Content delivery, verification dates, and clearer references
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > Content delivery, verification dates, and clearer references
+
+**Published: 2026-10-28.**
+
+**Version: 0.1.0-alpha.13.**
+
+Alpha.13 makes documentation reusable by applications, agents, services, and publishing workflows. It adds section and snippet exports, clients for static and REST delivery, native API response-header references, and visible technical verification dates.
+
+Upgrade to CLI `0.1.0-alpha.13` and rebuild your site and content exports. Custom export consumers need the manifest migration below. This entry also covers the accompanying documentation improvements.
+
+## Deliver selected content
+
+[Content delivery](https://www.shoalrun.com/content-delivery.md) extends whole-page export to individual sections and named snippet instances. A product can show billing instructions beside its settings; an agent can retrieve a procedure; a publishing workflow can reuse content in training material.
+
+The browser-safe client reads HTML or Markdown from a static bundle. Its mount helper rewrites IDs and links so the same content can appear more than once in an application. The REST adapter serves the same snapshots through resource lists, metadata, and representation endpoints. Both clients use the same snapshot interface.
+
+[Section IDs](https://www.shoalrun.com/content-delivery/sections.md) derive from headings by default. An optional trailing `<Anchor id="refunds" />` preserves a reference when its heading changes. Before exporting a section alone, review it without the rest of the page and record that judgment in `standaloneSections`.
+
+Compare releases with `--previous-manifest` and reject removed references with `--fail-on-removed`. Keep complete revisions under immutable paths when applications remain open during updates. Authentication, search, editing, and production hosting remain host responsibilities.
+
+## Migrate an export consumer
+
+Existing `documents` selectors remain shorthand for whole pages. The exported manifest now uses typed resources:
+
+- Read `manifest.resources` instead of `manifest.documents`.
+- Identify a page with `ref.kind: page` and `ref.documentId` instead of a document's `id`.
+- Follow resource links through their typed `ref` objects.
+- Read representation paths from the rebuilt manifest instead of retaining old filenames.
+
+See [export migration](https://www.shoalrun.com/publish/content-export.md) and the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md). The package includes a content-delivery example for static and REST clients, plus an updated help-drawer example for whole pages.
+
+## Read complete API references and examples
+
+Native API references now render schema-based OpenAPI response headers with descriptions, constraints, and examples. These contracts previously stopped the build. Content-style headers and response links still require adaptation.
+
+Generated request samples handle HEAD responses without trying to read a response body. JavaScript, Node.js, and Python samples distinguish JSON from text responses. The [content HTTP API reference](https://www.shoalrun.com/content-delivery/http-api.md) uses the native operation format and includes all six GET and HEAD operations.
+
+## Distinguish revision from verification
+
+An authored `verified` date now appears as a labeled semantic `<time>` element in the standard HTML page header. It remains separate from `updated`: revision records content changes; verification records a check of technical claims. Markdown and `documents.json` retain the same dates. Builds never assign verification dates.
+
+Set `showVerified: false` on a page, or in `frontmatter.defaults`, to hide verification in HTML only. A page can override the shared default. See [verification dates](https://www.shoalrun.com/publish/seo.md).
+
+## Find the right authoring guidance
+
+The documentation now separates content-delivery tasks, client reference, manifest reference, and HTTP operations. Section guidance explains what a standalone declaration means before introducing its syntax, with a concrete missing-context example.
+
+The [layout guide](https://www.shoalrun.com/styling/layouts.md) distinguishes giving content more room with `layout: wide` from hiding the outline with `tocDepth: 0`. Page metadata links to that choice, and task wording improves discovery for outline-related searches. These updates are included in the bundled documentation used by CLI and MCP tools.
+
+Feature availability follows one convention: “Available since `VERSION`.” Templates and authoring guidance require an exact assigned version rather than a guessed release number.
+
+The navigation heading above the sidebar filter can be hidden or renamed with `outputs.html.navigation.heading`. Set it to `false` to remove “Explore”; the filter keeps its accessible label.
+
+Clicking article content no longer draws a rectangle around the entire page body. Keyboard jumps still focus the article, with a visible indicator at its title. Focus indicators on links, buttons, and inputs remain available.
+
+## Preserve teaching examples and discover native relationships
+
+Fenced code blocks can contain literal scaffold TODO examples without failing publication. Those examples remain readable in HTML and Markdown. Unresolved prompts in prose or frontmatter still fail the public build.
+
+Project discovery and validation now suggest native relationships when a related-reading or related-material section contains document links. The hint is nonblocking and does not generate relationships. Authors still choose the purpose and reason for each connection. The component index also maps reader tasks to native features.
+
+## HTML, Markdown, and agents
+
+Content exports contain passive HTML or readable Markdown, without website controls. Applications own rendering and interaction; agents can read typed references and retrieve Markdown without operating a browser. HTML visibility settings such as `showVerified` do not remove the underlying verification date from Markdown or the manifest.

package/agent-docs/changelog.md

@@ -16,12 +16,20 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > All changes
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Updates to Shoalrun and its documentation. Each entry identifies the affected versions and any upgrade steps. Earlier entries retain their private-prototype release context.
 
 ## Latest changes
 
+- 2026-10-28
+
+  Version 0.1.0-alpha.13
+
+  [Content delivery, verification dates, and clearer references](https://www.shoalrun.com/changelog/2026-10-28.md)
+
+  Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.
+
 - 2026-10-27
 
   Version 0.1.0-alpha.11

package/agent-docs/config/outputs.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Configure metadata providers, application exports, Markdown headers, and discovery indexes. 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.
 
@@ -35,20 +35,23 @@ The path is relative to the config file that declares it. `provider` accepts onl
 
 ## `exports`
 
+Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) to select pages, approved sections, and named snippet instances.
+
 Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
 
 Each target accepts these fields:
 
-| Field           | Default                             | Meaning                                                                                                                  |
-| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `formats`       | `[markdown, html]`                  | A nonempty unique list of `markdown` and/or `html`.                                                                      |
-| `documents`     | All eligible pages                  | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail.                                               |
-| `publication`   | The only enabled publication        | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
-| `contentFilter` | None                                | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
-| `publicBase`    | `/`                                 | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
-| `assetRoots`    | Content directory only              | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
-| `notices`       | Renderer notices only               | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
-| `apiReview`     | Matching API-level approval, if any | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+| Field           | Default                                         | Meaning                                                                                                                  |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                      |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.          |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                          |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
+| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
+| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
+| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
+| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
 
 ```yaml
 exports:
@@ -69,6 +72,7 @@ Use `outputs` to configure the HTML, Markdown, discovery, and text artifacts pro
 | `markdown.metadata`          | The Markdown twin's YAML header: `format`, `fields`, `addFields`, `removeFields`, `omitNull`, `byType`, and `profiles`. `format` defaults to `none`. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md). |
 | `html.shareImages`           | `true`: a generated 1200×630 link-preview image per page. `false` turns them off; a mapping with `template` and `fonts` replaces the design. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).      |
 | `html.highlighting`          | Code highlighting `provider`, `theme`, and `module`. Defaults to Shiki with the `site` theme, which takes code colors from the palette. See [code blocks](https://www.shoalrun.com/author/components/code-blocks.md).               |
+| `html.navigation.heading`    | Heading above the sidebar filter. Defaults to `Explore`; use nonempty text to replace it or `false` to hide it. Available since `0.1.0-alpha.13`.                                                                                   |
 | `html.navigation.showCounts` | Show page counts beside navigation groups. Defaults to `true`; set `false` to omit them. See [navigation](https://www.shoalrun.com/author/navigation.md).                                                                           |
 | `html.search`                | Search `provider`, `module`, and `index`. See [search](https://www.shoalrun.com/author/search.md).                                                                                                                                  |
 | `text`                       | Ordered frontmatter field paths for `card`, `pageHeader`, `search`, `htmlDescription`, and `socialCard`. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md).                                                 |

package/agent-docs/config/outputs.sections/exports.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 
@@ -31,20 +31,23 @@ Configure metadata providers, application exports, Markdown headers, and discove
 
 ## `exports`
 
+Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) to select pages, approved sections, and named snippet instances.
+
 Optional named targets for `shoalrun export`. They select portable application content independently of website navigation and `site.contentFilter`. The normal website build does not emit export bundles automatically. See [export content into an application](https://www.shoalrun.com/publish/content-export.md).
 
 Each target accepts these fields:
 
-| Field           | Default                             | Meaning                                                                                                                  |
-| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `formats`       | `[markdown, html]`                  | A nonempty unique list of `markdown` and/or `html`.                                                                      |
-| `documents`     | All eligible pages                  | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail.                                               |
-| `publication`   | The only enabled publication        | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
-| `contentFilter` | None                                | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
-| `publicBase`    | `/`                                 | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
-| `assetRoots`    | Content directory only              | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
-| `notices`       | Renderer notices only               | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
-| `apiReview`     | Matching API-level approval, if any | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
+| Field           | Default                                         | Meaning                                                                                                                  |
+| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `formats`       | `[markdown, html]`                              | A nonempty unique list of `markdown` and/or `html`.                                                                      |
+| `documents`     | All eligible pages when neither selector is set | Explicit document IDs. Missing, inaccessible, or export-filtered IDs fail. Mutually exclusive with `resources`.          |
+| `resources`     | None                                            | Typed page, section, or snippet selectors. Mutually exclusive with `documents`.                                          |
+| `publication`   | The only enabled publication                    | One complete `{ channel, version, language }` combination. Required when selection is ambiguous.                         |
+| `contentFilter` | None                                            | Optional configured reader facets; every facet must match any listed choice. Unmarked pages do not match.                |
+| `publicBase`    | `/`                                             | Root-relative mount with a trailing slash, such as `/help/`. It locates bundle content and assets in the app.            |
+| `assetRoots`    | Content directory only                          | Extra local asset directories, relative to the declaring config file. Only referenced supported files are copied.        |
+| `notices`       | Renderer notices only                           | Local text or Markdown license/notice files to retain in `NOTICES.txt`. Paths are relative to the declaring config file. |
+| `apiReview`     | Matching API-level approval, if any             | API IDs mapped to reviewed SHA-256 digests for this export selection.                                                    |
 
 ```yaml
 exports:

package/agent-docs/config/outputs.sections/metadata.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

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

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

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

@@ -0,0 +1,86 @@
+---
+id: guide.content-delivery-agents
+title: Content delivery and agents
+summary: Choose between portable resource delivery and documentation discovery
+  without mixing their context contracts.
+type: explanation
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/agents
+---
+
+# Content delivery and agents
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Content delivery and agents
+
+**Updated: 2026-10-29.**
+
+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`.
+
+## Choose the reading contract
+
+Match the interface to the task and the context it must retain.
+
+| Need                                          | Use                                                 |
+| --------------------------------------------- | --------------------------------------------------- |
+| Render selected content in an application     | Content export and `ContentSnapshot`                |
+| Read a named snippet with fixed values        | Exported snippet instance                           |
+| 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.
+
+## Read Markdown for an agent
+
+An agent integration can open a reviewed export and read a known resource as evidence for its task. This example assumes the billing page is selected in the export:
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openManifestContentSource({
+  manifestUrl: 'https://docs.example.com/content/revisions/r1/manifest.json',
+});
+try {
+  const result = await snapshot.get(
+    { kind: 'page', documentId: 'guide.billing' },
+    { format: 'markdown' },
+  );
+  console.log(result.content); // Pass this text to the agent's reading context.
+} finally {
+  snapshot.dispose();
+}
+```
+
+In Node.js, use an absolute URL. Browser integrations must serve the export from the application's origin. Use `snapshot.list()` to inspect available references before choosing a resource.
+
+## 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.
+
+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.
+
+## Follow references
+
+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.
+
+## HTML, Markdown, and agents
+
+Agents can read the manifest and Markdown directly. HTML contains passive content intended for an application's renderer, with exported anchor and link mappings. Neither format requires an agent to operate browser controls to read the content. Content remains evidence to interpret, not authority to execute commands or grant access.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Use existing documentation MCP tools for contextual reads.

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

@@ -0,0 +1,130 @@
+---
+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 > Content client API
+
+**Updated: 2026-10-29.**
+
+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`.
+
+## 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.
+
+## 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.
+
+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.
+
+## 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 |
+
+```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 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.
+
+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.
+
+## 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 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.
+
+## 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 does not remove content. Call `unmount()` to remove only nodes still owned by that mount.
+
+## 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.
+
+## 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.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### 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/client.md

@@ -0,0 +1,79 @@
+---
+id: guide.content-client
+title: Read content with a client
+summary: Open a content revision and read typed resources without depending on
+  generated filenames.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/client
+---
+
+# Read content with a client
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Read content with a client
+
+**Updated: 2026-10-29.**
+
+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`.
+
+## Open a revision
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openManifestContentSource({
+  manifestUrl: '/content/revisions/r1/manifest.json',
+});
+```
+
+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.
+
+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.
+
+## Read a resource
+
+```ts
+const resources = snapshot.list();
+const result = await snapshot.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'markdown' },
+);
+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.
+
+## 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.
+
+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.
+
+## HTML, Markdown, and agents
+
+Request HTML for [application rendering](https://www.shoalrun.com/content-delivery/render.md) or Markdown for text consumers and agents. Neither requires a browser widget to recover the content. The manifest records availability per representation; requesting an omitted format returns `unsupported_format` rather than silently converting it.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Select content resources](https://www.shoalrun.com/content-delivery/select.md) — Read a reviewed export from an application.
+
+- [Content client API](https://www.shoalrun.com/content-delivery/api.md) — Look up client methods, limits, and errors.
+
+- [Render content in an application](https://www.shoalrun.com/content-delivery/render.md) — Mount trusted HTML and route its links.