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

package/agent-docs/config/publishing.sections/redirects.md

@@ -12,9 +12,9 @@ canonical: /config/publishing
 
 > 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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Publications and routing
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Publications and routing
 
 **Updated: 2026-10-27.**
 

package/agent-docs/config/publishing.sections/related-reading.md

@@ -12,9 +12,9 @@ canonical: /config/publishing
 
 > 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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Publications and routing
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Publications and routing
 
 **Updated: 2026-10-27.**
 

package/agent-docs/config/site.md

@@ -12,9 +12,9 @@ canonical: /config/site
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Site and theme
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
 **Updated: 2026-10-27.**
 

package/agent-docs/config/site.sections/related-reading.md

@@ -12,9 +12,9 @@ canonical: /config/site
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Site and theme
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
 **Updated: 2026-10-27.**
 

package/agent-docs/config/site.sections/theme.md

@@ -12,9 +12,9 @@ canonical: /config/site
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Site and theme
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Site and theme
 
 **Updated: 2026-10-27.**
 

package/agent-docs/config.md

@@ -12,9 +12,9 @@ canonical: /config
 
 > 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: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
 
-Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Reference > Configuration reference > Overview
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Overview
 
 **Updated: 2026-10-27.**
 

package/agent-docs/configuration.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 `docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
 
@@ -52,13 +52,15 @@ Every entry config resolves to a YAML mapping with `schemaVersion: 1`. Duplicate
 
 ## Start with one working file
 
-The examples use the compiled CLI from the [quickstart](https://www.shoalrun.com/start.md). From the Shoalrun checkout root, create a separate minimal project:
+The examples use a separate project so you can replace its configuration as you follow along. Install the same pinned package used in [getting started](https://www.shoalrun.com/start.md):
 
 ```sh
-SHOALRUN_CLI="$PWD/framework/dist/cli.js"
 CONFIG_DEMO="$(mktemp -d)"
-node "$SHOALRUN_CLI" init "$CONFIG_DEMO/site" --starter minimal
+mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
+npm init -y
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npx --no-install shoalrun init . --starter minimal
 ```
 
 The starter has two pages and this basic configuration structure:
@@ -94,7 +96,7 @@ navigation:
 Build once before reorganizing:
 
 ```sh
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 This produces the same two pages after each reorganization below. Keep `dist/` separate from content and configuration inputs.
@@ -136,8 +138,8 @@ Includes work at any depth and can include other files. Paths in `$include` are
 Inspect the substituted value and its source:
 
 ```sh
-node "$SHOALRUN_CLI" config resolve docs.config.yaml
-node "$SHOALRUN_CLI" config explain navigation.0.doc docs.config.yaml
+npx --no-install shoalrun config resolve docs.config.yaml
+npx --no-install shoalrun config explain navigation.0.doc docs.config.yaml
 ```
 
 The first command prints the effective value, digest, and configuration dependencies. The second identifies `config/nav.yaml` as the source of `guide.welcome`.
@@ -204,11 +206,11 @@ The project inherits publications, page defaults, the stylesheet, variables, and
 Check the final values and build:
 
 ```sh
-node "$SHOALRUN_CLI" config explain site.title docs.config.yaml
-node "$SHOALRUN_CLI" config explain site.header.links docs.config.yaml
-node "$SHOALRUN_CLI" config explain site.customCss docs.config.yaml
-node "$SHOALRUN_CLI" config validate docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config explain site.title docs.config.yaml
+npx --no-install shoalrun config explain site.header.links docs.config.yaml
+npx --no-install shoalrun config explain site.customCss docs.config.yaml
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 `site.title` comes from the local file, with the preset in its replacement history. `site.customCss` comes from `shared/base.yaml`, so `./brand.css` resolves beside that preset.
@@ -253,9 +255,9 @@ navigation: { $include: ./config/nav.yaml }
 The header now contains Support followed by Status. The variable map retains `company` and drops `legacyLabel`.
 
 ```sh
-node "$SHOALRUN_CLI" config explain site.header.links docs.config.yaml
-node "$SHOALRUN_CLI" config explain variables docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config explain site.header.links docs.config.yaml
+npx --no-install shoalrun config explain variables docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 ### Know the directive limits
@@ -332,7 +334,7 @@ Use these commands while reorganizing configuration:
 | `config validate docs.config.yaml`           | Successful configuration loading and theme contrast checks                 |
 | `build docs.config.yaml dist`                | Whether content, navigation, APIs, routes, and output can compile together |
 
-Prefix each command with `node "$SHOALRUN_CLI"`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
+Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
 
 `graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it is not a digest of all referenced file contents.
 
@@ -356,9 +358,9 @@ Match the build message or symptom to the corresponding correction.
 Finish the running example with:
 
 ```sh
