@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

package/schemas/content-rest.openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Shoalrun content REST API",
     "version": "1.0.0",
-    "description": "Read-only delivery of reviewed content snapshots. This is HTTP contract v1, independent of the Shoalrun package version. The reference adapter serves one supplied revision per publication. It retains no revision history. Exported HTML/Markdown bytes are unchanged: host their original static asset and link mount alongside the API."
+    "description": "Read-only delivery of reviewed content snapshots. The endpoints accept legacy productless publication envelopes (schemaVersion 1) and product-scoped envelopes (schemaVersion 2). This is HTTP contract v1, independent of the Shoalrun package version. The reference adapter serves one supplied revision per publication. It retains no revision history. Exported HTML/Markdown bytes are unchanged: host their original static asset and link mount alongside the API."
   },
   "servers": [
     {
@@ -26,6 +26,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/optionalRevision"
           },
@@ -251,6 +254,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/optionalRevision"
           },
@@ -376,6 +382,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/revision"
           },
@@ -600,6 +609,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/revision"
           },
@@ -728,6 +740,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/revision"
           },
@@ -923,6 +938,9 @@
           {
             "$ref": "#/components/parameters/language"
           },
+          {
+            "$ref": "#/components/parameters/product"
+          },
           {
             "$ref": "#/components/parameters/revision"
           },
@@ -1070,6 +1088,10 @@
           "language": {
             "type": "string",
             "minLength": 1
+          },
+          "product": {
+            "type": "string",
+            "minLength": 1
           }
         }
       },
@@ -1458,69 +1480,65 @@
           }
         }
       },
