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

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

package/agent-docs/publish/vercel.sections/prepare-your-project.md

@@ -0,0 +1,52 @@
+---
+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 > 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.
+
+## 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.

package/agent-docs/publish/vercel.sections/related-reading.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 > Publish on Vercel
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/publish/vercel.md)
+
+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.
+
+## 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.md

@@ -0,0 +1,95 @@
+---
+id: guide.publish
+title: Deploy your documentation
+summary: Build your site, choose Vercel or Node hosting, and verify the deployed
+  HTML and Markdown.
+type: how-to
+area: publishing
+subarea: publishing-hosting
+canonical: /publish
+---
+
+# Deploy your documentation
+
+> 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 > Deploy your documentation
+
+**Updated: 2026-10-26.**
+
+After the [quickstart](https://www.shoalrun.com/start.md), your documentation project has `@shoalrun/cli` installed. Run the commands below from that project directory, `my-docs/`.
+
+## Prepare a release
+
+Set `site.origin` in `docs.config.yaml` to your public HTTPS origin. Then audit the project and build it:
+
+```sh
+npx --no-install shoalrun audit docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
+```
+
+Review the generated HTML, Markdown, and `dist/documents.json`. A build replaces its output directory; keep source files outside `dist/`. If it fails, use [troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md).
+
+## Choose a host
+
+Choose a hosting route based on the artifacts and server features your site needs.
+
+| Hosting route                                        | What to deploy                                                                                                                         |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| [Vercel](https://www.shoalrun.com/publish/vercel.md) | The `.vercel/output/` bundle generated by the installed CLI.                                                                           |
+| Node server                                          | The compiled site and the installed `@shoalrun/cli` package, as described below.                                                       |
+| Another host                                         | The compiled files plus routing and headers implementing the [HTTP contract](https://www.shoalrun.com/publish/content-negotiation.md). |
+
+For a site hosted at `/docs`, set `site.basePath: /docs`. The Node and Vercel adapters serve the prefixed routes directly. On a static host that mounts a directory at `/docs`, publish the build output's `docs/` subtree as that directory's root. The build keeps internal manifests at the output root for local commands. Static hosts also need routing rules for [Markdown content negotiation](https://www.shoalrun.com/publish/content-negotiation.md).
+
+### Node hosting
+
+On a machine with Node.js 22.12 or newer and npm, check out your documentation project with its `package.json` and lockfile. Configure package registry access as described in the [quickstart](https://www.shoalrun.com/start.md), then run these commands from the project directory:
+
+```sh
+npm ci
+npx --no-install shoalrun build docs.config.yaml dist
+npx --no-install shoalrun serve dist --host 0.0.0.0 --port 8080
+```
+
+The last command runs the server in the foreground. Configure your host's process manager to run it from the project directory and restart it after a release. Route your public HTTPS endpoint to port 8080 using the host's proxy or load balancer. Preserve request `Accept` headers and response headers through that proxy. The Node server handles HTML, negotiated Markdown, explicit `.md` URLs, and discovery resources.
+
+For a local check, use `http://localhost:8080/install/` and `http://localhost:8080/install.md` from the minimal starter. Replace those paths with your own pages when you change the content.
+
+### Other hosts
+
+A static upload alone does not establish Markdown content negotiation. Configure the host to serve the resources and page variants described in [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), including `Vary: Accept`, content types, Markdown alternate links, redirects, and 404 responses. Use [generated outputs](https://www.shoalrun.com/publish/output.md) to identify the files to deploy.
+
+## Verify the public site
+
+Replace the example origin and page path below with a published page on your site:
+
+```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
+```
+
+Confirm that all three requests return HTTP 200. The first should return HTML; the second and third should return the page as Markdown. Check the response headers and missing-page behavior against the [HTTP contract](https://www.shoalrun.com/publish/content-negotiation.md). A local build verifies files; these requests check the host's responses.
+
+Shoalrun's docs repository also has a [whole-site deployment checker](https://www.shoalrun.com/publish/deployment-check.md). That repository script is separate from the installed CLI.
+
+Before sharing a page, [check its SEO and social preview metadata](https://www.shoalrun.com/publish/seo.md), including the public share-image URL.
+
+Next, [put multiple versions on one site](https://www.shoalrun.com/publish/publications.md) if you need several editions in one site. For branches, tags, and retained build snapshots, see [use Git branches for separate docs sites](https://www.shoalrun.com/publish/revisions.md).
+
+## Related reading
+
+### Next steps
+
+- [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) — Build the site and routing rules for Vercel.
+
+### Reference while working
+
+- [Check a deployed site](https://www.shoalrun.com/publish/deployment-check.md) — Check deployed HTML, Markdown, and discovery responses.
+
+### Related topics
+
+- [Add Shoalrun to another build or host](https://www.shoalrun.com/publish/host-adapters.md) — Apply the hosting contract on another platform.

package/agent-docs/recipes/add-page.md

@@ -0,0 +1,194 @@
+---
+id: recipe.add-page
+title: Add a page to this documentation site
+summary: Create a guide, add navigation, build and audit it, then refresh its
+  agent documentation.
+type: recipe
+area: authoring
+subarea: authoring-pages
+canonical: /recipes/add-page
+---
+
+# Add a page to this documentation site
+
+> 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) > Write documentation > Recipes and cookbooks > Recipes > Add a page to this documentation site
+
+**Updated: 2026-10-27.**
+
+Create a guide, add navigation, build and audit it, then refresh its agent documentation.
+
+## Before you start
+
+- `DOC_ID`: Set `export DOC_ID=guide.my-new-guide` for the new guide; use the same ID in navigation and every check.
+- `repositoryCheckout`: This documentation repository with its pinned package and lockfile.
+- Run commands from the documentation repository root.
+- Use Node.js 22.12 or newer.
+- Use Node.js 22.12 or newer and install site dependencies with `npm ci` if needed.
+- Install Vale 3.20 or newer for this repository's configured formatting check.
+
+## Install the site dependencies
+
+- Use `repositoryCheckout` from **Before you start**: This documentation repository and its package lockfile.
+
+Install the versions pinned by this site’s lockfile:
+
+```sh
+npm ci
+npx --no-install shoalrun config validate docs/docs.config.yaml
+```
+
+The manifest and lockfile pin the CLI version and registry artifact. Public npm releases need no package token or framework checkout. If your checkout still pins an older GitHub Packages release, follow [Getting started](https://www.shoalrun.com/start.md) to migrate registries. That older dependency still needs its original registry access until upgraded. Update and validate the dependency and lockfile together.
+
+Save `frameworkCli`: The installed shoalrun executable in node_modules/.bin.
+
+**Continue when:** The dependency installation succeeds and the installed CLI validates the site configuration.
+
+## Scaffold a new guide
+
+- Use `DOC_ID` from **Before you start**: The stable document ID chosen for the new guide.
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+
+Choose a file name, title, and stable document ID for your real topic. The commands use `my-new-guide` as the example; replace those values together.
+
+```sh
+npx --no-install shoalrun scaffold how-to -n docs/content/my-new-guide.mdx \
+  --config docs/docs.config.yaml --id "$DOC_ID" --title 'My new guide'
+```
+
+The command refuses to overwrite an existing file. If this guide already exists, edit it directly instead of scaffolding it again. Keep its access policy set to `draft` while writing.
+
+Save `draftPage`: The new draft at docs/content/my-new-guide.mdx with ID guide.my-new-guide.
+
+**Continue when:** The CLI creates the requested file with draft access and the intended document ID.
+
+## Complete the guide and add navigation
+
+- Use `draftPage` from **Scaffold a new guide**: The draft file and stable ID returned by the scaffold step.
+
+Open the scaffolded file and write the actual task, prerequisites, steps, and an observable success check. Set `updated` to today's date, replace the draft summary, and resolve every generated TODO prompt. Check every technical claim against the implementation or a tested workflow.
+
+Set a suitable `card.icon`, such as `file-text`, to meet this site's page-card audit. Once the content is ready for review in the built site, change `access.policy` to `public` and add the stable document ID under the appropriate group in `docs/config/nav.yaml`:
+
+```yaml
+- { id: my-new-guide, doc: guide.my-new-guide }
+```
+
+For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it does not deploy the site.
+
+Save `authoredPage`: The completed public page and its navigation entry, ready for a local build.
+
+**Continue when:** The summary and scaffold prompts are replaced, the guide has a card icon, and navigation references its stable ID.
+
+## Build the Shoalrun docs site
+
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+
+Use the installed CLI to build Shoalrun's documentation:
+
+```sh
+npx --no-install shoalrun build docs/docs.config.yaml docs/dist
+```
+
+The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
+
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+
+Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
+
+**Continue when:** The build reports status: ok and the expected number of documents.
+
+## Check the built page artifacts
+
+- Use `DOC_ID` from **Before you start**: The stable ID of the page being checked.
+- Use `builtSite` from **Build the Shoalrun docs site**: The site produced by the successful build.
+
+Choose a document by its stable ID. The default below checks the recipes overview; replace it with the ID of the page you changed.
+
+```sh
+export DOC_ID="${DOC_ID:-guide.recipes-overview}"
+node --input-type=module <<'JS'
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+const root = 'docs/dist';
+const manifest = JSON.parse(await readFile(path.join(root, 'documents.json'), 'utf8'));
+const doc = manifest.documents.find(item => item.id === process.env.DOC_ID);
+if (!doc) throw new Error(`No published document with ID ${process.env.DOC_ID}`);
+for (const route of [`${doc.url.replace(/\/$/, '')}/index.html`, doc.markdownUrl]) {
+  const file = path.join(root, route.replace(/^\//, ''));
+  if (!(await readFile(file, 'utf8')).trim()) throw new Error(`Empty output: ${file}`);
+  console.log(file);
+}
+JS
+```
+
+If the ID is missing, check the page's access policy and publication fields, then rebuild. Inspect the printed Markdown file for the expected instructions. Use a local HTTP preview for the HTML page so its assets and navigation resolve correctly.
+
+Save `checkedArtifacts`: The HTML and Markdown paths reported for the selected document.
+
+**Continue when:** The check prints two nonempty files for the chosen document ID.
+
+## Audit the Shoalrun docs project
+
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+
+Run Shoalrun's configured checks. This repository's formatting check requires [Vale](https://vale.sh/) 3.20 or newer:
+
+```sh
+npx --no-install shoalrun audit docs/docs.config.yaml
+```
+
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+
+Save `auditPassed`: A successful audit report with no failed configured checks.
+
+**Continue when:** The audit exits successfully and reports status: ok with no failed checks.
+
+## Regenerate the agent documentation bundle
+
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+
+Export the already built site for the framework’s next documentation snapshot:
+
+```sh
+npm run agent-docs:build
+```
+
+Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It does not modify the installed package.
+
+Review and transfer the export as a versioned artifact to the framework repository. Framework releases consume an explicitly selected snapshot; they must not fetch the latest site during a package build.
+
+Save `agentBundle`: The exported Markdown, manifest, search index, and provenance under agent-docs.
+
+**Continue when:** The command reports matching counts of bundled Markdown pages and search records.
+
+## Check agent search and page lookup
+
+- Use `DOC_ID` from **Before you start**: The stable ID of the page being checked.
+- Use `agentBundle` from **Regenerate the agent documentation bundle**: The refreshed offline documentation bundle.
+
+Search and read the exported site snapshot explicitly:
+
+```sh
+npx --no-install shoalrun docs search "recipes and cookbooks" --site agent-docs
+npx --no-install shoalrun docs read "$DOC_ID" --site agent-docs
+```
+
+Confirm the returned Markdown includes your change and links. Review `agent-docs/provenance.json` and the export inventory before handing the artifact to the framework release process. Plain `shoalrun docs read` uses the installed package’s snapshot, which is independent of this working tree.
+
+Save `agentLookupConfirmed`: Search results and page Markdown from the refreshed bundle, plus a reviewed generated diff.
+
+**Continue when:** Search includes the intended topic, docs read shows the current instructions, and generated changes are understood.
+
+## Check the outcome
+
+The new page appears in the local site and navigation. Its HTML and Markdown files exist, audits pass, and docs read returns the refreshed bundle entry. Use the new guide ID for the artifact and agent checks. Preview the rendered page before committing or publishing.
+
+## Related reading
+
+### Related topics
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Choose a related Shoalrun workflow.

package/agent-docs/recipes/add-page.sections/audit-the-shoalrun-docs-project.md

@@ -0,0 +1,40 @@
+---
+id: recipe.add-page
+title: Add a page to this documentation site
+summary: Create a guide, add navigation, build and audit it, then refresh its
+  agent documentation.
+type: recipe
+area: authoring
+subarea: authoring-pages
+canonical: /recipes/add-page
+---
+
+# Add a page to this documentation site
+
+> 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) > Write documentation > Recipes and cookbooks > Recipes > Add a page to this documentation site
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/recipes/add-page.md)
+
+Create a guide, add navigation, build and audit it, then refresh its agent documentation.
+
+## Audit the Shoalrun docs project
+
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+
+Run Shoalrun's configured checks. This repository's formatting check requires [Vale](https://vale.sh/) 3.20 or newer:
+
+```sh
+npx --no-install shoalrun audit docs/docs.config.yaml
+```
+
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+
+Save `auditPassed`: A successful audit report with no failed configured checks.
+
+**Continue when:** The audit exits successfully and reports status: ok with no failed checks.