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

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: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.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: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.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: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.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: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.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.

package/agent-docs/changelog/2026-10-19-visual-navigation.md

@@ -0,0 +1,44 @@
+---
+id: change.visual-navigation
+title: Experimental visual navigation and taxonomy enforcement
+summary: Visual navigation and taxonomy validation.
+type: changelog-entry
+area: discovery
+subarea: discovery-search
+canonical: /changelog/2026-10-19-visual-navigation
+date: 2026-10-19
+---
+
+# Experimental visual navigation and taxonomy enforcement
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Experimental visual navigation and taxonomy enforcement
+
+**Published: 2026-10-19.**
+
+These October 19 changes cover the documentation site's experimental explorer and taxonomy enforcement in CLI `0.1.0-alpha.3`. This entry does not announce a package release or a verified deployment.
+
+## Explore documentation visually
+
+The site's [experimental explorer](https://www.shoalrun.com/explore.md) provides five ways to navigate the same documentation: packed circles, expandable branches, connection arcs, a relationship matrix, and a force layout. Filter by declared area, subarea, page type, relationship, or configured reader facets. Demo pages are excluded from the explorer.
+
+Views support zoom and pan, with native browser fullscreen where supported. Fullscreen keeps layout controls visible and makes filters and the relationship key available in expandable panels. The matrix distinguishes source rows from destination columns and offers readable sizing alongside the full overview.
+
+Relationship arrows show direction. Related topics and comparisons apply in both directions. Line patterns, matrix symbols, labels, and a monochrome option supplement color. The sidebar identifies incoming, outgoing, and two-way relationships, their page endpoints, and why they are connected.
+
+Those explanations come from authored `reason` fields in the relationship configuration. The build publishes them in `documents.json`; the explorer makes no model calls and infers no new connections. [Related reading](https://www.shoalrun.com/author/related-reading.md) documents the authoring and validation rules.
+
+The Markdown twin retains the explorer guide and topic links. Agents can read the full page catalog and declared relationships directly from the document manifest. The visualization remains experimental; further sizing, density, interaction, and accessibility improvements are planned.
+
+## Classify pages explicitly
+
+This site's pages now declare areas and subareas rather than deriving subjects from navigation groups. MCP pages belong to Search & discovery. Breadcrumbs belongs to built-in site navigation, while API example and schema components belong to Content components.
+
+CLI `0.1.0-alpha.3` adds configurable [taxonomy enforcement](https://www.shoalrun.com/author/taxonomy.md) to the build, including allowed definitions, required fields, explicit authored values, and valid area/subarea pairs. Sites can choose whether to allow multiple areas or subareas on a page; the default permits a single value. These built-in options require CLI `0.1.0-alpha.3` or later. This site enables enforcement through `frontmatter.taxonomy`.
+
+## Continue improving the explorer
+
+The [project update](https://www.shoalrun.com/status.md) tracks further work on layout sizing, dense views, filtering, relationship presentation, and accessibility.

package/agent-docs/changelog/2026-10-25.md

@@ -0,0 +1,45 @@
+---
+id: change.2026-10-25
+title: Content exports and documentation checks
+summary: Content exports and documentation checks.
+type: changelog-entry
+area: project
+subarea: project-releases
+canonical: /changelog/2026-10-25
+date: 2026-10-25
+releaseVersion: 0.1.0-alpha.6
+---
+
+# Content exports and documentation checks
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Content exports and documentation checks
+
+**Published: 2026-10-25.**
+
+**Version: 0.1.0-alpha.6.**
+
+These October 25 changes group content exports in CLI `0.1.0-alpha.6` and optional documentation checks in our docs project.
+
+## Reuse documentation inside an application
+
+The [content export command](https://www.shoalrun.com/publish/content-export.md) builds shared pages into Markdown, static HTML fragments, assets, and a manifest. Applications can use those files in help drawers, onboarding screens, or other interfaces without loading Shoalrun in the browser.
+
+Named export targets select a publication and eligible pages independently of the website's navigation. Facet selection is optional. Reader-specific sections remain visible with labels; tabs and walkthroughs retain every panel and step. Document links identify their destinations for application routing, with eligible website links used for pages outside the bundle.
+
+Exports retain referenced local assets, notices, and API review requirements. A plain JavaScript help-drawer example demonstrates loading the bundle from an unrelated application route. Its `/help/` URL is an example; the configured path must match where the application serves the files.
+
+## Check documentation with Manni
+
+The [Manni integration](https://www.shoalrun.com/publish/manni.md) provides access to the project's installed Manni tools through a small launcher and existing Shoalrun audit hooks. Manni remains an optional project dependency; its configuration and built-in tools stay with Manni.
+
+Our documentation project uses glossary references and structure rules for selected guides. A procedure test runs the quickstart's initialization, scaffolding, and build instructions in a disposable project, then verifies HTML, Markdown, navigation, and links. A separate accessibility check uses the built document list to inspect every published HTML page, including pages outside navigation.
+
+A source citation connects one metadata explanation to its framework implementation and flags changes for review. This check needs a source checkout and runs separately from ordinary builds and isolated validation.
+
+## Planned work
+
+[Project status](https://www.shoalrun.com/status.md) also records optional vector-store connections as planned work. They are not required for content exports or the existing file-based retrieval path.

package/agent-docs/changelog/2026-10-26.md

@@ -0,0 +1,66 @@
+---
+id: change.2026-10-26
+title: Safer exports and easier discovery for AI assistants
+summary: Keep exported images and links with their pages, and help AI assistants
+  find docs by topic.
+type: changelog-entry
+area:
+  - project
+  - discovery
+subarea:
+  - project-releases
+  - discovery-agents
+canonical: /changelog/2026-10-26
+date: 2026-10-26
+releaseVersion: 0.1.0-alpha.7 and 0.1.0-alpha.8
+---
+
+# Safer exports and easier discovery for AI assistants
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Safer exports and easier discovery for AI assistants
+
+**Published: 2026-10-26.**
+
+**Version: 0.1.0-alpha.7 and 0.1.0-alpha.8.**
+
+Today's two private-alpha releases make documentation safer to reuse and easier for AI assistants to find. **Alpha.7 keeps exported images and links attached to the right document. Alpha.8 lets assistants choose a topic before reading a directory of every page.**
+
+Both versions are published in the private package registry. Upgrade to CLI `0.1.0-alpha.8` and rebuild your site to receive both sets of changes.
+
+## Find documentation by topic
+
+Previously, the starting directory listed every published page. Each new page made that directory longer, so an assistant had to read more text before choosing what to open.
+
+Now, larger sites link to smaller topic directories. An assistant looking for deployment instructions can choose **Publishing**, then open the relevant page. Topic names come from your project's categories, or page types when categories are absent. If a directory grows too large, Shoalrun divides it again. Small sites can still list their pages directly.
+
+Every published page remains reachable, including pages outside the website's navigation. On Shoalrun's own site, the starting directory shrank from roughly 6,000 tokens to 400. Tokens are the pieces of text an AI model reads. Larger sites may require more directory steps, but each step stays small.
+
+Assistants still start at `/llms.min.txt`. If you maintain a script that reads this file, update it to follow topic-directory links instead of expecting every page in the first response. The complete catalog remains at `/llms.txt`. Independently readable sections retain their sizes and links to the full page.
+
+## Keep exported images and links with their pages
+
+Two documents can share a website route while needing different images or links in an exported bundle. Alpha.7 keeps each document's own assets and link destinations in exported HTML and Markdown. This also covers cards, related reading, cookbook choices, deprecation notices, and changelog notices.
+
+The [help-drawer example](https://www.shoalrun.com/publish/content-export.md) now moves keyboard focus into opened content and follows links to specific headings. Closing the drawer with Escape returns focus to its launcher.
+
+## Check your output destination
+
+Use a real directory as the build or export destination. A destination that is itself a symbolic link is now rejected; symbolic links in its parent directories remain supported.
+
+Shoalrun also rejects paths that escape the output directory, empty path segments, unsafe export mount paths, and duplicate output aliases before writing. Different paths to the same parent directory share one output lock, preventing competing builds from writing there at the same time. The export manifest remains at schema version 1.
+
+## Technical details and validation
+
+Compact directories have a 2,000-token limit, measured with `cl100k_base`. This limits each response, not the total reading needed for a question. A title or summary that cannot fit in one entry still needs shortening. Tests cover 160 to 1,600 pages, large topics, hundreds of topics, and reachability of every published page and declared standalone section.
+
+The MCP server and client packages move to version `2.3.0`. Zod moves to `4.6.6`, and KaTeX to `0.18.2`. MCP tool arguments are limited to 1,024 elements before schema validation. HTTP requests retain the 64 KiB body limit and a separate server instance for each request.
+
+These updates address advisories for [MCP connection isolation](https://github.com/advisories/GHSA-jm63-cq47-j5jp), [MCP input validation](https://github.com/advisories/GHSA-46jr-4wx8-v453), [MCP bearer-token audience checks](https://github.com/advisories/GHSA-rvq5-wwqv-78pq), [Zod collection validation](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5), and [KaTeX inherited settings](https://github.com/advisories/GHSA-238p-pmpm-9mq7).
+
+Alpha.7 validation passed 723 framework tests, all five packaged skill checks, and clean installations of the minimal and API-documentation starters. Its dependency audit reported no vulnerabilities at validation time. Package checks also inspect the file inventory and exercise the installed help drawer in a browser. Test runs limit concurrency to four files, rebuild tests wait for complete server events, and skill validation reports missing Python prerequisites with setup instructions.
+
+This remains an alpha release. Publishing the CLI does not automatically upgrade or deploy an existing site. See [Agent-friendly documentation](https://www.shoalrun.com/publish/agent-friendliness.md) for the reading workflow and [portable content exports](https://www.shoalrun.com/publish/content-export.md) for reuse in another application.

package/agent-docs/changelog/2026-10-27.md

@@ -0,0 +1,85 @@
+---
+id: change.2026-10-27
+title: Clearer defaults, a feature showcase, and easier navigation
+summary: Explore a complete starter, read clearer controls, and find focused
+  configuration references alongside the new mobile navigation.
+type: changelog-entry
+area:
+  - appearance
+  - authoring
+  - publishing
+  - project
+subarea:
+  - appearance-navigation
+  - authoring-pages
+  - publishing-configuration
+  - project-releases
+canonical: /changelog/2026-10-27
+date: 2026-10-27
+releaseVersion: 0.1.0-alpha.11
+---
+
+# Clearer defaults, a feature showcase, and easier 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: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Clearer defaults, a feature showcase, and easier navigation
+
+**Published: 2026-10-27.**
+
+**Version: 0.1.0-alpha.11.**
+
+The October 27 releases improve reading and navigation, add a complete feature-showcase starter, and give agents page types and sizes before they fetch content. The documentation site also gets a refreshed logo and smaller configuration references.
+
+Upgrade to CLI `0.1.0-alpha.11` and rebuild your site to receive the framework changes from alpha.9 and alpha.10. Existing navigation configuration continues to work. The logo and reorganized reference are updates to this documentation site.
+
+## Install from public npm
+
+Alpha.11 moves the CLI to the public npm registry. Installation no longer needs an invitation, GitHub package access, or a package token. Follow [Getting started](https://www.shoalrun.com/start.md) for an exact-version install. If you used the earlier private alpha, remove or replace the old `@shoalrun` registry override and update the manifest and lockfile together.
+
+The package README now leads with the showcase. Starter instructions explain how to replace the fictional API and its connected operation bindings. Alpha.11 keeps the site configuration and output contracts from alpha.10.
+
+## Explore a complete starter
+
+Alpha.10 adds a fictional Cedar Parcel handbook with 18 pages. It includes component examples, code walkthroughs, Mermaid and D2 diagrams, reader views, a landing page, a local-workflow cookbook, and generated API references. **Explore the starter** is the first page in its navigation and maps the working examples.
+
+```sh
+shoalrun init my-handbook --starter showcase
+cd my-handbook
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist
+```
+
+The starter builds without provider credentials. Hosted chat, analytics, and remote services need your own configuration. The `minimal` and `api-docs` starters remain available. See [example projects](https://www.shoalrun.com/config/examples.md).
+
+## Read controls and prose comfortably
+
+Alpha.10 increases small reader, code, and API control labels. Ordinary lists use the same reading measure as paragraphs, while tables, code, and file trees retain their available width. Mobile header tools share a row when space permits, and search results fit within the header width.
+
+## Choose a page before fetching it
+
+Compact discovery and navigation indexes now include each page's content type and full-page token count. An agent can compare a short how-to with a longer reference before opening either. The existing 2,000-token limit per compact index still applies; larger catalogs split into linked topic indexes without losing pages.
+
+## Find configuration settings by topic
+
+The [configuration reference](https://www.shoalrun.com/config.md) is now an overview linking to six focused references. The former combined page was about 11,454 tokens; each focused reference is about 1,300–2,600 tokens in the reviewed build. Existing section bookmarks remain available on the overview and link to the new destinations.
+
+The site also has a refreshed logo and favicon. The header mark follows the selected theme, with a text fallback in forced-color mode.
+
+## Keep your place on a phone
+
+Alpha.9 brought section links and page navigation into one mobile **Menu**. Previously, section choices, the page menu, and the outline competed for space above the article. On smaller screens, **Menu** now opens a drawer containing section choices and the current section's pages. You can filter the page list, follow a link, or close the drawer to resume reading.
+
+**On this page** stays with the article as a compact disclosure below its introduction. Choosing a heading closes the disclosure and moves focus to that heading. Pages without an outline omit the control.
+
+## Reach the article sooner
+
+The HTML now places the article before the full site navigation. Readers and tools that process HTML in document order can reach the page content without first passing through the entire menu. Desktop styling still places navigation on the left and the outline on the right.
+
+Keyboard skip links appear when focused without moving the page layout. The mobile drawer keeps focus inside while open; Escape closes it and returns focus to its launcher. If the navigation filter contains text, the first Escape clears the filter and the next closes the drawer. Resizing preserves access to the focused control.
+
+Without JavaScript, Menu remains a link to the navigation below the article, and native disclosures remain usable. Markdown pages and documentation indexes remain available.
+
+See [navigation configuration](https://www.shoalrun.com/author/navigation.md) for section and sidebar settings.

package/agent-docs/changelog/authoring-preview.md

@@ -0,0 +1,40 @@
+---
+id: change.authoring-preview
+title: Authoring snapshot previews and review reports
+summary: Snapshot previews with coverage and freshness reports.
+type: changelog-entry
+area: authoring
+subarea: authoring-agent-workflows
+canonical: /changelog/authoring-preview
+date: 2026-10-13
+---
+
+# Authoring snapshot previews and review reports
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Authoring snapshot previews and review reports
+
+**Published: 2026-10-13.**
+
+This change concerns the private prototype; no package release or deployment is claimed.
+
+`docs review REPORT` presents a validated snapshot as JSON or Markdown. It identifies the task baseline, changed files and dependencies, findings, check coverage, and affected HTML/Markdown artifacts. Baselines contain digests rather than earlier contents; retain the task diff with your existing harness.
+
+`docs preview REPORT` serves a private copy of that exact build on a loopback address. It returns a browser review URL and routes for every affected page that rendered. HTML pages display freshness and a review link. Source edits make the preview stale rather than replacing its content; validate again and restart from the new report. Changed artifacts prevent startup or serving.
+
+Ctrl-C or SIGTERM closes the foreground server and removes its serving copy. Validation artifacts remain available separately. Failed or skipped checks retain their actual status while previewing. The tools make no authoring provider calls and do not apply edits, commit, or publish.
+
+Snapshot builds preserve captured freshness history. Configured checks can declare sibling files and directories with `audit.tests[].inputs`; validation captures those inputs and tracks their changes. Compiler checks do not replace factual or editorial review.
+
+## Related reading
+
+### Next steps
+
+- [Check working-tree documentation edits](https://www.shoalrun.com/author/workspace.md) — Validate working-tree edits and open the matching snapshot review. (Status: experimental.)
+
+### Reference while working
+
+- [Authoring tools commands](https://www.shoalrun.com/author/workspace/commands.md) — Look up review formats, preview lifecycle, statuses, and limits. (Status: experimental.)

package/agent-docs/changelog/authoring-search.md

@@ -0,0 +1,39 @@
+---
+id: change.authoring-search
+title: Agent authoring, search, and documentation answers
+summary: Reviewed agent drafts, search improvements, and answer context.
+type: changelog-entry
+area: authoring
+subarea: authoring-agent-workflows
+canonical: /changelog/authoring-search
+date: 2026-10-03
+---
+
+# Agent authoring, search, and documentation answers
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Changelog](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt) (ID: changelog-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Changelog](https://www.shoalrun.com/changelog.md) > Changelog > Agent authoring, search, and documentation answers
+
+**Published: 2026-10-03.**
+
+Prepared for the next prototype release:
+
+- **Agent authoring:** Skills, templates, project directives, source context, and checked edit plans help your existing agent draft and update documentation.
+- **Writing guidance:** Design templates and project writing guides, with a complete example to adapt.
+- **Search:** Semantic ranking, exact-key assistance, and clearer snippets. Word matching provides fallback results when embeddings fail or exceed the three-second deadline.
+- **Ask:** Follow-ups keep their topic, and explicit multi-part questions get evidence for each part. Citation and claim checks remain; multi-topic answers are experimental.
+
+## Related reading
+
+### Next steps
+
+- [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md) — Prepare and review a page update with your own model key. (Status: experimental.)
+
+### Related topics
+
+- [Site search](https://www.shoalrun.com/author/search.md) — Configure semantic search and lexical fallback.
+
+- [Check and speed up answers](https://www.shoalrun.com/chat/checks.md) — Understand documentation answer checks and their limits. (Status: experimental.)