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

package/agent-docs/index.md

@@ -0,0 +1,249 @@
+---
+id: guide.home
+title: Shoalrun
+summary: Preview API and product docs with content selection and agent discovery.
+type: overview
+area: project
+subarea: project-overview
+canonical: /
+---
+
+# Shoalrun
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+**Updated: 2026-10-27.**
+
+**Docs for people. Context for agents.**
+
+One source, with control over how each audience reads it. Build interactive docs for people and readable content for agents, with checks before you publish.
+
+- [See what an agent gets](https://www.shoalrun.com/publish/agent-friendliness.md)
+- [See what works today](https://www.shoalrun.com/status.md)
+
+> **Try the alpha:** Install `@shoalrun/cli` from npm and build your own site. No account or package token is needed. Pin an exact version while the alpha evolves.
+>
+> [Install Shoalrun →](https://www.shoalrun.com/start.md)
+
+## Readable output, with checks you can inspect
+
+Write Markdown, MDX, and OpenAPI once. People get tabs, disclosures, navigation, and reader views. Agents get the supported content in reading order, with stable page identities and machine-readable contracts.
+
+| What you can inspect                     | What it gives you                                                                                                                 |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| A manifest with byte digests             | Stable page IDs and publication variants, with SHA-256 digests for checking the exact Markdown bytes.                             |
+| Compact discovery and incremental sync   | Find a page without the full search index; compare saved snapshots when a build changes.                                          |
+| Focused per-operation OpenAPI contracts  | One small contract containing an operation and the local schemas it needs, when enabled.                                          |
+| Explicit component representations       | Tabs and disclosures become labeled sections. Snippets expand into their resolved content. Unsupported components fail the build. |
+| Reader views and format-specific content | Choose what people see in the browser and write different explanations for HTML and Markdown when needed.                         |
+
+### A tabbed page, without missing panels
+
+This example has two client choices and a closed disclosure. The Markdown includes both clients and the troubleshooting detail.
+
+### You write
+
+````mdx title="content/check-service.mdx"
+<Tabs label="Client">
+<Tab label="curl">
+
+```sh
+curl -fsS https://api.example.com/health
+```
+
+</Tab>
+<Tab label="JavaScript">
+
+```js
+const response = await fetch('https://api.example.com/health');
+console.log(response.status);
+```
+
+</Tab>
+</Tabs>
+
+<Collapsible title="If the request fails">
+Check the service URL and your network connection.
+</Collapsible>
+````
+
+### People get HTML
+
+### curl
+
+```sh
+curl -fsS https://api.example.com/health
+```
+
+### JavaScript
+
+```js
+const response = await fetch('https://api.example.com/health');
+console.log(response.status);
+```
+
+### If the request fails
+
+Check the service URL and your network connection.
+
+### Agents get Markdown
+
+````md title="/check-service.md (body excerpt)"
+### curl
+
+```sh
+curl -fsS https://api.example.com/health
+```
+
+### JavaScript
+
+```js
+const response = await fetch('https://api.example.com/health');
+console.log(response.status);
+```
+
+### If the request fails
+
+Check the service URL and your network connection.
+````
+
+### Fetch the published output
+
+Start with the compact page list, choose a page, and fetch its Markdown. The full manifest supplies byte digests when you need verification; build information and sync snapshots let returning clients detect changes. [Try the example on the agent-friendly guide](https://www.shoalrun.com/publish/agent-friendliness.md) to compare live components with tested Markdown output.
+
+```sh
+curl -fsSL https://www.shoalrun.com/llms.min.txt
+curl -fsSL https://www.shoalrun.com/publish/agent-friendliness.md
+```
+
+Hosts that support [content negotiation](https://www.shoalrun.com/publish/agent-friendliness.md) can serve the same Markdown at the HTML route when the request sends `Accept: text/markdown`:
+
+```sh
+curl -fsSL -H 'Accept: text/markdown' https://www.shoalrun.com/author/search
+```
+
+## Check both audiences before you publish
+
+Shoalrun builds static files for your host. Its audit builds HTML and Markdown, checks links and API contracts, and runs configured project tests. An unsupported component stops the build instead of disappearing from the agent's document.
+
+For example, adding `<UnknownWidget />` to a page makes `shoalrun check` fail with the source path:
+
+```text
+FAIL build
+  …/docs.config.yaml: …/content/welcome.mdx: <UnknownWidget> has no semantic/Markdown adapter
+Checks failed. Fix the findings above and rerun shoalrun check.
+```
+
+This is illustrative output, not a failure on the current site. The check catches unsupported representations; it does not establish that every sentence is correct.
+
+[Eval reports](https://www.shoalrun.com/publish/evals.md) let you add reviewed task results to the publishing gate. Required failures and reports from an older build fail the audit. You supply the agent run and answer review. Shoalrun's five example tasks are a self-reviewed demonstration, with prior context; they are not an independent measure of agent accuracy or a comparison with other platforms.
+
+- [Audit a docs project](https://www.shoalrun.com/publish/audit.md)
+
+  Run project tests and local API representation checks with one CI command.
+
+- [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md)
+
+  Define realistic tasks, record reviewed answers from your own agent, and check the results against a documentation build.
+
+- [Add an OpenAPI API](https://www.shoalrun.com/publish/api-references.md)
+
+  Import a local OpenAPI file, author an operation page, review its public content, and build HTML and Markdown.
+
+## Control the reading experience
+
+[Reader views](https://www.shoalrun.com/author/reader-views.md) use the `readerFilters` configuration to shape browser navigation, search, cards, and marked sections. A UI reader can follow screen actions while a developer sees request examples. The published Markdown retains every reader-marked section with a label.
+
+Reader views are visibility controls, not access controls. Hidden browser content remains in published files. Use `access.policy` to exclude pages from a public build and host authorization to protect private content.
+
+[Format-specific content](https://www.shoalrun.com/author/components/only.md) lets you replace an interactive instruction with a useful written explanation. [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md) choose which frontmatter fields are published for agents. These are authoring and publication choices; discovery files do not protect private data.
+
+- [Reader views](https://www.shoalrun.com/author/reader-views.md)
+
+  Reader-view configuration, page and section marks, controls, and agent-facing behavior.
+
+- [Content for one format](https://www.shoalrun.com/author/components/only.md)
+
+  Use Only to add content to the HTML page or its Markdown twin alone.
+
+- [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md)
+
+  Public field projection, source paths, profiles, precedence, and required values.
+
+## Make it look like yours
+
+Choose a theme and palette, follow the reader's light or dark setting, and customize brand colors or CSS. The build checks configured palette colors for contrast.
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: reef
+  palette: harbor
+  mode: system
+```
+
+### Try the themes and palettes
+
+Every preset works with every palette, in light or dark mode.
+
+| Preset   | Shape                                                                               | Default palette |
+| -------- | ----------------------------------------------------------------------------------- | --------------- |
+| `shoal`  | Flat page with a ruled sidebar and square-cornered controls.                        | `kelp`          |
+| `reef`   | Rounded panels on a tinted page, with pill navigation and controls.                 | `coral`         |
+| `ledger` | Technical manual with an inked masthead, monospace headings, and numbered sections. | `ink`           |
+| `vice`   | Night masthead with a sunset stripe, bold italic type, and neon rules.              | `vice`          |
+
+| Palette    | Colors                                                          |
+| ---------- | --------------------------------------------------------------- |
+| `kelp`     | Sea green on white.                                             |
+| `coral`    | Coral accent over cool blue-gray neutrals.                      |
+| `ink`      | Black ink on warm paper with a vermilion accent.                |
+| `harbor`   | Navy ink, blue links, and a yellow callout rule.                |
+| `amethyst` | Violet accents over lavender neutrals.                          |
+| `vice`     | Flamingo pink and aqua by day, neon on night purple after dark. |
+
+```yaml title="docs.config.yaml"
+theme:
+  preset: vice
+  palette: harbor
+  mode: system
+```
+
+[Explore themes](https://www.shoalrun.com/styling/themes.md) or [customize the CSS](https://www.shoalrun.com/author/css.md).
+
+## Bring your own tools
+
+Customize these parts through config, local modules, or a host adapter.
+
+| Part              | Configure it in             | What you can change                                                    |
+| ----------------- | --------------------------- | ---------------------------------------------------------------------- |
+| Search            | `outputs.html.search`       | Use the built-in index, supply a provider, or turn browser search off. |
+| Code highlighting | `outputs.html.highlighting` | Choose a Shiki theme or supply a highlighter.                          |
+| Page metadata     | `metadata.provider`         | Define the fields your build can read, with values you supply.         |
+| Reader views      | `readerFilters`             | Define reader choices and mark pages and sections for those choices.   |
+| Share images      | `outputs.html.shareImages`  | Customize the link-preview design and fonts.                           |
+| Hosting           | Build adapters              | Configure HTTP behavior for Vercel, Node, or your own host.            |
+
+Split config across files with `$include`, share a base with `extends`, and ask `shoalrun config explain` which file set a value.
+
+### Give your coding agent the docs
+
+The prototype bundles four authoring skills: setup, authoring, recipes, and code walkthroughs. It also includes Shoalrun's generated documentation for offline lookup:
+
+```sh
+shoalrun docs search "custom search provider"
+shoalrun docs read guide.search
+```
+
+[Use the bundled skills](https://www.shoalrun.com/contribute/agent-skills.md) or consult the [command reference](https://www.shoalrun.com/reference/agent-skills.md). Shoalrun does not generate reader-side skills for each site it builds. Skills need human expertise to create and maintain; see the [non-goals](https://www.shoalrun.com/non-goals.md).
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md)
+
+  Learn how Shoalrun resolves config files, layers presets, tracks path origins, and applies page defaults before building publications.
+
+- [Configuration reference](https://www.shoalrun.com/config.md)
+
+  Find configuration settings by topic and compose a project configuration.
+
+- [Deploy your documentation](https://www.shoalrun.com/publish.md)
+
+  Build your site, choose Vercel or Node hosting, and verify the deployed HTML and Markdown.

package/agent-docs/ingredients/audit-site.md

@@ -0,0 +1,27 @@
+---
+id: ingredient.audit-site
+title: Audit the Shoalrun docs project
+summary: Run configured project checks and inspect failures before sharing a change.
+type: ingredient
+area: quality
+subarea: quality-audits
+canonical: /ingredients/audit-site
+---
+
+# Audit the Shoalrun docs project
+
+> 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 > Reusable Shoalrun steps > Audit the Shoalrun docs project
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/build-site.md

@@ -0,0 +1,29 @@
+---
+id: ingredient.build-site
+title: Build the Shoalrun docs site
+summary: Compile authored documentation into local HTML, Markdown, and manifests.
+type: ingredient
+area: publishing
+subarea: publishing-builds
+canonical: /ingredients/build-site
+---
+
+# Build the Shoalrun docs site
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Reusable Shoalrun steps > Build the Shoalrun docs site
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/compile-framework.md

@@ -0,0 +1,28 @@
+---
+id: ingredient.compile-framework
+title: Install the site dependencies
+summary: Install the pinned Shoalrun package and this site’s declared dependencies.
+type: ingredient
+area: publishing
+subarea: publishing-builds
+canonical: /ingredients/compile-framework
+---
+
+# Install the site dependencies
+
+> 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 > Reusable Shoalrun steps > Install the site dependencies
+
+**Updated: 2026-10-27.**
+
+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.

package/agent-docs/ingredients/complete-page.md

@@ -0,0 +1,30 @@
+---
+id: ingredient.complete-page
+title: Complete the guide and add navigation
+summary: Write the guide, replace scaffold prompts, and make it discoverable in
+  the local build.
+type: ingredient
+area: authoring
+subarea: authoring-pages
+canonical: /ingredients/complete-page
+---
+
+# Complete the guide and add navigation
+
+> 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 > Reusable Shoalrun steps > Complete the guide and add navigation
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/inspect-agent-bundle.md

@@ -0,0 +1,28 @@
+---
+id: ingredient.inspect-agent-bundle
+title: Check agent search and page lookup
+summary: Confirm the refreshed bundle exposes the authored page through search and read.
+type: ingredient
+area: discovery
+subarea: discovery-agents
+canonical: /ingredients/inspect-agent-bundle
+---
+
+# Check agent search and page lookup
+
+> 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 > Reusable Shoalrun steps > Check agent search and page lookup
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/inspect-build.md

@@ -0,0 +1,41 @@
+---
+id: ingredient.inspect-build
+title: Check the built page artifacts
+summary: Resolve a document ID through the manifest and check its HTML and
+  Markdown files.
+type: ingredient
+area: quality
+subarea: quality-audits
+canonical: /ingredients/inspect-build
+---
+
+# Check the built page artifacts
+
+> 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 > Reusable Shoalrun steps > Check the built page artifacts
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/preview-site.md

@@ -0,0 +1,31 @@
+---
+id: ingredient.preview-site
+title: Serve the built docs locally
+summary: Open a successful build over HTTP and compare a page with its Markdown twin.
+type: ingredient
+area: publishing
+subarea: publishing-builds
+canonical: /ingredients/preview-site
+---
+
+# Serve the built docs 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 > Reusable Shoalrun steps > Serve the built docs locally
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/refresh-agent-bundle.md

@@ -0,0 +1,29 @@
+---
+id: ingredient.refresh-agent-bundle
+title: Regenerate the agent documentation bundle
+summary: Build the offline Markdown and search index used by the CLI.
+type: ingredient
+area: discovery
+subarea: discovery-agents
+canonical: /ingredients/refresh-agent-bundle
+---
+
+# Regenerate the agent documentation bundle
+
+> 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 > Reusable Shoalrun steps > Regenerate the agent documentation bundle
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/ingredients/scaffold-page.md

@@ -0,0 +1,28 @@
+---
+id: ingredient.scaffold-page
+title: Scaffold a new guide
+summary: Create a draft guide with a stable ID without overwriting an existing file.
+type: ingredient
+area: authoring
+subarea: authoring-pages
+canonical: /ingredients/scaffold-page
+---
+
+# Scaffold a new guide
+
+> 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 > Reusable Shoalrun steps > Scaffold a new guide
+
+**Updated: 2026-10-19.**
+
+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.

package/agent-docs/non-goals.md

@@ -0,0 +1,58 @@
+---
+id: guide.non-goals
+title: Non-goals
+summary: Scope limits for skill generation, agent orchestration, and reader-view
+  authorization.
+type: explanation
+area: project
+subarea: project-overview
+canonical: /non-goals
+---
+
+# Non-goals
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project updates](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project updates](https://www.shoalrun.com/status.md) > Project > Non-goals
+
+**Updated: 2026-10-26.**
+
+Shoalrun's scope includes publishing documentation that people and agents can discover and read. This page records capabilities we deliberately exclude and the reasoning behind those decisions.
+
+## Shipping a skill builder with the tool
+
+Shoalrun does not ship a non-interactive skill builder or automatically generate a reader-side skill for each site it builds.
+
+Skills need a human expert to guide their creation and maintenance. That expert brings knowledge of the domain, decides which workflows are appropriate, tests the instructions against real tasks, and keeps them accurate as the product changes.
+
+A non-interactive builder could produce something that looks complete and give users false confidence that they have “automatic agent skills.” Generating instructions alone does not establish that those instructions are useful, reliable, or kept current. We are not yet comfortable shipping a feature that implies that confidence.
+
+Shoalrun's bundled authoring skills are maintained instructions for working with Shoalrun. Published sites receive Markdown pages and discovery files during the build. Teams that create their own skills remain responsible for expert guidance, review, evaluation, and maintenance.
+
+## General agent orchestration
+
+Shoalrun provides [authoring tools](https://www.shoalrun.com/author/agent-overview.md) for project discovery, documentation references, snapshot validation, and local review. The author's coding agent owns planning, evidence gathering, editing, its model, and execution permissions. General orchestration of arbitrary agents and tasks remains outside Shoalrun's scope.
+
+The [evaluation task format and audit hook](https://www.shoalrun.com/publish/evals.md) let teams use their own agents to run tasks and record reviewed results against a build. Shoalrun checks the report; the team owns agent execution and grading.
+
+## Using reader views for authorization
+
+[Reader views](https://www.shoalrun.com/author/reader-views.md) shape navigation and visible sections. They do not protect content: published files and Markdown twins remain available. Using a reader's selected view as an authorization boundary is outside their purpose. Exclude nonpublic pages from a public build and use host-level authorization when private content must be protected.
+
+## Related reading
+
+### Reference while working
+
+- [Bundled agent skills](https://www.shoalrun.com/reference/agent-skills.md) — See the maintained authoring skills that Shoalrun bundles.
+
+### Related topics
+
+- [Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) — Understand why agent execution remains outside Shoalrun.
+
+- [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) — See how published Markdown and discovery files help agents read a site.
+
+- [Bundled agent skills](https://www.shoalrun.com/reference/agent-skills.md) — Understand why a non-interactive skill builder is outside the tool's scope.
+
+- [Project status](https://www.shoalrun.com/status.md) — Distinguish deliberate scope limits from deferred features.

package/agent-docs/provenance.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "siteBuild": {
+    "schemaVersion": 1,
+    "configDigest": "04ccbb9494dfce115a89d2e7385f7f31ea7d4700c60ecc68df866a037995af10",
+    "buildId": "68177258b5815d788ec3e5e31995885d8f6800cb329751f710eb73e5d6baad26"
+  },
+  "packageIntegrity": "sha512-rmqYv+uNY4P/fdwJAlJNfODcRQdLxgWJpVcdT20a/7MdDRfqO3GTYR7sZxF7Dbqw+zVQhvmjPQDnUs5A60VktQ==",
+  "manifestDigest": "f570f7f8d8d54dab43681fde79d884528c41c33a710168260d08691eadeef7b0"
+}