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

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 > 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 > 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.

package/agent-docs/publish/seo.md

@@ -0,0 +1,119 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> 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 > SEO and social previews
+
+**Updated: 2026-10-25.**
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Set the public address
+
+Put the address readers actually use in `site.origin`. This is where crawlers will fetch the page and its image:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Acme API docs
+  origin: https://docs.acme.com
+```
+
+Check the domain in the built `og:image` URL. A page may display in a browser while its social preview cannot load an image from that domain. Preview deployments behind sign-in cannot be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.
+
+## Write the page title and summary
+
+```yaml title="content/start.mdx (frontmatter)"
+title: Getting started
+summary: Create your first project and make a request.
+```
+
+The title becomes the page heading and browser title. The summary is the default preview description and appears on the generated share image. For short titles, Shoalrun adds `site.title` to the Open Graph and Twitter titles when the result fits within 70 characters. The browser title and page heading remain unchanged.
+
+If a page needs a different browser and social title, or a different description, use `seo.title` and `seo.description` in its [frontmatter](https://www.shoalrun.com/author/frontmatter.md):
+
+```yaml
+seo:
+  title: Getting started with Acme API
+  description: Create a project, choose a credential, and make your first request.
+```
+
+`seo.title` sets the exact browser and social title; it skips the automatic site-name suffix. `seo.description` sets the browser and social description unless the page selects a separate `displayText.socialCard`. The generated image uses the same selected description, so its copy agrees with the tags. You can configure the text choices site-wide under `outputs.text`; see [text surfaces](https://www.shoalrun.com/author/custom-metadata.md) for precedence.
+
+## What the build adds
+
+The build derives these metadata and discovery outputs from your site and page settings.
+
+| Output                                     | Default source                                                       |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| HTML `<title>`                             | `seo.title`, then page `title`                                       |
+| HTML `name="description"`                  | `seo.description`, then configured HTML description                  |
+| `og:title` and `twitter:title`             | Browser title, with `site.title` added for short titles when it fits |
+| `og:description` and `twitter:description` | Selected social description, falling back to the page `summary`      |
+| `og:url`                                   | `site.origin` plus the published page route                          |
+| Canonical URL                              | `site.origin` plus the published page route                          |
+| XML sitemap `lastmod`                      | Page `updated`, then optional `site.updated`                         |
+| `og:image` and `twitter:image`             | Absolute URL of that page's share image                              |
+| `twitter:card`                             | `summary_large_image` when a share image exists                      |
+
+The default image is a 1200×630 PNG with the page type, title, summary, site name, and URL. [Share images and favicon](https://www.shoalrun.com/styling/share-images.md) shows how to replace a page image or the site-wide design. Turning off share images removes image tags on pages without their own image.
+
+## Check the deployed page
+
+Build and deploy, then run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) with the public origin:
+
+```sh
+npm --prefix framework run deploy:check -- https://docs.acme.com/
+```
+
+It checks page responses, compares `og:url` and `og:image` with that origin, and fetches a share image. To inspect one page directly, view its HTML source and open the absolute `og:image` URL in a private browser window. On Vercel, the deployment's [Open Graph tab](https://vercel.com/docs/deployments/og-preview) can show a preview for Slack and other services.
+
+When `site.origin` is set, the build writes `/sitemap.xml` from public, indexable page routes and advertises it in `/robots.txt`. Every page gets a self-referencing canonical URL. A page with `seo.noindex: true` stays public, gets a noindex tag, and is omitted from the sitemap. Set `site.indexing: false` for a preview: every page gets noindex and the build omits the sitemap. Crawlers can still reach those pages to read noindex.
+
+Set `updated` in a page's frontmatter to the date of a meaningful content update, such as `2026-09-27`. A timezone-qualified ISO timestamp is also accepted. Shoalrun copies it to sitemap `lastmod`; it never substitutes build time. `site.updated` is an optional date fallback for generated pages and other pages without `updated`. Change it only when the material it covers changes. Dates may repeat across pages when they really changed together. Without `site.freshness`, the build uses declared dates. It never reads file modification times to determine content updates.
+
+### Derive revision dates from content changes
+
+Opt into a content-digest history:
+
+```yaml title="docs.config.yaml"
+site:
+  freshness:
+    history: ./config/content-updates.json
+```
+
+The history file must be inside the project and its parent directory must already exist. The first successful build seeds each page with its declared `updated`, then `site.updated`, then today's UTC date. Later builds compare the resolved HTML and Markdown content plus displayed page metadata. Unchanged content keeps its recorded Updated date; changed content receives today's UTC date. File touches, AST source positions, and changes to verification dates do not change the content digest. The history is written after a successful build. Commit it with the source so clean CI builds use the same history. Without that file, the next build seeds a new history from declared dates.
+
+The manifest records `contentDigest` for this comparison and `digest` for the complete generated Markdown. A Markdown date or metadata edit changes the latter; it does not necessarily change the technical content fingerprint.
+
+### Record verification separately
+
+Set native frontmatter `verified` only when someone checks the page's technical claims:
+
+```yaml title="Page frontmatter"
+verified: 2026-10-01
+```
+
+The HTML page, Markdown twin, and manifest expose this date independently of Updated. A build never assigns it. This project also declares private `editorial.lastVerified` and `editorial.verificationNote` fields for internal review notes; use native `verified` when the date should be public. A rebuild or unchanged-content file touch establishes neither a content change nor verification.
+
+Search indexing still depends on the public host and crawler access; metadata alone does not guarantee it. If Slack does not unfurl after a corrected deployment, confirm the page and image are public, then try sharing the link in a new conversation. [Slack may omit a preview](https://slack.com/help/articles/204399343-Share-links-and-set-preview-preferences) when the same link was recently posted in that conversation.
+
+## What agents receive
+
+The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body does not contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image does not replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.
+
+## Related reading
+
+No matching documents.

package/agent-docs/publish/single-source-sites.md

@@ -0,0 +1,168 @@
+---
+id: guide.single-source-sites
+title: Build separate sites from shared content
+summary: Publish separate sites from shared content using optional facet selection.
+type: how-to
+area: publishing
+subarea: publishing-configuration
+canonical: /publish/single-source-sites
+---
+
+# Build separate sites from shared content
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish > Build separate sites from shared content
+
+**Updated: 2026-10-26.**
+
+You can keep one content directory and build separate sites for any configured facet: audience, product, area, subarea, or a custom facet such as region. Each entry config can have its own origin, base path, branding, navigation, and output directory. A developer portal is one example; the same workflow applies to an operations site, a product site, or regional resources.
+
+## Share the base configuration
+
+Keep entry configs beside the base file so they resolve `contentDir` from the same directory:
+
+```text
+resources/
+  base.yaml
+  docs.config.yaml
+  developers.config.yaml
+  europe.config.yaml
+  content/
+    home.md
+    api.md
+    operations.md
+```
+
+Start with Shoalrun installed in your project. The base declares the content, publication, and available facet choices:
+
+```yaml title="base.yaml"
+schemaVersion: 1
+site:
+  title: Acme resources
+  contentDir: content
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+readerFilters:
+  facets:
+    audience:
+      label: Audience
+      options: { developer: Developers, operator: Operators }
+    region:
+      label: Region
+      options: { eu: Europe, us: United States }
+```
+
+Each page needs its ordinary identity fields and the facet values for the sites that should receive it. This overview belongs to both audiences and both regions:
+
+```yaml title="content/home.md frontmatter"
+---
+id: guide.home
+title: Resource overview
+summary: Shared setup for all resource sites.
+slug: /
+audiences: [developer, operator]
+readerFilters: { region: [eu, us] }
+---
+```
+
+Give `content/api.md` the ID `guide.api`, a unique slug such as `/api-requests`, `audiences: [developer]`, and `readerFilters: { region: [us] }`. Give `content/operations.md` the ID `guide.operations`, slug `/operations`, `audiences: [operator]`, and `readerFilters: { region: [eu] }`. Add a title, summary, and body to both files. Link either page to the overview with `[Shared setup](doc:guide.home)`.
+
+The `audience` facet reads the page's `audiences` field. Configured `product`, `area`, and `subarea` facets read their corresponding category fields. Other facets use page-level `readerFilters`. Resolved `readerFilters.typeDefaults` also participate. See [reader views](https://www.shoalrun.com/author/reader-views.md) for these marks.
+
+## Select the pages for each site
+
+The main site omits `contentFilter` and publishes all otherwise eligible pages:
+
+```yaml title="docs.config.yaml"
+extends: [./base.yaml]
+site:
+  origin: https://docs.example.com
+navigation:
+  - { id: home, doc: guide.home }
+  - { id: api, doc: guide.api }
+  - { id: operations, doc: guide.operations }
+```
+
+A developer site selects the audience facet and supplies navigation for its selected pages:
+
+```yaml title="developers.config.yaml"
+extends: [./base.yaml]
+site:
+  title: Acme developer resources
+  origin: https://developers.example.com
+  contentFilter: { audience: [developer] }
+navigation:
+  - { id: home, doc: guide.home }
+  - { id: api, doc: guide.api }
+```
+
+A regional site selects the custom region facet independently of audience:
+
+```yaml title="europe.config.yaml"
+extends: [./base.yaml]
+site:
+  title: Acme Europe resources
+  origin: https://eu.example.com
+  basePath: /resources
+  contentFilter: { region: [eu] }
+navigation:
+  - { id: home, doc: guide.home }
+  - { id: operations, doc: guide.operations }
+```
+
+Every selected facet must match. Choices within one facet are alternatives: `{ audience: [developer, operator], region: [eu] }` requires either audience and the European region. A page without a mark for a selected facet is excluded. Mark shared pages with all applicable values rather than leaving them unmarked. Unknown facets or choices, empty selections, and selections with no published pages fail the build.
+
+The selector does not rewrite publication metadata. Public access, enabled publications, and language still determine eligibility. Keep explicit navigation and page links within the selected set; missing targets fail validation rather than copying excluded pages into the output. Separate entry configs can replace inherited navigation lists.
+
+## Build and check each output
+
+From `resources/`, build each site into its own directory:
+
+```sh
+shoalrun build docs.config.yaml dist/main
+shoalrun build developers.config.yaml dist/developers
+shoalrun build europe.config.yaml dist/europe
+```
+
+Check each output's `documents.json` for its page IDs and routes. The main site contains all three pages. The developer site contains the overview and API guide. The European site contains the overview and operations guide beneath `/resources`. Inspect HTML, Markdown, search indexes, `llms.min.txt`, and the sitemap to confirm that excluded pages have no published entries or files. The runnable `faceted-sites` example ships with the framework's example configurations.
+
+Deploy each output separately to its configured host. Building one site does not update the others. After editing shared content, rebuild and deploy every affected site. Keep output directories separate from sources and from one another because a successful build replaces its output directory.
+
+Selection applies to whole authored and generated pages before rendering. A selected page retains its complete body, including reader-marked sections in HTML and Markdown. Browser reader controls cannot restore excluded pages. Section variants can use [publication blocks](https://www.shoalrun.com/publish/publications.md) where the sites also have distinct publications.
+
+Configure API sources and operation selection separately. A published OpenAPI source may contain operations beyond the selected reference pages. Generated references use their resolved facet marks, including `readerFilters.typeDefaults`. This setting is a page publication selector, not authorization for private content; protect private deployments at the host.
+
+For a help drawer or another application surface, [export the shared content](https://www.shoalrun.com/publish/content-export.md) instead of building another website. Export targets choose their own documents and produce portable content without the website shell.
+
+## Related reading
+
+### Next steps
+
+- [Deploy your documentation](https://www.shoalrun.com/publish.md) — Deploy each reviewed site output to its own destination.
+
+### Reference while working
+
+- [Configuration reference](https://www.shoalrun.com/config.md) — Look up content selection and configuration inheritance settings.
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md) — Define the page facets used to select each site's content.
+
+### Related topics
+
+- [Share pages across documentation versions](https://www.shoalrun.com/publish/publications.md) — Publish separate sites from one content source using facet selections.
+
+- [Export content into your application](https://www.shoalrun.com/publish/content-export.md) — Reuse the same authored content inside an application.

package/agent-docs/publish/troubleshooting.md

@@ -0,0 +1,112 @@
+---
+id: guide.troubleshooting
+title: Troubleshooting
+summary: Resolve build and publishing errors.
+type: how-to
+area: quality
+subarea: quality-audits
+canonical: /publish/troubleshooting
+---
+
+# Troubleshooting
+
+> 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 > Troubleshooting
+
+**Updated: 2026-10-26.**
+
+Run these commands from your documentation project, with Shoalrun installed as in the [quickstart](https://www.shoalrun.com/start.md). Start by rebuilding so the error names the current source file:
+
+```sh
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
+```
+
+Config validation checks configuration; a full build also resolves content, links, routes, and API reviews. The messages below are compiler message fragments; file paths and document IDs vary by project.
+
+## A page is missing
+
+### Why it happens
+
+Drafts and pages outside enabled publications can be excluded without a build error.
+
+### What to do
+
+Inspect both the effective config and the built page list:
+
+```sh
+npx --no-install shoalrun config resolve docs.config.yaml
+node -e 'const m = require("./dist/documents.json"); console.log(JSON.stringify(m.documents, null, 2))'
+```
+
+Check the page's resolved `access.policy` is `public` and its channel, version, and language match an entry in `publications.enabled`. `frontmatter.enforced` overrides page values; a draft enforced there keeps even an explicitly public page out of the build. See [versions and languages](https://www.shoalrun.com/publish/publications.md).
+
+If the manifest contains the page but the menu does not, add its exact document ID to `navigation` (or the YAML file included there):
+
+```yaml
+navigation:
+  - id: my-page
+    doc: guide.my-page
+```
+
+Append that entry to the existing list. Scaffolding a file does not add it to navigation. A navigation reference to an unavailable page is omitted for that publication.
+
+If publishing instead fails with `unresolved scaffold placeholders cannot be published`, finish every scaffold TODO and replace the draft summary before setting `access: { policy: public }`.
+
+## An internal link fails
+
+### Why it happens
+
+`unknown document link doc:guide.install` means the target is unavailable in the linking page's publication.
+
+### What to do
+
+Check spelling against the target's `id`, its public access, and its publication fields. A source file in another version or language does not satisfy the link. Add the corresponding variant or link to an available page.
+
+Use `doc:` plus a document ID for internal links, for example `[Install](doc:guide.install)`. File paths are not document IDs. Rebuild after correcting the source and target.
+
+## Two pages claim one identity or route
+
+`Duplicate document identity` means two files have the same ID and publication combination. Keep one file per variant, or assign a distinct ID to a different page.
+
+`Route collision /install` means different pages produce the same final URL. Check their slugs together with language, channel, and version prefixes. `Output artifact collision` can also mean a page conflicts with a generated resource or another output file. Resolve the source configuration; changing the output directory does not fix conflicting URLs. [Versions and languages](https://www.shoalrun.com/publish/publications.md) shows how prefixes distinguish editions.
+
+## MDX cannot compile
+
+`dynamic MDX expression has no semantic adapter` means the page contains JavaScript expressions that Shoalrun cannot project into its published formats. Replace executable MDX with Markdown or one of the [supported components](https://www.shoalrun.com/author/components.md). Put code intended for readers inside a fenced code block so it remains literal text.
+
+Component validation errors name the source file and component. Check the component's documented attributes and nesting. Ordinary MDX syntax errors can also come from unescaped braces or angle brackets in prose; use inline code for literal syntax.
+
+## An API review digest is missing or stale
+
+`apis.payments.publicReview.digest is missing` or `apis.payments.publicReview.digest is stale` means the published API content needs review. Generate a local candidate:
+
+```sh
+API_REVIEW_DIR="$(mktemp -d)"
+npx --no-install shoalrun api review docs.config.yaml --output "$API_REVIEW_DIR"
+```
+
+Inspect the candidate pages, contracts, source downloads, and input hashes. Copy the reported digest into that API's `publicReview.digest`, then run the normal build again. Source changes, selections, embeds, and source-publication choices can change the digest. Do not copy a digest from another project or bypass the review by publishing the candidate output. See [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md).
+
+## A diagram fails to render
+
+`failed to render mermaid diagram "Review flow"` (or `d2`) includes the source file and the renderer's underlying error. If it names diagram syntax, fix the code fence and rebuild. Errors such as `<Diagram> needs exactly one nonempty mermaid code fence` concern component structure; follow the [diagram reference](https://www.shoalrun.com/author/components/diagrams.md).
+
+Mermaid syntax renders with Pele; it does not need Chrome or Mermaid CLI. Check [Pele’s compatibility guide](https://pele.run/compatibility) if source from another Mermaid renderer fails. D2 uses the installed `@d2lang/d2` runtime. Reinstall framework dependencies if either renderer is missing. Include the source file, diagram title, and complete underlying error when reporting a failure.
+
+## Local output works but the deployed site fails
+
+A successful local build does not check the host's routing or headers. Use [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) for wrong Markdown content types, missing negotiation, discovery resources, or 404 responses. The [publishing guide](https://www.shoalrun.com/publish.md) links the supported hosting workflows.
+
+## Related reading
+
+### Reference while working
+
+- [CLI reference](https://www.shoalrun.com/cli.md) — Look up diagnostic commands and failure behavior.
+
+### Related topics
+
+- [Create a page](https://www.shoalrun.com/author/add-page.md) — Find why a page is missing or a build fails.