@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

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

@@ -0,0 +1,113 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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 `documents` 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
+   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 stable document 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 \
+     --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') {
+     throw new Error('Unsupported or unreviewed help export');
+   }
+   const help = manifest.documents.find(document => document.id === 'guide.api-keys');
+   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: 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`.
+
+   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

@@ -0,0 +1,29 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## 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 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

@@ -0,0 +1,29 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## Prerequisites
+
+Content exports require Shoalrun CLI `0.1.0-alpha.6` or later.
+
+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

@@ -0,0 +1,35 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up named export targets and selection settings.
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) — Understand why exported reader sections remain complete labeled content.
+
+### Related topics
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Reuse the same authored content inside an application.

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

@@ -0,0 +1,44 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## 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
+```
+
+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:
+
+```yaml
+exports:
+  app-help:
+    documents: [reference.catalog.listItems]
+    publicBase: /help/
+    apiReview:
+      catalog: "REPLACE_WITH_THE_REVIEWED_SHA256_DIGEST"
+```
+
+Run the normal export command again. Changed source bytes or exposed API selections invalidate approval. An existing `apis.<id>.publicReview.digest` also applies when it exactly matches the export's review fingerprint. Do not distribute candidates with review still required.

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

@@ -0,0 +1,34 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## Try the help-drawer example
+
+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
+node preview.mjs
+```
+
+Open `http://127.0.0.1:8774/settings/account`. Choose **Help with API keys**, follow **Billing help** inside the drawer, then follow the API-key link back. The app remains on its settings route. No Shoalrun browser runtime is loaded. The omitted account guide uses the configured example documentation origin; replace that origin and deploy the corresponding docs page for a working external destination.

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

@@ -0,0 +1,43 @@
+---
+id: guide.content-export
+title: Export content into your application
+summary: Export shared content for application help.
+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-26.**
+
+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.
+
+## What the representations retain
+
+Exports resolve snippets, supported components, and API material before rendering. Static output keeps the substantive content of interactive components:
+
+| Source content                                     | Export behavior                                                                              |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Prose, tables, lists, callouts, and code           | Preserve their content and structure.                                                        |
+| Tabs, disclosures, and walkthroughs                | Keep all panels, disclosure content, and steps as visible labeled content.                   |
+| Reader sections                                    | Keep every section with a readable audience or facet label.                                  |
+| Custom components                                  | Keep shared documentation content; omit browser modules, browser data, and component styles. |
+| Diagrams and images                                | Copy referenced local visuals; diagrams retain their source in Markdown.                     |
+| Math                                               | Preserve the LaTeX expression as readable code.                                              |
+| Browser filters, reader controls, and copy buttons | Omit the controls.                                                                           |
+
+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.
+
+Whole pages are the supported units. The website's size-based section resources are not exported as stable application-help IDs.

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

