@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 0.1.0-alpha.14 — 2026-10-30
+
+- Keep selected text readable in light and dark modes by pairing the selection
+  background with its contrasting foreground color.
+- Let paragraphs and ordinary lists fill their containers in wide, landing, and
+  splash layouts, including nested sections. Standard pages retain the 68ch
+  reading measure; hero text and other components keep their own limits.
+
+Upgrade to alpha.14 and rebuild your site to receive these styling fixes.
+
+## 0.1.0-alpha.13 — 2026-10-28
+
+Use documentation as content for applications, agents, services, and publishing
+workflows. Content delivery adds selected sections and named snippet instances to
+whole-page exports, with a shared client interface for static bundles and REST.
+
+- Read reviewed HTML or Markdown with `@shoalrun/cli/content`. The mount helper
+  rewrites IDs and links so the same content can appear more than once in an app.
+- Use heading-derived section IDs or preserve a reference with a trailing
+  `<Anchor id="refunds" />`. Declare `{ id: refunds, context: section }` in
+  `standaloneSections` after reviewing that section without the rest of its page.
+- Serve the same snapshots with `createContentRestHandler` and read them with
+  `openRestContentSource`. HTTP contract v1 covers resource lists, metadata,
+  representations, explicit publication and revision selection, and ETags.
+  Authentication, search, editing, and production hosting remain host concerns.
+- Compare exports using `--previous-manifest`; add `--fail-on-removed` to reject
+  removed references. Use immutable revision directories for running clients.
+- Render schema-based OpenAPI response headers in native API references. Generated
+  request samples handle HEAD responses and text representations correctly.
+- Show authored `verified` dates as labeled semantic dates in HTML page headers,
+  independently of `updated`. Set `showVerified: false` on a page or through
+  frontmatter defaults to hide verification in HTML only. Builds never assign it.
+- Find content-delivery guides, client and HTTP references, and clearer layout
+  choices in the bundled docs. The layout guide explains `layout: wide` versus
+  `tocDepth: 0`; section guidance explains what the author declaration means.
+
+- Preserve literal scaffold TODO examples inside fenced code in both outputs;
+  unfinished prompts in prose and frontmatter still block publication.
+- Suggest native relationships during project discovery and validation when
+  related-reading sections contain document links. Hints are nonblocking and
+  never create relationships automatically. The component index maps tasks to
+  native features.
+
+- Hide or rename the sidebar’s “Explore” heading with
+  `outputs.html.navigation.heading`; `false` hides it while retaining the filter label.
+
+- Remove the page-sized focus rectangle after clicking article content. Keyboard
+  jumps still focus the article and indicate the destination at its title.
+
+**Upgrade:** Rebuild exports and update custom consumers from `manifest.documents`
+to `manifest.resources` with typed `ref` objects. Existing `documents` selectors
+remain page-selection shorthand. Read paths from the new manifest; do not retain
+old payload paths. Whole-page consumers can use the updated help-drawer example;
+the content-delivery example demonstrates both transports and repeated mounts.
+
 ## 0.1.0-alpha.12 — 2026-10-27
 
 - Refresh the bundled documentation from the reviewed public site: organize navigation into Docs, Reference, Examples, and Project; use installed-package commands in customer workflows; and standardize component reference sections.

package/README.md

@@ -9,13 +9,13 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.12
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.14
 ```
 
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.12 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.14 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
@@ -124,7 +124,7 @@ exports:
 ```
 
 Run `shoalrun export docs.config.yaml --target app-help --out app/public/help`.
-Omit `documents` to export all eligible public pages in one enabled publication;
+Omit both `documents` and `resources` to export all eligible public pages in one enabled publication;
 select an explicit publication when more than one is enabled. Export selection
 is independent of the website's `site.contentFilter` and navigation. Selected
 pages retain all reader sections as labeled static content. Tabs and walkthroughs
@@ -144,10 +144,31 @@ older export is replaced.
 
 See [the help-drawer example](examples/help-drawer/README.md) for a plain-JavaScript
 consumer and local preview. The [export manifest schema](schemas/content-export.schema.json)
