@shoalrun/cli 0.1.0-alpha.17 → 0.1.0-alpha.18

package/agent-docs/publish/vercel.sections/include-an-mcp-endpoint.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Publish on Vercel
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/vercel.md)
 
@@ -35,4 +35,4 @@ The [content negotiation guide](https://www.shoalrun.com/publish/content-negotia
 
 Enable `mcp` in your project config before running `shoalrun vercel build`. The output includes a separate Node function for the selected public publication, without requiring Ask or embeddings. See [connect an MCP client](https://www.shoalrun.com/publish/mcp.md) for configuration, host trust, limits, and the current verification status.
 
-MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings do not collect MCP traffic.
+MCP analytics remains off unless you also configure its [server adapter](https://www.shoalrun.com/publish/mcp-analytics.md). If enabled, set its credentials on the function’s runtime environment. Browser analytics settings don't collect MCP traffic.

package/agent-docs/publish/vercel.sections/prepare-your-project.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Publish on Vercel
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/vercel.md)
 
@@ -49,4 +49,4 @@ Set `site.origin` in `docs.config.yaml` to your intended public HTTPS origin bef
 npx --no-install shoalrun vercel build docs.config.yaml .vercel/output
 ```
 
-Generating output does not deploy it.
+Generating output doesn't deploy it.

package/agent-docs/publish/vercel.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Publish on Vercel
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/vercel.md)
 

package/agent-docs/publish.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Deploy your documentation
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 After the [quickstart](https://www.shoalrun.com/start.md), your documentation project has `@shoalrun/cli` installed. Run the commands below from that project directory, `my-docs/`.
 
@@ -60,7 +60,7 @@ For a local check, use `http://localhost:8080/install/` and `http://localhost:80
 
 ### Other hosts
 
-A static upload alone does not establish Markdown content negotiation. Configure the host to serve the resources and page variants described in [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), including `Vary: Accept`, content types, Markdown alternate links, redirects, and 404 responses. Use [generated outputs](https://www.shoalrun.com/publish/output.md) to identify the files to deploy.
+A static upload alone doesn't establish Markdown content negotiation. Configure the host to serve the resources and page variants described in [content negotiation](https://www.shoalrun.com/publish/content-negotiation.md), including `Vary: Accept`, content types, Markdown alternate links, redirects, and 404 responses. Use [generated outputs](https://www.shoalrun.com/publish/output.md) to identify the files to deploy.
 
 ## Verify the public site
 

package/agent-docs/recipes/add-page.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Create a guide, add navigation, build and audit it, then refresh its agent documentation.
 
@@ -76,7 +76,7 @@ Set a suitable `card.icon`, such as `file-text`, to meet this site's page-card a
 - { id: my-new-guide, doc: guide.my-new-guide }
 ```
 
-For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it does not deploy the site.
+For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it doesn't deploy the site.
 
 Save `authoredPage`: The completed public page and its navigation entry, ready for a local build.
 
@@ -94,7 +94,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 
@@ -140,7 +140,7 @@ Run Shoalrun's configured checks. This repository's formatting check requires [V
 npx --no-install shoalrun audit docs/docs.config.yaml
 ```
 
-The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command doesn't run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
 
 Save `auditPassed`: A successful audit report with no failed configured checks.
 
@@ -157,7 +157,7 @@ Export the already built site for the framework’s next documentation snapshot:
 npm run agent-docs:build
 ```
 
-Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It does not modify the installed package.
+Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It doesn't modify the installed package.
 
 Review and transfer the export as a versioned artifact to the framework repository. Framework releases consume an explicitly selected snapshot; they must not fetch the latest site during a package build.
 

package/agent-docs/recipes/add-page.sections/audit-the-shoalrun-docs-project.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 
@@ -33,7 +33,7 @@ Run Shoalrun's configured checks. This repository's formatting check requires [V
 npx --no-install shoalrun audit docs/docs.config.yaml
 ```
 
-The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command doesn't run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
 
 Save `auditPassed`: A successful audit report with no failed configured checks.
 

package/agent-docs/recipes/add-page.sections/before-you-start.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/build-the-shoalrun-docs-site.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 
@@ -35,7 +35,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 

package/agent-docs/recipes/add-page.sections/check-agent-search-and-page-lookup.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/check-the-built-page-artifacts.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/check-the-outcome.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/complete-the-guide-and-add-navigation.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 
@@ -35,7 +35,7 @@ Set a suitable `card.icon`, such as `file-text`, to meet this site's page-card a
 - { id: my-new-guide, doc: guide.my-new-guide }
 ```
 
-For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it does not deploy the site.
+For useful next steps, add edges to `docs/config/relationships.yaml` and put `<RelatedReading />` at the end of the page. Preserve the page ID if you later change its title or slug. Setting public access includes the page in the local build; it doesn't deploy the site.
 
 Save `authoredPage`: The completed public page and its navigation entry, ready for a local build.
 

package/agent-docs/recipes/add-page.sections/install-the-site-dependencies.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/regenerate-the-agent-documentation-bundle.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 
@@ -34,7 +34,7 @@ Export the already built site for the framework’s next documentation snapshot:
 npm run agent-docs:build
 ```
 
-Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It does not modify the installed package.
+Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It doesn't modify the installed package.
 
 Review and transfer the export as a versioned artifact to the framework repository. Framework releases consume an explicitly selected snapshot; they must not fetch the latest site during a package build.
 

package/agent-docs/recipes/add-page.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/add-page.sections/scaffold-a-new-guide.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Add a page to this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/recipes/add-page.md)
 

package/agent-docs/recipes/audit-docs.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Build and audit this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Build current documentation, check its artifacts, and run the configured audits.
 
@@ -58,7 +58,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 
@@ -104,7 +104,7 @@ Run Shoalrun's configured checks. This repository's formatting check requires [V
 npx --no-install shoalrun audit docs/docs.config.yaml
 ```
 
-The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command doesn't run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
 
 Save `auditPassed`: A successful audit report with no failed configured checks.
 
@@ -112,7 +112,7 @@ Save `auditPassed`: A successful audit report with no failed configured checks.
 
 ## Check the outcome
 
-The current source builds, the selected page has both output formats, and all configured audits pass. Review the rendered change before publishing; this recipe does not deploy or run the full framework test suite.
+The current source builds, the selected page has both output formats, and all configured audits pass. Review the rendered change before publishing; this recipe doesn't deploy or run the full framework test suite.
 
 ## Related reading
 

package/agent-docs/recipes/build-docs.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Build this documentation site
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Use the pinned Shoalrun package and confirm a chosen page has HTML and Markdown output.
 
@@ -57,7 +57,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 

package/agent-docs/recipes/preview-hybrid-search.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Preview semantic search in this checkout
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
 Build the Shoalrun docs, index passages, and verify vector retrieval and lexical fallback locally.
 
@@ -53,9 +53,9 @@ Save `indexedSite`: The successful site build and current passage index under do
 npm run docs:search-preview
 ```
 
-Open `http://127.0.0.1:8770/`. This command occupies the terminal. Restart it after rebuilding the passage index, because the local endpoint reads its files at startup. Vector results include only passages with current embeddings. Reindex after editing pages so semantic results include the changed passages. A literal configuration key or command flag can also recover one word-matching explanation, but this is not a substitute for refreshing vectors.
+Open `http://127.0.0.1:8770/`. This command occupies the terminal. Restart it after rebuilding the passage index, because the local endpoint reads its files at startup. Vector results include only passages with current embeddings. Reindex after editing pages so semantic results include the changed passages. A literal configuration key or command flag can also recover one word-matching explanation, but this isn't a substitute for refreshing vectors.
 
-The browser search provider first asks `/__shoalrun/search`. That endpoint ranks passages by embedding similarity and returns page or section links. Successful semantic queries keep their first two pages ranked by meaning. A question containing dotted configuration keys or command flags can include one exact-identifier prose explanation as the third result. Filenames and requests for fewer than three results keep semantic ranking. It does not call the chat model. If the endpoint has no current vectors, it returns lexical passage results. If the endpoint is missing, slow, or fails, the browser uses `search-index.json` for lexical page search.
+The browser search provider first asks `/__shoalrun/search`. That endpoint ranks passages by embedding similarity and returns page or section links. Successful semantic queries keep their first two pages ranked by meaning. A question containing dotted configuration keys or command flags can include one exact-identifier prose explanation as the third result. Filenames and requests for fewer than three results keep semantic ranking. It doesn't call the chat model. If the endpoint has no current vectors, it returns lexical passage results. If the endpoint is missing, slow, or fails, the browser uses `search-index.json` for lexical page search.
 
 Save `runningPreview`: The local site and search endpoint while the server is running.
 
@@ -65,9 +65,9 @@ Save `runningPreview`: The local site and search endpoint while the server is ru
 
 - Use `runningPreview` from **Start the semantic endpoint**.
 
-Search for `navigation`, then describe a task in your own words without copying a page title or sentence. For example, ask about reusing warnings across documentation. Lexical search can now return partial matches for the sentence; returning a result alone does not prove semantic retrieval worked.
+Search for `navigation`, then describe a task in your own words without copying a page title or sentence. For example, ask about reusing warnings across documentation. Lexical search can now return partial matches for the sentence; returning a result alone doesn't prove semantic retrieval worked.
 
-In the browser Network inspector, inspect `/__shoalrun/search`. A successful response with `"mode": "vector"` confirms the endpoint used embeddings. `"mode": "lexical"` means the endpoint returned word-matching results. It can do this when current document vectors are missing, the embedding budget is exhausted, the provider fails, or the three-second deadline expires. The response mode alone does not tell you whether document vectors exist. A failed request followed by results demonstrates the browser provider's lexical fallback. For a preview without the endpoint, stop this server and run `npm run docs:preview`.
+In the browser Network inspector, inspect `/__shoalrun/search`. A successful response with `"mode": "vector"` confirms the endpoint used embeddings. `"mode": "lexical"` means the endpoint returned word-matching results. It can do this when current document vectors are missing, the embedding budget is exhausted, the provider fails, or the three-second deadline expires. The response mode alone doesn't tell you whether document vectors exist. A failed request followed by results demonstrates the browser provider's lexical fallback. For a preview without the endpoint, stop this server and run `npm run docs:preview`.
 
 Save `modeEvidence`: The response mode and relevant page or section links for the queries.
 

package/agent-docs/recipes/preview-page.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Preview a documentation change locally
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Build current documentation and inspect its HTML and Markdown over local HTTP.
 
@@ -56,7 +56,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 

package/agent-docs/recipes/queue-email.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Cookbook example > Queue a welcome email
 
-**Updated: 2026-10-25.**
+**Updated: 2026-11-05.**
 
 Use this path to check request acceptance. For delivery status and failure handling, follow [the complete delivery recipe](https://www.shoalrun.com/recipes/send-welcome-email.md).
 
@@ -46,4 +46,4 @@ printf '\nMessage ID: %s\n' "$MESSAGE_ID"
 
 ## Check the outcome
 
-The HTTP status is 202, the response says `status: queued`, and the returned `id` is nonempty. Keep that ID if you will check delivery later. A failed POST needs its own diagnostic; do not reuse an ID from an earlier attempt. Acceptance leaves delivery unknown.
+The HTTP status is 202, the response says `status: queued`, and the returned `id` is nonempty. Keep that ID if you'll check delivery later. A failed POST needs its own diagnostic; don't reuse an ID from an earlier attempt. Acceptance leaves delivery unknown.

package/agent-docs/recipes/refresh-agent-docs.md

@@ -16,7 +16,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Maintain this documentation site > Refresh Shoalrun's bundled agent docs
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Regenerate offline docs, verify CLI search and read, and run project audits.
 
@@ -57,7 +57,7 @@ npx --no-install shoalrun build docs/docs.config.yaml docs/dist
 
 The source configuration is `docs/docs.config.yaml`; output goes to `docs/dist`. The root shortcut is `npm run docs:build`; it uses the installed package.
 
-If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone is not evidence of a successful new build.
+If the build fails, fix the named source or configuration issue and rerun it. A previous successful output can remain on disk after a failure, so file existence alone isn't evidence of a successful new build.
 
 Save `builtSite`: The successful site build at docs/dist, including documents.json and each published page.
 
@@ -74,7 +74,7 @@ Export the already built site for the framework’s next documentation snapshot:
 npm run agent-docs:build
 ```
 
-Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It does not modify the installed package.
+Build the site first. The export copies that output without rebuilding and records the site build identity and pinned package integrity in `agent-docs/provenance.json`. It doesn't modify the installed package.
 
 Review and transfer the export as a versioned artifact to the framework repository. Framework releases consume an explicitly selected snapshot; they must not fetch the latest site during a package build.
 
@@ -110,7 +110,7 @@ Run Shoalrun's configured checks. This repository's formatting check requires [V
 npx --no-install shoalrun audit docs/docs.config.yaml
 ```
 
-The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command does not run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
+The audit checks configured project commands, API representations, and focused contracts. Read any reported finding and fix its source before continuing. This command doesn't run the complete framework test suite or replace a browser review. Framework source changes and tests belong in the framework repository.
 
 Save `auditPassed`: A successful audit report with no failed configured checks.
 

package/agent-docs/recipes/send-welcome-email.md

@@ -17,14 +17,14 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Cookbook example > Send a welcome email and confirm delivery
 
-**Updated: 2026-11-04.**
+**Updated: 2026-11-05.**
 
 Follow one message from an accepted request through delivery, and inspect a simulated failure.
 
 ## Before you start
 
 - `API_BASE`: Set `export API_BASE=http://127.0.0.1:8787/v1` in your command terminal.
-- From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it is already running, reuse it.
+- From the Shoalrun repository root, run `node framework/example-configs/notifications/demo.mjs` in a separate terminal and keep it running. If it's already running, reuse it.
 - Use a scratch directory for queued.json and delivery.json. These commands replace those files.
 - Have cURL and Node.js available in your command terminal.
 
@@ -45,7 +45,7 @@ MESSAGE_ID=$(node -p "JSON.parse(require('fs').readFileSync('queued.json', 'utf8
 printf '\nMessage ID: %s\n' "$MESSAGE_ID"
 ```
 
-A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Do not reuse a message ID from an earlier attempt.
+A successful response looks like `{"id":"msg_…","status":"queued"}`. If the POST fails, inspect its HTTP status and response before continuing. Don't reuse a message ID from an earlier attempt.
 
 Save `MESSAGE_ID`: The id returned in queued.json; use this exact value for the delivery check.
 
@@ -54,7 +54,7 @@ Save `MESSAGE_ID`: The id returned in queued.json; use this exact value for the
 ## Check delivery for that message
 
 - Use `API_BASE` from **Before you start**: Use the same environment as the queue request.
-- Use `MESSAGE_ID` from **Queue the welcome email**: Put the returned ID into the status URL; do not substitute the example ID.
+- Use `MESSAGE_ID` from **Queue the welcome email**: Put the returned ID into the status URL; don't substitute the example ID.
 
 Look up the message using the ID saved in the previous step:
 
@@ -67,23 +67,23 @@ cat delivery.json
 
 The local demo returns `queued` on the first lookup. Run the lookup once more to see its terminal status. This deterministic transition is part of the simulation; a real provider needs its own polling interval and timeout.
 
-| Status or error    | What to do next                                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `queued`           | The request was accepted; delivery is still pending. In this demo, repeat the lookup once.                          |
-| `delivered`        | Check that `id` matches `MESSAGE_ID`. The delivery check is complete.                                               |
-| `failed`           | Inspect `failureReason`. Correct the cause before creating another message; do not keep polling a terminal failure. |
-| HTTP 404           | Check the saved ID and API base URL. Restarting the demo clears its messages.                                       |
-| Connection refused | Start the demo and check that it is listening on port 8787.                                                         |
+| Status or error    | What to do next                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `queued`           | The request was accepted; delivery is still pending. In this demo, repeat the lookup once.                         |
+| `delivered`        | Check that `id` matches `MESSAGE_ID`. The delivery check is complete.                                              |
+| `failed`           | Inspect `failureReason`. Correct the cause before creating another message; don't keep polling a terminal failure. |
+| HTTP 404           | Check the saved ID and API base URL. Restarting the demo clears its messages.                                      |
+| Connection refused | Start the demo and check that it's listening on port 8787.                                                         |
 
 To exercise failure handling, repeat the queue step with `blocked@example.com`, save its new message ID, and check that ID twice. The demo returns `failed` with `failureReason: recipient_rejected`.
 
 Save `deliveryStatus`: The status returned for MESSAGE_ID in delivery.json.
 
-**Continue when:** The response id equals MESSAGE_ID and status is delivered. Queued and failed do not satisfy this recipe's goal.
+**Continue when:** The response id equals MESSAGE_ID and status is delivered. Queued and failed don't satisfy this recipe's goal.
 
 ## Check the outcome
 
-The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still does not prove the recipient read it.
+The final response contains the same message ID you saved and `status: delivered`. You have verified the simulated delivery flow. The local demo sends no email; a real provider reporting delivery still doesn't prove the recipient read it.
 
 ## Related reading
 

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

@@ -17,11 +17,11 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Bundled agent skills
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-Shoalrun ships five portable skill folders under `framework/skills/`. Each folder contains a `SKILL.md` with instructions for an agent that can read files and run the Shoalrun CLI. A skill supplies guidance; it does not run a separate authoring service.
+Shoalrun ships five portable skill folders under `framework/skills/`. Each folder contains a `SKILL.md` with instructions for an agent that can read files and run the Shoalrun CLI. A skill supplies guidance; it doesn't run a separate authoring service.
 
-These are authoring skills for Shoalrun. The build does not create a reader-side skill for each published site. Agents reading a generated site use its Markdown twins, `/llms.txt`, and `/documents.json`. A non-interactive skill builder is a [non-goal](https://www.shoalrun.com/non-goals.md): skill creation and maintenance need guidance from a human expert.
+These are authoring skills for Shoalrun. The build doesn't create a reader-side skill for each published site. Agents reading a generated site use its Markdown twins, `/llms.txt`, and `/documents.json`. A non-interactive skill builder is a [non-goal](https://www.shoalrun.com/non-goals.md): skill creation and maintenance need guidance from a human expert.
 
 ## Skill inventory
 
@@ -41,13 +41,13 @@ Each folder name matches its skill name. For example, the author skill's entry f
 
 The setup skill uses `shoalrun init` to create a project from the bundled `minimal` or `api-docs` starter, then uses `config validate`, `build`, and `dev` to check the result. The author skill uses stable IDs and project config provenance so edits stay attached to the intended publication. The walkthrough skill chooses a mode and layout, prefers code taken from project files, and checks each step's highlight. The recipes skill starts from a reader goal and success check, reuses ingredient source when useful, and distinguishes authoring from browser selection. All five ask the agent to inspect generated HTML and Markdown. They leave deployment decisions with the site owner.
 
-The author skill starts with project-wide discovery and policy reads, captures a task baseline, and edits ordinary working-tree files. It validates a separate capture and opens the matching snapshot review/preview. Required companions come from project policy; compiler success does not waive them. Existing local edits are included in the baseline rather than attributed to the new task. No extra authoring model key is needed. Explicit checked-plan clients can still use [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md).
+The author skill starts with project-wide discovery and policy reads, captures a task baseline, and edits ordinary working-tree files. It validates a separate capture and opens the matching snapshot review/preview. Required companions come from project policy; compiler success doesn't waive them. Existing local edits are included in the baseline rather than attributed to the new task. No extra authoring model key is needed. Explicit checked-plan clients can still use [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md).
 
 ## Component-authoring skill
 
 `shoalrun-component-author` guides a coding agent through creating or repairing a trusted component plugin. It asks the agent to inventory essential content and decide what belongs in MDX and data. The agent then writes validation and shared content, adds browser controls where needed, and tests both representations. The agent produces project files, fixtures, usage examples, check results, and a local preview for review.
 
-The skill is an instruction file, not a compiler feature or an automatic React-to-Markdown converter. The component author and agent must write the complete static explanation. A passing build does not establish that every interactive choice or warning is represented faithfully. [Custom components](https://www.shoalrun.com/author/components/custom.md) shows a small copy button with content in MDX, generated Markdown, and a sample agent request. [Data-driven React components](https://www.shoalrun.com/author/components/custom/react.md) adds a local policy file and generated explanations.
+The skill is an instruction file, not a compiler feature or an automatic React-to-Markdown converter. The component author and agent must write the complete static explanation. A passing build doesn't establish that every interactive choice or warning is represented faithfully. [Custom components](https://www.shoalrun.com/author/components/custom.md) shows a small copy button with content in MDX, generated Markdown, and a sample agent request. [Data-driven React components](https://www.shoalrun.com/author/components/custom/react.md) adds a local policy file and generated explanations.
 
 ## Offline documentation
 
@@ -58,11 +58,11 @@ shoalrun docs search "API reference navigation"
 shoalrun docs read guide.api-references
 ```
 
-Search returns JSON with document IDs and excerpts. Read returns the complete generated Markdown page. The commands work offline and do not require a docs site to be running. They are useful to any agent that can run a CLI, even when it cannot discover `SKILL.md` files automatically.
+Search returns JSON with document IDs and excerpts. Read returns the complete generated Markdown page. The commands work offline and don't require a docs site to be running. They're useful to any agent that can run a CLI, even when it can't discover `SKILL.md` files automatically.
 
 ## Limits
 
-Skills guide the agent's actions. They cannot establish whether a technical claim is true. Shoalrun's [audit](https://www.shoalrun.com/publish/audit.md) checks implemented build and representation rules and any configured external tests. Human review and behavior tests establish whether the instructions work.
+Skills guide the agent's actions. They can't establish whether a technical claim is true. Shoalrun's [audit](https://www.shoalrun.com/publish/audit.md) checks implemented build and representation rules and any configured external tests. Human review and behavior tests establish whether the instructions work.
 
 The recipes skill prefers complete task pages, adds ingredients when instructions are shared, and uses cookbooks when readers need help choosing tasks. It respects an explicitly requested format. [Ingredients, recipes, and cookbooks](https://www.shoalrun.com/author/recipes.md) explains those distinctions.
 

package/agent-docs/search-and-chat.md

@@ -17,9 +17,9 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Search, chat, and agent access > Overview
 
-**Updated: 2026-10-26.**
+**Updated: 2026-11-05.**
 
-Start with [site search](https://www.shoalrun.com/author/search.md) if readers need links to pages and sections. It is built in, works on a static host, and needs no provider account. Add chat when readers need answers written from your documentation.
+Start with [site search](https://www.shoalrun.com/author/search.md) if readers need links to pages and sections. It's built in, works on a static host, and needs no provider account. Add chat when readers need answers written from your documentation.
 
 ## Choose the result you want
 
@@ -31,7 +31,7 @@ These features have different setup and hosting needs. Passage retrieval and cha
 | Links that can match different wording | [Semantic search preview](https://www.shoalrun.com/recipes/preview-hybrid-search.md) | A passage index, embeddings, and a local search endpoint. The provider can fall back to keyword search.               |
 | An answer with source citations        | [Documentation chat](https://www.shoalrun.com/chat/setup.md)                         | A passage index, a configured chat service, and a terminal or server. Embeddings and a scorer are optional additions. |
 
-The sidebar's [navigation filter](https://www.shoalrun.com/author/navigation.md) only narrows the menu. Its search words do not change site-search results. The search dropdown returns links; it does not call a chat model.
+The sidebar's [navigation filter](https://www.shoalrun.com/author/navigation.md) only narrows the menu. Its search words don't change site-search results. The search dropdown returns links; it doesn't call a chat model.
 
 ## Start with a local chat
 
@@ -65,7 +65,7 @@ Fallback behavior depends on the configured feature.
 | Situation                                                    | Result                                                                      |
 | ------------------------------------------------------------ | --------------------------------------------------------------------------- |
 | Built-in search has no server or provider key                | Browser keyword search still works.                                         |
-| This site's custom search provider cannot reach its endpoint | It uses the browser keyword index.                                          |
+| This site's custom search provider can't reach its endpoint  | It uses the browser keyword index.                                          |
 | A search endpoint has no current vectors, or embeddings fail | It returns keyword passage results.                                         |
 | Chat has no current vectors                                  | Retrieval uses keywords. A configured chat model can still write an answer. |
 | A deployment has no chat function                            | The site remains available, but has no chat endpoint.                       |