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

package/agent-docs/provenance.json

@@ -2,9 +2,9 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "903641a369d32c0e716712c668ef7378b8ebfdd314f7d95f1553c00443b20eb5",
-    "buildId": "1aae676cf02856842a383f9e8f28b2b126e18cfbc75050227980b1d3d82762b6"
+    "configDigest": "31d33ea2d00a4333e120d37f58251238c0698e62f7320dccdaf1c2ace8df78fd",
+    "buildId": "38aac8472fa1fad778acd5b5bdc30067474eca35755706d09f916914326ed2f0"
   },
-  "packageIntegrity": "sha512-NmM2tIR7SSyz8STTZluEsATZZBcTrgH6mWBTjOju7Qz3E60onSrQF93IXmBuhBiInw+Zq9mysUAk8Lvo/UDj6Q==",
-  "manifestDigest": "5b181b5e3d09eaae37afaf0f08ce5c725ea393029df4cec8ad62c44939b07fe7"
+  "packageIntegrity": "sha512-Qs6yv+QFvt6L5huiKFQfIT5FYexxbSokwUVUnxIrXUx2TtY/VTdG0EKAJJuCLLi6FcrYVbnI/mC9uWqJ9nflsw==",
+  "manifestDigest": "c99f0684ea93c4add58ddee1fd19dc82fa1acd9099d6cc2b4b226a0ef85302fe"
 }

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

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,16 +16,27 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It does not need a Shoalrun browser runtime.
 
 ## Prerequisites
 
-Content exports require Shoalrun CLI `0.1.0-alpha.6` or later.
+Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This guide uses the resource-based export manifest described in the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md).
 
 Start with a Shoalrun project and public pages assigned to an enabled publication. Navigation, facets, a site title, and a previous website build are optional. A site origin is needed only when links must fall back to pages on the documentation website. The export does not generate embeddings or run documentation chat.
 
+## Upgrade an existing integration
+
+If an existing bundle contains `manifest.documents`, upgrade the CLI and rebuild the export before using this guide's loader. Update custom consumers to the resource contract:
+
+- Read `manifest.resources` instead of `manifest.documents`.
+- Select page resources with `ref.kind === 'page'` and `ref.documentId` instead of a document's `id`.
+- Route links with `kind: resource` through their typed `ref`, rather than `kind: document` and `documentId`.
+- Read file paths from the rebuilt manifest; do not retain paths from the old bundle.
+
+The `documents` configuration selector remains shorthand for whole pages. Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) when selecting approved sections or named snippet instances.
+
 ## Export selected pages
 
 1. ## Define an export target
@@ -40,7 +51,7 @@ Start with a Shoalrun project and public pages assigned to an enabled publicatio
        publicBase: /help/
    ```
 
-   Omit `documents` to export all eligible public pages in one enabled publication. If more than one publication is enabled, select all three coordinates:
+   Omit both `documents` and `resources` to export all eligible public pages in one enabled publication. If more than one publication is enabled, select all three coordinates:
 
    ```yaml
    exports:
@@ -60,7 +71,7 @@ Start with a Shoalrun project and public pages assigned to an enabled publicatio
    From the documentation project, run:
 
    ```sh
-   shoalrun export docs.config.yaml --target app-help --out ../app/public/help
+   npx --no-install shoalrun export docs.config.yaml --target app-help --out ../app/public/help
    ```
 
    Replace the output path with the directory your application will distribute. The command prints JSON with its publication, formats, selected document IDs, asset count, digest, API review requirements, and diagnostics. A successful export replaces an earlier export in that directory. A failure preserves it. Source directories, unrelated nonempty directories, and previous website builds cannot be used as the export destination.
@@ -77,12 +88,12 @@ Start with a Shoalrun project and public pages assigned to an enabled publicatio
      NOTICES.txt
    ```
 
-   File names derive from stable document identity and publication, not titles or source-file names. Read paths from the manifest rather than constructing them in your app.
+   File names derive from typed resource identity and publication, not titles or source-file names. Read paths from the manifest rather than constructing them in your app.
 
    For a one-off export without a named target:
 
    ```sh