-      "ResourceEntry": {
+      "PublicationV1": {
         "type": "object",
         "additionalProperties": false,
         "required": [
-          "key",
-          "resource"
+          "channel",
+          "version",
+          "language"
         ],
         "properties": {
-          "key": {
-            "$ref": "#/components/schemas/ResourceKey"
+          "channel": {
+            "type": "string",
+            "minLength": 1
           },
-          "resource": {
-            "$ref": "#/components/schemas/ContentResource"
+          "version": {
+            "type": "string",
+            "minLength": 1
+          },
+          "language": {
+            "type": "string",
+            "minLength": 1
           }
         }
       },
-      "ResourceList": {
+      "PublicationV2": {
         "type": "object",
         "additionalProperties": false,
         "required": [
-          "schemaVersion",
-          "revision",
-          "publication",
-          "resources"
+          "channel",
+          "version",
+          "language",
+          "product"
         ],
         "properties": {
-          "schemaVersion": {
-            "const": 1
+          "channel": {
+            "type": "string",
+            "minLength": 1
           },
-          "revision": {
-            "$ref": "#/components/schemas/digest"
+          "version": {
+            "type": "string",
+            "minLength": 1
           },
-          "publication": {
-            "$ref": "#/components/schemas/publication"
+          "language": {
+            "type": "string",
+            "minLength": 1
           },
-          "resources": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/ResourceEntry"
-            }
+          "product": {
+            "type": "string",
+            "minLength": 1
           }
         }
       },
-      "ResourceMetadata": {
+      "ResourceEntry": {
         "type": "object",
         "additionalProperties": false,
         "required": [
-          "schemaVersion",
-          "revision",
-          "publication",
           "key",
           "resource"
         ],
         "properties": {
-          "schemaVersion": {
-            "const": 1
-          },
-          "revision": {
-            "$ref": "#/components/schemas/digest"
-          },
-          "publication": {
-            "$ref": "#/components/schemas/publication"
-          },
           "key": {
             "$ref": "#/components/schemas/ResourceKey"
           },
@@ -1528,6 +1546,124 @@
             "$ref": "#/components/schemas/ContentResource"
           }
         }
+      },
+      "ResourceList": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "schemaVersion",
+              "revision",
+              "publication",
+              "resources"
+            ],
+            "properties": {
+              "schemaVersion": {
+                "const": 1
+              },
+              "revision": {
+                "$ref": "#/components/schemas/digest"
+              },
+              "publication": {
+                "$ref": "#/components/schemas/PublicationV1"
+              },
+              "resources": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/ResourceEntry"
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "schemaVersion",
+              "revision",
+              "publication",
+              "resources"
+            ],
+            "properties": {
+              "schemaVersion": {
+                "const": 2
+              },
+              "revision": {
+                "$ref": "#/components/schemas/digest"
+              },
+              "publication": {
+                "$ref": "#/components/schemas/PublicationV2"
+              },
+              "resources": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/ResourceEntry"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "ResourceMetadata": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "schemaVersion",
+              "revision",
+              "publication",
+              "key",
+              "resource"
+            ],
+            "properties": {
+              "schemaVersion": {
+                "const": 1
+              },
+              "revision": {
+                "$ref": "#/components/schemas/digest"
+              },
+              "publication": {
+                "$ref": "#/components/schemas/PublicationV1"
+              },
+              "key": {
+                "$ref": "#/components/schemas/ResourceKey"
+              },
+              "resource": {
+                "$ref": "#/components/schemas/ContentResource"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "schemaVersion",
+              "revision",
+              "publication",
+              "key",
+              "resource"
+            ],
+            "properties": {
+              "schemaVersion": {
+                "const": 2
+              },
+              "revision": {
+                "$ref": "#/components/schemas/digest"
+              },
+              "publication": {
+                "$ref": "#/components/schemas/PublicationV2"
+              },
+              "key": {
+                "$ref": "#/components/schemas/ResourceKey"
+              },
+              "resource": {
+                "$ref": "#/components/schemas/ContentResource"
+              }
+            }
+          }
+        ]
       }
     },
     "parameters": {
@@ -1567,6 +1703,17 @@
           "maxLength": 2048
         }
       },
+      "product": {
+        "name": "product",
+        "in": "query",
+        "required": false,
+        "description": "Exact product ID. Required for product-scoped publications; omitted selects only a legacy productless publication. No cross-product fallback.",
+        "schema": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048
+        }
+      },
       "revision": {
         "name": "revision",
         "in": "query",

package/skills/shoalrun-author/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shoalrun-author
-description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, customer editions, or project checks.
+description: Write or revise documentation in an existing Shoalrun project using the agent's own model, native file edits, and provider-free project, validation, and preview tools. Use for pages and their required navigation, relationships, API links, snippets, product publications, customer editions, or project checks.
 ---
 
 # Author Shoalrun documentation
@@ -21,9 +21,13 @@ When reading a published site through Markdown, follow topic-index links when pr
 
 Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
 
+## Products and availability
+
+For independently versioned products, cross-product reuse, product-scoped delivery, or feature availability labels, read [references/publications.md](references/publications.md). Preserve product/channel/version/language identity, distinguish publication membership from feature grants, and check installed-version support before using new fields. Availability labels describe support; they don't filter the published content.
+
 ## Customer editions and feature selection
 
-For SKU-selected or white-label documentation, read [references/customer-editions.md](references/customer-editions.md) before editing requirements, manifests, profiles, branding, or edition validation. Use the deployment's external profile, keep customer records out of shared source, and classify pages by feature IDs. Shared pages can use `<ForFeature>` for product-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, and export; a default-context pass does not verify a customer edition.
+For SKU-selected or white-label documentation, read [references/customer-editions.md](references/customer-editions.md) before editing requirements, manifests, profiles, branding, or edition validation. Use the deployment's external profile, keep customer records out of shared source, and classify pages by feature IDs. Shared pages can use `<ForFeature>` for feature-specific sections. Preserve the project's strict-classification policy and pass the same `--profile` to baseline, validation, build, export, and development preview; a default-context pass does not verify a customer edition.
 
 ## Record scope and edit
 

package/skills/shoalrun-author/references/customer-editions.md

@@ -64,6 +64,26 @@ directory and must remain inside it. Branding uses bounded existing `site`, `the
 and snippet `variables` settings, not arbitrary config merges. Profiles cannot
 replace content sources, plugins, access policy, or navigation labels.
 
+## Select independent product releases
+
+For `0.1.0-alpha.18` and later, inspect `publications.products` and read
+[publications.md](publications.md) before selecting releases. A deployment can
+select one product's v3 and another product's v1 independently. These are
+publication choices, separate from SKU revisions and feature grants:
+
+```yaml
+# Profile fragment using fictional products declared in the shared catalog
+publications:
+  enabled:
+    - { product: payments, channel: production, version: v3, language: en }
+    - { product: reporting, channel: production, version: v1, language: en }
+```
+
+Use the selected product when reading a repeated page ID or binding an API
+source. Preserve all publication coordinates in validation evidence, links,
+search reads, and content exports. Without a product catalog, retain existing
+productless coordinates rather than adding a product field to every page.
+
 ## Choose page and section requirements
 
 In normal mode, a page with no authored or inherited `requires` is shared after
@@ -94,7 +114,7 @@ Requirements name feature IDs, not SKUs. Use `allOf` when every feature is neede
 and `anyOf` when one suffices; if both clauses appear, both must pass. Lists are
 nonempty. Unmet page requirements omit the whole page.
 
-A shared page may contain product-specific sections:
+A shared page may contain feature-specific sections:
 
 ```mdx
 These setup instructions apply to every customer.
@@ -146,9 +166,19 @@ Use explicit `--file`/`--id` selectors if no baseline exists. Apply the authorin
 skill's applicable project checks, review, preview, and freshness workflow to the
 returned report. Snapshot capture includes the external profile and its declared
 assets; changing them invalidates the evidence. Export still needs its normal
-publication selection when multiple combinations are enabled. `dev` and
-checked-plan authoring do not resolve deployment editions; use build/serve or
-snapshot validation/preview. Preview URLs and artifacts may contain customer data.
+publication selection when multiple combinations are enabled. On `0.1.0-alpha.18`
+or later, preview the selected edition while editing with:
+
+```sh
+shoalrun dev docs.config.yaml edition-dist --profile /run/config/docs-profile.yaml
+```
+
+It watches the chosen profile and declared dependencies, keeps the last good
+output on a failed rebuild, and shows that failure in the preview. Correct the
+input and verify recovery. On older releases use a profiled build followed by
+`serve`. Checked-plan authoring doesn't resolve deployment editions; retain
+snapshot validation/preview for those authoring checks. Preview URLs and
+artifacts may contain customer data.
 
 Check both included and excluded content in HTML, Markdown, search/discovery,
 focused API contracts, and exports. Use synthetic no-grant, relevant single-feature,

package/skills/shoalrun-author/references/publications.md

@@ -0,0 +1,60 @@
+# Author independent product publications
+
+Use this reference when a project gives products independent releases, shares
+pages across products, or delivers documentation for a selected product release.
+Product catalogs and product-aware commands require `0.1.0-alpha.18` or later.
+Check the installed version and command help; don't silently upgrade a pin.
+Read `guide.publications` and `reference.config-publishing` when the bundled
+snapshot contains them. The package's `README.md` and `AUTHORING.md` describe
+newer behavior when that snapshot is older.
+
+## Preserve publication identity
+
+Inspect `publications.products` before treating `frontmatter.product` as a facet.
+With a catalog, a publication includes product, channel, version, and language.
+Each product has its own versions, default version, and route prefix. An omitted
+product version uses that product's default unless matching
+`publications.defaults.product` and `version` override it. Don't borrow another
+product's release or a global frontmatter version. Without a catalog, existing product
+metadata and productless publication identities retain their meaning.
+
+Set `product`, `channel`, and `version` for one page variant, or list complete
+coordinates in `publications` to share one source. Don't combine those two forms.
+Keep language at page level. `shared: true` classifies customer feature eligibility;
+it doesn't copy a page into other products. Use `<ForPublication product="...">`
+for publication-specific content and `<ForFeature>` for purchased features.
+
+Ordinary links, navigation, search, and reads stay in the selected publication.
+Name the destination product and version on a deliberate cross-product `DocLink`.
+Retain all coordinates from search results when reading repeated stable page IDs.
+For a built site, supply `--site OUTPUT --product ID --channel CHANNEL --version
+VERSION --language LANGUAGE` to scoped docs reads. MCP `get_publications` is a
+bounded discovery tool: follow `nextOffset` rather than fetching page inventories.
+A hosted endpoint still exposes only its configured publication.
+
+## Preview and delivery
+
+For customer editions, read [customer-editions.md](customer-editions.md). A profile
+selects product releases separately from feature grants. On supported releases,
+`shoalrun dev docs.config.yaml edition-dist --profile /path/to/profile.yaml`
+builds, serves, and watches that selection. Reader views and the publication
+dropdown aren't feature gates. Check included and excluded content in HTML,
+Markdown, search, and exports using the same profile.
+
+Product-aware content manifests and REST envelopes use schema v2; productless
+exports retain v1. The HTTP path remains `/content/v1`. Preserve exact product
+coordinates and use a compatible client; don't rewrite legacy resource keys or
+silently fall back to another product. Read `guide.content-export` and
+`reference.content-manifest` before changing an application consumer.
+
+## Feature availability
+
+On supported releases, use page-specific `availability: { since: VERSION }` and/or
+`through: VERSION` for authored support boundaries. Both are inclusive labels,
+not automatic version comparisons or publication selectors. They use the existing
+release-version text style beside page dates and remain readable in Markdown and
+the document manifest. Use the actual first supported release, backed by release
+evidence or an approved release plan. For a newer section in an older guide, place
+`<Badge variant="neutral">Since VERSION</Badge>` beside that section and keep the
+page's original availability. Don't assign the newest option's version to the
+whole guide.

package/skills/shoalrun-recipes/SKILL.md

@@ -13,6 +13,8 @@ Read `shoalrun docs read guide.recipes-overview`, then `guide.recipe-drafts` for
 
 When recipes or ingredients vary by purchased features, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md). Apply page classification to the final recipe source, use `<ForFeature>` for feature-specific sections, and validate editions that include each changed conditional branch. Do not assume a shared-page build checks an excluded recipe or ingredient branch.
 