-describes the file contract. Mount each document once per DOM; repeated instances
-need consumer-side ID and reference rewriting. Whole-page exports do not include
+describes the file contract. Direct HTML insertion requires consumer-side ID and
+reference rewriting for repeated instances; the content-delivery mount helper
+provides that rewriting. Whole-page exports do not include
 website navigation, search/chat runtimes, themes, or heuristic section resources.
 
+## Content delivery
+
+Content delivery extends export to selected pages, standalone sections, and named snippet instances. Applications can use the browser-safe client with a static manifest or a read-only REST endpoint. Static delivery requires no server or model provider.
+
+```ts
+import { openManifestContentSource } from '@shoalrun/cli/content';
+
+const source = await openManifestContentSource({
+  manifestUrl: '/content/releases/r42/manifest.json',
+});
+const resource = await source.get(
+  { kind: 'section', documentId: 'guide.billing', sectionId: 'refunds' },
+  { format: 'html' },
+);
+```
+
+Heading-derived section IDs are the default. Optional explicit IDs preserve references across heading renames. Export comparisons report removed references when a previous manifest is supplied. Each opened source stays on one publication and revision; open a new source to update it.
+
+See the [content-delivery example](examples/content-delivery/README.md) for resource selection, instance-safe HTML mounting, and a complete local preview. The example also runs the REST adapter and demonstrates `openRestContentSource` with the same reading interface. See the [OpenAPI contract](schemas/content-rest.openapi.json) for the HTTP API. Authentication, search, and production hosting remain application concerns.
+
 ## Publish discovery files
 
 Set `site.origin` to the HTTPS origin (for example, `https://example.github.io`)
@@ -190,3 +211,22 @@ Pin an exact package version and read the [changelog](CHANGELOG.md) before upgra
 ## License
 
 Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.
+
+## Verification dates
+
+Set `verified` only after checking a page's technical claims. It is separate from
+`updated`, which records content revision. Both appear as labeled `<time>` elements
+in the standard HTML page header, and as dates in Markdown and `documents.json`.
+Builds never assign `verified`.
+
+```yaml
+updated: 2026-10-28
+verified: 2026-10-27
+showVerified: false
+```
+
+`showVerified` defaults to `true`. Set it to `false` to hide the verification date
+in HTML only; Markdown and manifest metadata retain it. Set
+`frontmatter.defaults.showVerified: false` in project configuration for a shared
+default, then override it with `showVerified: true` on individual pages. A layout
+with a Hero replaces the standard page header and does not display its dates.

