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

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: [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 > 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,124 @@
+---
+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: [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 > 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.
+- Use Node.js 22.12 or newer and install site dependencies with `npm ci` if needed.
+
+## 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.

package/agent-docs/recipes/queue-email.md

@@ -0,0 +1,49 @@
+---
+id: recipe.queue-email
+title: Queue a welcome email
+summary: Submit the welcome template and confirm the API accepted the request.
+type: recipe
+area: api
+subarea: api-examples
+canonical: /recipes/queue-email
+---
+
+# Queue a welcome email
+
+> 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 > Queue a welcome email
+
+**Updated: 2026-10-25.**
+
+Use this path to check request acceptance. For delivery status and failure handling, follow [the complete delivery recipe](https://www.shoalrun.com/recipes/send-welcome-email.md).
+
+## Before you start
+
+Start the local simulation from the Shoalrun repository root in a separate terminal:
+
+```sh
+node framework/example-configs/notifications/demo.mjs
+```
+
+Keep it running. Have cURL and Node.js available, and use a scratch directory for `queued.json`; the command replaces that file. The demo sends no email.
+
+## Queue the message
+
+```sh
+export API_BASE=http://127.0.0.1:8787/v1
+curl --fail-with-body --silent --show-error \
+  --request POST "$API_BASE/messages/email" \
+  --header 'Content-Type: application/json' \
+  --data '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}' \
+  --output queued.json --write-out 'HTTP %{http_code}\n'
+cat queued.json
+MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8')).id")
+printf '\nMessage ID: %s\n' "$MESSAGE_ID"
+```
+
+## Check the outcome
+
+The HTTP status is 202, the response says `status: queued`, and the returned `id` is nonempty. Keep that ID if you will check delivery later. A failed POST needs its own diagnostic; do not reuse an ID from an earlier attempt. Acceptance leaves delivery unknown.

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

@@ -0,0 +1,109 @@
+---
+id: recipe.refresh-agent-docs
+title: Refresh Shoalrun's bundled agent docs
+summary: Regenerate offline docs, verify CLI search and read, and run project audits.
+type: recipe
+area: discovery
+subarea: discovery-agents
+canonical: /recipes/refresh-agent-docs
+---
+
+# Refresh Shoalrun's bundled agent docs
+
+> 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 > Refresh Shoalrun's bundled agent docs
+
+**Updated: 2026-10-27.**
+
+Regenerate offline docs, verify CLI search and read, and run project 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.
+- 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.
+
+## 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.
+
+## 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 bundle contains the current authored instructions, search and read find the intended page, and configured audits pass. Hand off the reviewed snapshot as a versioned artifact.
+
+## Related reading
+
+### Related topics
+
+- [Authoring workflows](https://www.shoalrun.com/cookbooks/authoring.md) — Choose a related Shoalrun workflow.

package/agent-docs/recipes/send-welcome-email.md

@@ -0,0 +1,92 @@
+---
+id: recipe.send-welcome-email
+title: Send a welcome email and confirm delivery
+summary: Follow one message from an accepted request through delivery, and
+  inspect a simulated failure.
+type: recipe
+area: api
+subarea: api-examples
+canonical: /recipes/send-welcome-email
+---
+
+# Send a welcome email and confirm delivery
+
+> 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 > Send a welcome email and confirm delivery
+
+**Updated: 2026-10-26.**
+
+Follow one message from an accepted request through delivery, and inspect a simulated failure.
+
+## Before you start
+
+- `API_BASE`: Set `export API_BASE=http://127.0.0.1:8787/v1` in your command terminal.
+- From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it is already running, reuse it.
+- Use a scratch directory for queued.json and delivery.json. These commands replace those files.
+- Have cURL and Node.js available in your command terminal.
+
+## Queue the welcome email
+
+- Use `API_BASE` from **Before you start**: The demo API base URL set in your terminal.
+
+Send the `welcome` template to the demo recipient. The demo stores a simulated message and sends no email.
+
+```sh
+curl --fail-with-body --silent --show-error \
+  --request POST "$API_BASE/messages/email" \
+  --header 'Content-Type: application/json' \
+  --data '{"to":"reader@example.com","template":"welcome","variables":{"firstName":"Avery"}}' \
+  --output queued.json --write-out 'HTTP %{http_code}\n'
+cat queued.json
+MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8')).id")
+printf '\nMessage ID: %s\n' "$MESSAGE_ID"
+```
+
+A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Do not reuse a message ID from an earlier attempt.
+
+Save `MESSAGE_ID`: The id returned in queued.json; use this exact value for the delivery check.
+
+**Continue when:** The POST returns HTTP 202, status is queued, and MESSAGE_ID is nonempty. This confirms acceptance only.
+
+## Check delivery for that message
+
+- Use `API_BASE` from **Before you start**: Use the same environment as the queue request.
+- Use `MESSAGE_ID` from **Queue the welcome email**: Put the returned ID into the status URL; do not substitute the example ID.
+
+Look up the message using the ID saved in the previous step:
+
+```sh
+curl --fail-with-body --silent --show-error \
+  "$API_BASE/messages/$MESSAGE_ID" \
+  --output delivery.json --write-out 'HTTP %{http_code}\n'
+cat delivery.json
+```
+
+The local demo returns `queued` on the first lookup. Run the lookup once more to see its terminal status. This deterministic transition is part of the simulation; a real provider needs its own polling interval and timeout.
+
+| Status or error    | What to do next                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `queued`           | The request was accepted; delivery is still pending. In this demo, repeat the lookup once.                          |
+| `delivered`        | Check that `id` matches `MESSAGE_ID`. The delivery check is complete.                                               |
+| `failed`           | Inspect `failureReason`. Correct the cause before creating another message; do not keep polling a terminal failure. |
+| HTTP 404           | Check the saved ID and API base URL. Restarting the demo clears its messages.                                       |
+| Connection refused | Start the demo and check that it is listening on port 8787.                                                         |
+
+To exercise failure handling, repeat the queue step with `blocked@example.com`, save its new message ID, and check that ID twice. The demo returns `failed` with `failureReason: recipient_rejected`.
+
+Save `deliveryStatus`: The status returned for MESSAGE_ID in delivery.json.
+
+**Continue when:** The response id equals MESSAGE_ID and status is delivered. Queued and failed do not satisfy this recipe's goal.
+
+## Check the outcome
+
+The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still does not prove the recipient read it.
+
+## Related reading
+
+### Related topics
+
+- [Welcome email workflows](https://www.shoalrun.com/cookbooks/welcome-email.md) — Compare the complete delivery path with the acceptance-only path.

package/agent-docs/reference/agent-skills.md

@@ -0,0 +1,73 @@
+---
+id: reference.agent-skills
+title: Bundled agent skills
+summary: Skill names, locations, workflow behavior, offline documentation, and
+  validation limits.
+type: reference
+area: authoring
+subarea: authoring-agent-workflows
+canonical: /reference/agent-skills
+---
+
+# Bundled agent skills
+
+> 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) > Get started > Bundled agent skills
+
+**Updated: 2026-10-26.**
+
+Shoalrun ships five portable skill folders under `framework/skills/`. Each folder contains a `SKILL.md` with instructions for an agent that can read files and run the Shoalrun CLI. A skill supplies guidance; it does not run a separate authoring service.
+
+These are authoring skills for Shoalrun. The build does not create a reader-side skill for each published site. Agents reading a generated site use its Markdown twins, `/llms.txt`, and `/documents.json`. A non-interactive skill builder is a [non-goal](https://www.shoalrun.com/non-goals.md): skill creation and maintenance need guidance from a human expert.
+
+## Skill inventory
+
+Each skill supplies instructions for a specific part of the authoring workflow.
+
+| Skill                       | Use it for                                                                                                                                                                                                                 |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `shoalrun-setup`            | Start a docs project, choose a working example config, build it, and inspect its first HTML and Markdown pages.                                                                                                            |
+| `shoalrun-author`           | Add or revise pages, navigation, API links, snippets, and project tests with the agent's own model and Shoalrun CLI. It uses normal file edits, project discovery, isolated validation, and snapshot review/preview tools. |
+| `shoalrun-recipes`          | Write task-oriented how-tos as complete recipes, reuse ingredients where helpful, and configure cookbook choices.                                                                                                          |
+| `shoalrun-component-author` | Create trusted [custom components](https://www.shoalrun.com/author/components/custom.md), validate their schemas and shared content, and review HTML/Markdown parity.                                                      |
+| `shoalrun-walkthrough`      | Turn notes, a tutorial, or project code into a [walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md) that explains code step by step.                                                                  |
+
+Each folder name matches its skill name. For example, the author skill's entry file is `framework/skills/shoalrun-author/SKILL.md`. Installation locations depend on the agent. [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) describes choosing and invoking one.
+
+## Workflow behavior
+
+The setup skill uses `shoalrun init` to create a project from the bundled `minimal` or `api-docs` starter, then uses `config validate`, `build`, and `dev` to check the result. The author skill uses stable IDs and project config provenance so edits stay attached to the intended publication. The walkthrough skill chooses a mode and layout, prefers code taken from project files, and checks each step's highlight. The recipes skill starts from a reader goal and success check, reuses ingredient source when useful, and distinguishes authoring from browser selection. All five ask the agent to inspect generated HTML and Markdown. They leave deployment decisions with the site owner.
+
+The author skill starts with project-wide discovery and policy reads, captures a task baseline, and edits ordinary working-tree files. It validates a separate capture and opens the matching snapshot review/preview. Required companions come from project policy; compiler success does not waive them. Existing local edits are included in the baseline rather than attributed to the new task. No extra authoring model key is needed. Explicit checked-plan clients can still use [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md).
+
+## Component-authoring skill
+
+`shoalrun-component-author` guides a coding agent through creating or repairing a trusted component plugin. It asks the agent to inventory essential content and decide what belongs in MDX and data. The agent then writes validation and shared content, adds browser controls where needed, and tests both representations. The agent produces project files, fixtures, usage examples, check results, and a local preview for review.
+
+The skill is an instruction file, not a compiler feature or an automatic React-to-Markdown converter. The component author and agent must write the complete static explanation. A passing build does not establish that every interactive choice or warning is represented faithfully. [Custom components](https://www.shoalrun.com/author/components/custom.md) shows a small copy button with content in MDX, generated Markdown, and a sample agent request. [Data-driven React components](https://www.shoalrun.com/author/components/custom/react.md) adds a local policy file and generated explanations.
+
+## Offline documentation
+
+All five skills can consult Shoalrun's bundled docs through a local, agent-neutral tool:
+
+```sh
+shoalrun docs search "API reference navigation"
+shoalrun docs read guide.api-references
+```
+
+Search returns JSON with document IDs and excerpts. Read returns the complete generated Markdown page. The commands work offline and do not require a docs site to be running. They are useful to any agent that can run a CLI, even when it cannot discover `SKILL.md` files automatically.
+
+## Limits
+
+Skills guide the agent's actions. They cannot establish whether a technical claim is true. Shoalrun's [audit](https://www.shoalrun.com/publish/audit.md) checks implemented build and representation rules and any configured external tests. Human review and behavior tests establish whether the instructions work.
+
+The recipes skill prefers complete task pages, adds ingredients when instructions are shared, and uses cookbooks when readers need help choosing tasks. It respects an explicitly requested format. [Ingredients, recipes, and cookbooks](https://www.shoalrun.com/author/recipes.md) explains those distinctions.
+
+## Related reading
+
+### Related topics
+
+- [Non-goals](https://www.shoalrun.com/non-goals.md) — Understand why a non-interactive skill builder is outside the tool's scope.

package/agent-docs/search-and-chat.md

@@ -0,0 +1,87 @@
+---
+id: guide.search-chat-overview
+title: Search and chat
+summary: Choose page search, meaning-based search, or cited answers for your
+  documentation.
+type: explanation
+area: discovery
+subarea: discovery-search
+canonical: /search-and-chat
+---
+
+# Search and chat
+
+> 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) > Search and chat > Overview
+
+**Updated: 2026-10-26.**
+
+Start with [site search](https://www.shoalrun.com/author/search.md) if readers need links to pages and sections. It is built in, works on a static host, and needs no provider account. Add chat when readers need answers written from your documentation.
+
+## Choose the result you want
+
+These features have different setup and hosting needs. Passage retrieval and chat are experimental.
+
+| Reader needs                           | Feature                                                                              | Requirements                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| Page and section links                 | [Site search](https://www.shoalrun.com/author/search.md)                             | A normal site build and a browser with JavaScript.                                                                    |
+| Links that can match different wording | [Semantic search preview](https://www.shoalrun.com/recipes/preview-hybrid-search.md) | A passage index, embeddings, and a local search endpoint. The provider can fall back to keyword search.               |
+| An answer with source citations        | [Documentation chat](https://www.shoalrun.com/chat/setup.md)                         | A passage index, a configured chat service, and a terminal or server. Embeddings and a scorer are optional additions. |
+
+The sidebar's [navigation filter](https://www.shoalrun.com/author/navigation.md) only narrows the menu. Its search words do not change site-search results. The search dropdown returns links; it does not call a chat model.
+
+## Start with a local chat
+
+Follow [Set up local documentation chat](https://www.shoalrun.com/chat/setup.md) to configure a service, index your pages, and inspect an answer with sources.
+
+Once that works, choose the next capability you need:
+
+- [Answer checks](https://www.shoalrun.com/chat/checks.md) explain coverage, citations, code checks, and answer reuse.
+- [Answer cards](https://www.shoalrun.com/chat/prepared-answers.md) prepare reviewed answers to recurring questions.
+- [Hosting](https://www.shoalrun.com/chat/host.md) adds a Vercel function, shared limits, and an off switch.
+- [Settings](https://www.shoalrun.com/chat/settings.md) define the provider fields and optional layers.
+
+## Which index does each feature use?
+
+Shoalrun keeps page search and passage retrieval separate.
+
+| File                            | Created by                                             | Used for                                                                                                     |
+| ------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `search-index.json`             | The normal site build when search indexing is enabled. | Browser page search and local documentation search. Contains titles, summaries, headings, and text excerpts. |
+| `ai/chunks.json`                | `shoalrun index` after the build.                      | Passage retrieval for semantic search and chat. Contains text from built Markdown pages, with source links.  |
+| `ai/embeddings.json` and `.bin` | `shoalrun index --embed`                               | Comparing the meaning of queries and passages. Requires an embedding provider.                               |
+
+An **embedding** represents text as numbers. Keyword, or **lexical**, retrieval compares words. **Semantic** retrieval compares embeddings; **hybrid** retrieval combines word-based and meaning-based rankings. Neither requires a chat model just to return search links.
+
+The [passage reference](https://www.shoalrun.com/chat/passage-index.md) describes these files in detail. The [glossary](https://www.shoalrun.com/glossary.md) defines the related terms.
+
+## When an optional service is unavailable
+
+Fallback behavior depends on the configured feature.
+
+| Situation                                                    | Result                                                                      |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| Built-in search has no server or provider key                | Browser keyword search still works.                                         |
+| This site's custom search provider cannot reach its endpoint | It uses the browser keyword index.                                          |
+| A search endpoint has no current vectors, or embeddings fail | It returns keyword passage results.                                         |
+| Chat has no current vectors                                  | Retrieval uses keywords. A configured chat model can still write an answer. |
+| A deployment has no chat function                            | The site remains available, but has no chat endpoint.                       |
+
+A Vercel build with `--chat` includes search and answer endpoints. Semantic queries have shared rate and daily limits. When the embedding budget is exhausted, search returns keyword results. A static deployment can use browser search without those endpoints.
+
+## Related reading
+
+### Next steps
+
+- [How documentation answers work](https://www.shoalrun.com/chat.md) — Turn passage retrieval into cited answers. (Status: experimental.)
+
+- [Site search](https://www.shoalrun.com/author/search.md) — Configure the masthead box, its provider, and searchable index fields.
+
+### Reference while working
+
+- [Glossary](https://www.shoalrun.com/glossary.md) — Look up the search and retrieval terms used in this section.
+
+- [Passage index](https://www.shoalrun.com/chat/passage-index.md) — Compare the page index with the passage and vector files. (Status: experimental.)