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

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

package/agent-docs/publish/vercel.md

@@ -0,0 +1,130 @@
+---
+id: guide.vercel
+title: Publish on Vercel
+summary: Build a Vercel deployment with Markdown negotiation and correct
+  discovery headers.
+type: how-to
+area: publishing
+subarea: publishing-hosting
+canonical: /publish/vercel
+---
+
+# Publish on Vercel
+
+> 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 > Publish on Vercel
+
+**Updated: 2026-10-27.**
+
+Shoalrun can produce a [Vercel Build Output API](https://vercel.com/docs/build-output-api) directory. It contains the compiled static site and routing rules for each published page. Vercel serves HTML to browsers and the generated Markdown twin when a request includes `Accept: text/markdown`. The route rules also set `Vary: Accept` and an HTTP `Link` header to the `.md` page. Explicit `.md` URLs remain available.
+
+The [content negotiation guide](https://www.shoalrun.com/publish/content-negotiation.md) explains the same HTTP contract for any host. This page shows how to configure Vercel specifically.
+
+## Prepare your project
+
+Start with the [quickstart](https://www.shoalrun.com/start.md). Your documentation repository installs the public npm package and keeps its own content and configuration. It needs no framework source checkout:
+
+```text
+package.json
+package-lock.json
+docs.config.yaml
+content/
+vercel.json
+```
+
+Set `site.origin` in `docs.config.yaml` to your intended public HTTPS origin before release. This controls canonical and share-image URLs. Generate deployment output locally:
+
+```sh
+npx --no-install shoalrun vercel build docs.config.yaml .vercel/output
+```
+
+Generating output does not deploy it.
+
+## Configure the project
+
+Public Shoalrun packages install with `npm ci` using your committed manifest and lockfile; no registry token is needed. If you previously used GitHub Packages, follow the migration instructions in [Getting started](https://www.shoalrun.com/start.md) and commit the updated lockfile before deploying. Keep credentials required by any other private dependencies.
+
+Set the Vercel project root to the documentation repository root and choose the **Other** framework preset. Add:
+
+```json filename="vercel.json"
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": null,
+  "installCommand": "npm ci",
+  "buildCommand": "npx --no-install shoalrun vercel build docs.config.yaml .vercel/output"
+}
+```
+
+Keep the build output directory setting unset: this command produces the Build Output API directory directly. If your config lives under `docs/`, adjust its path. Connecting the Git repository can trigger builds on pushes; check your build budget before enabling that integration.
+
+### Deploy Shoalrun's own documentation
+
+The docs repository's root `vercel.json` serves the site under `docs/`. It runs `npm ci` and `npm run docs:vercel` using the installed package. Production and local builds use the public `https://www.shoalrun.com` origin in `docs/docs.config.yaml` for absolute page and share-image URLs. Preview builds use their `VERCEL_URL` instead. Public link previews require the shared page and its image to be accessible without sign-in. Vercel deployment protection can prevent crawlers from reading preview deployments.
+
+The Vercel output puts pages and discovery files in `.vercel/output/static/`. Its `config.json` defines page routes and content types, including `text/markdown` for `.md` files and the linkset type for `/.well-known/api-catalog` when that file exists. Keep the entire `.vercel/output/` directory together for deployment. The API catalog is optional and appears only when the project declares a public API endpoint and publishes its source.
+
+For Shoalrun's own site, `npm run docs:build-all` makes a complete prebuilt bundle: it compiles the pages and embeds the passages for hosted chat and search. Repeat builds reuse private passage vectors when retrieval settings and passage digests match. Only new or changed passages need embedding. The build reports embedded and reused counts. It generates answer cards from `docs/config/answers.yaml` when the passages, questions, chat settings, or generator code have changed; otherwise it reuses the previous verified cards. It checks passage coverage and card digests before returning. The index and cards stay inside private functions. New embeddings call the configured provider; generating cards also calls the relevance scorer and chat model. Review `answers.json` in the function before deployment. Deleting `.vercel/output` removes the local vector and card caches. The docs repository's README has the local command sequence. The hosted search endpoint uses embeddings within shared rate and daily budgets, then returns lexical results when its embedding budget is exhausted.
+
+The card cache lives in the previous local `.vercel/output` bundle. The command compares a fingerprint of its passage index, embedding metadata, question list, chat and retrieval settings, and compiled generator code with the new bundle. When they match, it copies the prior cards into the new private function and checks their source digests again. If the inputs changed, the old bundle is missing, or validation fails, it regenerates all cards. The final line says `reused` or `generated`. This saves card model and scorer calls on an unchanged rebuild. A fresh checkout or deleted `.vercel/output` has no local card or passage vector cache.
+
+### Deploy without connecting GitHub
+
+You can keep building locally and deploy the Build Output API directory with the [Vercel CLI `--prebuilt` option](https://vercel.com/docs/cli/deploy#prebuilt). Use [`vercel link`](https://vercel.com/docs/cli/link) to connect the local directory to the existing Vercel project; this does not require importing your source repository. From the docs repository root, use `npm run docs:build-all` for Shoalrun's own site when you want fresh embeddings and answer cards. For another site, build its Vercel output as configured:
+
+```sh
+npm run docs:vercel
+vercel link
+vercel deploy --prebuilt --prod
+```
+
+The command uploads `.vercel/output` and applies its routes and headers. A folder upload of `docs/dist` through Vercel Drop publishes the static files but does not apply Shoalrun's Vercel routing rules. It is suitable for a visual preview; the deployment checker will still report missing Markdown negotiation and response headers. Run it against the final domain after a prebuilt deploy.
+
+The routes also cover:
+
+- **Redirects.** Each entry in the project's [`redirects`](https://www.shoalrun.com/config.md) config becomes a route with its status, 308 by default. A second route sends the old `.md` URL to the target's Markdown twin.
+- **The site root.** When no page has the slug `/`, a request for `/` gets a 302 to the page with ID `guide.overview`. If there is no such page, it goes to `/reference`, then to the first page. `shoalrun serve` uses the same rule.
+
+Each run of `vercel build` deletes and rewrites `.vercel/output/static/`, so don't keep other files there.
+
+## Include an MCP endpoint
+
+Enable `mcp` in your project config before running `shoalrun vercel build`. The output includes a separate Node function for the selected public publication, without requiring Ask or embeddings. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for configuration, host trust, limits, and the current verification status.
+
+MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings do not collect MCP traffic.
+
+## Check the deployment
+
+After Vercel gives you a deployment URL, run the [provider-neutral deployment checker](https://www.shoalrun.com/publish/deployment-check.md) before release. Shoalrun's docs repository includes it as a site-owned command:
+
+```sh
+npm run deploy:check -- https://your-docs.example/
+```
+
+It checks every published page, discovery resources, and missing routes. To inspect one page manually, replace `https://your-docs.example` below and compare the responses:
+
+```sh
+curl -I -H 'Accept: text/html' https://your-docs.example/install/
+curl -I -H 'Accept: text/markdown' https://your-docs.example/install/
+curl -I https://your-docs.example/install.md
+```
+
+The first request should return `Content-Type: text/html`; the second should return `Content-Type: text/markdown`, `Vary: Accept`, and `Content-Location: /install.md`. Both page responses include an HTTP `Link` to the Markdown twin. The third request tests the explicit `.md` URL. Check `/llms.txt` and, if enabled, `/.well-known/api-catalog` as well.
+
+The Vercel static routing rule selects Markdown when the `Accept` header explicitly includes `text/markdown` with nonzero quality. It keeps HTML when Markdown has a fractional weight and `text/html` has full weight, or when `text/html` is absent and `text/*` or `*/*` has full weight. A header rule can't compare two fractional weights. So `text/html;q=0.9, text/markdown;q=0.8` and `text/markdown;q=0.3, text/*;q=0.5` get Markdown on Vercel and HTML from the Node server.
+
+Run the post-deploy checker after publishing each new revision. The fractional-weight limitation above remains.
+
+## Related reading
+
+### Next steps
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — Confirm the deployed site returns the right content and headers.
+
+### Related topics
+
+- [Host and limit documentation chat](https://www.shoalrun.com/chat/host.md) — Deploy the site itself to Vercel before you add the chat function. (Status: experimental.)
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — The Vercel build generates its own HTTP rules; other hosts need them supplied.

package/agent-docs/publish/vercel.sections/check-the-deployment.md

@@ -0,0 +1,54 @@
+---
+id: guide.vercel
+title: Publish on Vercel
+summary: Build a Vercel deployment with Markdown negotiation and correct
+  discovery headers.
+type: how-to
+area: publishing
+subarea: publishing-hosting
+canonical: /publish/vercel
+---
+
+# Publish on Vercel
+
+> 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 > Publish on Vercel
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/vercel.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — Confirm the deployed site returns the right content and headers.
+
+Shoalrun can produce a [Vercel Build Output API](https://vercel.com/docs/build-output-api) directory. It contains the compiled static site and routing rules for each published page. Vercel serves HTML to browsers and the generated Markdown twin when a request includes `Accept: text/markdown`. The route rules also set `Vary: Accept` and an HTTP `Link` header to the `.md` page. Explicit `.md` URLs remain available.
+
+The [content negotiation guide](https://www.shoalrun.com/publish/content-negotiation.md) explains the same HTTP contract for any host. This page shows how to configure Vercel specifically.
+
+## Check the deployment
+
+After Vercel gives you a deployment URL, run the [provider-neutral deployment checker](https://www.shoalrun.com/publish/deployment-check.md) before release. Shoalrun's docs repository includes it as a site-owned command:
+
+```sh
+npm run deploy:check -- https://your-docs.example/
+```
+
+It checks every published page, discovery resources, and missing routes. To inspect one page manually, replace `https://your-docs.example` below and compare the responses:
+
+```sh
+curl -I -H 'Accept: text/html' https://your-docs.example/install/
+curl -I -H 'Accept: text/markdown' https://your-docs.example/install/
+curl -I https://your-docs.example/install.md
+```
+
+The first request should return `Content-Type: text/html`; the second should return `Content-Type: text/markdown`, `Vary: Accept`, and `Content-Location: /install.md`. Both page responses include an HTTP `Link` to the Markdown twin. The third request tests the explicit `.md` URL. Check `/llms.txt` and, if enabled, `/.well-known/api-catalog` as well.
+
+The Vercel static routing rule selects Markdown when the `Accept` header explicitly includes `text/markdown` with nonzero quality. It keeps HTML when Markdown has a fractional weight and `text/html` has full weight, or when `text/html` is absent and `text/*` or `*/*` has full weight. A header rule can't compare two fractional weights. So `text/html;q=0.9, text/markdown;q=0.8` and `text/markdown;q=0.3, text/*;q=0.5` get Markdown on Vercel and HTML from the Node server.
+
+Run the post-deploy checker after publishing each new revision. The fractional-weight limitation above remains.

package/agent-docs/publish/vercel.sections/include-an-mcp-endpoint.md

@@ -0,0 +1,38 @@
+---
+id: guide.vercel
+title: Publish on Vercel
+summary: Build a Vercel deployment with Markdown negotiation and correct
+  discovery headers.
+type: how-to
+area: publishing
+subarea: publishing-hosting
+canonical: /publish/vercel
+---
+
+# Publish on Vercel
+
+> 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 > Publish on Vercel
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/vercel.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — Confirm the deployed site returns the right content and headers.
+
+Shoalrun can produce a [Vercel Build Output API](https://vercel.com/docs/build-output-api) directory. It contains the compiled static site and routing rules for each published page. Vercel serves HTML to browsers and the generated Markdown twin when a request includes `Accept: text/markdown`. The route rules also set `Vary: Accept` and an HTTP `Link` header to the `.md` page. Explicit `.md` URLs remain available.
+
+The [content negotiation guide](https://www.shoalrun.com/publish/content-negotiation.md) explains the same HTTP contract for any host. This page shows how to configure Vercel specifically.
+
+## Include an MCP endpoint
+
+Enable `mcp` in your project config before running `shoalrun vercel build`. The output includes a separate Node function for the selected public publication, without requiring Ask or embeddings. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for configuration, host trust, limits, and the current verification status.
+
+MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings do not collect MCP traffic.