+When recipes or ingredients vary by product release, read [the publication workflow](../shoalrun-author/references/publications.md). Preserve product/channel/version/language in scaffolding, API selection, and preview. Explicit publication memberships control reuse; `shared: true` doesn't replicate a recipe into other products. Use an availability label for a newer capability without changing an older recipe's first supported version.
+
 Choose only the layers the task needs:
 
 - **Recipe:** write a complete page with prerequisites, ordered actions, explicit value handoffs, failure guidance, and a final success check. A recipe can be authored directly; ingredients are optional.

package/skills/shoalrun-setup/SKILL.md

@@ -11,7 +11,9 @@ When adapting existing documentation, start with a connected, representative set
 
 Use `shoalrun init <directory> --starter minimal` for a small site or `--starter api-docs` for a parcel API site with guides, generated references, and focused contracts. Use `--starter showcase` for a fuller Cedar Parcel handbook with component examples, diagrams, reader views, a landing page, local-workflow cookbook, and generated API references. All three starters build without provider credentials. The command copies a bundled example without overwriting existing files. From the source checkout, use `node framework/dist/cli.js init <directory> --starter <name>` from the repository root. Replace fixture names, prose, API files, navigation, and example domains. Keep `docs.config.yaml` as the entry point. Consult the Shoalrun config reference for unfamiliar keys; do not invent config fields or assume that a package has been published to npm.
 
