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

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: [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) > Email simulation > 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,127 @@
+---
+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: [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 > 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.
+- 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.
+
+## 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.
+
+## 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: [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) > Email simulation > 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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > 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, chat, and agent access > 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.)