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

package/agent-docs/recipes/add-page.sections/complete-the-guide-and-add-navigation.md

@@ -0,0 +1,42 @@
+---
+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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > 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.
+
+## 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.

package/agent-docs/recipes/add-page.sections/install-the-site-dependencies.md

@@ -0,0 +1,41 @@
+---
+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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > 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.
+
+## 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.

package/agent-docs/recipes/add-page.sections/regenerate-the-agent-documentation-bundle.md

@@ -0,0 +1,43 @@
+---
+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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > 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.
+
+## Regenerate the agent documentation bundle
+
+- Use `frameworkCli` from **Install the site dependencies**: The pinned Shoalrun package installed for this site.
+- Use `builtSite` from **Build the Shoalrun docs site**: The successful current site build at docs/dist.
+
+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.

package/agent-docs/recipes/add-page.sections/related-reading.md

@@ -0,0 +1,30 @@
+---
+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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > 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.
+
+## 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/scaffold-a-new-guide.md

@@ -0,0 +1,42 @@
+---
+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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > 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.
+
+## 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.

package/agent-docs/recipes/audit-docs.md

@@ -0,0 +1,121 @@
+---
+id: recipe.audit-docs
+title: Build and audit this documentation site
+summary: Build current documentation, check its artifacts, and run the
+  configured audits.
+type: recipe
+area: quality
+subarea: quality-audits
+canonical: /recipes/audit-docs
+---
+
+# Build and audit 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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Build and audit this documentation site
+
+**Updated: 2026-10-27.**
+
+Build current documentation, check its artifacts, and run the configured audits.
+
+## Before you start
+
+- `DOC_ID`: Set `export DOC_ID=guide.recipes-overview`, or use the stable ID of the page you changed.
+- `repositoryCheckout`: This documentation repository with its pinned package and lockfile.
+- Run commands from the documentation repository root.
+- Use Node.js 22.12 or newer.
+- 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.
+
+## 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.
+
+## Check the outcome
+
+The current source builds, the selected page has both output formats, and all configured audits pass. Review the rendered change before publishing; this recipe does not deploy or run the full framework test suite.
+
+## Related reading
+
+### Related topics
+
+- [Site workflows](https://www.shoalrun.com/cookbooks/site-workflows.md) — Choose a related Shoalrun workflow.

package/agent-docs/recipes/build-docs.md

@@ -0,0 +1,104 @@
+---
+id: recipe.build-docs
+title: Build this documentation site
+summary: Use the pinned Shoalrun package and confirm a chosen page has HTML and
+  Markdown output.
+type: recipe
+area: publishing
+subarea: publishing-builds
+canonical: /recipes/build-docs
+---
+
+# Build 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: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Build this documentation site
+
+**Updated: 2026-10-27.**
+
+Use the pinned Shoalrun package and confirm a chosen page has HTML and Markdown output.
+
+## Before you start
+
+- `DOC_ID`: Set `export DOC_ID=guide.recipes-overview`, or use the stable ID of the page you changed.
+- `repositoryCheckout`: This documentation repository with its pinned package and lockfile.
+- Run commands from the documentation repository root.
+- Use Node.js 22.12 or newer.
+
+## 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.
+
+## 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.
+
+## Check the outcome
+
+The build succeeded and the selected document has nonempty HTML and Markdown files. Use the preview recipe to inspect the rendered experience.
+
+## Related reading
+
+### Related topics
+
+- [Site workflows](https://www.shoalrun.com/cookbooks/site-workflows.md) — Choose a related Shoalrun workflow.

package/agent-docs/recipes/preview-hybrid-search.md

@@ -0,0 +1,84 @@
+---
+id: recipe.preview-hybrid-search
+title: Preview semantic search in this checkout
+summary: Build the Shoalrun docs, index passages, and verify vector retrieval
+  and lexical fallback locally.
+type: recipe
+area: discovery
+subarea: discovery-search
+canonical: /recipes/preview-hybrid-search
+---
+
+# Preview semantic search in this checkout
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Preview semantic search in this checkout
+
+**Updated: 2026-10-26.**
+
+Build the Shoalrun docs, index passages, and verify vector retrieval and lexical fallback locally.
+
+## Before you start
+
+- `repositoryCheckout`: A Shoalrun checkout with dependencies installed. Run commands from its root with Node.js 22.12 or newer.
+- `embeddingCredentials`: A shell-readable environment file at `~/.config/shoalrun/.env` containing the key for the embedding provider configured under `retrieval.embeddings`. This site's current config uses Voyage; the key stays on the server.
+- `previewPort`: Port 8770, available for the preview server. If occupied, use another port with the CLI and adjust the URL.
+
+## Build and index the docs
+
+- Use `repositoryCheckout` and `embeddingCredentials` from **Before you start**.
+
+```sh
+npm run docs:build
+set -a; . ~/.config/shoalrun/.env; set +a
+npm run docs:index
+```
+
+The build writes `search-index.json`. The index command sends documentation passages to the configured **embedding provider** and generates or reuses passage vectors. Each semantic query also calls the embedding provider. No chat model is needed for search.
+
+If indexing reports a missing key or provider error, check `retrieval.embeddings` and the environment file, then rerun indexing. The [passage index guide](https://www.shoalrun.com/chat/passage-index.md) explains digests and vector reuse.
+
+Save `indexedSite`: The successful site build and current passage index under docs/dist.
+
+**Continue when:** The build and index commands both succeed.
+
+## Start the semantic endpoint
+
+- Use `indexedSite` from **Build and index the docs** and `previewPort` from **Before you start**.
+
+```sh
+npm run docs:search-preview
+```
+
+Open `http://127.0.0.1:8770/`. This command occupies the terminal. Restart it after rebuilding the passage index, because the local endpoint reads its files at startup. Vector results include only passages with current embeddings. Reindex after editing pages so semantic results include the changed passages. A literal configuration key or command flag can also recover one word-matching explanation, but this is not a substitute for refreshing vectors.
+
+The browser search provider first asks `/__shoalrun/search`. That endpoint ranks passages by embedding similarity and returns page or section links. Successful semantic queries keep their first two pages ranked by meaning. A question containing dotted configuration keys or command flags can include one exact-identifier prose explanation as the third result. Filenames and requests for fewer than three results keep semantic ranking. It does not call the chat model. If the endpoint has no current vectors, it returns lexical passage results. If the endpoint is missing, slow, or fails, the browser uses `search-index.json` for lexical page search.
+
+Save `runningPreview`: The local site and search endpoint while the server is running.
+
+**Continue when:** The homepage and its search box load.
+
+## Verify the retrieval mode
+
+- Use `runningPreview` from **Start the semantic endpoint**.
+
+Search for `navigation`, then describe a task in your own words without copying a page title or sentence. For example, ask about reusing warnings across documentation. Lexical search can now return partial matches for the sentence; returning a result alone does not prove semantic retrieval worked.
+
+In the browser Network inspector, inspect `/__shoalrun/search`. A successful response with `"mode": "vector"` confirms the endpoint used embeddings. `"mode": "lexical"` means the endpoint returned word-matching results. It can do this when current document vectors are missing, the embedding budget is exhausted, the provider fails, or the three-second deadline expires. The response mode alone does not tell you whether document vectors exist. A failed request followed by results demonstrates the browser provider's lexical fallback. For a preview without the endpoint, stop this server and run `npm run docs:preview`.
+
+Save `modeEvidence`: The response mode and relevant page or section links for the queries.
+
+**Continue when:** You can identify the active retrieval mode and open a relevant result.
+
+## Check the outcome
+
+The indexed site serves local search, results open relevant documentation, and the Network inspector distinguishes vector retrieval from the lexical endpoint or browser fallback. Press **Ctrl+C** to stop the server.
+
+## Related reading
+
+### Next steps
+
+- [Passage index](https://www.shoalrun.com/chat/passage-index.md) — Understand passage digests, embedding input, and vector reuse. (Status: experimental.)

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

@@ -0,0 +1,123 @@
+---
+id: recipe.preview-page
+title: Preview a documentation change locally
+summary: Build current documentation and inspect its HTML and Markdown over local HTTP.
+type: recipe
+area: publishing
+subarea: publishing-builds
+canonical: /recipes/preview-page
+---
+
+# Preview a documentation change locally
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Preview a documentation change locally
+
+**Updated: 2026-10-27.**
+
+Build current documentation and inspect its HTML and Markdown over local HTTP.
+
+## Before you start
+
+- `DOC_ID`: Set `export DOC_ID=guide.recipes-overview`, or use the stable ID of the page you changed.
+- `repositoryCheckout`: This documentation repository with its pinned package and lockfile.
+- Run commands from the documentation repository root.
+- Use Node.js 22.12 or newer.
+
+## 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.
+
+## 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.
+
+## Serve the built docs locally
+
+- Use `builtSite` from **Build the Shoalrun docs site**: The successful site build at docs/dist.
+
+Serve the build from the repository root:
+
+```sh
+npx --no-install shoalrun serve docs/dist --port 8770
+```
+
+This command occupies the terminal. Open `http://127.0.0.1:8770/author/recipes/` and `http://127.0.0.1:8770/author/recipes.md` in a browser. For another page, use its `url` and `markdownUrl` from `docs/dist/documents.json`.
+
+Check the page title, navigation, links, images, code copying, and complete instructions in Markdown. Check the page at a narrow window width too. If port 8770 is occupied, select another port and use it in both URLs.
+
+Press **Ctrl+C** when finished. This server serves the existing build; rebuild and reload after editing. Use `npm run docs:dev` for ongoing work that should rebuild automatically.
+
+Save `previewOrigin`: The local preview at <http://127.0.0.1:8770> while the server is running.
+
+**Continue when:** The selected HTML page and its Markdown twin load, the sidebar reaches it, and the instructions are complete.
+
+## Check the outcome
+
+The page you changed works over HTTP, navigation reaches it, and its Markdown contains the complete instructions. Stop the preview server when finished.
+
+## Related reading
+
+### Related topics
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Choose a related Shoalrun workflow.