@shoalrun/cli 0.1.0-alpha.18 → 0.1.0-beta.1

package/agent-docs/author/writing-style.sections/voice-and-explanations.md

@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Authoring reference > Example writing guide
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/author/writing-style.md)
 

package/agent-docs/changelog/2026-10-16-navigation-layouts.md

@@ -69,4 +69,4 @@ Repository contributors now have a separate maintainer guide covering architectu
 
 ### Related topics
 
-- [Project status](https://www.shoalrun.com/status.md) — Check the alpha's capabilities and current limits.
+- [Project status](https://www.shoalrun.com/status.md) — Check the current capabilities and limits.

package/agent-docs/changelog/branding-security.md

@@ -0,0 +1,66 @@
+---
+id: change.branding-security
+title: Branding guidance and safer hosted chat
+summary: Match your documentation to your brand with an agent skill, and bind
+  hosted-chat visitor checks to the intended site.
+type: changelog-entry
+area:
+  - appearance
+  - discovery
+  - project
+subarea:
+  - appearance-themes
+  - discovery-chat
+  - project-releases
+canonical: /changelog/branding-security
+date: 2026-11-05
+releaseVersion: 0.1.0-alpha.19
+---
+
+# Branding guidance and safer hosted chat
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > alpha.19: Branding and security
+
+**Published: 2026-11-05.**
+
+**Version: 0.1.0-alpha.19.**
+
+Give your coding agent the `shoalrun-brand` skill to match a documentation site to your brand. It guides the agent through colors, fonts, logos, theme settings, and CSS, then checks menus, search results, buttons, keyboard focus, and mobile layouts for readability.
+
+Upgrade to CLI `0.1.0-alpha.19`. Rebuild and redeploy hosted chat to apply its new visitor checks. You don't need provider credentials to read the skill or brand a local site.
+
+## Match a documentation site to your brand
+
+Ask your agent to read the skill:
+
+```sh
+npx --no-install shoalrun skills read shoalrun-brand
+```
+
+The skill works from a supplied website, brand guide, or assets. It uses supported configuration first and project CSS where needed. It keeps brand assets in your project and preserves the documentation, navigation, and routes. It checks both the page and interactive surfaces: a dark header can contain light inputs, dropdowns, and search results that need their own text colors.
+
+The agent builds and previews the result for review. See [themes and fonts](https://www.shoalrun.com/styling/themes.md) and the [CSS reference](https://www.shoalrun.com/author/css.md) for the configuration it uses.
+
+## Keep visitor checks tied to the intended site
+
+Hosted chat checks the hostname returned by Turnstile rather than accepting a successful response alone. By default, the accepted names come from the site's trusted deployment addresses. You can supply an exact `chat.challenge.hostnames` list and an optional `action` for this operation.
+
+A session pass is now tied to the hostname/action policy as well as the caller. A pass from a different policy can't skip the check, even when deployments share a secret. Changing the policy invalidates existing passes; the next required check gives the visitor a new one.
+
+Local public preview handles the published dummy-token response separately from production verification. Hosted test previews need matching test credentials and a separate usage store. See [Host and limit documentation chat](https://www.shoalrun.com/chat/host.md) for the settings and preview behavior.
+
+## Check dependencies and hosting policy
+
+Coordinated releases now check both the framework and documentation dependency graphs, including development tools. The documentation site's browser tools and affected dependencies are updated without forcing an incompatible package version.
+
+The documentation site also restricts framing to the same origin, sets an explicit referrer policy, and checks the required headers after deployment. Its broader Content Security Policy starts in report-only mode: browser violations can be reviewed before enforcement, and that policy doesn't yet block scripts. These settings belong to this site; they aren't compiler defaults for customer sites.
+
+The repository and package READMEs now cover product versions, customer editions, branding, application content delivery, and agent workflows.
+
+## HTML, Markdown, and agents
+
+Branding changes the HTML site's appearance and interaction states. Markdown retains the documentation and examples without fonts, colors, menus, or focus styles. Agents read the packaged skill and bundled references, edit project source, validate the result, and share a local preview. A successful build doesn't replace visual checks of the browser output.

package/agent-docs/changelog/pdf-custom-languages.md

@@ -0,0 +1,48 @@
+---
+id: change.pdf-custom-languages
+title: Styled PDFs and custom code languages
+summary: Print branded pages, export a complete PDF manual, and highlight your
+  own code language.
+type: changelog-entry
+area:
+  - publishing
+  - components
+  - appearance
+  - authoring
+  - project
+subarea:
+  - publishing-builds
+  - components-code
+  - appearance-themes
+  - authoring-agent-workflows
+  - project-releases
+canonical: /changelog/pdf-custom-languages
+date: 2026-11-05
+releaseVersion: 0.1.0-beta.1
+---
+
+# Styled PDFs and custom code languages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt) (ID: project-updates). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > beta.1: PDFs and code languages
+
+**Published: 2026-11-05.**
+
+**Version: 0.1.0-beta.1.**
+
+Upgrade to CLI `0.1.0-beta.1` and rebuild to use these features.
+
+## [Print a page](https://www.shoalrun.com/publish/pdf.md)
+
+Add an optional, configurable **Print PDF** button with branded styling. Static sites use the reader's browser.
+
+## [Export a styled manual](https://www.shoalrun.com/publish/pdf.md)
+
+Export a page or full publication with custom fonts, covers, contents, and page layouts. CLI exports and optional Node downloads require installed Chrome or Chromium; static printing doesn't. The new `shoalrun-pdf` skill guides agents through print design.
+
+## [Highlight your own code language](https://www.shoalrun.com/author/components/code-blocks.md)
+
+Register a local TextMate JSON grammar containing syntax-coloring rules, then use its language ID or aliases in code fences.

package/agent-docs/changelog.md

@@ -16,12 +16,28 @@ Navigation section: [Project](https://www.shoalrun.com/.well-known/shoalrun/navi
 
 Breadcrumbs: [Project](https://www.shoalrun.com/status.md) > Changelog > All changes
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Updates to Shoalrun and its documentation. Each entry identifies the affected versions and any upgrade steps. Earlier entries retain their private-prototype release context.
 
 ## Latest changes
 
+- 2026-11-05
+
+  Version 0.1.0-alpha.19
+
+  [Branding guidance and safer hosted chat](https://www.shoalrun.com/changelog/branding-security.md)
+
+  Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
+
+- 2026-11-05
+
+  Version 0.1.0-beta.1
+
+  [Styled PDFs and custom code languages](https://www.shoalrun.com/changelog/pdf-custom-languages.md)
+
+  Print branded pages, export a complete PDF manual, and highlight your own code language.
+
 - 2026-11-04
 
   Version 0.1.0-alpha.17

package/agent-docs/chat/host.md

@@ -116,6 +116,22 @@ chat:
 
 The site key is public and goes in the config. The secret goes in the environment variable. A check that fails, times out, or has no secret refuses the request, so an outage can't let scripts through. Without `chat.challenge`, the function logs a warning, because only the daily caps then stand in the way of a script.
 
+The function also checks the hostname returned by Cloudflare. By default, it accepts the trusted site and deployment hostnames described above, without their ports. Set `hostnames` to an explicit list to narrow that check. Names are exact: don't include a scheme, path, port, or wildcard. Keep the widget's allowed domains in Cloudflare consistent with the addresses you intend to use.
+
+Use `action` when the widget needs to identify this operation. The browser sends it when requesting a token, and the server requires the same value in Cloudflare's verification response:
+
+```yaml title="docs.config.yaml"
+chat:
+  challenge:
+    provider: turnstile
+    siteKey: 0x4AAAAAAAexample
+    secretEnv: TURNSTILE_SECRET_KEY
+    hostnames: [docs.example.com]
+    action: documentation_chat
+```
+
+A missing or mismatched hostname, or a missing or mismatched configured action, refuses the request before answering. Adding a hostname here doesn't authorize incoming requests from that host; the function's host checks still apply.
+
 The default `adaptive` mode requests a challenge when usage crosses a threshold:
 
 - A caller is asked once they have used `freeQuestions` model answers in a day. The default is 3.
@@ -124,15 +140,17 @@ The default `adaptive` mode requests a challenge when usage crosses a threshold:
 
 When challenged, the panel runs the check and resends the question. It shows `Checking that you are a person…` while waiting.
 
-A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address. The signing key is derived from the Turnstile secret. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
+A successful check creates a signed, browser-script-inaccessible cookie tied to the caller’s address and the hostname/action policy. The signing key is derived from the Turnstile secret and that policy. Changing the policy invalidates existing passes. The pass lasts 15 minutes, so follow-up questions need no new challenge during that time.
 
 | Setting         | What it does                                                                                                                                                            |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hostnames`     | Exact hostnames accepted from token verification. Defaults to the trusted runtime hostnames; an explicit list must be nonempty.                                         |
+| `action`        | Optional operation name sent by the widget and checked by the server. Use 1–32 letters, digits, underscores, or hyphens.                                                |
 | `when`          | `adaptive` (the default) asks only when needed. `always` checks every conversation. It runs in the background when the panel opens, so the first question doesn't wait. |
 | `freeQuestions` | Model answers a caller gets before being asked. The default is 3.                                                                                                       |
 | `busyShare`     | The share of the daily budget at which everyone is asked. A number above 0 and at most 1. The default is 0.5.                                                           |
 
-Cloudflare publishes test keys for development. They work on any address and accept only their own test token, so a test site key needs the matching test secret. Use them for preview deployments, so you never have to register preview addresses.
+Cloudflare publishes test keys for development. A test site key needs the matching test secret. Test responses use synthetic hostname metadata and don't prove a production domain or action. `serve --ask --public-preview` configures its local test expectations for you. For hosted previews with real verification, register the preview hostname in the widget and include it among the function's trusted hosts. Keep test keys and test grants out of production.
 
 ### Record questions
 

package/agent-docs/chat/settings.md

@@ -98,7 +98,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](#use-more-than-one-model).                                                                                                                               |
 | `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](#use-more-than-one-model).                                                                                                                         |
 | `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
-| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                             |
 | `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
 | `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
 | `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |

package/agent-docs/chat/settings.sections/configure-chat.md

@@ -66,7 +66,7 @@ Add these fields to `chat` when the corresponding capability is needed. Scorer-d
 | `fallback`   | A list of one to five other models to try, in order, when the main one fails. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                      |
 | `escalate`   | A second model to ask when the checks flag an answer, with an optional `when` list. See [Use more than one model](https://www.shoalrun.com/chat/settings.md#use-more-than-one-model).                                                                                |
 | `budget`     | Daily caps on questions that reach the model. See [Cap the daily spend](https://www.shoalrun.com/chat/host.md).                                                                                                                                                      |
-| `challenge`  | A Turnstile check for a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                           |
+| `challenge`  | A Turnstile check for hosted chat, with verified hostnames and an optional action. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                             |
 | `log`        | Records questions on a hosted chat. See [Host the chat on Vercel](https://www.shoalrun.com/chat/host.md).                                                                                                                                                            |
 | `cache`      | Keeps clean answers so a repeated question costs nothing. `maxEntries` (default 500) and `ttlMinutes` (default 1,440) set the size and the age. See [Reuse answers](https://www.shoalrun.com/chat/checks.md).                                                        |
 | `cards`      | Needs `rerank: jev`. Serves answers written ahead of time. `threshold` (default 0.75) shortlists a card by similarity, and `confirm` (default 0.9) is the Jev score that must confirm it. See [Prepared answers](https://www.shoalrun.com/chat/prepared-answers.md). |

package/agent-docs/config/examples.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 The installed package includes complete projects under `node_modules/@shoalrun/cli/example-configs/`, with their pages and local OpenAPI files. Start with a bundled starter in a new directory:
 
@@ -27,7 +27,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -52,7 +52,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/feature-showcase.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist
@@ -54,7 +54,7 @@ The `showcase` starter provides 18 connected pages. Its component examples cover
 mkdir my-handbook
 cd my-handbook
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter showcase
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/minimal-site.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/multilingual-help-center.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/parcel-api-documentation.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

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

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/examples.sections/shared-company-preset.md

@@ -17,7 +17,7 @@ Navigation section: [Examples](https://www.shoalrun.com/.well-known/shoalrun/nav
 
 Breadcrumbs: [Examples](https://www.shoalrun.com/config/examples.md) > Starters and discovery > Example projects
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/examples.md)
 
@@ -29,7 +29,7 @@ Install Node.js 22.12 or newer and npm before running these commands.
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 npx --no-install shoalrun build docs.config.yaml site-dist
 npx --no-install shoalrun serve site-dist

package/agent-docs/config/outputs.md

@@ -1,8 +1,8 @@
 ---
 id: reference.config-outputs
 title: Output and export settings
-summary: Configure metadata providers, application exports, Markdown headers,
-  and discovery indexes.
+summary: Configure application exports, PDF styling, Markdown headers, and
+  discovery indexes.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -17,10 +17,31 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Configure metadata providers, application exports, Markdown headers, and discovery indexes. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
 
+## PDF output
+
+Since 0.1.0-beta.1
+
+Use `outputs.pdf` for shared PDF styling and `exports.<target>.pdf` for target overrides. Enable the optional page action separately with `outputs.html.pdf`; it's off by default. See [Export styled PDFs](https://www.shoalrun.com/publish/pdf.md) for complete commands, settings, local asset requirements, and the static or on-demand delivery choices.
+
+```yaml
+outputs:
+  pdf:
+    size: A4
+    stylesheet: ./styles/print.css
+    footer: "{page} / {pages}"
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after
+```
+
+PDF formats use their own export bundle; they aren't Content REST page representations. Browser print mode uses a shared branded layout, CSS, and fonts from `outputs.pdf`, with optional named-target styling through `outputs.html.pdf.style`. It generates no page PDFs or print documents. Optional manual downloads come from explicit CLI exports. Endpoint mode requires a Node host with Chromium. Header and footer text accepts `{title}`, `{page}`, and `{pages}` placeholders; browser views use browser-supported CSS page margins.
+
 ## `metadata`
 
 `metadata.provider.module` names an optional local module that exports `provideMetadata(context)`. The module can supply owned page fields to the build. The framework doesn't run an external vocabulary validator or publish supplied fields automatically. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md) for the return shape and ownership rule.
@@ -73,15 +94,15 @@ For a product release, set `publication: { product: payments, channel: productio
 
 Use `outputs` to configure the HTML, Markdown, discovery, and text artifacts produced by a build.
 
-| Key                          | Meaning                                                                                                                                                                                                                             |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `markdown.metadata`          | The Markdown twin's YAML header: `format`, `fields`, `addFields`, `removeFields`, `omitNull`, `byType`, and `profiles`. `format` defaults to `none`. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md). |
-| `html.shareImages`           | `true`: a generated 1200×630 link-preview image per page. `false` turns them off; a mapping with `template` and `fonts` replaces the design. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).      |
-| `html.highlighting`          | Code highlighting `provider`, `theme`, and `module`. Defaults to Shiki with the `site` theme, which takes code colors from the palette. See [code blocks](https://www.shoalrun.com/author/components/code-blocks.md).               |
-| `html.navigation.heading`    | Heading above the sidebar filter. Defaults to `Explore`; use nonempty text to replace it or `false` to hide it. Since 0.1.0-alpha.13                                                                                                |
-| `html.navigation.showCounts` | Show page counts beside navigation groups. Defaults to `true`; set `false` to omit them. See [navigation](https://www.shoalrun.com/author/navigation.md).                                                                           |
-| `html.search`                | Search `provider`, `module`, and `index`. See [search](https://www.shoalrun.com/author/search.md).                                                                                                                                  |
-| `text`                       | Ordered frontmatter field paths for `card`, `pageHeader`, `search`, `htmlDescription`, and `socialCard`. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md).                                                 |
+| Key                          | Meaning                                                                                                                                                                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `markdown.metadata`          | The Markdown twin's YAML header: `format`, `fields`, `addFields`, `removeFields`, `omitNull`, `byType`, and `profiles`. `format` defaults to `none`. See [Markdown metadata](https://www.shoalrun.com/author/markdown-metadata.md).                                 |
+| `html.shareImages`           | `true`: a generated 1200×630 link-preview image per page. `false` turns them off; a mapping with `template` and `fonts` replaces the design. See [share images and favicon](https://www.shoalrun.com/styling/share-images.md).                                      |
+| `html.highlighting`          | Code highlighting `provider`, `theme`, custom `languages` for Shiki, or a custom adapter `module`. Defaults to Shiki with the `site` theme, which takes code colors from the palette. See [code blocks](https://www.shoalrun.com/author/components/code-blocks.md). |
+| `html.navigation.heading`    | Heading above the sidebar filter. Defaults to `Explore`; use nonempty text to replace it or `false` to hide it. Since 0.1.0-alpha.13                                                                                                                                |
+| `html.navigation.showCounts` | Show page counts beside navigation groups. Defaults to `true`; set `false` to omit them. See [navigation](https://www.shoalrun.com/author/navigation.md).                                                                                                           |
+| `html.search`                | Search `provider`, `module`, and `index`. See [search](https://www.shoalrun.com/author/search.md).                                                                                                                                                                  |
+| `text`                       | Ordered frontmatter field paths for `card`, `pageHeader`, `search`, `htmlDescription`, and `socialCard`. See [custom metadata](https://www.shoalrun.com/author/custom-metadata.md).                                                                                 |
 
 The build always writes `/llms.txt`, `documents.json`, `redirects.json`, and `resource-headers.json`; there are no settings for them.
 

package/agent-docs/config/outputs.sections/exports.md

@@ -1,8 +1,8 @@
 ---
 id: reference.config-outputs
 title: Output and export settings
-summary: Configure metadata providers, application exports, Markdown headers,
-  and discovery indexes.
+summary: Configure application exports, PDF styling, Markdown headers, and
+  discovery indexes.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

package/agent-docs/config/outputs.sections/metadata.md

@@ -1,8 +1,8 @@
 ---
 id: reference.config-outputs
 title: Output and export settings
-summary: Configure metadata providers, application exports, Markdown headers,
-  and discovery indexes.
+summary: Configure application exports, PDF styling, Markdown headers, and
+  discovery indexes.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

package/agent-docs/config/outputs.sections/pdf-output.md

@@ -0,0 +1,51 @@
+---
+id: reference.config-outputs
+title: Output and export settings
+summary: Configure application exports, PDF styling, Markdown headers, and
+  discovery indexes.
+type: reference
+area: publishing
+subarea: publishing-configuration
+canonical: /config/outputs
+---
+
+# Output and export settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
+
+**Updated: 2026-11-06.**
+
+Parent page: [Full Markdown page](/config/outputs.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Read first**
+
+- [Organize project configuration](https://www.shoalrun.com/configuration.md) — Learn how files combine and how to validate configuration changes.
+
+Configure metadata providers, application exports, Markdown headers, and discovery indexes. These keys belong in `docs.config.yaml` or an included configuration file. For file composition and validation commands, see [Configure your project](https://www.shoalrun.com/configuration.md). Use the [configuration index](https://www.shoalrun.com/config.md) to find another setting.
+
+## PDF output
+
+Since 0.1.0-beta.1
+
+Use `outputs.pdf` for shared PDF styling and `exports.<target>.pdf` for target overrides. Enable the optional page action separately with `outputs.html.pdf`; it's off by default. See [Export styled PDFs](https://www.shoalrun.com/publish/pdf.md) for complete commands, settings, local asset requirements, and the static or on-demand delivery choices.
+
+```yaml
+outputs:
+  pdf:
+    size: A4
+    stylesheet: ./styles/print.css
+    footer: "{page} / {pages}"
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after
+```
+
+PDF formats use their own export bundle; they aren't Content REST page representations. Browser print mode uses a shared branded layout, CSS, and fonts from `outputs.pdf`, with optional named-target styling through `outputs.html.pdf.style`. It generates no page PDFs or print documents. Optional manual downloads come from explicit CLI exports. Endpoint mode requires a Node host with Chromium. Header and footer text accepts `{title}`, `{page}`, and `{pages}` placeholders; browser views use browser-supported CSS page margins.

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

@@ -1,8 +1,8 @@
 ---
 id: reference.config-outputs
 title: Output and export settings
-summary: Configure metadata providers, application exports, Markdown headers,
-  and discovery indexes.
+summary: Configure application exports, PDF styling, Markdown headers, and
+  discovery indexes.
 type: reference
 area: publishing
 subarea: publishing-configuration
@@ -17,7 +17,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Output and export
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/config/outputs.md)
 

package/agent-docs/configuration.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) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 `docs.config.yaml` connects your content, presentation, and publication settings. Start with one file, then extract sections or share defaults when several projects need them. This guide explains how those choices interact and how to inspect the result.
 
@@ -59,7 +59,7 @@ CONFIG_DEMO="$(mktemp -d)"
 mkdir "$CONFIG_DEMO/site"
 cd "$CONFIG_DEMO/site"
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.18
+npm install --save-exact @shoalrun/cli@0.1.0-beta.1
 npx --no-install shoalrun init . --starter minimal
 ```
 

package/agent-docs/configuration.sections/build-several-sites-from-shared-content.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) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/change-inherited-lists-deliberately.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) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/extract-a-section-with-include.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) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/inspect-and-validate-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) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Parent page: [Full Markdown page](/configuration.md)