-   shoalrun export docs.config.yaml --out ../app/public/help \
+   npx --no-install shoalrun export docs.config.yaml --out ../app/public/help \
      --format html --document guide.api-keys --document guide.billing \
      --public-base /help/
    ```
@@ -97,10 +108,13 @@ Start with a Shoalrun project and public pages assigned to an enabled publicatio
 
    ```js
    const manifest = await fetch('/help/manifest.json').then(response => response.json());
-   if (manifest.schemaVersion !== 1 || manifest.review.status !== 'ok') {
+   if (manifest.schemaVersion !== 1 || manifest.review?.status !== 'ok' ||
+       !Array.isArray(manifest.resources)) {
      throw new Error('Unsupported or unreviewed help export');
    }
-   const help = manifest.documents.find(document => document.id === 'guide.api-keys');
+   const help = manifest.resources.find(resource =>
+     resource.ref.kind === 'page' && resource.ref.documentId === 'guide.api-keys');
+   if (!help?.representations.html) throw new Error('API-key HTML is unavailable');
    const html = await fetch(manifest.publicBase + help.representations.html.path)
      .then(response => response.text());
    helpContainer.innerHTML = html;
@@ -112,7 +126,7 @@ Start with a Shoalrun project and public pages assigned to an enabled publicatio
 
 4. ## Handle document links and check the result
 
-   Links to other exported pages have `data-export-link` markers. Each marker identifies a record in that representation's `links` array. For `kind: document`, your app can prevent ordinary navigation and open `documentId` in the drawer. `fragment` identifies the original heading or anchor; the HTML representation's `anchors` array maps it to its namespaced `exportedId`.
+   Links to other exported pages have `data-export-link` markers. Each marker identifies a record in that representation's `links` array. For `kind: resource`, your app can prevent ordinary navigation and retrieve the target using its typed `ref`. A page reference contains `kind: page` and `documentId`; section and snippet references have their own identity fields. `fragment` identifies the original heading or anchor; the HTML representation's `anchors` array maps it to its namespaced `exportedId`.
 
    A link to an omitted document uses its canonical website URL only when that document is public, enabled, and selected for the website. Without an eligible destination and a configured origin, the export fails. Linked pages are never silently added to the export. Explicit external links retain their destinations.
 
@@ -136,9 +150,9 @@ Exports resolve snippets, supported components, and API material before renderin
 
 HTML contains no site navigation, theme, required scripts, or app-wide stylesheet. It remains readable without CSS; your app styles its content container. HTML and Markdown are rendered independently from the same resolved source, so [representation-specific blocks](https://www.shoalrun.com/author/components/only.md) retain their intended differences.
 
-HTML heading, footnote, and other IDs are namespaced per document. Mount each exported document once per DOM. Repeated simultaneous instances require the application to rewrite IDs and all corresponding fragment and ARIA references. Markdown heading anchors depend on the customer's renderer; the export does not promise identical anchor generation across Markdown libraries.
+HTML heading, footnote, and other IDs are namespaced per resource. Directly inserting the same HTML more than once can duplicate IDs. Use [mountContent](https://www.shoalrun.com/content-delivery/render.md) for simultaneous instances; it rewrites IDs and their fragment and ARIA references for each mount. Markdown heading anchors depend on the customer's renderer; the export does not promise identical anchor generation across Markdown libraries.
 
-Whole pages are the supported units. The website's size-based section resources are not exported as stable application-help IDs.
+Exports support pages, explicitly approved sections, and named snippet instances. Application section fragments use `{ id, context: section }` approval; they are separate from the website's size-based contextual agent sections. See [select content resources](https://www.shoalrun.com/content-delivery/select.md) for configuration and approval examples.
 
 ## Assets, downloads, and notices
 
@@ -155,14 +169,14 @@ exports:
 
 Supported files include PNG, JPEG, GIF, WebP, AVIF, passive SVG, PDF, plain text, CSV, JSON, and YAML. Local assets use content-hashed paths. Unsupported asset types, missing files, symlink escapes, active SVG, and unresolved local links fail the export. Asset directories are not copied wholesale. Self-contained focused OpenAPI downloads are included when referenced.
 
-Remote images are not downloaded. The manifest records them in each document's `externalDependencies`, and the command reports them in diagnostics. A document with a remote image is not offline-complete. Explicit notice files and applicable diagram-renderer notices are retained in `NOTICES.txt`.
+Remote images are not downloaded. The manifest records them in each resource's `externalDependencies`, and the command reports them in diagnostics. A document with a remote image is not offline-complete. Explicit notice files and applicable diagram-renderer notices are retained in `NOTICES.txt`.
 
 ## Review exported API material
 
 The export preserves the API source-review gate. If its selected API material has no matching review digest, the normal command fails before replacing the previous bundle. Produce a candidate for inspection with:
 
 ```sh
-shoalrun export docs.config.yaml --target app-help --out review/app-help --review
+npx --no-install shoalrun export docs.config.yaml --target app-help --out review/app-help --review
 ```
 
 A candidate needing review reports `status: needs-review`, sets `manifest.review.status: required`, and exits with code 2. Inspect its references and downloads, then pin the reported API digests to the target:
@@ -180,7 +194,9 @@ Run the normal export command again. Changed source bytes or exposed API selecti
 
 ## Inspect the manifest
 
-The versioned `manifest.json` identifies documents by ID and publication. It includes titles, summaries, types, eligible canonical URLs, representation paths and digests, typed links, HTML anchor maps, local assets, external image dependencies, and diagnostics. It does not copy raw source frontmatter, configuration, local dependency paths, or browser runtime payloads.
+The manifest uses typed `resources` for pages, sections, and snippet instances. See the [manifest contract](https://www.shoalrun.com/content-delivery/manifest.md) and [content client](https://www.shoalrun.com/content-delivery/client.md) for resource lookup and retrieval.
+
+The versioned `manifest.json` identifies resources by typed reference and publication. It includes titles, summaries, types, eligible canonical URLs, representation paths and digests, typed links, HTML anchor maps, local assets, external image dependencies, and diagnostics. It does not copy raw source frontmatter, configuration, local dependency paths, or browser runtime payloads.
 
 The bundle's `digest` is the SHA-256 of `JSON.stringify` of the parsed manifest with its own `digest` field removed. The `files` list records byte counts and SHA-256 digests for every payload file, including notices. All text is UTF-8. The manifest itself is excluded from that list. Deterministic output lets applications compare bundles and invalidate cached content.
 
@@ -189,7 +205,7 @@ The bundle's `digest` is the SHA-256 of `JSON.stringify` of the parsed manifest
 The package's `examples/help-drawer` directory contains a small application with two help documents, an image, a diagram, reader sections, tabs, a walkthrough, and a custom component. Copy it into a project with Shoalrun installed, then run from that example directory:
 
 ```sh
-shoalrun export docs.config.yaml --target app-help --out public/help
+npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help
 node preview.mjs
 ```
 

package/agent-docs/publish/content-export.sections/assets-downloads-and-notices.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -37,4 +37,4 @@ exports:
 
 Supported files include PNG, JPEG, GIF, WebP, AVIF, passive SVG, PDF, plain text, CSV, JSON, and YAML. Local assets use content-hashed paths. Unsupported asset types, missing files, symlink escapes, active SVG, and unresolved local links fail the export. Asset directories are not copied wholesale. Self-contained focused OpenAPI downloads are included when referenced.
 
-Remote images are not downloaded. The manifest records them in each document's `externalDependencies`, and the command reports them in diagnostics. A document with a remote image is not offline-complete. Explicit notice files and applicable diagram-renderer notices are retained in `NOTICES.txt`.
+Remote images are not downloaded. The manifest records them in each resource's `externalDependencies`, and the command reports them in diagnostics. A document with a remote image is not offline-complete. Explicit notice files and applicable diagram-renderer notices are retained in `NOTICES.txt`.

package/agent-docs/publish/content-export.sections/check-the-result.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/export-selected-pages.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -36,7 +36,7 @@ Keep application help and your documentation website in one content source. `sho
        publicBase: /help/
    ```
 
-   Omit `documents` to export all eligible public pages in one enabled publication. If more than one publication is enabled, select all three coordinates:
+   Omit both `documents` and `resources` to export all eligible public pages in one enabled publication. If more than one publication is enabled, select all three coordinates:
 
    ```yaml
    exports:
@@ -56,7 +56,7 @@ Keep application help and your documentation website in one content source. `sho
    From the documentation project, run:
 
    ```sh
-   shoalrun export docs.config.yaml --target app-help --out ../app/public/help
+   npx --no-install shoalrun export docs.config.yaml --target app-help --out ../app/public/help
    ```
 
    Replace the output path with the directory your application will distribute. The command prints JSON with its publication, formats, selected document IDs, asset count, digest, API review requirements, and diagnostics. A successful export replaces an earlier export in that directory. A failure preserves it. Source directories, unrelated nonempty directories, and previous website builds cannot be used as the export destination.
@@ -73,12 +73,12 @@ Keep application help and your documentation website in one content source. `sho
      NOTICES.txt
    ```
 
-   File names derive from stable document identity and publication, not titles or source-file names. Read paths from the manifest rather than constructing them in your app.
+   File names derive from typed resource identity and publication, not titles or source-file names. Read paths from the manifest rather than constructing them in your app.
 
    For a one-off export without a named target:
 
    ```sh
-   shoalrun export docs.config.yaml --out ../app/public/help \
+   npx --no-install shoalrun export docs.config.yaml --out ../app/public/help \
      --format html --document guide.api-keys --document guide.billing \
      --public-base /help/
    ```
@@ -93,10 +93,13 @@ Keep application help and your documentation website in one content source. `sho
 
    ```js
    const manifest = await fetch('/help/manifest.json').then(response => response.json());
-   if (manifest.schemaVersion !== 1 || manifest.review.status !== 'ok') {
+   if (manifest.schemaVersion !== 1 || manifest.review?.status !== 'ok' ||
+       !Array.isArray(manifest.resources)) {
      throw new Error('Unsupported or unreviewed help export');
    }
-   const help = manifest.documents.find(document => document.id === 'guide.api-keys');
+   const help = manifest.resources.find(resource =>
+     resource.ref.kind === 'page' && resource.ref.documentId === 'guide.api-keys');
+   if (!help?.representations.html) throw new Error('API-key HTML is unavailable');
    const html = await fetch(manifest.publicBase + help.representations.html.path)
      .then(response => response.text());
    helpContainer.innerHTML = html;
@@ -108,6 +111,6 @@ Keep application help and your documentation website in one content source. `sho
 
 4. ## Handle document links and check the result
 
-   Links to other exported pages have `data-export-link` markers. Each marker identifies a record in that representation's `links` array. For `kind: document`, your app can prevent ordinary navigation and open `documentId` in the drawer. `fragment` identifies the original heading or anchor; the HTML representation's `anchors` array maps it to its namespaced `exportedId`.
+   Links to other exported pages have `data-export-link` markers. Each marker identifies a record in that representation's `links` array. For `kind: resource`, your app can prevent ordinary navigation and retrieve the target using its typed `ref`. A page reference contains `kind: page` and `documentId`; section and snippet references have their own identity fields. `fragment` identifies the original heading or anchor; the HTML representation's `anchors` array maps it to its namespaced `exportedId`.
 
    A link to an omitted document uses its canonical website URL only when that document is public, enabled, and selected for the website. Without an eligible destination and a configured origin, the export fails. Linked pages are never silently added to the export. Explicit external links retain their destinations.

package/agent-docs/publish/content-export.sections/inspect-the-manifest.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -24,6 +24,8 @@ Keep application help and your documentation website in one content source. `sho
 
 ## Inspect the manifest
 
-The versioned `manifest.json` identifies documents by ID and publication. It includes titles, summaries, types, eligible canonical URLs, representation paths and digests, typed links, HTML anchor maps, local assets, external image dependencies, and diagnostics. It does not copy raw source frontmatter, configuration, local dependency paths, or browser runtime payloads.
+The manifest uses typed `resources` for pages, sections, and snippet instances. See the [manifest contract](https://www.shoalrun.com/content-delivery/manifest.md) and [content client](https://www.shoalrun.com/content-delivery/client.md) for resource lookup and retrieval.
+
+The versioned `manifest.json` identifies resources by typed reference and publication. It includes titles, summaries, types, eligible canonical URLs, representation paths and digests, typed links, HTML anchor maps, local assets, external image dependencies, and diagnostics. It does not copy raw source frontmatter, configuration, local dependency paths, or browser runtime payloads.
 
 The bundle's `digest` is the SHA-256 of `JSON.stringify` of the parsed manifest with its own `digest` field removed. The `files` list records byte counts and SHA-256 digests for every payload file, including notices. All text is UTF-8. The manifest itself is excluded from that list. Deterministic output lets applications compare bundles and invalidate cached content.

package/agent-docs/publish/content-export.sections/prerequisites.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -24,6 +24,6 @@ Keep application help and your documentation website in one content source. `sho
 
 ## Prerequisites
 
-Content exports require Shoalrun CLI `0.1.0-alpha.6` or later.
+Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This guide uses the resource-based export manifest described in the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md).
 
 Start with a Shoalrun project and public pages assigned to an enabled publication. Navigation, facets, a site title, and a previous website build are optional. A site origin is needed only when links must fall back to pages on the documentation website. The export does not generate embeddings or run documentation chat.

package/agent-docs/publish/content-export.sections/related-reading.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 

package/agent-docs/publish/content-export.sections/review-exported-api-material.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -27,7 +27,7 @@ Keep application help and your documentation website in one content source. `sho
 The export preserves the API source-review gate. If its selected API material has no matching review digest, the normal command fails before replacing the previous bundle. Produce a candidate for inspection with:
 
 ```sh
-shoalrun export docs.config.yaml --target app-help --out review/app-help --review
+npx --no-install shoalrun export docs.config.yaml --target app-help --out review/app-help --review
 ```
 
 A candidate needing review reports `status: needs-review`, sets `manifest.review.status: required`, and exits with code 2. Inspect its references and downloads, then pin the reported API digests to the target:

package/agent-docs/publish/content-export.sections/try-the-help-drawer-example.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -27,7 +27,7 @@ Keep application help and your documentation website in one content source. `sho
 The package's `examples/help-drawer` directory contains a small application with two help documents, an image, a diagram, reader sections, tabs, a walkthrough, and a custom component. Copy it into a project with Shoalrun installed, then run from that example directory:
 
 ```sh
-shoalrun export docs.config.yaml --target app-help --out public/help
+npx --no-install shoalrun export docs.config.yaml --target app-help --out public/help
 node preview.mjs
 ```
 

package/agent-docs/publish/content-export.sections/upgrade-an-existing-integration.md

@@ -0,0 +1,34 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export selected documentation and assets for your application.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/content-export
+---
+
+# Export content into your 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) > Publish and maintain > Export content into your application
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/content-export.md)
+
+Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It does not need a Shoalrun browser runtime.
+
+## Upgrade an existing integration
+
+If an existing bundle contains `manifest.documents`, upgrade the CLI and rebuild the export before using this guide's loader. Update custom consumers to the resource contract:
+
+- Read `manifest.resources` instead of `manifest.documents`.
+- Select page resources with `ref.kind === 'page'` and `ref.documentId` instead of a document's `id`.
+- Route links with `kind: resource` through their typed `ref`, rather than `kind: document` and `documentId`.
+- Read file paths from the rebuilt manifest; do not retain paths from the old bundle.
+
+The `documents` configuration selector remains shorthand for whole pages. Use [resource selectors](https://www.shoalrun.com/content-delivery/select.md) when selecting approved sections or named snippet instances.

package/agent-docs/publish/content-export.sections/what-the-representations-retain.md

@@ -1,7 +1,7 @@
 ---
 id: guide.content-export
 title: Export content into your application
-summary: Export shared content for application help.
+summary: Export selected documentation and assets for your application.
 type: how-to
 area: publishing
 subarea: publishing-builds
@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export content into your application
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/content-export.md)
 
@@ -38,6 +38,6 @@ Exports resolve snippets, supported components, and API material before renderin
 
 HTML contains no site navigation, theme, required scripts, or app-wide stylesheet. It remains readable without CSS; your app styles its content container. HTML and Markdown are rendered independently from the same resolved source, so [representation-specific blocks](https://www.shoalrun.com/author/components/only.md) retain their intended differences.
 
-HTML heading, footnote, and other IDs are namespaced per document. Mount each exported document once per DOM. Repeated simultaneous instances require the application to rewrite IDs and all corresponding fragment and ARIA references. Markdown heading anchors depend on the customer's renderer; the export does not promise identical anchor generation across Markdown libraries.
+HTML heading, footnote, and other IDs are namespaced per resource. Directly inserting the same HTML more than once can duplicate IDs. Use [mountContent](https://www.shoalrun.com/content-delivery/render.md) for simultaneous instances; it rewrites IDs and their fragment and ARIA references for each mount. Markdown heading anchors depend on the customer's renderer; the export does not promise identical anchor generation across Markdown libraries.
 
-Whole pages are the supported units. The website's size-based section resources are not exported as stable application-help IDs.
+Exports support pages, explicitly approved sections, and named snippet instances. Application section fragments use `{ id, context: section }` approval; they are separate from the website's size-based contextual agent sections. See [select content resources](https://www.shoalrun.com/content-delivery/select.md) for configuration and approval examples.

package/agent-docs/publish/mcp.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Connect an MCP client to built documentation through four read-only tools. Use stdio for a client-launched local process, or enable an HTTP endpoint on Node or in a generated Vercel function. Both use the same search and Markdown reading core.
 
@@ -187,4 +187,6 @@ The tools are read-only and do not expose authoring commands. Stdio makes them a
 
 ### Related topics
 
+- [Content delivery and agents](https://www.shoalrun.com/content-delivery/agents.md) — Use existing documentation MCP tools for contextual reads.
+
 - [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Understand the published Markdown and discovery surfaces alongside MCP.

package/agent-docs/publish/mcp.sections/check-budgets-and-errors.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/choose-the-documentation-source.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/configure-the-client.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/generate-a-vercel-endpoint.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 
@@ -39,4 +39,6 @@ You need Node.js 22.12 or newer, the installed Shoalrun CLI, and a client that s
 
 ### Related topics
 
+- [Content delivery and agents](https://www.shoalrun.com/content-delivery/agents.md) — Use existing documentation MCP tools for contextual reads.
+
 - [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — Understand the published Markdown and discovery surfaces alongside MCP.

package/agent-docs/publish/mcp.sections/search-then-read.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/serve-a-public-endpoint-on-node.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/verify-the-connection.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/mcp.sections/why-offer-mcp-for-public-docs.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Connect an MCP client
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/publish/mcp.md)
 

package/agent-docs/publish/seo.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
 
-**Updated: 2026-10-25.**
+**Updated: 2026-10-29.**
 
 When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
 
@@ -106,7 +106,21 @@ Set native frontmatter `verified` only when someone checks the page's technical
 verified: 2026-10-01
 ```
 
-The HTML page, Markdown twin, and manifest expose this date independently of Updated. A build never assigns it. This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
+The standard HTML page header displays `Verified` with a semantic `<time>` element. Markdown and `documents.json` expose the same date independently of `Updated`, which records content revision. A build never assigns `verified`; a build or editorial review alone does not establish technical verification.
+
+The HTML verification-date display and `showVerified` setting are available since `0.1.0-alpha.13`.
+
+Set `showVerified: false` in a page's frontmatter to hide the verification date in HTML only. It remains in Markdown and the manifest. The default is `true`. To hide it throughout a project, set a shared default:
+
+```yaml title="docs.config.yaml"
+frontmatter:
+  defaults:
+    showVerified: false
+```
+
+An individual page can override that default with `showVerified: true`. A page using a Hero replaces the standard header, so its header dates are not displayed.
+
+This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
 
 Search indexing still depends on the public host and crawler access; metadata alone does not guarantee it. If Slack does not unfurl after a corrected deployment, confirm the page and image are public, then try sharing the link in a new conversation. [Slack may omit a preview](https://slack.com/help/articles/204399343-Share-links-and-set-preview-preferences) when the same link was recently posted in that conversation.