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

package/agent-docs/publish/output.sections/published-output-contract.md

@@ -0,0 +1,58 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Published-output contract
+
+This page is the consumer reference for Shoalrun's current published output. It describes the existing producer, not a general format that other generators must implement. The manifest and sync snapshot use `schemaVersion: 1`. Editorial revisions to this reference do not change that wire version.
+
+The repository maintains JSON Schema 2020-12 definitions at `framework/schemas/manifest.schema.json` and `framework/schemas/sync.schema.json`. They specify required fields and known value shapes; this reference explains their meaning. Schema identifiers are stable names for local resolution, not a promise that a site hosts the schema files. Register both schemas together when validating a sync snapshot. They remain repository validation resources and are not added to site output.
+
+Consumers must tolerate unknown properties. Optional fields may be absent; absence is not evidence of a negative claim. Removing a required field, changing a field's meaning, or making existing valid output incompatible requires a new wire version. Adding optional fields can retain version 1. Changes to a constrained value set also need compatibility review; accepting unknown properties does not mean a consumer accepts unknown enum values.
+
+| Capability                                                                                                        | Availability                                                                                        |
+| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| HTML and Markdown pages                                                                                           | Every included public page has both representations.                                                |
+| Manifest, sync snapshot, build information, response headers, redirect inventory, and both text discovery indexes | Emitted by the build. Empty inventories are allowed.                                                |
+| Search indexes                                                                                                    | Both full and compact indexes are emitted when search indexing is enabled.                          |
+| Section resources                                                                                                 | Emitted only for eligible sections of sufficiently long pages.                                      |
+| Focused contracts and published API sources                                                                       | Emitted when configured for an API source.                                                          |
+| Sitemap                                                                                                           | Requires a site origin and enabled indexing.                                                        |
+| Markdown negotiation, redirect responses, caching, and HTTP 404 status                                            | Hosting behavior; the Node server and Vercel adapter implement it. Other hosts need matching rules. |
+
+Routes include the configured base path and publication prefixes. Start at `llms.min.txt` under that base path, follow a matching topic index when present, then choose a page by its ID, title, and summary and fetch its Markdown URL. Fetch the manifest when you need structured metadata. Each compact index is limited to 2,000 `cl100k_base` tokens; total discovery cost depends on the number of indexes you read.
+
+A document's identity is `(id, channel, version, language)`, not its title, URL, or array position. The same ID in two publications identifies two records. That tuple must be unique in both the manifest and sync snapshot. Cite it with the resource URL; for sections, also retain section identity and parent/section digests. A manifest array pointer is a link into that snapshot, not a permanent document identifier.
+
+`indexable` describes indexing, not access. `demo: false` means unmarked, not a verified service. Missing or null `subjectLifecycle` does not mean stable. `verified` is an author's review date, not compiler or independent verification. `updated` records content freshness and can be a calendar date or a timestamp with a timezone. Reader filters control presentation, not authorization.

package/agent-docs/publish/output.sections/reader-appearance-and-controls.md

