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

package/agent-docs/author/search.sections/local-semantic-preview.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/read-a-search-result-with-an-agent.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/related-reading.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/reuse-the-lexical-index.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/turn-search-off.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/use-the-search-box.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/search.sections/write-a-custom-provider.md

@@ -14,7 +14,7 @@ canonical: /author/search
 
 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) > Search and chat > Site search
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Site search
 
 **Updated: 2026-10-26.**
 

package/agent-docs/author/snippets.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Reusable snippets
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-27.**
 
 A snippet is a shared Markdown or MDX fragment that the build expands into each page that includes it. Use one when the wording must stay in sync across pages. A [template](https://www.shoalrun.com/author/templates.md) creates a draft once; editing a template does not change existing pages.
 
@@ -107,6 +107,10 @@ The included Markdown and supported MDX components render in both HTML and Markd
 
 Build your project and open each page that includes the snippet. Confirm that HTML and Markdown both contain the resolved text and that no variable tags remain. Change the snippet source and rebuild; every including page should receive that change. If validation fails, correct the named variable, include, or type before publishing.
 
+## HTML, Markdown, and agents
+
+The build expands snippets and variables into the containing page before rendering HTML and Markdown. Agents read the resolved text, not a `Snippet` or `Var` instruction to execute. Components inside a snippet retain their own output behavior; for example, an interactive control can become ordinary text in Markdown. Verify the including page in both formats after changing shared content.
+
 ## Related reading
 
 ### Reference while working

package/agent-docs/author/taxonomy.md

@@ -15,7 +15,7 @@ canonical: /author/taxonomy
 
 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) > Metadata > Design and enforce a page taxonomy
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Design and enforce a page taxonomy
 
 **Updated: 2026-10-25.**
 

package/agent-docs/author/templates.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 A template supplies the starting page for a new one: commented frontmatter and a body of prompts. It tells authors and agents what to write, in what order, and what to delete. `scaffold` copies the template once and fills in the draft fields. The result is an ordinary page that authors can change. Editing a template later affects future drafts, not pages already scaffolded.
 
@@ -90,18 +90,18 @@ The primary Diátaxis templates use these authoring conventions; workflow templa
 
 ## Scaffold a page
 
