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

package/agent-docs/author/writing-style.sections/example-audience-and-scope.md

@@ -0,0 +1,28 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Example audience and scope
+
+Write for someone trying to understand or complete a task in Shoalrun. Assume they can edit a text file; introduce framework-specific concepts before relying on them. State prerequisites when a task needs terminal, Git, API, or deployment knowledge.

package/agent-docs/author/writing-style.sections/ingredients-recipes-and-cookbooks.md

@@ -0,0 +1,36 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Ingredients, recipes, and cookbooks
+
+Use a recipe for a task that should participate in the recipe and cookbook features. A recipe can be authored directly; ingredients and a composition spec are optional. Use ingredients when multiple recipes share instructions you want to maintain once. Use a cookbook when readers need help choosing a complete path. See [how these page types fit together](https://www.shoalrun.com/author/recipes.md).
+
+For an ingredient, name what must already be available and what success makes available to the next step. When using `workflow` metadata, keep `inputs` and `outputs` consistent across the recipe and include the required `check`. State a check the reader can perform, such as “the build reports success and both output files exist,” rather than “make sure it works.” Metadata declares handoffs; it does not run commands or verify their results. Keep essential instructions in the body.
+
+For a recipe, choose the order deliberately and explain how to recover from a failed step. The published recipe must contain the complete instructions; readers should not need to assemble ingredients themselves. Review assembled drafts before publication. Do not describe passing assembly checks as proof that the procedure succeeds. [Compose and maintain recipes](https://www.shoalrun.com/author/recipe-drafts.md) explains the authoring workflow.
+
+For a cookbook, describe each choice's starting state and outcome. Use single selection for alternative or overlapping paths, such as build versus build-and-audit. Offer multiple selection only when the recipes make sense together. A chooser displays published recipes; it does not deduplicate their steps, connect dependencies, or execute them. If a combined task needs shared setup and explicit handoffs, write one complete recipe for it. [Configure a cookbook](https://www.shoalrun.com/author/cookbooks.md) explains the options.
+
+Check each ingredient's instructions and each recipe's full outcome. Inspect the cookbook's HTML choices and Markdown recipe links. Keep prerequisites, failure guidance, and success checks readable in both formats.

package/agent-docs/author/writing-style.sections/page-purpose-and-structure.md

@@ -0,0 +1,49 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Page purpose and structure
+
+Choose the page type by the reader's goal and the actual content. Keep one primary purpose per page. Split substantial conceptual discussion from a procedure and connect the pages with related reading.
+
+| Page type       | Reader goal                                    | Useful structure                                                                                                                                                                        |
+| --------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tutorial        | Learn through a guided exercise.               | Outcome, prerequisites, one reliable path with sample values, visible results, and a final check. Explain only what the exercise needs; link to deeper discussion.                      |
+| How-to          | Complete a specific task.                      | Starting state, necessary prerequisites, actions in execution order, success check, and likely failures. Put decisions before the steps they affect.                                    |
+| Reference       | Look up an exact fact.                         | When the feature applies, syntax or fields, defaults, constraints, examples, and errors. Organize facts for lookup.                                                                     |
+| Explanation     | Understand a concept or design.                | The question being explained, definitions, a concrete example, reasons and tradeoffs, and links to practical tasks.                                                                     |
+| Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
+| Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
+| Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
+| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+
+Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
+
+Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and agents** for predictable lookup. Document required values, defaults, accepted types, and constraints in Attributes; say when a component takes no attributes. Keep feature-specific examples and errors under descriptive headings. Fenced-code options and configured site features can use their own precise labels. Preserve old fragment IDs when changing a heading.
+
+Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
+
+Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
+
+These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.

package/agent-docs/author/writing-style.sections/procedures-and-examples.md

@@ -0,0 +1,32 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Procedures and examples
+
+Show the starting directory, required inputs, and expected result when a command depends on them. Say which values readers must replace. Keep commands supported by source or verified behavior; do not invent flags to make an example look complete.
+
+Give each procedure step one purpose. Put the explanation beside the action it supports. Include a check that readers can perform and describe what success looks like. Troubleshooting should identify a symptom, likely cause, and concrete next action.
+
+Examples demonstrate the feature under discussion. Use the smallest example that still shows the important behavior. Preserve required fields, defaults, constraints, and meaningful errors during a rewrite. An example copied from a different page is not evidence that it applies to this task.

package/agent-docs/author/writing-style.sections/related-reading.md

@@ -0,0 +1,32 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Related reading
+
+### Reference while working
+
+- [Design a writing guide](https://www.shoalrun.com/author/design-writing-guides.md) — Adapt editorial rules to your own readers.
+
+- [Templates](https://www.shoalrun.com/author/templates.md) — Look up page types, starter structures, and formatting checks.

package/agent-docs/author/writing-style.sections/review-a-draft.md

@@ -0,0 +1,30 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Review a draft
+
+Check purpose, organization, definitions, factual support, examples, and the success check. Compare technical details with the original source. Run the compiler and Vale, then inspect HTML and Markdown. This site's Vale configuration enables Voices, Direct, and Shoalrun; those rules catch detectable wording and structure problems. Passing them does not establish factual accuracy or usefulness.
+
+Give your agent this guide and an example appropriate to the page's purpose. Examples guide structure and tone; verify technical claims against the relevant sources.

package/agent-docs/author/writing-style.sections/reviewed-writing-examples.md

@@ -0,0 +1,39 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Reviewed writing examples
+
+These pages illustrate specific editorial choices. Copy their approach, then verify the facts for the page being written.
+
+| Example                                                                                                      | What to learn from it                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| [Getting started](https://www.shoalrun.com/start.md)                                                         | One guided exercise, explicit prerequisites, working-directory context, and observable preview results.                |
+| [Add a page](https://www.shoalrun.com/author/add-page.md)                                                    | A practical starting state, actions in order, and checks before publication.                                           |
+| [Steps reference](https://www.shoalrun.com/author/components/steps.md)                                       | Syntax beside live examples, exact attributes and defaults, and complete output behavior.                              |
+| [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md)                       | Definitions, reasons for the design, concrete discovery paths, and limits. Match its reasoning rather than its length. |
+| [Build-site ingredient](https://www.shoalrun.com/ingredients/build-site.md)                                  | Named inputs and outputs, a focused action, and an observable handoff check.                                           |
+| [Build-and-audit recipe](https://www.shoalrun.com/recipes/audit-docs.md)                                     | Complete ordered instructions with prerequisites and a final task outcome.                                             |
+| [Site workflows cookbook](https://www.shoalrun.com/cookbooks/site-workflows.md)                              | Clear choices between overlapping complete paths and links to their recipes.                                           |
+| [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) | Reader-visible behavior, precise scope, and an explicit private-prototype qualification.                               |

package/agent-docs/author/writing-style.sections/voice-and-explanations.md

@@ -0,0 +1,39 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing 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: [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) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Voice and explanations
+
+Address the reader as “you.” Use active voice and concrete verbs. Start a paragraph with its main point, then supply the reason or example needed to understand it. Keep sentences short enough to follow without breaking every thought into a separate paragraph.
+
+Name the action and its result. Replace claims such as “powerful,” “seamless,” and “easy” with behavior the reader can observe. Avoid inflated words, ceremonial introductions, repeated summaries, and invented terminology.
+
+| Before                                                            | Better                                                                                                                    | Reason                                       |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `Utilize the configuration to leverage publication capabilities.` | “Set the channel and version in the page's frontmatter.”                                                                  | Names the fields and action.                 |
+| `It is important to note that a Markdown twin is generated.`      | “The build creates a Markdown copy of each published page.”                                                               | Identifies the actor and defines the result. |
+| “Run CI to validate it.”                                          | “Run the project's automated checks. Continuous integration (CI) runs those checks when code changes.”                    | Explains the acronym and mechanism.          |
+| “Hybrid improves relevance.”                                      | “Hybrid search combines word matching and vector rankings. Whether it helps depends on the queries and ranking settings.” | Defines the term and limits the claim.       |
+
+Define an unfamiliar term at its first useful appearance, even when the glossary also defines it. Explain acronyms before using them repeatedly. Prefer one small example to a chain of new terms. Preserve exact command, field, model, and component names in code formatting.

package/agent-docs/changelog/2026-10-14-agent-readiness.md

@@ -0,0 +1,29 @@
+---
+id: change.agent-readiness
+title: Agent discovery, verified Markdown, and incremental sync
+summary: Compact discovery, content verification, and incremental fetching.
+type: changelog-entry
+area: discovery
+subarea: discovery-agents
+canonical: /changelog/2026-10-14-agent-readiness
+date: 2026-10-14
+---
+
+# Agent discovery, verified Markdown, and incremental sync
+
+> 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](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](https://www.shoalrun.com/status.md) > Changelog > Agent discovery, verified Markdown, and incremental sync
+
+**Published: 2026-10-14.**
+
+Agents can now find pages through smaller indexes, check which build they are reading, and compare saved page inventories before fetching updates.
+
+- **Smaller discovery files.** `llms.min.txt` lists page IDs, titles, summaries, and Markdown links. `search-index.min.json` adds headings without article text. Markdown 404 responses point to these compact files.
+- **Incremental sync.** Clients can check `build-info.json` for a new build, then compare `documents.sync.json` with their saved snapshot to find added, changed, and removed pages. They can fetch only the pages that need updating instead of downloading the full manifest and every page again. `shoalrun docs changes CURRENT-SNAPSHOT --since PREVIOUS-SNAPSHOT` performs the comparison locally.
+- **Verifiable responses.** Markdown responses include a fingerprint that lets clients check whether a page changed without downloading it again, plus a link to its manifest record. Focused API contracts now use their actual content digest in the URL, allowing a one-year immutable cache policy.
+- **Clearer examples.** Fictional pages carry a machine-readable `demo` flag. The refreshed agent-friendly guide puts working tabs, a disclosure, and reader choices beside the Markdown an agent receives.
+
+[Try the example and see what an agent reads](https://www.shoalrun.com/publish/agent-friendliness.md). The [output reference](https://www.shoalrun.com/publish/output.md) covers the files, digests, and sync workflow.

package/agent-docs/changelog/2026-10-15-evaluation-builds.md

@@ -0,0 +1,84 @@
+---
+id: change.evaluation-builds
+title: Agent reading and evaluation
+summary: Smaller reads, lifecycle guidance, and reproducible evaluations.
+type: changelog-entry
+area: quality
+subarea: quality-evaluations
+canonical: /changelog/2026-10-15-evaluation-builds
+date: 2026-10-15
+---
+
+# Agent reading and evaluation
+
+> 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](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](https://www.shoalrun.com/status.md) > Changelog > Agent reading and evaluation
+
+**Published: 2026-10-15.**
+
+This entry combines the October 15 changes to the private prototype. It does not announce a package release or a verified deployment.
+
+## Compare evaluation builds
+
+Evaluation reports can now identify which published files changed. New report templates include a file inventory; `eval check` lists additions, edits, and removals when the evaluated build differs from the current output.
+
+Use `shoalrun eval snapshot` to save an inventory and `shoalrun eval compare` to compare builds. The check still requires the exact evaluated output. Copying a build to another machine preserves its identity; rebuilding it may produce different bytes.
+
+The repository can also capture hosted builds with their tasks and an ungraded report template for later review. Capturing a build does not run the tasks or award a passing grade.
+
+The packaged Markdown bundle also stops carrying a whole-site build ID for assets it does not include. Its page digests and metadata remain intact.
+
+[Evaluate agent tasks against your docs](https://www.shoalrun.com/publish/evals.md) explains the workflow and its limits.
+
+## Find and read Markdown
+
+The manifest and compact search index now expose exact published Markdown byte counts and `cl100k_base` token counts. **Copy as Markdown** copies the full published twin, with an accessible status and a plain link fallback. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md) and [agent discovery](https://www.shoalrun.com/publish/agent-discovery.md).
+
+Pages now publish complete Markdown resources for top-level sections, with outlines, exact sizes, and parent/section digests. Use `docs outline` and `docs section`, or MCP `get_outline` and `get_section`, to retrieve them. Nested reader content stays together. Generated section IDs can change when headings change; see [section identity and citations](https://www.shoalrun.com/author/markdown-metadata.md).
+
+Search now returns the exact next read call and a direct Markdown URL, with a full-page fallback. Section files are limited to longer pages and must halve both bytes and tokens; short pages no longer produce redundant section files. Compact search records expose eligible section URLs without requiring the full manifest. Search now recommends a smaller section only when the author explicitly lists its heading in `standaloneSections`; otherwise the next read fetches the full page. This addresses an observed case where a matching section omitted prerequisite configuration. Declarations are author judgments, not compiler verification of completeness.
+
+CLI/MCP search now allows a stronger match missing one meaningful query term to outrank complete matches found only in body text. Complete matches with relevant titles, summaries, or headings keep their preference. Page-title matching also accepts simple final-`s` query plurals against singular titles. These changes fix an observed discovery miss without project-specific synonyms; browser search is unchanged. See [search ranking](https://www.shoalrun.com/author/search.md).
+
+For partial CLI/MCP matches, a focused subject match can now outrank a result with one extra incidental term. Only candidates within one meaningful term of the best coverage and at least two matched terms receive this ordering. Sparse matches stay below that group. This corrects an observed MCP client setup query while preserving full-page reads for setup and budget instructions.
+
+Fetch-only agents can now reach approved section resources from the small text index. The HTML discovery block opens `/llms.min.txt`, which lists full pages and author-declared standalone sections with exact sizes and explicit full-page fallbacks. Publication labels distinguish editions. No JSON parsing, CLI or MCP is needed for that reading path; the detailed index remains available.
+
+HTML metadata and Markdown page backlinks now point to the same compact index as the visible agent guidance. The full index remains available from that list. The [diagram reference](https://www.shoalrun.com/author/components/diagrams.md) also includes complete D2 and Mermaid authoring examples with intact nested code fences. These small private-prototype changes address discovery detours and missing copyable syntax observed during fetch-only evaluations.
+
+## Follow deprecation and migration guidance
+
+This private prototype update adds `subjectDeprecation` to page metadata. Authors can supply deprecation and sunset dates, a replacement document ID, and a migration guide ID for a deprecated API or feature.
+
+Readers see the same guidance in HTML, full-page Markdown, and published section resources. Fetch-only agents can follow the Markdown links directly. The document manifest also exposes the dates and resolved targets. Builds reject invalid dates and references outside the current publication.
+
+The guidance describes the documented subject. It does not remove the documentation page or emit HTTP retirement headers. Dates are author declarations, not evidence that a service has retired.
+
+See [page metadata](https://www.shoalrun.com/author/frontmatter.md) for syntax and validation rules.
+
+## Keep reading paths in section Markdown
+
+This private prototype update preserves reading guidance when an agent fetches one section of a longer page. Prerequisites and next steps from top-level, current-page `RelatedReading` views now travel with the section, including the reason to follow each link and the target's status.
+
+The added block says that the links apply to the full page. Links already in the section or its introduction are not repeated. Conditional and nested reading views stay with their original content. HTML and full-page Markdown keep their authored placement.
+
+The extra guidance counts toward exact section sizes and can make a section too large to publish separately. It does not establish that a section is self-contained or that the reader has completed its prerequisites. See [related reading](https://www.shoalrun.com/author/related-reading.md) for the rules.
+
+## Understand authored change meaning
+
+This private prototype update adds optional `change` metadata to changelog entries. Authors can distinguish editorial corrections, procedure changes, behavior changes, and breaking changes, then name the affected pages and a migration guide when available.
+
+The declaration appears in HTML, full-page Markdown, section Markdown, and the document manifest. Fetch-only agents can read it and follow the links without a tool integration.
+
+The build validates the fields and resolves public targets within the entry's publication. It does not verify the author's classification. Older entries remain visible without metadata and are unclassified. No separate change feed or deployment claim is added.
+
+See [write release notes and changelog entries](https://www.shoalrun.com/author/release-notes.md) for syntax and limits.
+
+## Check the published-output contract
+
+The [output reference](https://www.shoalrun.com/publish/output.md) now defines the existing manifest and sync contract, including optional capabilities, section identity, field meanings, and the limits of byte verification. Two repository JSON Schemas and a local check validate existing build output without rebuilding or making network requests. The check covers field shapes, document identities, manifest/sync agreement, and referenced Markdown sizes and digests. This documentation and validation update does not change the published format or enable hosted checks.
+
+The site's five-question agent self-assessment is now retained as historical example evidence instead of a routine audit requirement. Local build, link, schema, output-consistency, behavior, and browser checks remain available. New agent evaluations should address a concrete product question.

package/agent-docs/changelog/2026-10-16-navigation-layouts.md

@@ -0,0 +1,72 @@
+---
+id: change.navigation-layouts
+title: Navigation, page layouts, and browser analytics
+summary: Navigation sections, reader controls, layouts, and browser analytics.
+type: changelog-entry
+area: appearance
+subarea: appearance-layouts
+canonical: /changelog/2026-10-16-navigation-layouts
+date: 2026-10-16
+---
+
+# Navigation, page layouts, and browser analytics
+
+> 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](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](https://www.shoalrun.com/status.md) > Changelog > Navigation, page layouts, and browser analytics
+
+**Published: 2026-10-16.**
+
+This entry groups the October 16 changes to Shoalrun's private prototype and documentation. It does not announce a package release or a verified deployment.
+
+## Navigate between sections
+
+Top-level navigation groups can now become tabs, each with its own landing page and sidebar. This site uses **Docs**, **Project updates**, and **Changelog**. API documentation and recipes remain in Docs.
+
+Tabs use ordinary page links. Direct links select the correct section without a saved browser choice, and navigation works without JavaScript. On smaller screens, a Sections disclosure holds the links. Existing navigation lists continue to work without tabs.
+
+Agents receive the same structure through explicit section membership in Markdown, the document manifest, and both search indexes. Each tab has a scoped text index that links to its member pages and back to the global index. The global indexes still list every published page, including shared pages and pages omitted from navigation. The offline agent documentation bundle includes the scoped indexes.
+
+See [navigation configuration](https://www.shoalrun.com/author/navigation.md) and the [published-output contract](https://www.shoalrun.com/publish/output.md).
+
+## Give readers more room
+
+Documentation pages keep their table of contents visible at laptop widths. Readers can hide it to widen the article, including paragraphs and code examples, without moving the article's left edge. Restoring the contents restores the original width, and the browser remembers the choice across pages.
+
+The navigation uses aligned chevrons, lighter group headings, quieter selection styling, and consistent spacing. Projects can omit group page counts with `outputs.html.navigation.showCounts: false`; counts remain visible by default, and filtering works with either setting.
+
+Header spacing and title sizing are tighter. The Reef theme keeps equal padding around text and examples, and its Contents control follows the panel's inset. Wide pages retain their wider content area. The reading and navigation changes work across all four themes.
+
+## Keep entry pages focused
+
+Navigation tabs show by default on `docs` and `wide` pages and stay hidden on `landing` and `splash` pages. Page frontmatter can override that choice with `showNavigationTabs: true` or `false`. This site's splash homepage hides the tab bar.
+
+Pages led by a Hero omit the page-level Markdown action row. Markdown twins and discovery links remain available. Hiding the tab bar changes only its HTML presentation; section membership and agent indexes remain intact. See [page layouts](https://www.shoalrun.com/styling/layouts.md).
+
+## Measure browser interactions
+
+Projects can now connect browser analytics through the top-level `analytics.module` setting. Shoalrun supplies versioned events for navigation, content tabs, disclosures, clipboard successes, search outcomes, and reader selections. Events include stable page IDs and publication context. Site scripts can emit additional events through the same hook.
+
+The browser adapter owns service initialization, consent, and delivery. Analytics is off by default, and disabled builds omit its runtime and adapter. SDK failures do not interrupt the site. Browser instrumentation leaves Markdown and agent discovery unchanged; agent request measurements belong at the host or server. See [bring your own analytics](https://www.shoalrun.com/author/analytics.md).
+
+## Add contributor documentation
+
+Repository contributors now have a separate maintainer guide covering architecture, development, validation, hosting, and release work. It is separate from the public documentation and packaged agent bundle.
+
+## Related reading
+
+### Reference while working
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Configure navigation tabs, landing pages, and optional group counts.
+
+- [Publishing and agent representations](https://www.shoalrun.com/publish/output.md) — Inspect section membership and scoped text indexes for agents.
+
+- [Page layouts, landing pages, and splash pages](https://www.shoalrun.com/styling/layouts.md) — Choose a page layout and control whether its tab bar appears.
+
+- [Bring your own analytics](https://www.shoalrun.com/author/analytics.md) — Connect your analytics service to documented browser interaction events.
+
+### Related topics
+
+- [Project status](https://www.shoalrun.com/status.md) — Check the alpha's capabilities and current limits.

package/agent-docs/changelog/2026-10-17-mcp-hosting.md

@@ -0,0 +1,60 @@
+---
+id: change.mcp-hosting
+title: MCP hosting, analytics, and component improvements
+summary: MCP hosting, analytics, and shared component content.
+type: changelog-entry
+area: discovery
+subarea: discovery-mcp
+canonical: /changelog/2026-10-17-mcp-hosting
+date: 2026-10-17
+---
+
+# MCP hosting, analytics, and component improvements
+
+> 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](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](https://www.shoalrun.com/status.md) > Changelog > MCP hosting, analytics, and component improvements
+
+**Published: 2026-10-17.**
+
+This entry groups the October 17 changes to Shoalrun’s private prototype. It does not announce a package release.
+
+## Serve documentation tools over HTTP
+
+Projects can enable an MCP endpoint for one explicitly public publication. It exposes the existing read-only search, page, outline, and section tools through the Node server. The Vercel build can package an independent function without Ask, embeddings, or a model key. Read-only SDK calls have also been verified on this site’s production Vercel endpoint.
+
+The endpoint uses a scoped, byte-verified copy of published Markdown and indexes. Search works independently of browser search settings. Host and origin checks, request limits, deadlines, and publication checks apply before serving documentation. Stdio remains available.
+
+See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for configuration, limits, and when MCP helps alongside public Markdown.
+
+## Measure MCP tool calls
+
+An optional `mcp.analytics.module` server adapter receives tool outcomes, duration, build/publication identity, and published page or section IDs. Analytics is off by default. The adapter is separate from browser analytics and runs on the serving host.
+
+The PostHog example emits native MCP events and flushes before the HTTP response completes. Separate opt-ins add supported client/model labels, agent intent, and conversation grouping. Labels are unverified. Intent is limited to fixed categories; free text is replaced before delivery. Unknown model labels are omitted. The example excludes raw queries, complete arguments, results, headers, and exception bodies from outbound events. GeoIP enrichment and person profiles are disabled; session grouping remains pseudonymous.
+
+See [measure MCP tool usage](https://www.shoalrun.com/publish/mcp-analytics.md) for the adapter contract, privacy limits, and setup steps. Other services can use the same server adapter interface.
+
+## Render Mermaid syntax with Pele
+
+[Pele](https://pele.run/) replaces Mermaid CLI for Mermaid-syntax diagrams. Diagram builds no longer launch Chrome, and production package installs no longer include Puppeteer. Browser development tests still use it.
+
+Inline diagrams follow the site’s palette and color mode, support per-diagram width caps, and retain source and summaries in Markdown. Use native Pele CSS variables to override the default theme mapping. The [Pele gallery](https://www.shoalrun.com/author/components/diagrams/pele-gallery.md) shows the built-in families and 48 flowchart shapes. The [D2 gallery](https://www.shoalrun.com/author/components/diagrams/d2-gallery.md) adds 17 examples covering shapes, containers, sequence diagrams, tables, classes, and layout engines. Both galleries include source examples you can copy.
+
+## More interactive documentation components
+
+[File trees](https://www.shoalrun.com/author/components/file-tree.md) now have expandable folders, keyboard navigation, and optional expand-all controls. [Collapsible groups](https://www.shoalrun.com/author/components/collapsible.md) keep related disclosures in one compact stack while allowing multiple items to stay open.
+
+[Tabs](https://www.shoalrun.com/author/components/tabs.md) can synchronize matching choices across related examples on a page. [Images](https://www.shoalrun.com/author/components/images.md) support captions and an optional expanded viewer; width is optional. The viewer supports keyboard dismissal and returns focus to the image link.
+
+Markdown retains all tree nodes, disclosure bodies, tab alternatives, image descriptions, and captions. Native disclosures and original-image links remain useful without JavaScript.
+
+## Build custom components
+
+Projects can register [trusted custom components](https://www.shoalrun.com/author/components/custom.md) from local files or installed packages through one component manifest. Each component implements a required `content()` function using shared content helpers. Shoalrun renders that content as HTML and Markdown, including links, search content, and section resources. Attribute and child validation report authoring errors during the build.
+
+Optional browser modules add interactive controls, including React, with explicit data from the same content function. Shoalrun bundles imports and JSX, publishes browser assets, and tracks dependencies for rebuilds and isolated authoring validation. Shared documentation remains readable without JavaScript. Configured component code is trusted; arbitrary MDX imports and React page rendering remain outside this API.
+
+The bundled `shoalrun-component-author` skill guides agents through the component contract, implementation, and focused validation.

package/agent-docs/changelog/2026-10-18-search-and-tooltips.md

@@ -0,0 +1,46 @@
+---
+id: change.search-and-tooltips
+title: Search results and tooltips
+summary: Indexed search and hover and focus tooltips.
+type: changelog-entry
+area: discovery
+subarea: discovery-search
+canonical: /changelog/2026-10-18-search-and-tooltips
+date: 2026-10-18
+---
+
+# Search results and tooltips
+
+> 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](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](https://www.shoalrun.com/status.md) > Changelog > Search results and tooltips
+
+**Published: 2026-10-18.**
+
+These October 18 changes improve search and supporting explanations in Shoalrun’s private prototype. This entry does not announce a package release.
+
+## Find useful search results
+
+Search results now select substantive passages instead of generated related-reading lists or source-only fragments. An exact page-title query opens that page’s introduction. Large galleries no longer crowd other pages out of the search candidates.
+
+Explicit identifiers and commands remain searchable in code and tables. Matching pages keep their retrieved order. They open the passage containing the exact match, and the result description shows its code line or table row.
+
+The [passage index](https://www.shoalrun.com/chat/passage-index.md) prepares result paragraphs, code lines, and table rows during indexing. Search requests no longer parse the Markdown passages to prepare these results.
+
+Preparing this data does not change the embedding input, so unchanged passages reuse their existing vectors.
+
+Queries such as “charts” and “graphs” lead to chart and diagram examples with readable descriptions. Searching “diagrams” opens the [Diagrams guide](https://www.shoalrun.com/author/components/diagrams.md). Semantic search retains its keyword fallback when embeddings are unavailable; Ask passage retrieval is unchanged.
+
+## Distinguish short definitions from tooltips
+
+The former Tooltips reference is now [Short definitions](https://www.shoalrun.com/author/components/info-hint.md). `<InfoHint>` keeps its native click-to-expand disclosure, including keyboard and touch support without JavaScript.
+
+`<Tooltip>` previously named the same disclosure. If you used it for click-to-expand definitions, replace it with `<InfoHint>` to retain that behavior.
+
+## Show supporting text on hover or focus
+
+The separate [Tooltip component](https://www.shoalrun.com/author/components/tooltips.md) now shows brief supporting text when readers hover over or focus its label. It works inline or as a standalone block. Readers can move the pointer onto the popup, dismiss it with Escape, or tap the label to open and close it on touch screens.
+
+Without JavaScript, the label and explanation remain visible together. Markdown includes the full label and explanation, so agents can read both without interaction. Keep essential warnings and instructions in visible page content.