# Shoalrun documentation framework

Fetch a matching full Markdown page by default. Use a listed standalone section only for its stated topic; for setup, broader questions, or missing context, follow Full page. Standalone is an author declaration, not proof of completeness.

Publication (channel/version/language): production/current/en.

[Full documentation index](/llms.txt). Full manifests and search indexes are optional. A missing match does not establish that a feature exists or does not exist.

## Navigation sections

- [Docs (production/current/en)](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt): Section ID: docs. Scoped page index; all pages remain listed below.

- [Project updates (production/current/en)](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt): Section ID: project-updates. Scoped page index; all pages remain listed below.

- [Changelog (production/current/en)](https://www.shoalrun.com/.well-known/shoalrun/navigation/changelog-tab-50f26fe22670.txt): Section ID: changelog-tab. Scoped page index; all pages remain listed below.

- [guide.home · Shoalrun](/index.md): A preview of Shoalrun, a flexible framework for API and product docs with fine-grained controls for what people see and what agents can discover and read.

- [guide.about · About Shoalrun](/about.md): Learn what Shoalrun is exploring and where the private prototype stands.

- [guide.focused-contracts · Focused OpenAPI contracts](/api-docs/focused-contracts.md): Give tools one operation and its required schemas without the rest of the API source.

- [guide.api-generation · Generate and select API pages](/api-docs/generate.md): Choose operations, generate reference pages, and add editorial context to an API reference.

- [guide.openapi-support · OpenAPI support and limits](/api-docs/support.md): Check supported OpenAPI operations, schema keywords, examples, and source restrictions before importing a specification.

- [guide.add-page · Create a page](/author/add-page.md): Create a page from a template, complete its scaffolded draft, and publish it in navigation.

- [guide.authoring-agent-overview · Authoring tools for your coding agent](/author/agent-overview.md): Understand project discovery, working-tree editing, snapshot validation, and human review.

- [guide.authoring-agent-workflow · How snapshot validation works](/author/agent-workflow.md): Understand captured files, affected-page coverage, freshness, and validation limits.

- [guide.write-with-agents · Write with agents](/author/agents.md): Use your existing coding agent with project guidance, templates, and provider-free documentation tools.

- [guide.analytics · Bring your own analytics](/author/analytics.md): Send documentation interaction events to your analytics service through an optional browser adapter.

- [guide.authoring-agent · Apply a checked edit plan](/author/authoring-agent.md): Find a page's sources, review an edit, and apply it through Shoalrun checks.

- [guide.coding-agent-authoring · Use your coding agent](/author/coding-agent.md): Give your agent project guidance and draft a new documentation page.

- [guide.components · Component reference](/author/components.md): Find a dedicated guide for every supported MDX component and code block.

- [guide.component.action-link · Action links](/author/components/action-link.md): Give a next step a prominent link style while retaining real navigation semantics.

- [guide.component.api-embeds · ApiExample and ApiSchema](/author/components/api-embeds.md): Include named OpenAPI examples and selected schemas in authored pages.

- [guide.component.badge · Badges](/author/components/badge.md): Put a short, labeled status or platform name inside a sentence.

- [guide.component.breadcrumbs · Breadcrumbs](/author/components/breadcrumbs.md): Show where a page sits in the configured navigation hierarchy.

- [guide.component.callout · Callouts](/author/components/callout.md): Use built-in callouts or register a type with its own label, tone, and icon.

- [guide.cards · Cards and collections](/author/components/cards.md): Link to documents by stable ID and build filtered card collections.

- [guide.component.code-blocks · Code blocks](/author/components/code-blocks.md): Write fenced examples and configure Shiki or another highlighter.

- [guide.component.collapsible · Collapsibles](/author/components/collapsible.md): Show optional detail in individual disclosures or compact groups, with full Markdown output.

- [guide.component.cookbook-chooser · CookbookChooser](/author/components/cookbook-chooser.md): Let readers select reviewed recipes and assemble them into one reading path.

- [guide.custom-components · Custom components](/author/components/custom.md): Register trusted component plugins with shared HTML and Markdown content.

- [guide.custom-components.react · Data-driven React components](/author/components/custom/react.md): Follow local data through a component plugin, shared documentation, and a React calculator.

- [guide.component.definition-list · Definition lists](/author/components/definition-list.md): Pair terms with full explanations in semantic HTML and readable Markdown.

- [guide.component.diagrams · Diagrams](/author/components/diagrams.md): Render flowcharts, sequence diagrams, charts, and graphs from D2 or Mermaid source as static SVG.

- [reference.d2-gallery · D2 gallery](/author/components/diagrams/d2-gallery.md): Browse D2 diagrams, layout engines, and basic shapes with copyable source.

- [reference.pele-gallery · Pele gallery](/author/components/diagrams/pele-gallery.md): Browse Mermaid-syntax diagrams and flowchart shapes rendered with Pele.

- [guide.component.doc-link · DocLink](/author/components/doc-link.md): Link to a page by stable document ID.

- [guide.component.fields · Fields](/author/components/fields.md): Write field lists in MDX with the same readable format as OpenAPI schemas.

- [guide.component.file-tree · File trees](/author/components/file-tree.md): Show nested files and folders with links and an indented Markdown equivalent.

- [guide.component.images · Images](/author/components/images.md): Add responsive images with optional width limits, captions, and expanded viewing.

- [guide.component.info-hint · Short definitions](/author/components/info-hint.md): Let readers open a brief definition with a click, tap, or keyboard.

- [guide.component.kbd · Keyboard shortcuts](/author/components/kbd.md): Mark up key names and shortcuts inside documentation text.

- [guide.component.math · Math](/author/components/math.md): Render inline and display LaTeX expressions at build time.

- [guide.component.only · Content for one format](/author/components/only.md): Use Only to add content to the HTML page or its Markdown twin alone.

- [guide.component.progress · Progress](/author/components/progress.md): Show a bounded count with a visible label and native progress bar.

- [guide.component.related-reading · RelatedReading](/author/components/related-reading.md): Display authored relationships as links or cards.

- [guide.component.steps · Steps](/author/components/steps.md): Show a short procedure as numbered steps with full instructions in both outputs.

- [guide.component.table · Tables](/author/components/tables.md): Add optional filtering and sticky headings to long HTML tables while preserving every row in Markdown.

- [guide.component.tabs · Tabs](/author/components/tabs.md): Group alternate views while retaining every view in Markdown.

- [guide.component.timeline · Timelines](/author/components/timeline.md): Show the current milestone and overall progress through a process.

- [guide.component.tooltip · Tooltips](/author/components/tooltips.md): Show brief supporting text on hover or keyboard focus, with a tap option for touch readers.

- [guide.component.walkthrough · Walkthroughs](/author/components/walkthroughs.md): Build code tutorials that explain code one step at a time, with a scrolling pane in HTML and every step in Markdown.

- [guide.content-identity · Content and stable IDs](/author/content.md): Give each page a durable identity and publish explicit variants.

- [guide.cookbooks · Let readers choose recipes with a cookbook](/author/cookbooks.md): Create a page that helps readers choose among complete published recipes.

- [guide.css · CSS and theme reference](/author/css.md): Customize colors, typography, layout, navigation, code, and component styles with one project stylesheet.

- [guide.custom-metadata · Metadata customization](/author/custom-metadata.md): Defaults, enforcement, custom field declarations, text selection, and provider contracts.

- [guide.design-templates · Design templates](/author/design-templates.md): Make repeatable page structures that help authors and agents serve readers.

- [guide.design-writing-guides · Design a writing guide](/author/design-writing-guides.md): Give authors and agents clear editorial rules, examples, and review expectations.

- [guide.frontmatter · Page metadata](/author/frontmatter.md): Set page identity, publication, and presentation fields before publishing.

- [guide.frontmatter-reference · Frontmatter field reference](/author/frontmatter-reference.md): Browse the built-in and project-defined page fields this site supports.

- [guide.markdown-metadata · Markdown metadata](/author/markdown-metadata.md): Public field projection, source paths, profiles, precedence, and required values.

- [guide.navigation-lifecycle · Organize site navigation](/author/navigation.md): Arrange guides, reference pages, and other documents into a clear site menu.

- [guide.reader-filters · Reader views](/author/reader-views.md): Reader-view configuration, page and section marks, controls, and agent-facing behavior.

- [guide.recipe-drafts · Compose and maintain recipes](/author/recipe-drafts.md): Use Shoalrun ingredient files and a recipe spec to produce a complete, reviewable task page.

- [guide.recipes-overview · Understand ingredients, recipes, and cookbooks](/author/recipes.md): See how reusable source instructions become complete recipe pages that a cookbook helps readers choose.

- [guide.related-reading · Related reading](/author/related-reading.md): Relationship fields, purposes, ordering, validation, and rendered reading paths.

- [guide.release-notes · Write release notes and changelog entries](/author/release-notes.md): Write flexible release summaries and changelog entries identified by date or version.

- [guide.search · Site search](/author/search.md): Search settings, keyboard behavior, provider interfaces, and index fields.
  - Standalone section: [Write a custom provider](/author/search.sections/write-a-custom-provider.md) — 1050 tokens (cl100k_base), 5285 UTF-8 bytes. [Full page](/author/search.md).

  - Standalone section: [Turn search off](/author/search.sections/turn-search-off.md) — 506 tokens (cl100k_base), 2125 UTF-8 bytes. [Full page](/author/search.md).

- [guide.snippets · Reuse prose across pages](/author/snippets.md): Share validated prose across pages with typed variables.

- [guide.page-taxonomy · Design and enforce a page taxonomy](/author/taxonomy.md): Define page categories, validate allowed values, and enforce your project's area and subarea rules.

- [guide.templates · Templates](/author/templates.md): Create and edit page starting points, then scaffold drafts from them.

- [guide.authoring-workspace · Check working-tree documentation edits](/author/workspace.md): Discover a project, capture a baseline, edit files, and validate an isolated copy.

- [reference.authoring-workspace · Authoring tools commands](/author/workspace/commands.md): Look up provider-free project discovery, reference reads, baselines, and snapshot validation.

- [reference.writing-style · Example writing guide](/author/writing-style.md): Adapt this site's writing guide for your own documentation and agent instructions.

- [reference.changelog · Changelog](/changelog.md): Notable changes to Shoalrun's compiler, CLI, and reader experience.

- [change.agent-readiness · Agent discovery, verified Markdown, and incremental sync](/changelog/2026-10-14-agent-readiness.md): Find the right page with less context, verify its contents, and fetch only what changed.

- [change.evaluation-builds · Agent reading and evaluation](/changelog/2026-10-15-evaluation-builds.md): Smaller Markdown reads, clearer lifecycle and change guidance, and exact-output evaluation comparisons.

- [change.navigation-layouts · Navigation, page layouts, and browser analytics](/changelog/2026-10-16-navigation-layouts.md): Navigation sections, reader controls, page layouts, and optional browser interaction analytics.

- [change.mcp-hosting · MCP hosting, analytics, and component improvements](/changelog/2026-10-17-mcp-hosting.md): Serve documentation tools, measure MCP calls, and build custom components with shared HTML and Markdown content.

- [change.search-and-tooltips · Search results and tooltips](/changelog/2026-10-18-search-and-tooltips.md): Improve search results with a prepared index and add separate hover and focus tooltips.

- [change.visual-navigation · Experimental visual navigation and taxonomy enforcement](/changelog/2026-10-19-visual-navigation.md): Visual navigation and taxonomy validation.

- [change.authoring-preview · Authoring snapshot previews and review reports](/changelog/authoring-preview.md): Review affected pages, findings, coverage, and freshness beside an exact snapshot preview.

- [change.authoring-search · Agent authoring, search, and documentation answers](/changelog/authoring-search.md): Reviewed agent drafts, improved search results, and better context for documentation answers.

- [change.authoring-tools · Working-tree authoring tools](/changelog/authoring-tools.md): Discover project context and validate working-tree edits in a separate capture.

- [change.working-tree-skill · Portable working-tree authoring workflow](/changelog/working-tree-skill.md): Guide existing coding agents through discovery, native editing, validation, and snapshot review.

- [guide.retrieval-chat · How documentation answers work](/chat.md): Understand how passages, embeddings, scoring, and a chat model produce cited answers.

- [guide.chat-checks · Check and speed up answers](/chat/checks.md): Understand answer checks, direct excerpts, caching, and the limits of each.

- [guide.host-chat · Host and limit documentation chat](/chat/host.md): Deploy chat on Vercel with shared usage limits, a visitor challenge, optional logs, and an off switch.

- [guide.passage-index · Passage index](/chat/passage-index.md): Passage file formats, chunking rules, identifiers, embedding behavior, and limits.

- [guide.prepared-answers · Generate and refresh answer cards](/chat/prepared-answers.md): Generate and review common answers ahead of time, then serve confirmed cards without a new chat-model answer.

- [reference.chat-config · Retrieval and chat settings](/chat/settings.md): Look up embedding, chat-model, scoring, and answer-reuse configuration.

- [guide.set-up-chat · Set up local documentation chat](/chat/setup.md): Build a passage index, configure a chat service, and verify cited answers locally.

- [reference.cli · CLI reference](/cli.md): Every shoalrun command, its arguments and defaults, what it prints, and when it fails.

- [guide.concepts · How Shoalrun works](/concepts.md): Follow a page from source file to published HTML and Markdown, and learn the terms the rest of these docs use.

- [reference.config · Configuration reference](/config.md): Every top-level setting in docs.config.yaml, with defaults, validation rules, and links to the full guides.

- [reference.config-examples · Example configs](/config/examples.md): Complete, working docs.config.yaml files for common kinds of documentation sites.

- [guide.configuration · Organize project configuration](/configuration.md): Learn how Shoalrun resolves config files, layers presets, tracks path origins, and applies page defaults before building publications.

- [guide.site-mcp · Use this site's MCP](/connect/mcp.md): Connect your agent to Shoalrun's public documentation and ask it to search, read pages, or fetch sections.

- [guide.agent-skills · Use the bundled agent skills](/contribute/agent-skills.md): Give an agent the setup and authoring workflows that ship with Shoalrun.

- [cookbook.authoring · Authoring workflows](/cookbooks/authoring.md): Choose a complete Shoalrun workflow for adding a guide, previewing a change, or refreshing agent docs.

- [cookbook.site-workflows · Site workflows](/cookbooks/site-workflows.md): Choose a build check or a complete build-and-audit workflow for Shoalrun.

- [cookbook.welcome-email · Welcome email workflows](/cookbooks/welcome-email.md): Choose an acceptance check or follow the same message through delivery.

- [guide.cedar-parcel · Fictional example: API reference styling lab](/example-api/cedar.md): Demonstration only; not a live API. Inspect a synthetic API with complex schemas, filters, response formats, and webhooks.

- [reference.cedar.createEnrollment · Fictional example: Create a parcel enrollment](/example-api/cedar/create-enrollment-7af3e5d2.md): Demonstration only; not a live API. POST /Enrollments

- [reference.cedar.getLegacyParcel · Fictional example: Get a parcel through the old route](/example-api/cedar/get-legacy-parcel-6758d051.md): Demonstration only; not a live API. GET /legacy/parcels/{parcelId}

- [reference.cedar.getParcel · Fictional example: Get a parcel](/example-api/cedar/get-parcel-edee10e6.md): Demonstration only; not a live API. GET /parcels/{parcelId}

- [reference.cedar.listParcels · Fictional example: List parcel records](/example-api/cedar/list-parcels-0345fb5f.md): Demonstration only; not a live API. GET /Search/parcels/{scope}

- [reference.cedar.parcelDelivered · Fictional example: Parcel delivered event](/example-api/cedar/parcel-delivered-7d1ba6db.md): Demonstration only; not a live API. Webhook event: parcel.delivered

- [reference.cedar.uploadManifest · Fictional example: Upload a manifest](/example-api/cedar/upload-manifest-1af17891.md): Demonstration only; not a live API. POST /manifests

- [reference.create-note · Fictional example: Create a note](/example-api/create-note.md): Demonstration only; not a live API. Preview an API operation page built from a small, fictional OpenAPI file.

- [reference.notes.getNote · Fictional example: Get a note](/example-api/generated/get-note-cbedb319.md): Demonstration only; not a live API. GET /notes/{id}

- [guide.example-note · Fictional example: Prepare a note request](/example-api/write-note.md): Demonstration only; not a live API. Prepare a fictional note payload and follow its linked operation contracts.

- [guide.explore · Explore the docs](/explore.md): Explore topics and follow connections to find your next page.

- [reference.glossary · Glossary](/glossary.md): Look up documentation, publishing, search, and agent terminology, with links to the relevant guides.

- [ingredient.audit-site · Audit the Shoalrun docs project](/ingredients/audit-site.md): Run configured project checks and inspect failures before sharing a change.

- [ingredient.build-site · Build the Shoalrun docs site](/ingredients/build-site.md): Compile authored documentation into local HTML, Markdown, and manifests.

- [ingredient.compile-framework · Install the site dependencies](/ingredients/compile-framework.md): Install the pinned Shoalrun package and this site’s declared dependencies.

- [ingredient.complete-page · Complete the guide and add navigation](/ingredients/complete-page.md): Write the guide, replace scaffold prompts, and make it discoverable in the local build.

- [ingredient.inspect-agent-bundle · Check agent search and page lookup](/ingredients/inspect-agent-bundle.md): Confirm the refreshed bundle exposes the authored page through search and read.

- [ingredient.inspect-build · Check the built page artifacts](/ingredients/inspect-build.md): Resolve a document ID through the manifest and check its HTML and Markdown files.

- [ingredient.preview-site · Serve the built docs locally](/ingredients/preview-site.md): Open a successful build over HTTP and compare a page with its Markdown twin.

- [ingredient.refresh-agent-bundle · Regenerate the agent documentation bundle](/ingredients/refresh-agent-bundle.md): Build the offline Markdown and search index used by the CLI.

- [ingredient.scaffold-page · Scaffold a new guide](/ingredients/scaffold-page.md): Create a draft guide with a stable ID without overwriting an existing file.

- [guide.non-goals · Non-goals](/non-goals.md): Deliberate limits on Shoalrun's scope, including automatic skill builders, general agent orchestration, and using reader views for authorization.

- [guide.publish · Deploy your documentation](/publish.md): Build your site, choose Vercel or Node hosting, and verify the deployed HTML and Markdown.

- [guide.agent-discovery · Configure the agent discovery block](/publish/agent-discovery.md): Choose how early HTML guidance appears, customize its wording, and verify its links.

- [guide.agent-friendliness · Agent-friendly documentation](/publish/agent-friendliness.md): See how interactive docs become readable Markdown, then discover pages and verify their contents.
  - Standalone section: [Try the page controls](/publish/agent-friendliness.sections/try-the-page-controls.md) — 598 tokens (cl100k_base), 2621 UTF-8 bytes. [Full page](/publish/agent-friendliness.md).

- [guide.api-references · Add an OpenAPI API](/publish/api-references.md): Import a local OpenAPI file, author an operation page, review its public content, and build HTML and Markdown.

- [guide.audit · Audit a docs project](/publish/audit.md): Run project tests and local API representation checks with one CI command.

- [guide.content-negotiation · Content negotiation](/publish/content-negotiation.md): Understand content negotiation, why it helps agents, and what a hosting provider needs to do.

- [guide.deployment-check · Check a deployed site](/publish/deployment-check.md): Run the provider-neutral HTTP checker after publishing and before release.

- [guide.evals · Evaluate agent tasks against your docs](/publish/evals.md): Define realistic tasks, record reviewed answers from your own agent, and check the results against a documentation build.

- [guide.host-adapters · Add Shoalrun to another build or host](/publish/host-adapters.md): Publish compiled files alongside another site and supply the host's HTTP rules.

- [guide.mcp · Connect an MCP client](/publish/mcp.md): Connect read-only MCP clients over stdio or HTTP to search and read built documentation.

- [guide.mcp-analytics · Measure MCP tool usage](/publish/mcp-analytics.md): Send optional server events to your analytics service without changing the documentation tools.

- [reference.openapi-extension-mappings · OpenAPI extension mappings](/publish/openapi-extension-mappings.md): Map selected operation-level x-\* values into Shoalrun metadata without depending on a particular authoring service.

- [guide.output · Publishing and agent representations](/publish/output.md): Read the published-output contract for HTML, Markdown, manifests, and incremental sync.

- [guide.publications · Share pages across documentation versions](/publish/publications.md): Versioning one docs site without copying every page: share unchanged pages, vary sections, and publish changed pages separately.

- [guide.release-revisions · Use Git branches for separate docs sites](/publish/revisions.md): Build a chosen Git branch for each docs address, add links between sites, and verify the deployed commit.

- [guide.seo · SEO and social previews](/publish/seo.md): Give each page a useful title and summary, generate share cards, and verify public preview URLs.

- [guide.troubleshooting · Troubleshooting](/publish/troubleshooting.md): Troubleshoot a build, recover missing pages and fix document links, route collisions, MDX errors, API review digests, and diagram rendering.

- [guide.vercel · Publish on Vercel](/publish/vercel.md): Build a Vercel deployment with Markdown negotiation and correct discovery headers.

- [recipe.add-page · Add a page to this documentation site](/recipes/add-page.md): Create a guide, add navigation, build and audit it, then refresh its agent documentation.

- [recipe.audit-docs · Build and audit this documentation site](/recipes/audit-docs.md): Build current documentation, check its artifacts, and run the configured audits.

- [recipe.build-docs · Build this documentation site](/recipes/build-docs.md): Use the pinned Shoalrun package and confirm a chosen page has HTML and Markdown output.

- [recipe.preview-hybrid-search · Preview semantic search in this checkout](/recipes/preview-hybrid-search.md): Build the Shoalrun docs, index passages, and verify vector retrieval and lexical fallback locally.

- [recipe.preview-page · Preview a documentation change locally](/recipes/preview-page.md): Build current documentation and inspect its HTML and Markdown over local HTTP.

- [recipe.queue-email · Queue a welcome email](/recipes/queue-email.md): Submit the welcome template and confirm the API accepted the request.

- [recipe.refresh-agent-docs · Refresh Shoalrun's bundled agent docs](/recipes/refresh-agent-docs.md): Regenerate offline docs, verify CLI search and read, and run project audits.

- [recipe.send-welcome-email · Send a welcome email and confirm delivery](/recipes/send-welcome-email.md): Follow one message from an accepted request through delivery, and inspect a simulated failure.

- [reference.agent-skills · Bundled agent skills](/reference/agent-skills.md): Skill names, locations, workflow behavior, offline documentation, and validation limits.

- [guide.search-chat-overview · Search and chat](/search-and-chat.md): Choose page search, meaning-based search, or cited answers for your documentation.

- [guide.overview · Getting started](/start.md): Create a documentation site, scaffold your first page from a template, and preview its HTML and Markdown.

- [guide.status · Project status](/status.md): What Shoalrun can do today, what I want to add next, and where its limits are.

- [guide.color-modes · Light and dark mode](/styling/color-modes.md): Light, dark, and system modes, toggle behavior, storage, and accessibility.

- [guide.footer · Site footer](/styling/footer.md): Add link columns, a bottom row of links, and a short text line below every page.

- [guide.header · Header links](/styling/header.md): Add links and buttons to the site masthead.

- [guide.layouts · Page layouts, landing pages, and splash pages](/styling/layouts.md): Give a page more width, or build a landing or full-bleed splash page with a Hero and Sections, using the layout frontmatter field.

- [guide.palettes · Color palettes](/styling/palettes.md): Use a built-in palette or extend one with your brand colors. The build checks every palette against WCAG contrast.

- [guide.share-images · Share images and favicon](/styling/share-images.md): Generated social images, metadata precedence, SVG placeholders, fonts, and favicon settings.

- [guide.themes · Themes](/styling/themes.md): Pick a site shape, pair it with a color palette, and choose how light and dark mode behave.

- [guide.theme-preview · Try a theme](/styling/try.md): Preview every preset, palette, and color mode on this page, then copy the config.

- [guide.what-is-shoalrun · What is Shoalrun?](/what-is-shoalrun.md): A one-page introduction to Shoalrun's document-first approach, its outputs, and the current prototype.