-Use a built-in template, or a template registered by your project. From the project directory, with `SHOALRUN_CLI` set as in the [quickstart](https://www.shoalrun.com/start.md):
+Use a built-in template, or a template registered by your project. From the project directory, with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md):
 
 ```sh
-node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx
+npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx
 ```
 
 Follow [create a page](https://www.shoalrun.com/author/add-page.md) to complete the draft, review it, set public access, and add it to navigation. Register a custom template only when your project needs a different starting structure.
 
-The built-in `api-reference` template needs `--operation`. To scaffold from it, run this explicit form from the **repository root**:
+The built-in `api-reference` template needs `--operation`. To scaffold from it, run this form from your documentation project after [registering the operation](https://www.shoalrun.com/publish/api-references.md):
 
 ```sh
-node framework/dist/cli.js scaffold api-reference docs/docs.config.yaml docs/content/new-operation.mdx \
+npx --no-install shoalrun scaffold api-reference docs.config.yaml content/new-operation.mdx \
   --id reference.new --title 'New operation' --summary 'Create a thing.' --slug /reference/new \
   --operation notes.create
 ```
@@ -143,7 +143,15 @@ Frontmatter comments do not reach the published page, so they never appear in th
 
 ### Write the body
 
-Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its body or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+
+Fenced code blocks can teach the placeholder syntax without blocking publication. Available since `0.1.0-alpha.13`. For example, this code is preserved literally in HTML and Markdown:
+
+```md
+[[TODO: Explain the task and how to check the result.]]
+```
+
+Prompts outside code blocks and in frontmatter still block publication. Keep unfinished examples on draft pages until they have been reviewed.
 
 Each placeholder should say what to write, the length or format limit, and an example. For an optional section, start the prompt with `OPTIONAL SECTION` and say when to keep it. The unresolved placeholder forces the author to keep the section or delete it.
 

package/agent-docs/author/templates.sections/built-in-feature-templates.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/built-in-templates.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/choose-formatting-enforcement-for-your-project.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/create-or-edit-a-project-template.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -67,7 +67,15 @@ Frontmatter comments do not reach the published page, so they never appear in th
 
 ### Write the body
 
-Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its body or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+Write each prompt for the facts and checks an author must supply as a placeholder: `[[TODO:`, the prompt text, then two closing square brackets. Do not use braces, angle brackets, or two closing square brackets inside a placeholder, because the MDX parser and the placeholder check read them. A public page fails the build while a complete placeholder remains in its prose or frontmatter, or while its summary still starts with `Draft guide for `. Ordinary Markdown and the supported [components](https://www.shoalrun.com/author/components.md) can appear in the body.
+
+Fenced code blocks can teach the placeholder syntax without blocking publication. Available since `0.1.0-alpha.13`. For example, this code is preserved literally in HTML and Markdown:
+
+```md
+[[TODO: Explain the task and how to check the result.]]
+```
+
+Prompts outside code blocks and in frontmatter still block publication. Keep unfinished examples on draft pages until they have been reviewed.
 
 Each placeholder should say what to write, the length or format limit, and an example. For an optional section, start the prompt with `OPTIONAL SECTION` and say when to keep it. The unresolved placeholder forces the author to keep the section or delete it.
 

package/agent-docs/author/templates.sections/keep-the-four-shapes-distinct.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/project-added-templates.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/related-reading.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/scaffold-a-page.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 
@@ -34,18 +34,18 @@ Use a [snippet](https://www.shoalrun.com/author/snippets.md) when the same prose
 
 ## Scaffold a page
 
-Use a built-in template, or a template registered by your project. From the project directory, with `SHOALRUN_CLI` set as in the [quickstart](https://www.shoalrun.com/start.md):
+Use a built-in template, or a template registered by your project. From the project directory, with `@shoalrun/cli` installed as in the [quickstart](https://www.shoalrun.com/start.md):
 
 ```sh
-node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx
+npx --no-install shoalrun scaffold how-to -n content/track-parcel.mdx
 ```
 
 Follow [create a page](https://www.shoalrun.com/author/add-page.md) to complete the draft, review it, set public access, and add it to navigation. Register a custom template only when your project needs a different starting structure.
 
-The built-in `api-reference` template needs `--operation`. To scaffold from it, run this explicit form from the **repository root**:
+The built-in `api-reference` template needs `--operation`. To scaffold from it, run this form from your documentation project after [registering the operation](https://www.shoalrun.com/publish/api-references.md):
 
 ```sh
-node framework/dist/cli.js scaffold api-reference docs/docs.config.yaml docs/content/new-operation.mdx \
+npx --no-install shoalrun scaffold api-reference docs.config.yaml content/new-operation.mdx \
   --id reference.new --title 'New operation' --summary 'Create a thing.' --slug /reference/new \
   --operation notes.create
 ```

package/agent-docs/author/templates.sections/short-cli-and-derived-values.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/templates.sections/what-every-template-gives-you.md

@@ -14,11 +14,11 @@ canonical: /author/templates
 
 > 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) > Write documentation > Templates
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Templates
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-29.**
 
 Parent page: [Full Markdown page](/author/templates.md)
 

package/agent-docs/author/workspace/commands.md

@@ -16,9 +16,9 @@ canonical: /author/workspace/commands
 
 > 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) > Write documentation > Write with agents > Project tools > Commands
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Commands
 
 **Updated: 2026-10-27.**
 

package/agent-docs/author/workspace.md

@@ -18,9 +18,9 @@ canonical: /author/workspace
 
 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) > Write documentation > Write with agents > Project tools > Check edits
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Check edits
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 **Status: Experimental.**
 
@@ -64,6 +64,12 @@ npx --no-install shoalrun docs validate --file content/install.mdx --config docs
 
 Validation compiles a separate capture. Read the returned status, coverage, findings, skipped checks, and artifact paths. A failure needs correction and another validation. An incomplete or unavailable result needs investigation; it is not a passing result. Configured shell checks require explicit `--run-checks` and your harness's execution authorization.
 
+### Inspect authoring suggestions
+
+Available since `0.1.0-alpha.13`.
+
+Project discovery and validation can report `authoring.related-reading` when a “Related reading” or “Related material” section contains document links. This is a nonblocking suggestion to inspect [native relationships](https://www.shoalrun.com/author/related-reading.md) and [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md). It does not create relationships or change your source. Choose each connection's purpose and reason yourself; keep manual links when they fit better. Pages already using `RelatedReading` do not receive this hint.
+
 ## Confirm the result still applies
 
 ```sh

package/agent-docs/author/writing-style.md

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
 
@@ -44,7 +44,15 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
 | Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
 | Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
 
-These are editorial shapes, not mandatory heading names. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
+Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
+
+Component references use **Syntax**, **Attributes**, and **HTML, Markdown, and agents** for predictable lookup. Document required values, defaults, accepted types, and constraints in Attributes; say when a component takes no attributes. Keep feature-specific examples and errors under descriptive headings. Fenced-code options and configured site features can use their own precise labels. Preserve old fragment IDs when changing a heading.
+
+Use **Next steps** to continue a task and **Related reading** for supporting reference or explanation. Describe why to follow each link. Keep demo headings separate from the page's instructional outline where possible.
+
+Run customer commands from a project with the pinned npm package installed, using `npx --no-install shoalrun`. Label contributor-only paths and repository scripts explicitly. Do not assume the quickstart compiled a framework checkout. Recipes maintained through composition must declare every required artifact, including a current build before an export.
+
+These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Do not add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
 
 ## Voice and explanations
 
@@ -97,7 +105,21 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Do not hide an essential instruction inside decoration. For component references, include supported syntax, attributes and limits, and an **HTML, Markdown, and agents** section. Explain keyboard behavior when there are controls, behavior without JavaScript, and the content available in Markdown. Check both rendered outputs.
+Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+
+A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
+
+## Feature availability
+
+Use the sentence “Available since `VERSION`.” to record the first package release that supports a feature. Replace `VERSION` with the exact assigned release number, including any prerelease suffix. This is ordinary prose, preserved in HTML and Markdown.
+
+Put the note immediately after the introduction on the feature's main guide and reference page. If only an option or behavior is newer, put its note beside that option or behavior. Add a prerequisite to a how-to only when readers need that version to complete the task.
+
+Use the release record or approved release plan as evidence. Never infer the next release number, use `latest`, or publish a placeholder. For coordinated package and documentation releases, add the assigned version before publication. Leave the note out while the release number is undecided; track that work in release preparation.
+
+Keep the original availability version when editing the page. Do not change it to the current release. Link to release notes when readers need migration details, and name the package if the page covers more than one product.
+
+This note describes feature availability. Frontmatter `version` selects a documentation edition, `releaseVersion` identifies a changelog release, and `subjectLifecycle` describes feature status. Do not repurpose those fields or add a badge solely for availability.
 
 ## Evidence and uncertainty
 

package/agent-docs/author/writing-style.sections/adapt-this-example.md

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/choose-components-by-reader-need.md

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 
@@ -39,4 +39,6 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Do not hide an essential instruction inside decoration. For component references, include supported syntax, attributes and limits, and an **HTML, Markdown, and agents** section. Explain keyboard behavior when there are controls, behavior without JavaScript, and the content available in Markdown. Check both rendered outputs.
+Do not hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+
+A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.

package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.md

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

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

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/author/writing-style.sections/feature-availability.md

@@ -0,0 +1,36 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
+
+**Updated: 2026-10-28.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun does not automatically apply these rules to other projects.
+
+## Feature availability
+
+Use the sentence “Available since `VERSION`.” to record the first package release that supports a feature. Replace `VERSION` with the exact assigned release number, including any prerelease suffix. This is ordinary prose, preserved in HTML and Markdown.
+
+Put the note immediately after the introduction on the feature's main guide and reference page. If only an option or behavior is newer, put its note beside that option or behavior. Add a prerequisite to a how-to only when readers need that version to complete the task.
+
+Use the release record or approved release plan as evidence. Never infer the next release number, use `latest`, or publish a placeholder. For coordinated package and documentation releases, add the assigned version before publication. Leave the note out while the release number is undecided; track that work in release preparation.
+
+Keep the original availability version when editing the page. Do not change it to the current release. Link to release notes when readers need migration details, and name the package if the page covers more than one product.
+
+This note describes feature availability. Frontmatter `version` selects a documentation edition, `releaseVersion` identifies a changelog release, and `subjectLifecycle` describes feature status. Do not repurpose those fields or add a badge solely for availability.

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

@@ -13,11 +13,11 @@ canonical: /author/writing-style
 
 > 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) > Write documentation > Write with agents > Shared writing guidance > Example writing guide
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)