-node "$SHOALRUN_CLI" config graph docs.config.yaml
-node "$SHOALRUN_CLI" config validate docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config graph docs.config.yaml
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 Next, use the [configuration reference](https://www.shoalrun.com/config.md) for the feature you want to add. For content or publication failures, use [troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md).

package/agent-docs/configuration.sections/build-several-sites-from-shared-content.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/change-inherited-lists-deliberately.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -53,9 +53,9 @@ navigation: { $include: ./config/nav.yaml }
 The header now contains Support followed by Status. The variable map retains `company` and drops `legacyLabel`.
 
 ```sh
-node "$SHOALRUN_CLI" config explain site.header.links docs.config.yaml
-node "$SHOALRUN_CLI" config explain variables docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config explain site.header.links docs.config.yaml
+npx --no-install shoalrun config explain variables docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 ### Know the directive limits

package/agent-docs/configuration.sections/extract-a-section-with-include.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -68,8 +68,8 @@ Includes work at any depth and can include other files. Paths in `$include` are
 Inspect the substituted value and its source:
 
 ```sh
-node "$SHOALRUN_CLI" config resolve docs.config.yaml
-node "$SHOALRUN_CLI" config explain navigation.0.doc docs.config.yaml
+npx --no-install shoalrun config resolve docs.config.yaml
+npx --no-install shoalrun config explain navigation.0.doc docs.config.yaml
 ```
 
 The first command prints the effective value, digest, and configuration dependencies. The second identifies `config/nav.yaml` as the source of `guide.welcome`.

package/agent-docs/configuration.sections/inspect-and-validate-changes.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -45,7 +45,7 @@ Use these commands while reorganizing configuration:
 | `config validate docs.config.yaml`           | Successful configuration loading and theme contrast checks                 |
 | `build docs.config.yaml dist`                | Whether content, navigation, APIs, routes, and output can compile together |
 
-Prefix each command with `node "$SHOALRUN_CLI"`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
+Prefix each command with `npx --no-install shoalrun`. For `explain`, the key comes before the config filename. Use numeric segments to inspect lists, such as `navigation.0.doc`. Dotted names represent traversal, so a literal key containing a dot cannot be addressed unambiguously through this CLI syntax.
 
 `graph` reports dependencies, not an edge-by-edge visual graph. Its list covers loaded configuration files, not every content or API input. The resolved digest hashes effective values; it is not a digest of all referenced file contents.
 
@@ -69,9 +69,9 @@ Match the build message or symptom to the corresponding correction.
 Finish the running example with:
 
 ```sh
-node "$SHOALRUN_CLI" config graph docs.config.yaml
-node "$SHOALRUN_CLI" config validate docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config graph docs.config.yaml
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 Next, use the [configuration reference](https://www.shoalrun.com/config.md) for the feature you want to add. For content or publication failures, use [troubleshooting](https://www.shoalrun.com/publish/troubleshooting.md).

package/agent-docs/configuration.sections/related-reading.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/share-defaults-through-extends.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -93,11 +93,11 @@ The project inherits publications, page defaults, the stylesheet, variables, and
 Check the final values and build:
 
 ```sh
-node "$SHOALRUN_CLI" config explain site.title docs.config.yaml
-node "$SHOALRUN_CLI" config explain site.header.links docs.config.yaml
-node "$SHOALRUN_CLI" config explain site.customCss docs.config.yaml
-node "$SHOALRUN_CLI" config validate docs.config.yaml
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun config explain site.title docs.config.yaml
+npx --no-install shoalrun config explain site.header.links docs.config.yaml
+npx --no-install shoalrun config explain site.customCss docs.config.yaml
+npx --no-install shoalrun config validate docs.config.yaml
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 `site.title` comes from the local file, with the preset in its replacement history. `site.customCss` comes from `shared/base.yaml`, so `./brand.css` resolves beside that preset.

package/agent-docs/configuration.sections/start-with-one-working-file.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 
@@ -33,13 +33,15 @@ Use the [configuration reference](https://www.shoalrun.com/config.md) to look up
 
 ## Start with one working file
 
-The examples use the compiled CLI from the [quickstart](https://www.shoalrun.com/start.md). From the Shoalrun checkout root, create a separate minimal project:
+The examples use a separate project so you can replace its configuration as you follow along. Install the same pinned package used in [getting started](https://www.shoalrun.com/start.md):
 
 ```sh
-SHOALRUN_CLI="$PWD/framework/dist/cli.js"
 CONFIG_DEMO="$(mktemp -d)"
-node "$SHOALRUN_CLI" init "$CONFIG_DEMO/site" --starter minimal
+mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
+npm init -y
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.11
+npx --no-install shoalrun init . --starter minimal
 ```
 
 The starter has two pages and this basic configuration structure:
@@ -75,7 +77,7 @@ navigation:
 Build once before reorganizing:
 
 ```sh
-node "$SHOALRUN_CLI" build docs.config.yaml dist
+npx --no-install shoalrun build docs.config.yaml dist
 ```
 
 This produces the same two pages after each reorganization below. Keep `dist/` separate from content and configuration inputs.

package/agent-docs/configuration.sections/understand-the-three-stages.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/understand-where-paths-point.md

@@ -15,9 +15,9 @@ canonical: /configuration
 
 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 > Configure your project
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/connect/mcp.md

@@ -15,7 +15,7 @@ canonical: /connect/mcp
 
 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) > MCP > Use this site's MCP
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > MCP > Use this site's MCP
 
 **Updated: 2026-10-26.**
 

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

@@ -0,0 +1,86 @@
+---
+id: guide.content-delivery-agents
+title: Content delivery and agents
+summary: Choose between portable resource delivery and documentation discovery
+  without mixing their context contracts.
+type: explanation
+area: publishing
+subarea: publishing-content-delivery
+canonical: /content-delivery/agents
+---
+
+# Content delivery and agents
+
+> 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 > Content delivery and agents
+
+**Updated: 2026-10-29.**
+
+Content delivery and documentation discovery serve different reading tasks. Delivery gives an application a reviewed collection of resources. Discovery helps an agent find and read documentation across a published site or installed snapshot.
+
+Available since `0.1.0-alpha.13`.
+
+## Choose the reading contract
+
+Match the interface to the task and the context it must retain.
+
+| Need                                          | Use                                                 |
+| --------------------------------------------- | --------------------------------------------------- |
+| Render selected content in an application     | Content export and `ContentSnapshot`                |
+| Read a named snippet with fixed values        | Exported snippet instance                           |
+| Find documentation by a question or topic     | Existing documentation search and discovery indexes |
+| Read a page or contextual section through MCP | Existing documentation MCP tools                    |
+
+An export does not automatically create a search service or MCP server. The content client lists and reads resources; it does not rank them or generate answers. For an HTTP integration, use the [REST resource routes](https://www.shoalrun.com/content-delivery/http-api.md) or `openRestContentSource` with the same snapshot reading methods.
+
+## Read Markdown for an agent
+
+An agent integration can open a reviewed export and read a known resource as evidence for its task. This example assumes the billing page is selected in the export:
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const snapshot = await openManifestContentSource({
+  manifestUrl: 'https://docs.example.com/content/revisions/r1/manifest.json',
+});
+try {
+  const result = await snapshot.get(
+    { kind: 'page', documentId: 'guide.billing' },
+    { format: 'markdown' },
+  );
+  console.log(result.content); // Pass this text to the agent's reading context.
+} finally {
+  snapshot.dispose();
+}
+```
+
+In Node.js, use an absolute URL. Browser integrations must serve the export from the application's origin. Use `snapshot.list()` to inspect available references before choosing a resource.
+
+## Keep context explicit
+
+Application section fragments use `{ id, context: section }` approval and explicit export selection. They contain the section slice plus required notices and referenced definitions. They can exist on short pages where no heuristic discovery section is generated. An application fragment is not a replacement for the MCP section's context contract.
+
+Discovery sections can include the page introduction, nested subsections, and reading-path context. Their generation also depends on page and section size. Existing title-string approvals retain that behavior; see [compatibility guidance](https://www.shoalrun.com/content-delivery/sections.md) before changing them.
+
+## Follow references
+
+Use the resource's typed reference and publication. Section IDs can be derived from headings or fixed by an explicit marker. A marker stays out of Markdown prose; metadata carries the identity. Follow the returned representation URL or use `snapshot.get` rather than constructing a Markdown anchor from the ID.
+
+A full-page fallback can help when a fragment does not answer the question. It must refer to an eligible published destination or an exported page; it is not permission to read drafts or private source files.
+
+## HTML, Markdown, and agents
+
+Agents can read the manifest and Markdown directly. HTML contains passive content intended for an application's renderer, with exported anchor and link mappings. Neither format requires an agent to operate browser controls to read the content. Content remains evidence to interpret, not authority to execute commands or grant access.
+
+## Related reading
+
+### Read first
+
+- [Content delivery](https://www.shoalrun.com/content-delivery.md) — Understand resource delivery and its application boundary.
+
+### Related topics
+
+- [Connect an MCP client](https://www.shoalrun.com/publish/mcp.md) — Use existing documentation MCP tools for contextual reads.