@shoalrun/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/agent-docs/content-delivery/sections.md

@@ -0,0 +1,110 @@
+---
+id: guide.content-section-identity
+title: Section identity and compatibility
+summary: Understand when a section can be exported on its own, declare it, and
+  keep its reference stable.
+type: reference
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/sections
+---
+
+# Section identity and compatibility
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Section identity and compatibility
+
+**Updated: 2026-10-29.**
+
+A section is a heading and the content beneath it. For content delivery, Shoalrun selects sections beginning at a top-level `##` heading, including nested subsections, and ending before the next `##` or `#` heading. Exporting a section extracts that part of the page so an application can use it separately.
+
+Available since `0.1.0-alpha.13`.
+
+## Why a section needs a declaration
+
+A section can lose essential information when separated from its page. For example:
+
+```md
+Before resetting your database, back it up. Resetting deletes all records.
+
+## Reset the database
+
+Run the reset command from Settings.
+```
+
+Exporting only “Reset the database” would leave out the backup instruction and deletion warning. Before exporting this section, move those details into the section or export the whole page instead.
+
+A **standalone section** is one the author has reviewed and declared understandable without the rest of the page. Record that judgment in the page's `standaloneSections` frontmatter. This is what “approval” means here: a declaration in a source file, not a separate reviewer, permission request, or approval service. Shoalrun checks that the declaration exists and identifies a section; it cannot prove the content is complete.
+
+You need this declaration when exporting an individual section. You do not need it to write a page, link to a heading, or export a whole page. Declaring a section does not export it: the export target separately chooses which declared sections to include.
+
+## Identify the section
+
+A section reference contains a document ID and a section ID. Ordinary top-level `##` headings receive derived IDs. Use an explicit marker when an application must retain the same reference after a heading changes.
+
+## Derive an ID
+
+```md
+## Request a refund
+```
+
+This heading derives `request-a-refund`. Derivation normalizes the heading text, uses lowercase letters, numbers, and dashes, and adds a suffix for repeated headings. Changing a heading or reordering repeated headings can change a derived ID. Compare exports before publishing such edits.
+
+## Preserve an explicit ID
+
+```mdx
+## Request a refund <Anchor id="refunds" />
+```
+
+The ID remains `refunds` if the title changes. The marker must be the single trailing element of a root H2, with one literal `id` and no children. IDs use 1–512 lowercase letters, numbers, or dashes, beginning with a letter or number. Duplicate IDs and collisions with another anchor fail. `Anchor` is a reserved built-in name.
+
+The marker cannot be placed inside emphasis, a link, a tab, a reader section, or a snippet. Code examples containing marker syntax remain ordinary code. Both `##` headings and Setext H2 headings are supported.
+
+## Declare a section ready for separate use
+
+Read the section without the rest of the page. Check that it includes the prerequisites, definitions, warnings, and steps needed for its stated purpose. Then add its ID to the page's frontmatter:
+
+```yaml
+standaloneSections:
+  - { id: refunds, context: section }
+```
+
+`context: section` records that your review covered the section on its own, without the page introduction. A derived ID can be declared too; an explicit `<Anchor>` is optional. Next, [select the section in an export target](https://www.shoalrun.com/content-delivery/select.md) using `resources`. If the declaration is missing, section export fails.
+
+Recheck the declaration when the section or its prerequisites change. If the content needs the rest of the page to make sense, export the whole page instead.
+
+## Compatibility with heading-title declarations
+
+Existing projects may use the older title-string form:
+
+```yaml
+standaloneSections:
+  - Request a refund
+```
+
+This form remains supported. It matches the exact heading text and approves a discovery read that includes page introduction and reading-path context. It does not approve a section-only export. Keep it when the section relies on that surrounding context.
+
+Do not mechanically replace a title string with `{ id, context: section }`. First review the section without the page introduction and include any missing prerequisites, definitions, or warnings. Then replace the title string with the ID-based object and select the section in the export target. A heading cannot be declared in both forms.
+
+The object form also marks the section as approved for contextual discovery when it meets discovery size requirements. Switching to the object does not remove context from existing discovery responses; it additionally approves the section-only export. See [section discovery](https://www.shoalrun.com/author/markdown-metadata.md) for those response rules.
+
+## Maintain references
+
+Renaming an explicit ID or removing an exported section removes a public content reference. Use `--previous-manifest` and `--fail-on-removed` when publishing an established collection. An unchanged ID with edited content receives a new digest; identity does not mean immutable wording.
+
+## HTML, Markdown, and agents
+
+HTML preserves the existing heading-derived anchor and adds an explicit ID as an alias when it is distinct and available. Markdown keeps the clean heading text. Agents receive IDs through outlines or export metadata; they should follow the returned resource URL rather than invent a Markdown fragment URL. Existing contextual MCP section reads retain their page context and size heuristics; application fragments are a separate output.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Select content resources](https://www.shoalrun.com/content-delivery/select.md) — Approve section slices and preserve their references.

package/agent-docs/content-delivery/select.md

@@ -0,0 +1,100 @@
+---
+id: guide.content-delivery-selection
+title: Select content resources
+summary: Choose pages, approved sections, and named snippet instances for a
+  portable export.
+type: how-to
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/select
+---
+
+# Select content resources
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Select content resources
+
+**Updated: 2026-10-29.**
+
+Use an export target to choose exactly which content an application receives. Work from a Shoalrun project with public pages in an enabled publication. Whole pages need no section declaration. To export just one section, first read it without the rest of its page. Check that it includes the context needed to understand or follow it. Record that review in the source page's `standaloneSections` frontmatter; [declare a section ready for separate use](https://www.shoalrun.com/content-delivery/sections.md) explains why and shows the syntax.
+
+The declaration says the section can be used on its own. The export target below says which content to include in this bundle. Both are required for a section export.
+
+Available since `0.1.0-alpha.13`.
+
+## Define the target
+
+Add this target to `docs.config.yaml`. Replace the example IDs with your own:
+
+```yaml
+exports:
+  application:
+    formats: [html, markdown]
+    publicBase: /content/revisions/r1/
+    publication: { channel: production, version: current, language: en }
+    resources:
+      - { kind: page, documentId: guide.account }
+      - { kind: section, documentId: guide.billing, sectionId: refunds }
+      - kind: snippet
+        id: refund.standard
+        snippetId: refund-window
+        title: Refund window
+        summary: Time available to request a refund.
+        values: { days: 30 }
+```
+
+`resources` and the older `documents` selection are mutually exclusive. A page selector includes the complete page. A section selector includes its approved H2 and nested subsections, ending at the next H2 or H1. The export retains applicable notices and referenced definitions without copying ordinary page introduction text.
+
+A requested page must be public and available in the chosen publication. An export `contentFilter` can narrow eligible pages; it is independent of website navigation and `site.contentFilter`. Reader filters select content, not access permissions.
+
+## Name snippet instances
+
+Register reusable snippet source in the project's existing `snippets` configuration:
+
+```yaml
+snippets:
+  refund-window:
+    file: ./snippets/refund-window.mdx
+    variables:
+      days: { type: number, required: true, default: 14 }
+```
+
+The snippet file contains:
+
+```mdx
+Request a refund within <Var name="days" /> days.
+```
+
+`snippetId` chooses that source; `id` names the exported instance. Multiple instances can use different literal values. The application reads `refund.standard`, not a runtime template. Instances have no containing page or page variables. Page-dependent components and headings are not supported in standalone snippets.
+
+## Export and inspect
+
+```sh
+npx --no-install shoalrun export docs.config.yaml \
+  --target application --out ./content-release
+```
+
+Inspect `manifest.json`, each selected representation, and its referenced assets. Unknown references, missing approval, and unsupported content fail before replacing an existing export. Imported API material still follows the existing source-review gate.
+
+Links to fragments in unselected pages fail export because their anchors cannot be verified. Select the target page or section explicitly. Missing or ambiguous fragments also fail. A sliced section keeps its full-source heading identity. Links to sibling content can use a canonical page URL only when the source HTML anchor is verified.
+
+## HTML, Markdown, and agents
+
+Both formats receive the selected resources, with their own links and anchor metadata. Tabs and reader-marked content become complete labeled text. A fragment with no substantive content in a requested representation fails export. Agents can inspect the exact resource references and publication in the manifest instead of inferring meaning from a filename.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Choose which resources the application receives.
+
+- [Section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) — Approve section slices and preserve their references.
+
+- [Read content with a client](https://www.shoalrun.com/content-delivery/client.md) — Read a reviewed export from an application.

package/agent-docs/content-delivery.md

@@ -0,0 +1,79 @@
+---
+id: guide.content-delivery
+title: Content delivery
+summary: Deliver pages, sections, and snippet instances to applications from one
+  reviewed content bundle.
+type: explanation
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery
+---
+
+# Content delivery
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Content delivery > Overview
+
+**Updated: 2026-10-29.**
+
+Content delivery makes your documentation a reusable content source for applications, agents, services, and workflows. They can retrieve whole pages, individual sections, or reusable snippets in HTML or Markdown. You control how the content is displayed, combined, or processed; Shoalrun supplies the content and its metadata.
+
+For example:
+
+- A product displays billing instructions beside its payment settings.
+- An agent retrieves a deployment procedure as context for completing a task.
+- A publishing workflow reuses sections in onboarding emails or training material.
+- A service feeds the documentation into its own search or retrieval index.
+
+These are starting points. The consuming system decides what to build with the content.
+
+Available since `0.1.0-alpha.13`.
+
+## Choose a resource
+
+Choose the unit that matches the application surface.
+
+| Resource         | Identity                   | Typical use                                                    |
+| ---------------- | -------------------------- | -------------------------------------------------------------- |
+| Page             | Document ID                | A complete guide or reference                                  |
+| Section          | Document ID and section ID | Part of a page, reviewed for use without the rest of that page |
+| Snippet instance | Named export instance      | Reused text with fixed build-time values                       |
+
+[Select resources](https://www.shoalrun.com/content-delivery/select.md) in an export target, then build a directory containing a manifest, passive HTML, Markdown, and local assets. An application opens the manifest and reads resources by their typed references. It never needs to guess generated filenames.
+
+Exporting a section leaves out the ordinary page introduction and neighboring sections. Before selecting one, check that it still makes sense on its own and record that judgment in `standaloneSections`. This declaration is required only for section exports, not whole-page exports. [Section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) shows a missing-context example and the declaration.
+
+## Start with static delivery
+
+A static server can serve the bundle from your application's origin. The content client opens one revision and checks each representation against the manifest's byte count and digest. No content API server, model provider, or website build is required.
+
+```text
+Authored pages and snippets
+  -> reviewed export
+  -> static files on the application origin
+  -> content client
+  -> application interface
+```
+
+Keep the application's content access behind the [ContentSnapshot interface](https://www.shoalrun.com/content-delivery/api.md). The [REST adapter](https://www.shoalrun.com/content-delivery/rest.md) exposes the same resources through HTTP, and its client returns that interface. The host supplies its listener and authorization. The adapter does not add search or live content editing.
+
+## Choose the next task
+
+- [Select content resources](https://www.shoalrun.com/content-delivery/select.md) to define the bundle.
+- [Read content with a client](https://www.shoalrun.com/content-delivery/client.md) to fetch static exports.
+- [Serve content through REST](https://www.shoalrun.com/content-delivery/rest.md) to expose the same snapshots over HTTP.
+- [Render content in an application](https://www.shoalrun.com/content-delivery/render.md) to display it.
+- [Publish and update content](https://www.shoalrun.com/content-delivery/publish.md) to keep revisions consistent.
+
+## HTML, Markdown, and agents
+
+HTML exports contain passive fragments that the application styles. Markdown exports retain readable content for agents or another renderer. Interactive controls are lowered to static content; no Shoalrun browser behavior ships with a fragment. Agents can use the manifest and typed references without operating the application. [Compare delivery and discovery](https://www.shoalrun.com/content-delivery/agents.md) before choosing an agent integration.
+
+## Related reading
+
+### Related topics
+
+- [Select content resources](https://www.shoalrun.com/content-delivery/select.md) — Choose which resources the application receives.

package/agent-docs/contribute/agent-skills.md

@@ -14,7 +14,7 @@ canonical: /contribute/agent-skills
 
 Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Use the bundled agent skills
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Use the bundled agent skills
 
 **Updated: 2026-10-26.**
 

package/agent-docs/cookbooks/authoring.md

@@ -13,11 +13,11 @@ canonical: /cookbooks/authoring
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Cookbooks > Authoring workflows
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Authoring workflows
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Choose the outcome you need for Shoalrun's own documentation. Each recipe includes setup, ordered work, handoffs, and an observable final check.
 
@@ -53,6 +53,10 @@ Adding a guide includes manual writing and review. The recipe then builds and au
 
 Use **Link to this path** to share the selected instructions, **Download Markdown** to work from a saved copy, or **Print this path** for a checklist. These workflows prepare local changes for review; they do not commit or deploy them.
 
+## HTML, Markdown, and agents
+
+In HTML, the chooser loads and displays the selected published recipes. Without JavaScript, readers can follow the recipe links. This page's Markdown lists the choices and their destinations; it does not contain the selected recipes' full instructions. Give an agent a recipe's Markdown page or the chooser's **Download Markdown** file to follow the complete task.
+
 ## Related reading
 
 ### Go deeper

package/agent-docs/cookbooks/site-workflows.md

@@ -12,11 +12,11 @@ canonical: /cookbooks/site-workflows
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Cookbooks > Site workflows
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Site workflows
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Use these recipes on a local Shoalrun checkout after editing documentation. Choose the level of validation you need. The audit path already includes the build and artifact checks, so run one complete path.
 
@@ -40,7 +40,11 @@ How much validation do you need?. Choose one recipe.
 
   You will have: A successful build, checked artifacts, and no failed configured audits.
 
-These recipes use the same compile, build, and artifact-check ingredients. The audit recipe adds the configured project and API checks. Neither path deploys the site. Use the preview workflow to inspect the rendered result before publishing.
+These recipes use the same installation, build, and artifact-check ingredients. The audit recipe adds the configured project and API checks. Neither path deploys the site. Use the preview workflow to inspect the rendered result before publishing.
+
+## HTML, Markdown, and agents
+
+The HTML chooser displays the complete recipe you select; its recipe links also work without JavaScript. The cookbook's Markdown lists the build and audit choices with links to their recipe pages. It does not contain a browser-selected workflow. An agent should read the chosen recipe's Markdown or receive the file from **Download Markdown** before carrying out its steps.
 
 ## Related reading
 

package/agent-docs/cookbooks/welcome-email.md

@@ -12,11 +12,11 @@ canonical: /cookbooks/welcome-email
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/navigation/examples-tab-50f26fe22670.txt) (ID: examples-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Recipes and cookbooks > Cookbooks > Email simulation
+Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Email simulation > Email simulation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 An accepted request is the first checkpoint. Choose how far you want to follow the message. Both paths use a local simulation that sends no email.
 
@@ -44,6 +44,10 @@ What do you need to confirm?. Choose one recipe.
 
 The delivery path includes the queue step, so choose one path. Use **Link to this path** to share your selection, **Download Markdown** to keep the instructions, or **Print this path** for a paper copy. Shared links contain your recipe choice only; they do not contain a message ID.
 
+## HTML, Markdown, and agents
+
+The HTML chooser loads the selected email recipes, while ordinary recipe links remain available without JavaScript. Markdown lists the choices and links rather than the browser-selected recipe bodies. An agent must follow those links or read the chooser's **Download Markdown** file for the complete simulator instructions. Selecting a recipe does not send an email or execute its commands.
+
 ## Related reading
 
 ### Go deeper