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

package/agent-docs/content-delivery/http-api/operations/list-content-resources-head-b67cbad9.md

@@ -0,0 +1,236 @@
+---
+id: reference.content-rest.listContentResourcesHead
+title: List resource metadata headers
+summary: HEAD /resources
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /content-delivery/http-api/operations/list-content-resources-head-b67cbad9
+---
+
+# List resource metadata headers
+
+> 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 REST API > Other > List resource metadata headers
+
+**Updated: 2026-10-28.**
+
+This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-listcontentresourceshead-220a5fd6f9ff22577a0823f7f772b7f76e01c38aa0b24dd895d7a91ebbad4021.json).
+
+## HEAD /resources
+
+List resource metadata headers
+
+Query parameters are single-valued; unknown or duplicate parameters are rejected. Publication and revision checks run before conditional ETag checks. No pagination, search, writes, authentication, or cross-origin policy is supplied by this reference adapter. HEAD returns the GET status and headers without a response body.
+
+### Servers
+
+`/content/v1`
+
+### Parameters
+
+#### channel (query)
+
+Required
+
+Exact publication channel. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"production"`
+
+#### version (query)
+
+Required
+
+Exact publication version. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"current"`
+
+#### language (query)
+
+Required
+
+Exact publication language. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"en"`
+
+#### revision (query)
+
+Optional
+
+Omit to discover the currently supplied snapshot. Supply to require that exact revision.
+
+string; pattern: ^\[a-f0-9]{64}$
+
+**Default example**: `"0770e6d70db51967fac8dcc7bb4ff5a5bff87378eb2e2bbb63dea93d090c82e8"`
+
+#### If-None-Match (header)
+
+Optional
+
+An ETag, comma-separated ETags, or \*. Weak comparison is supported for GET and HEAD.
+
+string
+
+### Example request
+
+```bash
+curl --head \
+  --url 'https://YOUR_API_HOST/content/v1/resources?channel=YOUR_CHANNEL&version=YOUR_VERSION&language=YOUR_LANGUAGE'
+```
+
+### Responses
+
+#### 200: OK
+
+The selected resource or inventory.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+#### 304: Not Modified
+
+The validated selected response matches If-None-Match. No response body.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+#### 400: Bad Request
+
+invalid_request: missing, duplicate, unknown, or malformed query parameter.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+#### 404: Not Found
+
+not_found: unknown publication, resource, or route.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+#### 405: Method Not Allowed
+
+method_not_allowed: only GET and HEAD are supported; Allow lists both.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+###### Allow
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "GET, HEAD"
+
+#### 406: Not Acceptable
+
+unsupported_format: unsupported or unavailable representation format.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+#### 409: Conflict
+
+stale_revision: revision unavailable, or source bytes no longer match the pinned snapshot.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+#### 500: Internal Server Error
+
+internal_error: the source could not complete the request.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"

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

@@ -0,0 +1,78 @@
+---
+id: reference.content-rest
+title: Content REST API
+summary: Look up resource routes, publication parameters, revision checks,
+  caching, and HTTP errors.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/http-api
+---
+
+# Content REST 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 REST API > Overview
+
+**Updated: 2026-10-29.**
+
+Content REST contract v1 exposes one reviewed resource inventory per configured publication. The default base path is `/content/v1`. Protocol v1 is independent of the package release and publication version.
+
+The host application supplies the API origin. The relative server URL `/content/v1` describes a mount, not a live endpoint on this documentation site. Use the [local example](https://www.shoalrun.com/content-delivery/rest.md) to try requests.
+
+Available since `0.1.0-alpha.13`.
+
+## Operations
+
+The following references are generated from the reviewed OpenAPI source. They contain each operation's parameters, response schemas, examples, and source download.
+
+| Operation                                                                                                                                | Purpose                                              |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| [List resource metadata](https://www.shoalrun.com/content-delivery/http-api/operations/list-content-resources-8e977ec7.md)               | Discover resources and the loaded revision           |
+| [List metadata headers](https://www.shoalrun.com/content-delivery/http-api/operations/list-content-resources-head-b67cbad9.md)           | Check the inventory without a response body          |
+| [Read resource metadata](https://www.shoalrun.com/content-delivery/http-api/operations/get-content-resource-849f1c49.md)                 | Inspect one resource in a pinned revision            |
+| [Read metadata headers](https://www.shoalrun.com/content-delivery/http-api/operations/get-content-resource-head-0a352acd.md)             | Check one resource without a response body           |
+| [Read HTML or Markdown](https://www.shoalrun.com/content-delivery/http-api/operations/get-content-representation-fa1d2e3f.md)            | Fetch original representation bytes                  |
+| [Read representation headers](https://www.shoalrun.com/content-delivery/http-api/operations/get-content-representation-head-4052375c.md) | Check representation headers without a response body |
+
+## Keep publication and revision together
+
+All routes require a channel, version, and language. Omit `revision` only to discover the current inventory; copy its returned revision into subsequent requests. There is no pagination, search query, or fallback to another publication.
+
+Treat the returned resource `key` as opaque. It identifies a page, section, or snippet instance independently of publication and revision. JavaScript integrations can use `contentResourceKey(ref)` from `@shoalrun/cli/content`. Do not substitute filenames, headings, or document IDs for the returned key.
+
+## Caching and revisions
+
+Successful responses include a strong `ETag` containing the SHA-256 of their response bytes. `If-None-Match` can return `304` without a body. An inventory request without `revision` uses `Cache-Control: no-cache`. Successful revision-pinned requests use `public, max-age=31536000, immutable`.
+
+An unavailable revision returns `409`; the handler does not silently serve newer content. Errors use JSON with an `error.code` and `error.message`, and `Cache-Control: no-store`. `HEAD` returns the same status and headers without a body. The supplied browser client requests fresh responses and verifies representation bytes against the inventory; it does not maintain an HTTP response cache.
+
+## Host the reference handler
+
+Import `createContentRestHandler` from `@shoalrun/cli/content/server`:
+
+```ts
+createContentRestHandler({ sources, basePath? }):
+  (request: Request) => Promise<Response>
+```
+
+`sources` is an array of already-open `ContentSnapshot` instances with distinct publications. `basePath` defaults to `/content/v1`; use an absolute path without a trailing slash. Segments accept ASCII letters, numbers, underscores, and hyphens. The caller owns the listener, routing, source disposal, and access policy. See [serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) for setup.
+
+The adapter sends representation bytes unchanged. Continue hosting the original export's static asset and link mount. It does not supply authentication, search, editing, or revision history.
+
+## HTML, Markdown, and agents
+
+Each native operation reference presents its source-backed request and response contract in HTML and Markdown. Agents can use those schemas and examples to list resources and request Markdown with the same publication and revision. HTML responses are passive content; the API does not supply application styling or browser behavior.
+
+## Related reading
+
+### Read first
+
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) — Set up the reference HTTP adapter.
+
+### Related topics
+
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) — Look up HTTP routes and revision handling.

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

@@ -0,0 +1,79 @@
+---
+id: reference.content-manifest
+title: Content manifest
+summary: Look up resource references, representations, assets, revision digests,
+  and export diagnostics.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/manifest
+---
+
+# Content manifest
+
+> 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 manifest
+
+**Updated: 2026-10-29.**
+
+`manifest.json` is the entry point for a content export. The resource-aware implementation uses `kind: shoalrun-content-export`, `schemaVersion: 1`, and a `resources` array. Earlier whole-page exports use a `documents` array; rebuild those exports before opening them with the resource client.
+
+Available since `0.1.0-alpha.13`.
+
+## Bundle fields
+
+These fields describe the complete export and its publication.
+
+| Field         | Meaning                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| `digest`      | Revision digest for the bundle manifest                              |
+| `publicBase`  | Root-relative serving mount with a trailing slash                    |
+| `publication` | One channel, version, and language                                   |
+| `review`      | API source-review status and digests                                 |
+| `resources`   | Selected pages, sections, and snippet instances                      |
+| `assets`      | Local asset records                                                  |
+| `files`       | Exported file paths, sizes, and digests                              |
+| `diagnostics` | Export findings such as external images or static interaction output |
+
+A review status of `required` identifies a review candidate. Do not serve it as an approved content release.
+
+## Resource fields
+
+Each resource has `ref`, `publication`, `title`, `summary`, `type`, `representations`, `assets`, and `externalDependencies`. A `canonicalUrl` or source metadata may also be present.
+
+```json
+{
+  "kind": "section",
+  "documentId": "guide.billing",
+  "sectionId": "refunds"
+}
+```
+
+This is a section's `ref`, not a complete manifest. Page references use `kind` and `documentId`; snippet-instance references use `kind` and `id`. Identity is scoped to the publication. A title or generated filename is not a resource reference.
+
+## Representations and links
+
+Each available `html` or `markdown` representation declares `path`, `mediaType`, `bytes`, `digest`, `anchors`, and `links`. Paths point to files under the export mount. Anchors map source IDs to exported DOM IDs. Link records distinguish `resource`, `canonical`, `external`, and `asset` targets; resource links include a typed reference.
+
+A resource's asset list names local dependencies. `externalDependencies` identifies remote images that were not copied. Distribute `NOTICES.txt` and any required attribution with the content.
+
+## Validate a consumer
+
+Use the content client or validate the manifest before fetching its declared paths. Unknown references and unavailable formats are errors. Check representation bytes and digest against the opened revision. Do not assume that a valid digest makes an untrusted host or its HTML safe.
+
+## HTML, Markdown, and agents
+
+The manifest records each representation separately because anchors, links, and rendered bytes can differ. It supplies IDs and revision context without inserting machine labels into ordinary Markdown headings. An agent can select Markdown by a resource reference while an application selects HTML from the same revision.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Publish and update content](https://www.shoalrun.com/content-delivery/publish.md) — Inspect revision and representation metadata.

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

@@ -0,0 +1,72 @@
+---
+id: guide.content-delivery-publishing
+title: Publish and update content
+summary: Publish complete revisions, compare removed references, and replace
+  content snapshots deliberately.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/publish
+---
+
+# Publish and update content
+
+> 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 > Publish and update content
+
+**Updated: 2026-10-29.**
+
+Publish a complete export as one revision. The manifest and representation files must agree; replacing only the manifest or only an article can leave a running application with mismatched content.
+
+Available since `0.1.0-alpha.13`.
+
+## Build a revision
+
+Choose a revision mount, such as `/content/revisions/r2/`, and set the target's `publicBase` to that path. Export into a separate output directory:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml \
+  --target application --out ./content-r2
+```
+
+Review every selected resource in HTML and Markdown, including links, images, notices, and snippet values. Imported API material requires the existing source-review approval before the bundle is ready for delivery.
+
+## Compare public references
+
+Keep the manifest of the last published revision. For an established collection, compare against it:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml \
+  --target application --out ./content-r2 \
+  --previous-manifest ./content-r1/manifest.json \
+  --fail-on-removed
+```
+
+The comparison reports added and removed typed references within their publication. A title or body edit changes content without changing an explicit identity. A renamed derived section ID can remove a reference. Strict removal checking fails before replacing the previous output; without a baseline, removal checking is reported as unavailable.
+
+Review intentional removals with the applications that consume them. Keep old revisions available while deployed applications still need them. Comparison does not create redirects or aliases.
+
+## Serve and switch
+
+Upload the complete directory to its configured mount. Serve the manifest as `application/json`, HTML as `text/html`, and Markdown as `text/markdown`. Keep relative file paths and local assets intact.
+
+The application chooses which manifest URL to open. An already-open snapshot stays on its revision. Open and validate the replacement before switching the UI, then dispose the old snapshot when its views are finished. The [REST adapter](https://www.shoalrun.com/content-delivery/rest.md) can supply the same interface. Replacing its handler updates the loaded snapshots; authorization, historical revision routing, and asset hosting remain the host application's responsibility.
+
+## HTML, Markdown, and agents
+
+Publish both representations together when both are selected. Agents and applications can record the manifest revision with a resource reference to explain which content they read. A digest verifies that bytes match the declared revision; it is not a signature or proof of factual accuracy. Remote images remain external dependencies and need separate availability planning.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Render content in an application](https://www.shoalrun.com/content-delivery/render.md) — Publish complete revisions and update the client.
+
+- [Content manifest](https://www.shoalrun.com/content-delivery/manifest.md) — Inspect revision and representation metadata.

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

@@ -0,0 +1,73 @@
+---
+id: guide.content-rendering
+title: Render content in an application
+summary: Mount passive HTML and keep application styling, navigation, and
+  lifecycle under your control.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/render
+---
+
+# Render content in an application
+
+> 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 > Render content in an application
+
+**Updated: 2026-10-29.**
+
+Your application can display a resource in a panel, onboarding surface, article view, or help drawer. Fetch the resource through a [content snapshot](https://www.shoalrun.com/content-delivery/client.md), then mount its HTML in a container you own.
+
+Available since `0.1.0-alpha.13`.
+
+## Mount the result
+
+```ts
+import { mountContent, openManifestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openManifestContentSource({
+  manifestUrl: '/content/revisions/r1/manifest.json',
+});
+const result = await snapshot.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'html' },
+);
+const container = document.querySelector('#content-panel');
+if (!container) throw new Error('Missing content panel');
+const mounted = mountContent(container, result);
+```
+
+Mounting assigns a unique prefix to IDs and rewrites local fragments, footnote references, and supported ID-reference attributes. This allows separate instances of the same resource without duplicating those DOM IDs. An explicit `instanceId` must be unique where the content is mounted.
+
+## Own the interface
+
+Apply your application's CSS to passive elements. The mount helper does not install the documentation theme or recreate interactive components. Preserve headings, link labels, image alternatives, and other semantic content when styling.
+
+Your app owns loading and failure states, navigation history, focus management, close controls, keyboard behavior, and announcements when content changes. Preserve heading levels from the content; arrange the surrounding page so those levels make sense.
+
+The helper inserts trusted compiler output. It is not a sanitizer for arbitrary HTML from users or unknown publishers.
+
+## Route links and clean up
+
+`mounted.links` records each exported link's kind and target. Resource links include a typed `ref`; canonical and external links have ordinary URLs. Intercept a resource link only when the app can open that target and preserve its fragment or query. Other links should retain their normal destination.
+
+Use the returned `mounted.anchors` for instance-specific fragment targets. Do not guess DOM IDs from headings. When the view closes, call `mounted.unmount()` and dispose the snapshot when it is no longer shared by another view.
+
+## HTML, Markdown, and agents
+
+HTML fragments retain static content but omit component browser enhancements. The application supplies the interface around them. Markdown consumers receive the readable representation without mount IDs or application controls. Agents should use resource references and manifest links rather than inspect a rendered drawer to find the original content.
+
+## 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) — Mount trusted HTML and route its links.
+
+- [Publish and update content](https://www.shoalrun.com/content-delivery/publish.md) — Publish complete revisions and update the client.

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

@@ -0,0 +1,108 @@
+---
+id: guide.content-rest
+title: Serve content through REST
+summary: Expose reviewed content snapshots over HTTP and read them through the
+  content client.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/rest
+---
+
+# Serve content through REST
+
+> 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 > Serve content through REST
+
+**Updated: 2026-10-29.**
+
+Serve the same reviewed pages, sections, and snippet instances through the Content REST API. The reference adapter accepts already-open snapshots and exposes a Fetch-style request handler. Your host provides the HTTP listener, request routing, and any access controls.
+
+Available since `0.1.0-alpha.13`.
+
+## Prepare a snapshot
+
+First [export selected resources](https://www.shoalrun.com/content-delivery/select.md) and serve the complete bundle at its configured `publicBase`. Open its manifest on the server:
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+import { createContentRestHandler } from '@shoalrun/cli/content/server';
+
+const source = await openManifestContentSource({
+  manifestUrl: 'http://localhost:8787/content/revisions/r1/manifest.json',
+});
+const handleContent = createContentRestHandler({ sources: [source] });
+
+// In your host's /content/v1 request route:
+const response = await handleContent(request);
+```
+
+The host passes a standard `Request` and sends the returned `Response`. `createContentRestHandler` does not start a listener. Import its server entry point only in server code. Browser clients use the separate entry point shown below.
+
+Supply at most one snapshot for each channel, version, and language combination. The handler retains those revisions for its lifetime. It does not reload manifests or keep an archive. Keep sources alive while requests use them, then dispose them during host shutdown.
+
+## Read through the client
+
+A browser client opens the API from the application's origin. Use HTTPS or localhost for Web Crypto:
+
+```ts
+import { openRestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openRestContentSource({
+  baseUrl: '/content/v1',
+  publication: { channel: 'production', version: 'current', language: 'en' },
+});
+try {
+  const result = await snapshot.get(
+    { kind: 'page', documentId: 'guide.billing' },
+    { format: 'markdown' },
+  );
+  console.log(result.content);
+} finally {
+  snapshot.dispose();
+}
+```
+
+Select `guide.billing` in the export before running this example. Outside a browser, provide an absolute HTTP(S) `baseUrl`. Opening loads the resource list and pins later reads to its revision. Pass `revision` when the caller already knows which revision it needs. The returned [ContentSnapshot](https://www.shoalrun.com/content-delivery/api.md) has the same `list`, `get`, and `dispose` methods as the manifest client.
+
+## Try the local example
+
+Copy the package's `examples/content-delivery` directory into a project with the new implementation installed. From that copied directory, build the export and start its preview:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help/releases/demo
+node preview.mjs
+```
+
+Open `http://127.0.0.1:8775/settings/billing?delivery=rest`. The example hosts its static bundle and REST routes on the same origin. Open the billing guide and refund section to check both resource shapes. Removing `?delivery=rest` uses static manifest delivery with the same application interface.
+
+## Keep assets and links available
+
+The adapter sends representation bytes unchanged. Images and links still point to the export's configured static locations; the REST endpoint does not replace that asset mount. Keep the complete bundle hosted alongside the API. Applications can also route typed resource links through their own interface.
+
+For a new release, open the new snapshot and replace the handler in your host. Clients pinned to an unavailable older revision receive `409 stale_revision`. Retaining historical revisions or routing between them requires host code beyond this adapter. See [publish and update content](https://www.shoalrun.com/content-delivery/publish.md).
+
+## Check the HTTP boundary
+
+The [HTTP reference](https://www.shoalrun.com/content-delivery/http-api.md) describes REST contract v1. That protocol version is separate from the package release and the content publication's `version` value.
+
+The adapter lists and reads approved resources. It does not implement authentication, search, content editing, or an MCP service. Place authorization before the handler when required. Successful pinned responses use public immutable caching; a host protecting private content must override that cache policy before sending responses.
+
+## HTML, Markdown, and agents
+
+Agents can list resources, keep the returned revision, and fetch Markdown without operating browser controls. HTML responses remain passive fragments for a trusted application renderer. REST changes the transport, not section approval, content context, or representation bytes.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand reviewed resources and snapshots.
+
+### Related topics
+
+- [Content REST API](https://www.shoalrun.com/content-delivery/http-api.md) — Look up HTTP routes and revision handling.
+
+- [Content client API](https://www.shoalrun.com/content-delivery/api.md) — Use the shared snapshot methods and client limits.