@@ -0,0 +1,121 @@
+---
+id: guide.content-negotiation
+title: Content negotiation
+summary: Understand content negotiation, why it helps agents, and what a hosting
+  provider needs to do.
+type: reference
+area: discovery
+subarea: discovery-agents
+canonical: /publish/content-negotiation
+---
+
+# Content negotiation
+
+> 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) > Output and presentation > Content negotiation
+
+**Updated: 2026-10-26.**
+
+Shoalrun builds two versions of every published page from one authored source. The HTML version is for people using a browser. The generated Markdown version contains shared material in a form agents can read directly. Authors can also add or suppress [format-specific content](https://www.shoalrun.com/author/components/only.md) in either version. The versions share a core but need not contain identical text.
+
+**Content negotiation** lets a visitor ask for a format at the page's usual URL. Some agents send the request header `Accept: text/markdown`. A host that supports negotiation responds with Shoalrun's Markdown version. A browser asking for HTML gets the HTML version. The URL stays the same:
+
+| Request to `/publish/output/`       | Response                                     |
+| ----------------------------------- | -------------------------------------------- |
+| Browser sends `Accept: text/html`   | HTML page, `Content-Type: text/html`         |
+| Agent sends `Accept: text/markdown` | Markdown page, `Content-Type: text/markdown` |
+
+`Accept` says what the visitor can use. `Content-Type` says what the host actually returned. The `.md` URL, such as `/publish/output.md`, also works directly.
+
+## Why this matters
+
+An agent reading HTML may receive navigation, styles, scripts, and interactive controls along with the article. It may then have to extract the useful content or convert the HTML to Markdown. Shoalrun's generated Markdown gives it the article directly, including material inside tabs and collapsibles and resolved OpenAPI examples. This can make the page easier to retrieve and less likely to lose content during conversion. [AFDocs checks](https://afdocs.dev/checks/markdown-availability) both `.md` URLs and content negotiation for this reason.
+
+The direct `.md` links in each HTML page and [`/llms.txt`](https://www.shoalrun.com/llms.txt) help agents that know to follow them. Negotiation helps an agent that arrives at the ordinary page URL and requests Markdown without first discovering a second URL. It does not require writers to maintain a separate article.
+
+## What Shoalrun builds and what the host does
+
+Shoalrun creates the HTML page, its `.md` twin, and a [`/documents.json`](https://www.shoalrun.com/documents.json) manifest listing both URLs. It also writes [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) with content types for Markdown and discovery files.
+
+The host receives each HTTP request. It must read `Accept` and select the right built file. Providers use different names for this step: a server handler, a routing rule, or an edge function. The HTTP behavior is the same. A static file alone cannot read a request header.
+
+Shoalrun's Node server handles this. The standalone [Vercel build](https://www.shoalrun.com/publish/vercel.md) generates Vercel rules. On another host, use the contract below to configure its routing feature. The [host adapter guide](https://www.shoalrun.com/publish/host-adapters.md) covers adding Shoalrun's files to another build.
+
+## Hosting contract
+
+For each published page, use the two URLs in `documents.json`. Configure the host as follows:
+
+1. At the page URL, return the Markdown twin when `Accept` explicitly requests `text/markdown` with a nonzero quality value. Otherwise return HTML.
+2. Keep the URL in the browser unchanged when serving the twin. Use an internal rewrite or server response, not a redirect to `.md`.
+3. On the Markdown response, set `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, and `Content-Location` to the `.md` URL.
+4. On both page responses, set `Link: <PAGE.md>; rel="alternate"; type="text/markdown"`. Keep the HTML document's existing alternate link as well.
+5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it is published.
+6. Limit the negotiation rule to published documentation pages. Leave assets, API contracts, and `/llms.txt` alone. Missing routes use the error responses described below.
+
+The Vercel rule matches the Node server except when `text/markdown` and the HTML or wildcard entry it competes with both have fractional weights. The [Vercel guide](https://www.shoalrun.com/publish/vercel.md) gives the details. The Node server compares the requested HTML and Markdown weights. When the weights tie, Markdown wins. A wildcard such as `text/*` or `*/*` alone never selects Markdown; the request must name `text/markdown`.
+
+To try it locally, run `npm run docs:preview` from the repository root, then request a page:
+
+```sh
+curl -i -H 'Accept: text/markdown' http://127.0.0.1:8770/publish/agent-friendliness/
+```
+
+## Validators and manifest links
+
+A Markdown response includes its canonical HTML link and a `rel="describedby"` link to its current manifest record. The latter uses a JSON Pointer fragment, such as `/documents.json#/documents/3`. Fetch the manifest and select that array entry to read the page's ID, publication variant, and digests. The index can move between builds; use the response's current link and verify the Markdown digest.
+
+Generated hosting metadata specifies a strong `ETag` equal to the quoted SHA-256 Markdown digest and `Cache-Control: public, max-age=0, must-revalidate`. The Node server handles matching `If-None-Match` requests with `304` and no body, including Markdown negotiated at an HTML URL. Negotiated responses retain `Vary: Accept`. Vercel receives the generated headers but can replace the ETag with its own validator, including a weak validator for compressed responses. Send the ETag returned by the host in `If-None-Match`; treat its value as opaque. To verify downloaded Markdown bytes, compare their SHA-256 with `digest` in the document manifest, independently of the HTTP validator.
+
+Focused contracts have content-addressed URLs and a one-year immutable cache policy. Mutable JSON manifests and indexes require revalidation. See [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.md) for URL identity and retention limits. `resource-headers.json` describes selected hosting headers, including Markdown, JSON metadata, and contracts; it is not an exhaustive inventory of every static asset.
+
+## Missing pages
+
+A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It does not redirect to the homepage or return an unrelated article with status `200`.
+
+Shoalrun's Node server returns Markdown for a missing `.md` URL or a request that prefers `Accept: text/markdown`; other requests receive HTML. Both responses carry `X-Robots-Tag: noindex`. If a known Markdown twin is missing while its HTML page exists, the response links to that HTML page in its body and `Link` header. Unexpected server errors return `500`.
+
+The build generates `404.html` and `404.md` under `site.basePath`. The Vercel adapter applies error routes after checking for existing files and preserves HTTP `404`. A missing known Markdown route includes an HTML alternate in its `Link` header. Its generic error body provides the discovery links.
+
+On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them does not configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.
+
+## What if the host cannot negotiate?
+
+GitHub Pages can publish Shoalrun's HTML, `.md` files, and `/llms.txt`. It serves static files and has no request handler for choosing a file from `Accept` or setting the page response headers described above. Agents can still read the `.md` URLs, but a request to the HTML URL cannot negotiate there. A programmable proxy or CDN can add that behavior. You can also publish the same built files on a host with request rules. Bare GitHub Pages cannot pass AFDocs' content-negotiation check.
+
+`site.basePath` also prefixes assets, API contracts, `/llms.txt`, and discovery files. For a GitHub Pages project site at `/<repository>/`, set `site.basePath: /<repository>` and publish the matching subtree from the build output as the project site's root. GitHub Pages still cannot provide Markdown content negotiation at an HTML URL.
+
+## Verify the deployed URL
+
+Run the [post-deploy checker](https://www.shoalrun.com/publish/deployment-check.md) against the real site origin from `framework/`. It tests every page in the deployed manifest, direct `.md` URLs, required headers, discovery resources, and 404 behavior:
+
+```sh
+npm run deploy:check -- https://your-docs.example/
+```
+
+For a manual check of one page, replace the domain and page path below with one from your site:
+
+```sh
+curl -i -H 'Accept: text/html' https://your-docs.example/publish/output/
+curl -i -H 'Accept: text/markdown' https://your-docs.example/publish/output/
+curl -i https://your-docs.example/publish/output.md
+curl -i -H 'Accept: text/markdown;q=0' https://your-docs.example/publish/output/
+```
+
+Check the status, headers, and body. The first and fourth requests should return HTML. The second and third should return readable Markdown that gives its reader what they need for the intended task. Shared facts and API constraints should stay consistent, while human- and agent-oriented content may differ; see [Shoalrun's authoring position](https://www.shoalrun.com/publish/agent-friendliness.md). The first two responses should include `Vary: Accept` so caches keep the formats separate, and a Markdown `Link` so clients can find the twin. The negotiated Markdown response should include `Content-Location` with its `.md` URL. Also check that a missing page returns 404 and the published discovery files have the types declared in `resource-headers.json`.
+
+Run these checks against the production domain after deployment. Local preview results establish what Shoalrun's Node server does; they do not prove that a CDN applies the same rules. For a whole-site audit, run the [AFDocs scorecard](https://afdocs.dev/) against the deployed site and review its findings against the site's content requirements.
+
+## Related reading
+
+### Next steps
+
+- [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) — Generate a Vercel deployment with negotiation already configured.
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — Supply the same HTTP rules on another host.
+
+### Related topics
+
+- [Content for one format](https://www.shoalrun.com/author/components/only.md) — Write instructions that apply to only the HTML page or only the Markdown twin.

package/agent-docs/publish/content-negotiation.sections/hosting-contract.md

@@ -0,0 +1,60 @@
+---
+id: guide.content-negotiation
+title: Content negotiation
+summary: Understand content negotiation, why it helps agents, and what a hosting
+  provider needs to do.
+type: reference
+area: discovery
+subarea: discovery-agents
+canonical: /publish/content-negotiation
+---
+
+# Content negotiation
+
+> 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) > Output and presentation > Content negotiation
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/content-negotiation.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) — Generate a Vercel deployment with negotiation already configured.
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — Supply the same HTTP rules on another host.
+
+Shoalrun builds two versions of every published page from one authored source. The HTML version is for people using a browser. The generated Markdown version contains shared material in a form agents can read directly. Authors can also add or suppress [format-specific content](https://www.shoalrun.com/author/components/only.md) in either version. The versions share a core but need not contain identical text.
+
+**Content negotiation** lets a visitor ask for a format at the page's usual URL. Some agents send the request header `Accept: text/markdown`. A host that supports negotiation responds with Shoalrun's Markdown version. A browser asking for HTML gets the HTML version. The URL stays the same:
+
+| Request to `/publish/output/`       | Response                                     |
+| ----------------------------------- | -------------------------------------------- |
+| Browser sends `Accept: text/html`   | HTML page, `Content-Type: text/html`         |
+| Agent sends `Accept: text/markdown` | Markdown page, `Content-Type: text/markdown` |
+
+`Accept` says what the visitor can use. `Content-Type` says what the host actually returned. The `.md` URL, such as `/publish/output.md`, also works directly.
+
+## Hosting contract
+
+For each published page, use the two URLs in `documents.json`. Configure the host as follows:
+
+1. At the page URL, return the Markdown twin when `Accept` explicitly requests `text/markdown` with a nonzero quality value. Otherwise return HTML.
+2. Keep the URL in the browser unchanged when serving the twin. Use an internal rewrite or server response, not a redirect to `.md`.
+3. On the Markdown response, set `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, and `Content-Location` to the `.md` URL.
+4. On both page responses, set `Link: <PAGE.md>; rel="alternate"; type="text/markdown"`. Keep the HTML document's existing alternate link as well.
+5. Serve direct `.md` URLs as `text/markdown`. Apply the content types in [`/resource-headers.json`](https://www.shoalrun.com/resource-headers.json) to discovery files, especially `/.well-known/api-catalog` when it is published.
+6. Limit the negotiation rule to published documentation pages. Leave assets, API contracts, and `/llms.txt` alone. Missing routes use the error responses described below.
+
+The Vercel rule matches the Node server except when `text/markdown` and the HTML or wildcard entry it competes with both have fractional weights. The [Vercel guide](https://www.shoalrun.com/publish/vercel.md) gives the details. The Node server compares the requested HTML and Markdown weights. When the weights tie, Markdown wins. A wildcard such as `text/*` or `*/*` alone never selects Markdown; the request must name `text/markdown`.
+
+To try it locally, run `npm run docs:preview` from the repository root, then request a page:
+
+```sh
+curl -i -H 'Accept: text/markdown' http://127.0.0.1:8770/publish/agent-friendliness/
+```

package/agent-docs/publish/content-negotiation.sections/missing-pages.md

@@ -0,0 +1,51 @@
+---
+id: guide.content-negotiation
+title: Content negotiation
+summary: Understand content negotiation, why it helps agents, and what a hosting
+  provider needs to do.
+type: reference
+area: discovery
+subarea: discovery-agents
+canonical: /publish/content-negotiation
+---
+
+# Content negotiation
+
+> 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) > Output and presentation > Content negotiation
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/content-negotiation.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) — Generate a Vercel deployment with negotiation already configured.
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — Supply the same HTTP rules on another host.
+
+Shoalrun builds two versions of every published page from one authored source. The HTML version is for people using a browser. The generated Markdown version contains shared material in a form agents can read directly. Authors can also add or suppress [format-specific content](https://www.shoalrun.com/author/components/only.md) in either version. The versions share a core but need not contain identical text.
+
+**Content negotiation** lets a visitor ask for a format at the page's usual URL. Some agents send the request header `Accept: text/markdown`. A host that supports negotiation responds with Shoalrun's Markdown version. A browser asking for HTML gets the HTML version. The URL stays the same:
+
+| Request to `/publish/output/`       | Response                                     |
+| ----------------------------------- | -------------------------------------------- |
+| Browser sends `Accept: text/html`   | HTML page, `Content-Type: text/html`         |
+| Agent sends `Accept: text/markdown` | Markdown page, `Content-Type: text/markdown` |
+
+`Accept` says what the visitor can use. `Content-Type` says what the host actually returned. The `.md` URL, such as `/publish/output.md`, also works directly.
+
+## Missing pages
+
+A missing page returns HTTP `404`, with links to the documentation index, the search index when published, and the homepage. The response stays a `404` even though it provides recovery links. It does not redirect to the homepage or return an unrelated article with status `200`.
+
+Shoalrun's Node server returns Markdown for a missing `.md` URL or a request that prefers `Accept: text/markdown`; other requests receive HTML. Both responses carry `X-Robots-Tag: noindex`. If a known Markdown twin is missing while its HTML page exists, the response links to that HTML page in its body and `Link` header. Unexpected server errors return `500`.
+
+The build generates `404.html` and `404.md` under `site.basePath`. The Vercel adapter applies error routes after checking for existing files and preserves HTTP `404`. A missing known Markdown route includes an HTML alternate in its `Link` header. Its generic error body provides the discovery links.
+
+On another static host, configure missing routes to serve these error files with HTTP `404`. Merely uploading them does not configure the host's error status or content negotiation. Serve `404.md` as `text/markdown; charset=utf-8`, and keep error responses out of search indexes with `X-Robots-Tag: noindex`.

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

@@ -0,0 +1,45 @@
+---
+id: guide.content-negotiation
+title: Content negotiation
+summary: Understand content negotiation, why it helps agents, and what a hosting
+  provider needs to do.
+type: reference
+area: discovery
+subarea: discovery-agents
+canonical: /publish/content-negotiation
+---
+
+# Content negotiation
+
+> 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) > Output and presentation > Content negotiation
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/publish/content-negotiation.md)
+
+Shoalrun builds two versions of every published page from one authored source. The HTML version is for people using a browser. The generated Markdown version contains shared material in a form agents can read directly. Authors can also add or suppress [format-specific content](https://www.shoalrun.com/author/components/only.md) in either version. The versions share a core but need not contain identical text.
+
+**Content negotiation** lets a visitor ask for a format at the page's usual URL. Some agents send the request header `Accept: text/markdown`. A host that supports negotiation responds with Shoalrun's Markdown version. A browser asking for HTML gets the HTML version. The URL stays the same:
+
+| Request to `/publish/output/`       | Response                                     |
+| ----------------------------------- | -------------------------------------------- |
+| Browser sends `Accept: text/html`   | HTML page, `Content-Type: text/html`         |
+| Agent sends `Accept: text/markdown` | Markdown page, `Content-Type: text/markdown` |
+
+`Accept` says what the visitor can use. `Content-Type` says what the host actually returned. The `.md` URL, such as `/publish/output.md`, also works directly.
+
+## Related reading
+
+### Next steps
+
+- [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) — Generate a Vercel deployment with negotiation already configured.
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — Supply the same HTTP rules on another host.
+
+### Related topics
+
+- [Content for one format](https://www.shoalrun.com/author/components/only.md) — Write instructions that apply to only the HTML page or only the Markdown twin.