-For customer-specific or white-label editions, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md) before configuring selection. Keep the SKU manifest shared and the selected customer profile in its deployment environment. Check CLI support before using `--profile`, preserve strict-classification choices, and use that profile for validation and build/serve; `dev` does not resolve deployment editions.
+For customer-specific or white-label editions, read [the customer-edition workflow](../shoalrun-author/references/customer-editions.md) before configuring selection. Keep the SKU manifest shared and the selected customer profile in its deployment environment. Check CLI support before using `--profile`, preserve strict-classification choices, and use that profile for validation, build, and export. On `0.1.0-alpha.18` or later, `shoalrun dev docs.config.yaml edition-dist --profile /path/to/profile.yaml` builds, serves, and watches that edition; older releases need a profiled build followed by `serve`.
+
+When products need independent releases, read [the publication workflow](../shoalrun-author/references/publications.md). On supported releases, configure `publications.products` with each product's versions, default, and prefix; select exact product coordinates in enabled publications and pages. Don't turn a reader facet into a product catalog unless the task calls for that migration. The package's `example-configs/products` is a fictional multi-product/profile example, not an `init --starter` option.
 
 Run scaffolding from the project directory or use an absolute target path. Passing `--config` does not rebase `scaffold -n` against that config's directory. Resolve scaffold placeholders and remove unused optional sections while retaining the page's intended identity and draft access.
 

package/styles/header.css

@@ -2,6 +2,8 @@
 /* Form fields need a 3:1 boundary (WCAG 1.4.11); this outranks the base navigation filter rule. */
 .side .nav-search input{border-color:var(--color-field-border)}
 .mast-tools{display:flex;align-items:center;gap:.75rem;margin-left:auto;min-width:0}
+.publication-picker{flex:0 1 auto;min-width:0;max-width:min(28rem,100%);min-height:2.5rem;padding:.35rem .7rem;border:1px solid var(--color-field-border);border-radius:var(--radius-small);background:var(--color-field-surface);color:var(--color-ink);font:inherit;font-size:.8rem;font-weight:650;cursor:pointer}
+.publication-picker:focus-visible{outline:2px solid var(--color-accent);outline-offset:2px}
 .publication-switcher{position:relative;flex:none}
 .publication-switcher summary{display:flex;align-items:center;gap:.45rem;min-height:2.5rem;padding:.35rem .7rem;border:1px solid var(--color-field-border);border-radius:var(--radius-small);background:var(--color-field-surface);color:var(--color-ink);font-size:.8rem;cursor:pointer;list-style:none}
 .publication-switcher summary::-webkit-details-marker{display:none}