package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -14,13 +14,15 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Clearer defaults, a feature showcase, and easier navigation](https://www.shoalrun.com/changelog/2026-10-27.md) — ID: change.2026-10-27. changelog-entry; 1223 tokens. Explore a complete starter, read clearer controls, and find focused configuration references alongside the new mobile navigation.
 
+- [Content delivery, verification dates, and clearer references](https://www.shoalrun.com/changelog/2026-10-28.md) — ID: change.2026-10-28. changelog-entry; 1393 tokens. Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.
+
 - [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 551 tokens. Snapshot previews with coverage and freshness reports.
 
 - [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 466 tokens. Reviewed agent drafts, search improvements, and answer context.
 
 - [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 378 tokens. Project discovery and captured working-tree validation.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 999 tokens. Compiler, CLI, and reader changes.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1074 tokens. Compiler, CLI, and reader changes.
 
 - [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1145 tokens. MCP hosting, analytics, and shared component content.
 

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "0e40930cc80207ff9cb22fcaade5fc5dbdd464a5",
-  "siteBuildId": "1aae676cf02856842a383f9e8f28b2b126e18cfbc75050227980b1d3d82762b6",
-  "manifestDigest": "5b181b5e3d09eaae37afaf0f08ce5c725ea393029df4cec8ad62c44939b07fe7",
-  "indexDigest": "57736349c41e4b36d0b9726e76b512415b85443d49eababbd3387fa416c996c9",
-  "packageIntegrity": "sha512-NmM2tIR7SSyz8STTZluEsATZZBcTrgH6mWBTjOju7Qz3E60onSrQF93IXmBuhBiInw+Zq9mysUAk8Lvo/UDj6Q=="
+  "sourceCommit": "fe92983e9f5710d9c2265972a2477448df4ae82d",
+  "siteBuildId": "38aac8472fa1fad778acd5b5bdc30067474eca35755706d09f916914326ed2f0",
+  "manifestDigest": "c99f0684ea93c4add58ddee1fd19dc82fa1acd9099d6cc2b4b226a0ef85302fe",
+  "indexDigest": "f38899eb2e53af8600714002a64538fb436d3cf90fa8e1247d3e892ef703fc48",
+  "packageIntegrity": "sha512-Qs6yv+QFvt6L5huiKFQfIT5FYexxbSokwUVUnxIrXUx2TtY/VTdG0EKAJJuCLLi6FcrYVbnI/mC9uWqJ9nflsw=="
 }

package/agent-docs/api-docs/support.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > API support > OpenAPI support and limits
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Shoalrun renders a defined subset of OpenAPI into HTML, Markdown, and focused contracts. Check these limits before importing a large specification. A supported OpenAPI version does not mean every feature in that version can be rendered.
 
@@ -60,15 +60,16 @@ Exclusive bounds follow the entry document's version even when a schema lives in
 
 These features have limits that may require adapting the source or authored documentation.
 
-| Feature                         | Current limit and recovery                                                                                                                                                                                                                |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Remote `$ref` in a normal build | Fails with `Remote $ref requires a pinned snapshot`. Use `api import` for public HTTPS sources with same-origin relative references, then build from its local snapshot. Cross-origin references need a separately prepared local source. |
-| Local `externalValue`           | Fails with `local externalValue needs a pinned adapter`. Use a local inline example value, or an HTTPS external example link.                                                                                                             |
-| Callbacks                       | Operation callbacks fail with an unsupported feature diagnostic. Top-level 3.1 webhooks are supported separately.                                                                                                                         |
-| Response headers and links      | Fail with `Response headers or links need an adapter`. Prepare a supported documentation source while retaining the original contract separately.                                                                                         |
-| Parameter `content`             | Requires an adapter; use supported parameter schemas in the documentation source.                                                                                                                                                         |
-| Request media `encoding`        | Fails with `Request encoding needs an adapter`. Multipart binary fields have limited generated upload commands, but media encoding settings are not rendered.                                                                             |
-| Other schema keywords           | Fail with `Unsupported schema keyword`. Adapt the documentation source without claiming omitted constraints are represented.                                                                                                              |
+| Feature                         | Current limit and recovery                                                                                                                                                                                                                               |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Remote `$ref` in a normal build | Fails with `Remote $ref requires a pinned snapshot`. Use `api import` for public HTTPS sources with same-origin relative references, then build from its local snapshot. Cross-origin references need a separately prepared local source.                |
+| Local `externalValue`           | Fails with `local externalValue needs a pinned adapter`. Use a local inline example value, or an HTTPS external example link.                                                                                                                            |
+| Callbacks                       | Operation callbacks fail with an unsupported feature diagnostic. Top-level 3.1 webhooks are supported separately.                                                                                                                                        |
+| Response headers                | Schema-based headers and local references render descriptions, required/deprecated status, constraints, examples, and simple serialization. Content-style headers remain unsupported. `Content-Type` header definitions are ignored as OpenAPI requires. |
+| Response links                  | Require an adapter; prepare a supported documentation source while retaining the original contract separately.                                                                                                                                           |
+| Parameter `content`             | Requires an adapter; use supported parameter schemas in the documentation source.                                                                                                                                                                        |
+| Request media `encoding`        | Fails with `Request encoding needs an adapter`. Multipart binary fields have limited generated upload commands, but media encoding settings are not rendered.                                                                                            |
+| Other schema keywords           | Fail with `Unsupported schema keyword`. Adapt the documentation source without claiming omitted constraints are represented.                                                                                                                             |
 
 Avoid removing source semantics silently. If your API needs an unsupported feature, describe that limitation in the authored page and keep the authoritative contract available to readers where appropriate.
 

package/agent-docs/author/components.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-29.**
 
 Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components are not available.
 
@@ -24,6 +24,18 @@ Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, fo
 
 [Navigation and breadcrumbs](https://www.shoalrun.com/author/navigation.md) are configured site features. Their guides live under Customize.
 
+## Choose by task
+
+Start with the reader's task, then open the linked reference before choosing syntax.
+
+| Task                                                 | Feature                                                                                                                                                 |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Link related pages with a reason for each connection | [Relationships](https://www.shoalrun.com/author/related-reading.md) and [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) |
+| Explain a procedure with titled steps                | [Steps](https://www.shoalrun.com/author/components/steps.md)                                                                                            |
+| Explain how code changes step by step                | [Walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md)                                                                               |
+| Show configuration fields and their constraints      | [Fields](https://www.shoalrun.com/author/components/fields.md)                                                                                          |
+| Offer alternate views of the same topic              | [Tabs](https://www.shoalrun.com/author/components/tabs.md)                                                                                              |
+
 ## Reading and layout
 
 - [Callouts](https://www.shoalrun.com/author/components/callout.md) — notes, tips, important messages, warnings, and cautions.

package/agent-docs/author/frontmatter-reference.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 This is the field inventory for this documentation site. The tables below are built from Shoalrun's native field definitions and this site's `frontmatter.fields` declarations on each build. They describe source page headers, not the shorter YAML header selected for a published Markdown page.
 
@@ -24,6 +24,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Identify and route a page
 
 Use the page ID for links and cards that should survive a URL change. The slug supplies the page part of the URL; publication prefixes may be added around it. Summary is short preview text; description is a separate, optional fuller account. Project output rules choose which field supplies each surface.
@@ -58,30 +60,31 @@ Language is the content language and selects a publication. Locale describes for
 
 By default, `product`, `area`, and `subarea` are optional, nonempty string categories. They can come from project defaults and appear in the document manifest and search index. A matching configured reader facet makes each category a page filter; without that facet it remains taxonomy only. `operations` links a guide or reference to stable API operation IDs. On a guide or how-to page, `relatedApiReferences` names API reference page IDs to add cross links in both directions within the same publication. Tags help document collections find the page. Card settings change its preview when another page links to it; they do not change the destination. `subjectLifecycle` displays the status of the documented API or feature; `lifecycle` is available for the document's editorial state. `tocDepth` limits the HTML page table of contents; use 0 to hide it. `layout` picks the HTML page layout: `docs`, `wide`, `landing`, or `splash`. `showNavigationTabs` overrides the navigation tab bar for this page; landing and splash pages hide it by default. `image` replaces the generated link-preview image. `date` and `releaseVersion` can identify a changelog entry under the project's `frontmatter.changelogIdentifier` rule.
 
-| Field                  | Type            | Needed       | What it changes                                                                                                                                                                                                           |
-| ---------------------- | --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `product`              | string          | Optional     | Optional product category. Also selects the product reader facet when that facet is configured.                                                                                                                           |
-| `area`                 | string or array | On each page | Optional area category. Also selects the area reader facet when that facet is configured.                                                                                                                                 |
-| `subarea`              | string or array | On each page | Optional finer category. Also selects the subarea reader facet when that facet is configured.                                                                                                                             |
-| `operations`           | array           | Optional     | Stable API operation IDs that connect this page to endpoint references and related documents.                                                                                                                             |
-| `relatedApiReferences` | array           | Optional     | API reference page IDs linked automatically from this guide and back from each reference, within the same publication.                                                                                                    |
-| `tags`                 | array           | Optional     | Editorial labels used to select pages in document collections.                                                                                                                                                            |
-| `date`                 | string          | Optional     | Publication date in YYYY-MM-DD format; optional for release notes and one possible changelog identifier.                                                                                                                  |
-| `releaseVersion`       | string          | Optional     | Release label for a note or changelog entry; separate from the documentation publication version.                                                                                                                         |
-| `subjectLifecycle`     | string          | Optional     | Displays a content status badge in the page and navigation.                                                                                                                                                               |
-| `subjectDeprecation`   | object          | Optional     | Page-specific subject retirement dates and stable document IDs; requires deprecated subjectLifecycle, including OpenAPI inference. Dates do not change status automatically.                                              |
-| `change`               | object          | Optional     | Page-specific authored change meaning on a changelog-entry: kind, affected document IDs, and optional migration guide ID in the same publication. Omission means unclassified, not nonbreaking.                           |
-| `lifecycle`            | string          | Optional     | Editorial lifecycle of the document; validated by an opted-in external vocabulary.                                                                                                                                        |
-| `card`                 | object          | Optional     | Overrides how this page appears when another page includes a document card; its destination still resolves by page ID.                                                                                                    |
-| `card.title`           | string          | Optional     | Card title; defaults to the page title.                                                                                                                                                                                   |
-| `card.description`     | string          | Optional     | Card description; defaults to the page summary.                                                                                                                                                                           |
-| `card.eyebrow`         | string          | Optional     | Short label above a card title.                                                                                                                                                                                           |
-| `card.icon`            | string          | Optional     | Optional Lucide icon name such as book-open. Decorative in HTML; omitted from Markdown.                                                                                                                                   |
-| `standaloneSections`   | array           | Optional     | Page-specific exact level-two heading titles reviewed by the author as self-contained with the page introduction. Allows eligible sections to be recommended alone; omitted means full-page reads.                        |
-| `tocDepth`             | integer         | Optional     | Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.                                                                                                                                           |
-| `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks). |
-| `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                           |
-| `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                 |
+| Field                  | Type            | Needed       | What it changes                                                                                                                                                                                                                                                             |
+| ---------------------- | --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `product`              | string          | Optional     | Optional product category. Also selects the product reader facet when that facet is configured.                                                                                                                                                                             |
+| `area`                 | string or array | On each page | Optional area category. Also selects the area reader facet when that facet is configured.                                                                                                                                                                                   |
+| `subarea`              | string or array | On each page | Optional finer category. Also selects the subarea reader facet when that facet is configured.                                                                                                                                                                               |
+| `operations`           | array           | Optional     | Stable API operation IDs that connect this page to endpoint references and related documents.                                                                                                                                                                               |
+| `relatedApiReferences` | array           | Optional     | API reference page IDs linked automatically from this guide and back from each reference, within the same publication.                                                                                                                                                      |
+| `tags`                 | array           | Optional     | Editorial labels used to select pages in document collections.                                                                                                                                                                                                              |
+| `date`                 | string          | Optional     | Publication date in YYYY-MM-DD format; optional for release notes and one possible changelog identifier.                                                                                                                                                                    |
+| `releaseVersion`       | string          | Optional     | Release label for a note or changelog entry; separate from the documentation publication version.                                                                                                                                                                           |
+| `subjectLifecycle`     | string          | Optional     | Displays a content status badge in the page and navigation.                                                                                                                                                                                                                 |
+| `subjectDeprecation`   | object          | Optional     | Page-specific subject retirement dates and stable document IDs; requires deprecated subjectLifecycle, including OpenAPI inference. Dates do not change status automatically.                                                                                                |
+| `change`               | object          | Optional     | Page-specific authored change meaning on a changelog-entry: kind, affected document IDs, and optional migration guide ID in the same publication. Omission means unclassified, not nonbreaking.                                                                             |
+| `lifecycle`            | string          | Optional     | Editorial lifecycle of the document; validated by an opted-in external vocabulary.                                                                                                                                                                                          |
+| `card`                 | object          | Optional     | Overrides how this page appears when another page includes a document card; its destination still resolves by page ID.                                                                                                                                                      |
+| `card.title`           | string          | Optional     | Card title; defaults to the page title.                                                                                                                                                                                                                                     |
+| `card.description`     | string          | Optional     | Card description; defaults to the page summary.                                                                                                                                                                                                                             |
+| `card.eyebrow`         | string          | Optional     | Short label above a card title.                                                                                                                                                                                                                                             |
+| `card.icon`            | string          | Optional     | Optional Lucide icon name such as book-open. Decorative in HTML; omitted from Markdown.                                                                                                                                                                                     |
+| `standaloneSections`   | array           | Optional     | Page-specific standalone approval: a heading title approves contextual discovery with the page introduction; {id, context: section} approves the root level-two section slice for content export. IDs may be derived or explicitly anchored. Omitted means full-page reads. |
+| `tocDepth`             | integer         | Optional     | Deepest heading shown in the page table of contents; 0 hides it. Defaults to 3.                                                                                                                                                                                             |
+| `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
+| `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
+| `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.
 

package/agent-docs/author/frontmatter-reference.sections/choose-a-publication-and-visibility.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Choose a publication and visibility
 
 The project enables specific channel/version/language combinations. A page is built only for combinations matching its resolved values. `audiences` and `readerFilters` select reader views when the site config enables them; `access.policy` determines whether the page enters this public build. A draft page is excluded.

package/agent-docs/author/frontmatter-reference.sections/control-output-details.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Control output details
 
 `seo` changes the browser title or HTML meta description. `displayText` overrides the text chosen for one output surface on this page. `variables` supplies values to registered snippets before they expand into the page body. `markdownMetadata` selects or overrides the YAML preamble of the generated Markdown twin—the machine-readable copy of this page. That generated preamble is separate from the source frontmatter shown above.

package/agent-docs/author/frontmatter-reference.sections/global-defaults-and-enforced-values.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Global defaults and enforced values
 
 These are project config settings, not keys in a page header. `frontmatter.defaults` supplies values when a page omits them; `frontmatter.enforced` replaces page values. Resolution follows defaults → page → enforced. Objects merge recursively and arrays replace. IDs and slugs remain page-specific. Required fields and declared types are checked after resolution. Use an access default if authors need to keep individual pages as drafts.

package/agent-docs/author/frontmatter-reference.sections/html-markdown-and-agents.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## HTML, Markdown, and agents
 
 `FrontmatterReference` writes the project's field definitions into both the HTML page and its Markdown twin. An agent can read those tables without running JavaScript or opening the local schema file. The tables describe accepted source fields; they do not expose each page's private metadata values. The separate `.shoalrun` files are local authoring resources, not public routes.

package/agent-docs/author/frontmatter-reference.sections/identify-and-route-a-page.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Identify and route a page
 
 Use the page ID for links and cards that should survive a URL change. The slug supplies the page part of the URL; publication prefixes may be added around it. Summary is short preview text; description is a separate, optional fuller account. Project output rules choose which field supplies each surface.

package/agent-docs/author/frontmatter-reference.sections/point-agents-to-it.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Point agents to it
 
 Add a line to the repository's agent instructions, such as `AGENTS.md` or `CLAUDE.md`:

package/agent-docs/author/frontmatter-reference.sections/project-defined-fields.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Project-defined fields
 
 A project can add page fields by declaring them in `frontmatter.fields`. The declaration gives a field path (such as `agent.intent`), a type, and a description. A dotted path means nested YAML on the page. Undeclared fields are still accepted in source pages, but only declared fields appear in this table and receive type checks.

package/agent-docs/author/frontmatter-reference.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Related reading
 
 ### Related topics

package/agent-docs/author/frontmatter-reference.sections/use-the-local-files-while-authoring.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## Use the local files while authoring
 
 Every project also gets `.shoalrun/frontmatter-reference.md` and `.shoalrun/frontmatter.schema.json` beside `docs.config.yaml`. They contain that project's inventory for authors, editors, and agents working in its repository. For this site, the paths are `docs/.shoalrun/frontmatter-reference.md` and `docs/.shoalrun/frontmatter.schema.json`. These internal files are not published site routes.

package/agent-docs/author/frontmatter-reference.sections/when-the-files-update.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Generated frontmatter reference
 
-**Updated: 2026-10-27.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter-reference.md)
 
@@ -26,6 +26,8 @@ This is the field inventory for this documentation site. The tables below are bu
 
 To publish an equivalent inventory on your site, place `<FrontmatterReference />` on a page. It takes no attributes or child content and renders the current project's native and declared fields in HTML and Markdown.
 
+For section exports, declare `standaloneSections` with `{ id, context: section }` objects after reviewing each section without its page introduction. Older heading-title strings remain supported for contextual discovery. See [section identity and compatibility](https://www.shoalrun.com/content-delivery/sections.md) before changing an existing declaration.
+
 ## When the files update
 
 The files update whenever `shoalrun build` writes a site, including `npm run docs:build` and `vercel build`. Commands that compile without writing a site, such as `operation inspect`, leave them alone. The files are generated, so add `.shoalrun/` to `.gitignore`; this repository already does.

package/agent-docs/author/frontmatter.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Frontmatter is the YAML header between the first two `---` lines of a `.md` or `.mdx` page. It gives a page its identity, URL, and publication settings. Start with this complete header, then write the page body below it:
 
@@ -154,7 +154,8 @@ These fields categorize pages, add connections, or change presentation. `product
 | `subjectDeprecation`   | object                             | Page-specific deprecation and sunset dates, replacement ID, and migration guide ID for a deprecated subject; see below.                                                                      |
 | `change`               | object                             | Optional authored kind, affected page IDs, and migration guide ID on a changelog entry; see [describe what changed](https://www.shoalrun.com/author/release-notes.md).                       |
 | `lifecycle`            | string                             | Editorial state of the document. Shoalrun preserves it; a project can validate its values with a separate vocabulary tool.                                                                   |
-| `tocDepth`             | integer                            | Deepest heading in the HTML table of contents; `0` hides it.                                                                                                                                 |
+| `showVerified`         | boolean                            | Show the authored verification date in the HTML page header. Defaults to `true`; `false` hides it only in HTML. See [verification dates](https://www.shoalrun.com/publish/seo.md).           |
+| `tocDepth`             | integer                            | Deepest heading in the HTML table of contents; `0` hides it. To remove the outline and give content more room, use [`layout: wide`](https://www.shoalrun.com/styling/layouts.md).            |
 | `card`                 | object                             | Optional `title`, `description`, `eyebrow`, and Lucide `icon` for metadata-driven cards.                                                                                                     |
 | `seo`                  | object                             | Page-level HTML title and description overrides; see below.                                                                                                                                  |
 | `markdownMetadata`     | string or object                   | Named profile or page override for the Markdown twin's YAML preamble.                                                                                                                        |
@@ -163,6 +164,8 @@ These fields categorize pages, add connections, or change presentation. `product
 
 For example, a page can use `product: payments`, `area: reporting`, and `subarea: settlements`. Those resolved values appear in `documents.json` and `search-index.json`. If the site config defines reader facets with those names, each value must be a configured choice ID and becomes that page's reader filter. Do not also set `readerFilters.product`, `.area`, or `.subarea` for the same field. Without a matching facet, the category is metadata only. A site's Markdown metadata projection can also select `frontmatter.product`, `frontmatter.area`, and `frontmatter.subarea`.
 
+Choose the [page layout](https://www.shoalrun.com/styling/layouts.md) before adjusting the outline. Use `layout: wide` to remove “On this page” and give interactive content more space while keeping navigation. Use `tocDepth: 0` when you only need to hide the outline within the current layout.
+
 The default ToC includes headings through level 3. This page sets `tocDepth: 2`, so its ToC lists only the main sections. Use `tocDepth: 0` to suppress the ToC, or choose a depth from 2 through 6. Headings still appear in the page and Markdown twin when they are left out of the ToC.
 
 ## Give deprecation guidance

package/agent-docs/author/frontmatter.sections/audience-badges.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter.md)
 

package/agent-docs/author/frontmatter.sections/give-deprecation-guidance.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter.md)
 

package/agent-docs/author/frontmatter.sections/global-defaults-and-enforced-values.md

@@ -23,7 +23,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Page metadata > Page metadata
 
-**Updated: 2026-10-26.**
+**Updated: 2026-10-28.**
 
 Parent page: [Full Markdown page](/author/frontmatter.md)