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

package/agent-docs/publish/agent-friendliness.sections/discover-a-page-with-a-small-context-budget.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,15 +33,15 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
 ## Discover a page with a small context budget
 
-An agent does not need to download every discovery artifact. Start with [`/llms.min.txt`](https://www.shoalrun.com/llms.min.txt), follow a matching topic index when present, and fetch the supplied Markdown page URL. Small indexes list pages directly. Larger indexes group pages by publication and primary taxonomy area, or page type when no area is declared. Topics split into narrower indexes as they grow.
+An agent doesn't need to download every discovery artifact. Start with [`/llms.min.txt`](https://www.shoalrun.com/llms.min.txt), follow a matching topic index when present, and fetch the supplied Markdown page URL. Small indexes list pages directly. Larger indexes group pages by publication and primary taxonomy area, or page type when no area is declared. Topics split into narrower indexes as they grow.
 
 Each compact or navigation-section index is limited to 2,000 `cl100k_base` tokens. This is a limit per response, not a fixed total for every reading task. Page entries retain IDs, titles, summaries, publication labels, and Markdown links. Author-declared standalone sections retain exact sizes and a **Full page** fallback. Default to the full page for setup or broader questions. Every published page remains reachable, including pages outside navigation.
 
@@ -56,6 +56,6 @@ Choose another artifact only when the task needs it:
 | [`documents.sync.json`](https://www.shoalrun.com/documents.sync.json)     | Compare a saved inventory with the current build.                        |
 | [`build-info.json`](https://www.shoalrun.com/build-info.json)             | Check whether the assembled build has changed.                           |
 
-Both search indexes are generated when search indexing is enabled. The full `/search-index.json` includes bounded article text for browser search, CLI search, and custom lexical fallbacks. It remains available, but it is not needed to find a page through the compact list. These files are downloadable indexes, not query endpoints. Shoalrun does not produce `llms-full.txt`.
+Both search indexes are generated when search indexing is enabled. The full `/search-index.json` includes bounded article text for browser search, CLI search, and custom lexical fallbacks. It remains available, but it isn't needed to find a page through the compact list. These files are downloadable indexes, not query endpoints. Shoalrun doesn't produce `llms-full.txt`.
 
 HTML pages provide a visible **Read as Markdown** link, a `rel="alternate"` link, and optional early agent guidance. The guidance links to the article, the compact index, and the current twin. The HTML head’s `rel="describedby"` link and Markdown index backlinks also point to `/llms.min.txt`, so entering through either format leads to the same starting list. Follow those supplied links when a fetch tool rejects guessed URLs. Compact-list links are site-relative; resolve them against the fetched index's origin. Markdown page links use the configured public origin when present.

package/agent-docs/publish/agent-friendliness.sections/distinguish-examples-from-a-real-service.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,16 +33,16 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
 ## Distinguish examples from a real service
 
-Pages under configured `outputs.llms.fictionalPrefixes` carry `demo: true` in the document manifest and both search indexes. The plain-text indexes retain their fictional-example labels. Software can filter these records without interpreting prose. `demo: false` means unmarked; it does not certify that a service exists or is available.
+Pages under configured `outputs.llms.fictionalPrefixes` carry `demo: true` in the document manifest and both search indexes. The plain-text indexes retain their fictional-example labels. Software can filter these records without interpreting prose. `demo: false` means unmarked; it doesn't certify that a service exists or is available.
 
 API-reference pages can also link to a focused, digest-addressed OpenAPI contract containing one operation and its local definitions. This gives an agent an exact contract without requiring the complete API description. The [focused-contract reference](https://www.shoalrun.com/api-docs/focused-contracts.md) explains the export and audit checks.
 
-An API catalog, when configured, links a declared endpoint to its description and documentation. This site's example endpoint uses a reserved `.test` domain and does not describe a live service. A contract or catalog entry is a description, not permission to execute an operation.
+An API catalog, when configured, links a declared endpoint to its description and documentation. This site's example endpoint uses a reserved `.test` domain and doesn't describe a live service. A contract or catalog entry is a description, not permission to execute an operation.

package/agent-docs/publish/agent-friendliness.sections/evidence-has-a-scope.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,14 +33,14 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
 ## Evidence has a scope
 
-Compiler tests, the example above, and digest checks establish specific behavior. They do not substitute for task evaluation or independent factual review. AFDocs checks also inspect discovery, Markdown availability, and HTTP behavior; parity findings need review because authors can intentionally tailor each format.
+Compiler tests, the example above, and digest checks establish specific behavior. They don't substitute for task evaluation or independent factual review. AFDocs checks also inspect discovery, Markdown availability, and HTTP behavior; parity findings need review because authors can intentionally tailor each format.
 
-A local build and passing Node-host checks do not establish what a production host currently serves. Run the deployment checks against the published origin after releasing a build. The [output reference](https://www.shoalrun.com/publish/output.md) and [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) describe the artifacts and live checks separately.
+A local build and passing Node-host checks don't establish what a production host currently serves. Run the deployment checks against the published origin after releasing a build. The [output reference](https://www.shoalrun.com/publish/output.md) and [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) describe the artifacts and live checks separately.

package/agent-docs/publish/agent-friendliness.sections/keep-shared-instructions-complete.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
@@ -43,6 +43,6 @@ Try the example below. Switch the client tab, open **Retry detail**, and choose
 
 Supported tabs and disclosures expand into readable Markdown sections. Reader-marked sections remain present with readable labels, even when a reader choice hides them in interactive HTML. Snippets and API examples resolve during the build. Unknown components and unsupported dynamic MDX fail compilation.
 
-The example above preserves the instructions while changing how they are presented. HTML still has tabs, disclosures, and reader controls. Markdown presents the content in reading order. The formats do not need identical bytes to be useful.
+The example above preserves the instructions while changing how they're presented. HTML still has tabs, disclosures, and reader controls. Markdown presents the content in reading order. The formats don't need identical bytes to be useful.
 
-Authors can deliberately tailor sections to each format with [Only](https://www.shoalrun.com/author/components/only.md). Review those choices for missing prerequisites, warnings, or shared product facts. A build gate can reject an unknown component; it cannot decide whether an intentional omission makes a task impossible. Similarly, [reader views](https://www.shoalrun.com/author/reader-views.md) are presentation controls. They do not authorize access or remove published content from the site's files.
+Authors can deliberately tailor sections to each format with [Only](https://www.shoalrun.com/author/components/only.md). Review those choices for missing prerequisites, warnings, or shared product facts. A build gate can reject an unknown component; it can't decide whether an intentional omission makes a task impossible. Similarly, [reader views](https://www.shoalrun.com/author/reader-views.md) are presentation controls. They don't authorize access or remove published content from the site's files.

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

@@ -17,13 +17,13 @@ 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 > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 

package/agent-docs/publish/agent-friendliness.sections/secret-handshake.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 

package/agent-docs/publish/agent-friendliness.sections/try-the-page-controls.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 

package/agent-docs/publish/agent-friendliness.sections/use-the-transport-your-client-supports.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
@@ -47,4 +47,4 @@ The Shoalrun npm package also bundles this framework's own documentation. `shoal
 
 `shoalrun docs mcp` exposes the local search/read core over stdio. You can also [connect to this site’s public HTTP MCP endpoint](https://www.shoalrun.com/connect/mcp.md). The local read tool applies a token budget and can truncate a response; fetch the published twin when you need complete bytes for digest verification. See [the MCP reference](https://www.shoalrun.com/publish/mcp.md) for its current contract.
 
-Shoalrun does not automatically generate a reader skill for every site. Its maintained authoring skills guide an author's existing agent through writing and validation; teams remain responsible for reviewing their instructions. The [non-goals](https://www.shoalrun.com/non-goals.md) explain that boundary.
+Shoalrun doesn't automatically generate a reader skill for every site. Its maintained authoring skills guide an author's existing agent through writing and validation; teams remain responsible for reviewing their instructions. The [non-goals](https://www.shoalrun.com/non-goals.md) explain that boundary.

package/agent-docs/publish/agent-friendliness.sections/verify-the-page-and-detect-changes.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
@@ -45,13 +45,13 @@ Page identity is the stable document ID plus channel, version, and language. Dif
 
 The manifest exposes three distinct signals:
 
-| Signal               | What it establishes                                                                                          |
-| -------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Page `digest`        | SHA-256 of the complete generated Markdown bytes. Compare it with the bytes you fetched.                     |
-| Page `contentDigest` | A resolved article-content fingerprint used for freshness tracking. It is not the hash of the Markdown file. |
-| Top-level `buildId`  | Identity of the assembled publication, including pages, contracts, assets, and metadata.                     |
+| Signal               | What it establishes                                                                                         |
+| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Page `digest`        | SHA-256 of the complete generated Markdown bytes. Compare it with the bytes you fetched.                    |
+| Page `contentDigest` | A resolved article-content fingerprint used for freshness tracking. It isn't the hash of the Markdown file. |
+| Top-level `buildId`  | Identity of the assembled publication, including pages, contracts, assets, and metadata.                    |
 
-An author-set `verified` date is also available in the manifest. It records supplied review metadata, separately from `updated`; it is not proof that an external reviewer approved the page.
+An author-set `verified` date is also available in the manifest. It records supplied review metadata, separately from `updated`; it isn't proof that an external reviewer approved the page.
 
 For a long-lived client, save the sync snapshot and poll the small build-information file. An unchanged build ID means the saved inventory still applies. When the ID changes, compare the current snapshot with the saved one and refresh added or changed pages. Remove records that disappeared. The comparison includes route moves, metadata changes, and removed publication variants.
 

package/agent-docs/publish/agent-friendliness.sections/what-an-agent-reads.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,15 +33,15 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
 ## What an agent reads
 
-Here is the Markdown generated from the example above. An agent does not need to click the tabs, expand the disclosure, or choose a reader to get these instructions.
+Here is the Markdown generated from the example above. An agent doesn't need to click the tabs, expand the disclosure, or choose a reader to get these instructions.
 
 ```md
 ### Command line
@@ -65,4 +65,4 @@ Open the activity screen to inspect the result.
 Inspect the response status and returned identifier.
 ```
 
-The labels become headings or ordinary text. The controls themselves are omitted. This site's test compares the example's generated Markdown with the text shown here so they cannot drift apart unnoticed. The [reader views reference](https://www.shoalrun.com/author/reader-views.md) explains how authors configure those choices.
+The labels become headings or ordinary text. The controls themselves are omitted. This site's test compares the example's generated Markdown with the text shown here so they can't drift apart unnoticed. The [reader views reference](https://www.shoalrun.com/author/reader-views.md) explains how authors configure those choices.

package/agent-docs/publish/agent-friendliness.sections/what-happens-to-an-unsupported-component.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) > Search, chat, and agent access > Agent-friendly documentation
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
@@ -33,9 +33,9 @@ Parent page: [Full Markdown page](/publish/agent-friendliness.md)
 
 - [Content negotiation](https://www.shoalrun.com/publish/content-negotiation.md) — Serve the Markdown twin when an agent asks for it.
 
-Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices should not make essential content disappear from that copy.
+Shoalrun lets people use an interactive documentation page while agents read a Markdown copy of the same instructions. Tabs, closed disclosures, and reader choices shouldn't make essential content disappear from that copy.
 
-The build checks that it knows how to turn each component into readable Markdown. If it does not, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
+The build checks that it knows how to turn each component into readable Markdown. If it doesn't, it stops with an error. Each generated Markdown page also has a SHA-256 digest, a fingerprint of its bytes. An agent can compare it with the fetched file to verify that the bytes match the published manifest.
 
 Try the example below. Switch the client tab, open **Retry detail**, and choose a reader. Then compare what is visible with the Markdown underneath, which retains both clients, the retry advice, and both reader sections. You can also open [this page's actual Markdown](https://www.shoalrun.com/publish/agent-friendliness.md).
 
@@ -57,4 +57,4 @@ Running `shoalrun check docs.config.yaml` reports a diagnostic containing:
 <UnregisteredPanel> has no semantic/Markdown adapter
 ```
 
-The example is displayed as code here so you can read it. A test also runs it as an actual component, checks that compilation fails, and verifies that the previous successful output remains intact. This check establishes how unsupported components are handled; it does not prove that every supported component or authored instruction is correct.
+The example is displayed as code here so you can read it. A test also runs it as an actual component, checks that compilation fails, and verifies that the previous successful output remains intact. This check establishes how unsupported components are handled; it doesn't prove that every supported component or authored instruction is correct.

package/agent-docs/publish/api-references.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
@@ -138,7 +138,7 @@ notes:
   # Keep source and operations here.
 ```
 
-Replace the angle-bracket placeholder with the actual digest. Keep the candidate local and remove it after review. The digest records what you reviewed; it does not determine whether content is safe. Changing source bytes, selected operations or embeds, focused contracts, or full-source publication requires another review. Changing only authored page copy does not.
+Replace the angle-bracket placeholder with the actual digest. Keep the candidate local and remove it after review. The digest records what you reviewed; it doesn't determine whether content is safe. Changing source bytes, selected operations or embeds, focused contracts, or full-source publication requires another review. Changing only authored page copy doesn't.
 
 ## Build and verify the output
 
@@ -150,7 +150,7 @@ npx --no-install shoalrun serve site-dist --port 8765
 
 Open `http://127.0.0.1:8765/example-api/create-note/` and choose **Create a note** in the sidebar. Confirm the introduction, `POST /notes`, the `201` response with its required `id` field, and the named example. Open `http://127.0.0.1:8765/example-api/create-note.md` to check the same details as Markdown. Follow the focused contract link and check that it contains only this operation and its required contract data.
 
-The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they are not runnable payloads. Generated request commands have not been executed.
+The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they aren't runnable payloads. Generated request commands haven't been executed.
 
 For a larger live example of the documentation layout, see the [fictional Create a note reference](https://www.shoalrun.com/example-api/create-note.md). Its `archivedAt` response field is both **always present** and **nullable**: presence and nullability describe different things. A field marked **may be absent** can be omitted entirely.
 
@@ -158,7 +158,7 @@ Next, [generate and select more API pages](https://www.shoalrun.com/api-docs/gen
 
 ## What readers get
 
-An authored reference adds editorial context to the operation contract. A [generated reference](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) includes the same contract details without an MDX introduction. For tasks spanning several operations, write a linked guide such as [Write a note](https://www.shoalrun.com/example-api/write-note.md). These fictional examples do not imply a live API or tested requests.
+An authored reference adds editorial context to the operation contract. A [generated reference](https://www.shoalrun.com/example-api/generated/get-note-cbedb319.md) includes the same contract details without an MDX introduction. For tasks spanning several operations, write a linked guide such as [Write a note](https://www.shoalrun.com/example-api/write-note.md). These fictional examples don't imply a live API or tested requests.
 
 Response status and media type share a heading row. Descriptions remain visible above property disclosures; enum choices appear below field descriptions. Markdown includes all of this without interactive controls. OpenAPI `deprecated: true` sets the page's status to deprecated; conflicting authored status values fail the build.
 

package/agent-docs/publish/api-references.sections/author-the-reference-page.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/build-and-verify-the-output.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
@@ -41,7 +41,7 @@ npx --no-install shoalrun serve site-dist --port 8765
 
 Open `http://127.0.0.1:8765/example-api/create-note/` and choose **Create a note** in the sidebar. Confirm the introduction, `POST /notes`, the `201` response with its required `id` field, and the named example. Open `http://127.0.0.1:8765/example-api/create-note.md` to check the same details as Markdown. Follow the focused contract link and check that it contains only this operation and its required contract data.
 
-The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they are not runnable payloads. Generated request commands have not been executed.
+The HTML uses a reference column and an API data panel at wide widths; on narrow screens the panel follows the article. The Markdown twin contains every property, variant, enum choice, and named example in reading order. JSON shapes use type placeholders; they aren't runnable payloads. Generated request commands haven't been executed.
 
 For a larger live example of the documentation layout, see the [fictional Create a note reference](https://www.shoalrun.com/example-api/create-note.md). Its `archivedAt` response field is both **always present** and **nullable**: presence and nullability describe different things. A field marked **may be absent** can be omitted entirely.
 

package/agent-docs/publish/api-references.sections/inspect-the-machine-readable-contract.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/next-steps.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/preview-a-small-api-reference.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/put-the-spec-in-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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/register-the-operation.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/related-reading.md

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 

package/agent-docs/publish/api-references.sections/review-imported-content-before-publishing.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) > Document an API > Add an OpenAPI API
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-05.**
 
 Parent page: [Full Markdown page](/publish/api-references.md)
 
@@ -27,7 +27,7 @@ Parent page: [Full Markdown page](/publish/api-references.md)
 
 - [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — Include named examples and selected schemas in your guides.
 
-Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You will register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
+Add one authored API reference to the project created in the [quickstart](https://www.shoalrun.com/start.md). This walkthrough uses a fictional Notes API as its example. You'll register an operation, write its introduction, add it to navigation, review the imported content, and verify its published files.
 
 Run commands from the documentation project directory created in the quickstart, where `@shoalrun/cli` is installed. The commands use that local package. Check [OpenAPI support and limits](https://www.shoalrun.com/api-docs/support.md) before importing a larger specification.
 
@@ -51,4 +51,4 @@ notes:
   # Keep source and operations here.
 ```
 
-Replace the angle-bracket placeholder with the actual digest. Keep the candidate local and remove it after review. The digest records what you reviewed; it does not determine whether content is safe. Changing source bytes, selected operations or embeds, focused contracts, or full-source publication requires another review. Changing only authored page copy does not.
+Replace the angle-bracket placeholder with the actual digest. Keep the candidate local and remove it after review. The digest records what you reviewed; it doesn't determine whether content is safe. Changing source bytes, selected operations or embeds, focused contracts, or full-source publication requires another review. Changing only authored page copy doesn't.