@@ -43,6 +45,7 @@
 .mode-toggle .mode-icon-dark,.mode-toggle[aria-pressed=true] .mode-icon-light{display:none}
 .mode-toggle[aria-pressed=true] .mode-icon-dark{display:block}
 @media(max-width:48rem){
+  .publication-picker{max-width:100%;flex:1 1 15rem}
   .mast-tools{position:relative;order:3;width:100%;flex-wrap:wrap;margin-left:0}
   .site-search{position:static;flex:1 1 10rem;min-width:0;width:auto}
   .site-search-results{left:0;right:auto;width:100%}

package/styles/site.css

@@ -176,6 +176,9 @@ button{cursor:pointer}
 .content .summary{font-size:1.1rem;line-height:1.65;color:var(--color-summary);max-width:58ch;margin:0 0 1.25rem}
 .page-date,.page-version{display:block;font-family:var(--font-code);font-size:.8rem;color:var(--color-muted);margin:-.45rem 0 1.2rem}
 .page-date+.page-version{margin-top:-.8rem}
+.page-head .page-meta{display:flex;align-items:center;flex-wrap:wrap;gap:.45rem .85rem;margin:-.45rem 0 1.2rem}
+.page-head .page-meta .page-date,.page-head .page-meta .page-version{display:inline;margin:0}
+
 .audience-labels{display:flex;align-items:center;flex-wrap:wrap;gap:.4rem;margin:-.25rem 0 1.25rem;font-size:.78rem}
 .audience-label-heading{font-weight:650;color:var(--color-muted);margin-right:.1rem}
 .audience-badge{padding:.2rem .55rem;border:1px solid var(--color-border);border-radius:999px;background:var(--color-surface);color:var(--color-ink);font-weight:600;line-height:1.4;overflow-wrap:anywhere}

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

@@ -1,116 +0,0 @@
----
-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.
-
-## Export selected pages
-
-1. ## Define an export target
-
-   Add a named target to `docs.config.yaml`. These IDs refer to pages in the project's configured content directory:
-
-   ```yaml
-   exports:
-     app-help:
-       formats: [markdown, html]
-       documents: [guide.api-keys, guide.billing]
-       publicBase: /help/
-   ```
-
-   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:
-     app-help:
-       formats: [html]
-       documents: [guide.api-keys, guide.billing]
-       publication: { channel: production, version: current, language: en }
-       publicBase: /help/
-   ```
-
-   Optional `contentFilter` uses configured reader facets. Every selected facet must match; choices within a facet are alternatives. Pages missing a selected facet are excluded. An explicitly requested ID that is absent, private, unavailable in the publication, or excluded by the export filter fails with a diagnostic.
-
-   Export selection is independent of the website's `site.contentFilter` and navigation. Changing a website menu does not change the app's help collection. See [separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) for website selection.
-
-2. ## Build the portable bundle
-
-   From the documentation project, run:
-
-   ```sh
-   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.
-
-   The result has this structure:
-
-   ```text
-   help/
-     manifest.json
-     content/
-       ...HTML and Markdown files
-     assets/
-       ...referenced local files
-     NOTICES.txt
-   ```
-
-   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
-   npx --no-install shoalrun export docs.config.yaml --out ../app/public/help \
-     --format html --document guide.api-keys --document guide.billing \
-     --public-base /help/
-   ```
-
-3. ## Mount and load the content in your app
-
-   `/help/` is an example value, not a required path. Choose any root-relative path ending with a slash, such as `/resources/`. Set `publicBase` to that path, serve the generated bundle there, and update the manifest URL in your app's loader to match (for example, `/resources/manifest.json`). The `--out` filesystem directory can have a different name from the URL path.
-
-   The examples below use `/help/`. This base locates content and assets; it does not define your application's routes.
-
-   Your app can find a page by ID and load its HTML fragment:
-
-   ```js
-   const manifest = await fetch('/help/manifest.json').then(response => response.json());
-   if (manifest.schemaVersion !== 1 || manifest.review?.status !== 'ok' ||
-       !Array.isArray(manifest.resources)) {
-     throw new Error('Unsupported or unreviewed help export');
-   }
-   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;
-   ```
-
-   Use this pattern for trusted output from your own documentation build. Handle missing documents and failed requests in your application's loading and error states. The manifest also provides Markdown paths if your app uses its own Markdown renderer.
-
-   Images use the configured mount. This matters when HTML fetched from `/help/content/` is inserted into an app page such as `/settings/account`: relative image URLs would otherwise resolve against the app page.
-
-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: 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.