@@ -0,0 +1,44 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Reader appearance and controls
+
+Choose a [theme preset](https://www.shoalrun.com/styling/themes.md), [palette](https://www.shoalrun.com/styling/palettes.md), and [color mode](https://www.shoalrun.com/styling/color-modes.md) in the `theme` config. For anything else, add a project stylesheet with `site.customCss`; the [CSS reference](https://www.shoalrun.com/author/css.md) lists the tokens and selectors it can override. You don't need to edit the framework's own stylesheets.
+
+The layout uses three columns for endpoint pages on wide screens. At narrower widths the examples follow the article; on small screens navigation becomes a disclosure above the page. Use Enter or Space to open it. Navigation filtering matches labels, ancestors, methods, and paths; Escape clears the filter. The active page remains marked in navigation.
+
+Code blocks scroll horizontally without widening the page. Keyboard users can focus them to scroll, and copy buttons provide success or failure feedback. Copying uses the code text, so syntax-color spans never enter the clipboard. Clipboard access requires browser support and a secure context such as HTTPS or localhost. Without it, readers can select and copy manually. Without JavaScript, code highlighting and native disclosures remain available and mobile navigation starts expanded.
+
+The overview, authoring guide, and endpoint fixture were checked in headless Chrome at desktop and 320 CSS-pixel widths, including navigation keyboard controls and filtering. Clipboard-handler checks verified the exact text passed to the browser API; normal-browser clipboard copying was verified on September 25, 2026. Manual 400% browser zoom was verified on September 26, 2026. The maintainer confirmed completion of manual screen-reader verification on September 30, 2026. See [project status](https://www.shoalrun.com/status.md) for validation evidence and remaining release checks.

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

@@ -0,0 +1,34 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Related reading
+
+### Next steps
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.

package/agent-docs/publish/output.sections/response-identity.md

@@ -0,0 +1,38 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Response identity
+
+Markdown responses link to their current manifest array entry with `rel="describedby"` and a JSON Pointer fragment. The Node server uses the exact Markdown digest as a strong ETag. A CDN can substitute its own validator; use the returned ETag for conditional requests and the manifest digest for byte verification. Focused contracts use their full content digest in the filename, so their responses can be cached as immutable for one year. Markdown and mutable JSON metadata require revalidation. The [HTTP reference](https://www.shoalrun.com/publish/content-negotiation.md) explains the response headers and conditional requests.

package/agent-docs/publish/output.sections/site-files.md

@@ -0,0 +1,64 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Site files
+
+- `documents.json` is the document manifest. Its top-level keys are `schemaVersion`, `buildId`, `configDigest`, `dependencies`, `documents`, `operations`, `relationships`, `redirects`, and `apiSources`. Each entry in `documents` describes one page variant. `contentDigest` fingerprints resolved article content for freshness; `digest` is the SHA-256 of the complete generated Markdown bytes. Use `digest` to check a fetched Markdown twin for changes, and pair the stable ID with its publication variant when comparing records. A page with an author-set `verified` date exposes it independently of `updated`. It has the stable ID, type, title, summary, subjectLifecycle, publication variant, and HTML and Markdown URLs. Optional `subjectDeprecation` carries author-declared `deprecatedOn` and `sunsetOn` dates and resolved `replacement` and `migration` targets, each with `id`, `title`, `url`, and `markdownUrl`. A changelog entry can also expose optional `change` with an author-declared `kind`, an `affects` target list, and a `migration` target when supplied. Change targets use the same `id`, `title`, `url`, and `markdownUrl` shape; absence means unclassified. Deprecation guidance appears in HTML, full Markdown, and section Markdown; it describes the subject rather than retirement of the documentation resource. Every record has a boolean `demo`, set from `outputs.llms.fictionalPrefixes`. A true value identifies an author-declared fictional example. False means unmarked; it does not verify that an API is live. The full and compact search indexes carry the same flag. Optional `product`, `area`, and `subarea` categories appear when set. It also lists card targets and queries, snippet and API embed uses, focused contract details, and a content digest. When reader views are configured, the manifest also has top-level `readerFacets` and a resolved `readerFilters` map on each page. An empty map means the page is shared. `dependencies` lists the source files the build read, without local paths. Project files are relative to `docs.config.yaml`, framework files start with `shoalrun:`, and installed packages start with `package:`.
+
+- `documents.sync.json` contains the build ID and compact page signatures for comparing saved snapshots. See **Incremental sync** below.
+
+- `build-info.json` records the build ID, resolved config digest and, when supplied by the build command, the source commit and release label. It is public build provenance, not a version archive. See [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
+
+- `404.html` and `404.md` provide concise recovery links for missing pages. Node serving and Vercel routing preserve HTTP `404`; another static host needs an error-page rule. These files are omitted from the document manifest, sitemap, and search index.
+
+- `redirects.json` lists each [redirect](https://www.shoalrun.com/config.md) as `from`, `to`, `markdownFrom`, `markdownTo`, and `status`. `markdownFrom` is the old page's `.md` URL, and it redirects to `markdownTo`. `shoalrun serve` and the Vercel build apply them; other hosts need their own rules.
+
+- `resource-headers.json` declares MIME types for page and discovery routes, Markdown alternate links for HTML, and canonical HTML links for Markdown.
+
+- `/llms.txt` points agents to pages, contracts, and manifests. Every Markdown twin links back to the compact `/llms.min.txt` index and `/documents.json`; the compact index links to the detailed `/llms.txt` index.
+
+- `llms.min.txt` is the compact starting point for agents. Small sites list page variants directly; larger sites link to topic indexes grouped by publication and primary taxonomy area, or page type when no area is declared. Growing topics split automatically. Each index stays within 2,000 `cl100k_base` tokens. Page entries retain stable IDs, titles, summaries, Markdown URLs, and fictional-example labels. Follow index links until you reach a matching page. All published pages remain reachable, including pages outside navigation; the complete catalog and search index remain optional.
+
+- `search-index.min.json` adds page headings to titles, summaries, IDs, types, publication variants, and URLs. It omits article text and reader segments. It is generated whenever the full search index is enabled. Both are static files, not query endpoints.
+
+- `search-index.json` lists page IDs, HTML and Markdown URLs, titles, summaries, headings, and text for the [search box](https://www.shoalrun.com/author/search.md) and local search command. The default lexical provider needs it; a custom provider can opt in.
+
+- `/assets/search-provider.js` is the search provider module, built-in or custom.
+
+When `site.origin` is set and indexing is enabled, the build writes `/sitemap.xml` with canonical HTML page URLs, `/llms.txt`, and optional page `lastmod` values. Markdown twins are alternate representations; their HTTP `Link` header names the HTML page as canonical. They are omitted from the sitemap. `/robots.txt` advertises it. Both derive from the same published pages as `documents.json`; `seo.noindex` pages are omitted. Large sitemaps are split into direct child URL sitemaps under a single index. The manifest records `sitemap`, and each document records `indexable` and optional `updated`.
+
+The local frontmatter inventory and JSON Schema are build outputs in `.shoalrun/` beside `docs.config.yaml`. They are available to authors and agents in the repository. A site can also publish its current field inventory on an authored page with `<FrontmatterReference />`, as [this documentation site does](https://www.shoalrun.com/author/frontmatter-reference.md).
+
+After publishing, run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) against the live origin to verify the host serves these formats and discovery files with the expected response headers.

package/agent-docs/publish/output.sections/validate-an-existing-build-locally.md

@@ -0,0 +1,48 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Validate an existing build locally
+
+This checker belongs to Shoalrun’s documentation repository; it is not an installed CLI command. From that repository with its dependencies installed, run:
+
+```sh
+node scripts/check-output-contract.mjs docs/dist
+```
+
+Replace `docs/dist` with an already-built site's directory. The checker loads both schemas locally and makes no network requests. It checks field shapes, unique document identities, manifest/sync correspondence, build/config identity agreement, record and metadata hashes, same-publication change/deprecation targets, section parent linkage, and exact Markdown byte counts, token counts, and digests. It also verifies referenced focused-contract bytes. Unknown fields remain allowed and participate in the applicable record or metadata hash.
+
+The report has `status`, `findings`, and document/section counts. A failure exits nonzero. The command never rebuilds, writes output, evaluates model tasks, or checks live hosting. The existing repository built-site check includes this check, so run either path rather than duplicating it for unchanged output. Use the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) separately for HTTP behavior.
+
+Passing checks establish the specified structure and consistency, not authored truth, semantic completeness, or a fresh evaluation grade. The build identity is compared across files, not recomputed from final stamped artifacts. This contract does not add `llms-full.txt`, a public evaluation report, signatures, or an offline release archive.

package/agent-docs/publish/output.sections/where-files-go.md

@@ -0,0 +1,49 @@
+---
+id: guide.output
+title: Publishing and agent representations
+summary: Read the published-output contract for HTML, Markdown, manifests, and
+  incremental sync.
+type: reference
+area: publishing
+subarea: publishing-builds
+canonical: /publish/output
+---
+
+# Publishing and agent representations
+
+> 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 > Generated outputs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/output.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how these files help agents discover and read the site.
+
+`shoalrun build` turns accepted source pages and local OpenAPI files into a static site. A **publication** is one enabled channel, version, and language combination, such as production, v1, and English. The build includes a public page only in publications matching its frontmatter. It makes no model calls or remote requests.
+
+For each included page, the build writes an HTML page for browsing. It also writes a **Markdown twin**, a generated `.md` copy that agents can read as text. The Markdown twin can start with a short YAML header. That header contains only the page metadata selected in project config, so agents get useful context without a long source header or internal notes. Shared content appears in both bodies; authors can also add content to either format alone with [Only](https://www.shoalrun.com/author/components/only.md).
+
+The site also includes a **document manifest**, `documents.json`, which indexes the built pages and their URLs. Projects with an API source can publish operation pages and **focused contracts**, small OpenAPI files containing one operation and the definitions it needs.
+
+## Where files go
+
+`shoalrun build <config> <output>` writes the site to the output directory. It builds in a temporary directory, then **deletes the output directory and replaces it**, so point it at a directory that holds only build output. To protect other folders, it replaces a directory only when it is new, empty, or an earlier build. Otherwise the build stops before deleting anything.
+
+| Output                     | Path                                                                                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| HTML page                  | `<route>/index.html`                                                                                                                  |
+| Markdown twin              | `<route>.md`; a page at `/` gets `/index.md`                                                                                          |
+| Framework and theme assets | `/assets/`: `site.css`, `tokens.css`, `header.css`, scripts, `themes/`, and, when used, `theme.css`, `palette.css`, and `project.css` |
+| Diagram images             | `/assets/diagrams/<engine>-<hash>-light.svg` and `-dark.svg`, named by a hash of the source so identical diagrams share a file        |
+| Published OpenAPI source   | `/api/<apiId>/<channel>/<version>/<file>`, plus the local files it references                                                         |
+| Focused contracts          | `/api/operations/<channel>/<version>/<language>/<name>-<hash>.json`                                                                   |
+
+The `/api` and `/.well-known` paths are reserved for these files, so page slugs cannot use them. A [diagram](https://www.shoalrun.com/author/components/diagrams.md) in the Markdown twin keeps its title, summary, a link to the light SVG, and its fenced source.

package/agent-docs/publish/publications.md

@@ -0,0 +1,153 @@
+---
+id: guide.publications
+title: Share pages across documentation versions
+summary: "Versioning one docs site without copying every page: share unchanged
+  pages, vary sections, and publish changed pages separately."
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/publications
+---
+
+# Share pages across documentation versions
+
+> 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 > Share pages across documentation versions
+
+**Updated: 2026-10-26.**
+
+Say you support v1 and v2. Your setup instructions are mostly the same, but v2 has a new credential and one extra guide. You can keep the common instructions in **one source file**, show the right credential in each version, and publish the extra guide only in v2.
+
+Shoalrun calls each channel, version, and language combination a **publication**. You choose which publications a build makes. A Git branch or tag chooses *which revision of the repository to build*; it does not automatically create a docs version. For separate sites such as stable and next, see [publish separate docs sites from Git](https://www.shoalrun.com/publish/revisions.md).
+
+For separate sites selected by audience, product, region, or another configured facet, see [build sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md). That workflow shares one content directory and uses a separate entry config and output directory for each site.
+
+## Choose which versions exist
+
+This config publishes two versions at `/v1` and `/v2`:
+
+```yaml title="docs.config.yaml (fragment)"
+publications:
+  defaults: { channel: production, version: v1, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    v1: { pathPrefix: /v1 }
+    v2: { pathPrefix: /v2 }
+  enabled:
+    - { channel: production, version: v1, language: en }
+    - { channel: production, version: v2, language: en }
+```
+
+`enabled` sets the combinations the build may publish. It does not create pages or fill gaps in them. The paths come from the prefixes above plus each page's `slug`.
+
+## Keep an unchanged page in one file
+
+List the versions that should receive the page in its frontmatter. This one file creates `/v1/start` and `/v2/start`:
+
+```mdx title="content/start.mdx"
+---
+id: guide.start
+title: Get started
+summary: Set up your first request.
+type: guide
+slug: /start
+publications:
+  - { channel: production, version: v1 }
+  - { channel: production, version: v2 }
+language: en
+access: { policy: public }
+---
+
+Install the client and create a project.
+```
+
+The `publications` list is explicit: add a version when the page should appear there, and omit it when the page should not. Only enabled combinations are built. Keep the same `id` and `slug` in every publication so links and the Version menu can find the corresponding page. A shared file cannot also set page-level `channel` or `version`.
+
+## Change just one part of a shared page
+
+Put version-specific content inside `<ForPublication>`. The rest of the page stays shared:
+
+```mdx
+Create a project, then choose a credential.
+
+<ForPublication version="v1">
+
+Use a legacy key.
+
+</ForPublication>
+
+<ForPublication version="v2">
+
+Use a scoped key. [Set permissions](doc:guide.permissions)
+
+</ForPublication>
+```
+
+You can select a `channel`, `version`, `language`, or a combination, such as `<ForPublication channel="sandbox" version="v2">`. Omitted attributes match any value. The block needs at least one attribute and ordinary block content. A `doc:` link inside a block resolves in that publication, so a v2-only target can live in a v2-only block.
+
+If a whole page changes substantially, write separate source files with the same `id` and `slug`, each with its own `channel` and `version`. If a page exists only in v2, write only its v2 file. You do not need a blank v1 copy. The Version menu shows a matching page only where one was published.
+
+| Source choice                                              | Result                                                                  |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------- |
+| One file listing v1 and v2                                 | The same page appears at both paths.                                    |
+| One file listing v1 and v2, with `<ForPublication>` blocks | Shared text appears in both; each version gets its own selected blocks. |
+| Two files with the same ID, one for each version           | Each version gets different page content.                               |
+| One file assigned only to v2                               | The page appears only in v2.                                            |
+
+Run `shoalrun build docs.config.yaml dist` and inspect `dist/documents.json` for the actual pages and routes. Links, navigation, search, and the Version menu use those published variants. A link to a page missing from the current publication fails the build instead of sending readers to another version.
+
+## Give each API version its own contract
+
+When API behavior differs by version, bind an OpenAPI file to each publication in `apis.<name>.publications`. The top-level API `source` belongs to `publications.defaults`. A shared guide can refer to the same stable operation ID in both versions; each version resolves that operation against its own API source. The build fails if a page needs an API operation but that publication has no source. See [API references](https://www.shoalrun.com/publish/api-references.md) for the config and [example configs](https://www.shoalrun.com/config/examples.md) for full projects.
+
+## What agents receive
+
+Each published page has a Markdown copy at its route plus `.md`, such as `/v1/start.md` and `/v2/start.md`. These are separate artifacts built from the same source file. Each copy includes only its own `<ForPublication>` sections, so an agent reading v1 instructions does not see v2-only text. `documents.json`, `search-index.json`, and the site's agent discovery files list the published variants and their Markdown URLs. A missing version of a page has no Markdown copy or search result. [Published outputs](https://www.shoalrun.com/publish/output.md) lists those files.
+
+For channel and prefix rules, see the [publication configuration reference](https://www.shoalrun.com/config.md).
+
+## Add a language
+
+To add a language such as Japanese, add its combination to `enabled`, then write a translated file for each page with that `language`. The translated file reuses the page's `id` and `slug`, so it is another language of the same page:
+
+```yaml title="docs.config.yaml"
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+    - { channel: production, version: current, language: ja }
+```
+
+```yaml title="content/install.ja.mdx"
+---
+id: guide.install
+title: インストール
+summary: Acme のコマンドラインツールをインストールします。
+slug: /install
+language: ja
+---
+```
+
+The Japanese page publishes at `/ja/install` with `lang="ja"`, and its Markdown copy is `/ja/install.md`. The default language keeps the ordinary route. Pages without a `language` are in the default language.
+
+Shoalrun does not translate text. Your translation pipeline writes the files, one for each page and language. A page with no Japanese file has no Japanese version, and it gets no Markdown copy or search result there. To keep a language out of a build, leave it out of `enabled`.
+
+## Related reading
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up publication defaults and route prefixes.
+
+### Related topics
+
+- [Use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md) — Distinguish content editions from source revisions and retained builds.
+
+- [Build separate sites from shared content](https://www.shoalrun.com/publish/single-source-sites.md) — Publish separate sites from one content source using facet selections.

package/agent-docs/publish/revisions.md

@@ -0,0 +1,104 @@
+---
+id: guide.release-revisions
+title: Use Git branches for separate docs sites
+summary: Build a chosen Git branch for each docs address, add links between
+  sites, and verify the deployed commit.
+type: how-to
+area: publishing
+subarea: publishing-versions
+canonical: /publish/revisions
+---
+
+# Use Git branches for separate docs sites
+
+> 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 > Use Git branches for separate docs sites
+
+**Updated: 2026-10-26.**
+
+A deployment takes the docs files from a Git branch or commit, builds them, and serves the result at an address you choose. Your host or CI service chooses the source and destination. Branch names have no special meaning to Shoalrun.
+
+For example, either of these mappings can work:
+
+| Workflow               | Source    | Docs address               |
+| ---------------------- | --------- | -------------------------- |
+| Sandbox and production | `sandbox` | `sandbox-docs.example.com` |
+| Sandbox and production | `main`    | `docs.example.com`         |
+| Next and stable        | `next`    | `next-docs.example.com`    |
+| Next and stable        | `stable`  | `docs.example.com`         |
+
+You can use another branch name, a tag, or a fixed commit. You can also use [path-based versions within one build](https://www.shoalrun.com/publish/publications.md) instead of separate sites. Branches choose *which files to build*; publications choose *which editions those files produce*.
+
+## Build and deploy each source
+
+Set `site.origin` in each site's config to its public HTTPS origin. A site at `next-docs.example.com`, for example, uses `site.origin: https://next-docs.example.com`. Commit the pages, API sources, and publication settings for that site.
+
+After the deployment job checks out its chosen source, build it with the full commit hash:
+
+```sh
+shoalrun build docs.config.yaml site-dist --source-commit "$(git rev-parse HEAD)"
+```
+
+Deploy all of `site-dist/` to the address assigned to that source. Configure this source-to-address rule in your host or CI service; Shoalrun does not deploy files or infer a branch from `channel`. See [deploy your documentation](https://www.shoalrun.com/publish.md) for hosting options. If two separate domains should both serve `/start`, use an empty channel `pathPrefix` in each site's config.
+
+## Add another site to the Version menu
+
+Add an external site when readers should be able to move between addresses. In the current site's `publications` section, keep its existing `defaults`, `channels`, `versions`, and `enabled` entries, and add:
+
+```yaml title="docs.config.yaml (fragment)"
+publications:
+  externalSites:
+    - label: Next docs
+      baseUrl: https://next-docs.example.com
+```
+
+This adds **Next docs** to the Version menu on every page. The link opens that site's root. Add the corresponding link in the other site's config if readers should be able to switch back. `baseUrl` can be another domain or an address with a path, such as `https://docs.example.com/next/`.
+
+To keep a reader on the *matching page*, provide a local snapshot of the other site's built `documents.json`:
+
+```yaml title="docs.config.yaml (fragment)"
+publications:
+  externalSites:
+    - label: Next docs
+      baseUrl: https://next-docs.example.com
+      manifest: ./config/next-documents.json
+```
+
+Shoalrun matches stable document IDs and uses the other site's published paths. Only pages in that manifest appear in the menu. Copy or refresh the manifest as part of your release process when pages change. This extra step is optional; the direct site link above is enough for a simple branch switcher.
+
+A `baseUrl` with a path changes where the menu points. Hosting a *whole standalone build* under a path also requires the host to handle Shoalrun's root-level assets and discovery files. [Path prefixes inside one build](https://www.shoalrun.com/publish/publications.md) already work without that hosting setup.
+
+## What agents receive
+
+Each deployed site has its own Markdown pages, `documents.json`, search index, and agent discovery files, built from that site's selected Git revision. An agent using the stable site reads its stable artifacts; an agent using the next site reads its next artifacts. The external Version menu helps human readers navigate between sites, but it does not combine their manifests or Markdown copies. Preserve a built release or its tagged source if agents must be able to consult it later. See [published outputs](https://www.shoalrun.com/publish/output.md) for the file list.
+
+## Check the deployed source
+
+Each build writes its source commit to `/build-info.json`. Run the [post-deploy checker](https://www.shoalrun.com/publish/deployment-check.md) with the full hash selected by that site's deployment job:
+
+```sh
+npm --prefix framework run deploy:check -- https://next-docs.example.com/ --source-commit "$DEPLOYED_COMMIT"
+```
+
+The checker fails if the address serves a different commit or if its published HTML and Markdown routes fail their HTTP checks. Run it for each site. For a durable release record, tag the source commit and retain the built output with `/build-info.json`; a branch moves as new commits arrive.
+
+## Related reading
+
+### Read first
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — Understand publications, channels, and versions.
+
+### Next steps
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — Check each deployed revision before you release it.
+
+### Related topics
+
+- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Distinguish content editions from source revisions and retained builds.
+
+### Often confused with
+
+- [Write release notes and changelog entries](https://www.shoalrun.com/author/release-notes.md) — Release notes tell readers what changed; release revisions choose which Git revision of the docs to build and deploy.