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

package/agent-docs/features.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Shoalrun features
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Shoalrun compiles product and API documentation into a website and agent-readable content from the same source. You own the source files, build output, and deployment. The normal compiler build makes no model calls or network requests.
 
@@ -29,12 +29,15 @@ Follow a topic link for configuration, examples, and limits.
 | [One source, multiple outputs](https://www.shoalrun.com/publish/agent-friendliness.md) | Write Markdown and supported MDX; publish HTML, Markdown copies, discovery indexes, manifests, and readable sections.                                                                                                         |
 | [Structured authoring](https://www.shoalrun.com/author/content.md)                     | Give documents stable IDs; reuse templates, snippets, variables, metadata, and configuration. Connect navigation and related reading by ID.                                                                                   |
 | [Documentation components](https://www.shoalrun.com/author/components.md)              | Use tabs, callouts, tables, steps, walkthroughs, diagrams, and trusted custom components with defined Markdown representations.                                                                                               |
+| [Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md)         | Highlight built-in languages or register a custom language with a local TextMate JSON grammar and aliases. Preserve the original code in Markdown.                                                                            |
 | [OpenAPI documentation](https://www.shoalrun.com/publish/api-references.md)            | Generate reference pages, embed API examples and schemas, show request samples, and publish focused operation contracts. Review source changes before publishing.                                                             |
 | [Customer editions](https://www.shoalrun.com/publish/deployment-profiles.md)           | Select exact product releases, SKU revisions, and feature grants. Remove excluded pages and sections during compilation.                                                                                                      |
 | [Independent products and versions](https://www.shoalrun.com/publish/publications.md)  | Give each product its own documentation versions and defaults, with explicit languages and routes.                                                                                                                            |
 | [Search and agent tools](https://www.shoalrun.com/search-and-chat.md)                  | Search the selected publication by keyword or optional semantic retrieval. Read-only Model Context Protocol (MCP) tools discover publications and read pages within token budgets. Optional cited answers use your providers. |
 | [Content delivery](https://www.shoalrun.com/content-delivery.md)                       | Export selected pages, approved sections, and snippets for an application. Clients and REST retain exact product scope; productless version 1 contracts remain supported.                                                     |
+| [Printing and styled PDFs](https://www.shoalrun.com/publish/pdf.md)                    | Offer branded Print PDF buttons, export styled pages or full manuals with the CLI, and serve optional page PDF downloads through a Node host.                                                                                 |
 | [Workflows and validation](https://www.shoalrun.com/author/agent-overview.md)          | Use your coding agent with project discovery, isolated validation, and matching previews. Watch a customer edition with `dev --profile`. Compose recipes and cookbooks.                                                       |
+| [Agent skills](https://www.shoalrun.com/reference/agent-skills.md)                     | Use packaged workflows for setup, authoring, components, recipes, walkthroughs, branding, and PDF design with `shoalrun-pdf`.                                                                                                 |
 | [Presentation and navigation](https://www.shoalrun.com/styling/themes.md)              | Configure themes, layouts, branding, and navigation. Switch publications through a grouped dropdown, with language labels hidden automatically for single-language editions.                                                  |
 | [Publishing and measurement](https://www.shoalrun.com/publish.md)                      | Publish static output or use Node and Vercel serving options. Add analytics through optional adapters.                                                                                                                        |
 

package/agent-docs/index.md

@@ -12,7 +12,7 @@ canonical: /
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 **Docs for people. Context for agents.**
 
@@ -22,7 +22,7 @@ One source, two audiences. Build interactive docs for people and readable conten
 - [See what an agent gets](https://www.shoalrun.com/publish/agent-friendliness.md)
 - [See what works today](https://www.shoalrun.com/status.md)
 
-> **Try the alpha:** Install `@shoalrun/cli` from npm. No account or token is needed, and the normal build makes no model calls or network requests. Pin an exact version while the alpha evolves.
+> **Try the beta:** Install `@shoalrun/cli` from npm. No account or token is needed, and the normal build makes no model calls or network requests. Pin an exact version during the beta.
 >
 > [Install Shoalrun →](https://www.shoalrun.com/start.md)
 

package/agent-docs/provenance.json

@@ -2,15 +2,15 @@
   "schemaVersion": 1,
   "siteBuild": {
     "schemaVersion": 1,
-    "configDigest": "2a4f31a26f253a82d999fa1ed1d2a1220053ba53bea00435844ec76815e67bfa",
-    "buildId": "3ca70f64a4b3562b2c51fd6a4a6beceb3578705d2fc545b7788589aebd0e6ff5"
+    "configDigest": "e3d0124ef8866a0cd2080cd8b3822909d5b4e288ef0c642b1ebcaebe2591c305",
+    "buildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f"
   },
-  "packageIntegrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA==",
+  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw==",
   "compilerPackage": {
     "kind": "reviewed-local-artifact",
     "name": "@shoalrun/cli",
-    "version": "0.1.0-alpha.19",
-    "integrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA=="
+    "version": "0.1.0-beta.1",
+    "integrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
   },
-  "manifestDigest": "2fb2a205cf322384919c7546e0626c42de82c34cfcdc2f5e244c92968993fd03"
+  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132"
 }

package/agent-docs/publish/content-export.md

@@ -20,6 +20,8 @@ Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Prerequisites
 
 Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This guide uses the resource-based export manifest described in the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md).

package/agent-docs/publish/content-export.sections/assets-downloads-and-notices.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Assets, downloads, and notices
 
 Local assets must be inside the content directory or an explicitly configured `assetRoots` directory. Roots and notice paths resolve relative to the config file that declares them:

package/agent-docs/publish/content-export.sections/check-the-result.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Check the result
 
 Check the app from a route unrelated to the export mount. Confirm that images load, document links stay in the drawer when intercepted, canonical links open the website, and all expected content is visible. Re-export after changing source content, and distribute the updated bundle with the application.

package/agent-docs/publish/content-export.sections/inspect-the-manifest.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Inspect the manifest
 
 The manifest uses typed `resources` for pages, sections, and snippet instances. See the [manifest contract](https://www.shoalrun.com/content-delivery/manifest.md) and [content client](https://www.shoalrun.com/content-delivery/client.md) for resource lookup and retrieval.

package/agent-docs/publish/content-export.sections/prerequisites.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Prerequisites
 
 Install Shoalrun `0.1.0-alpha.13` or newer in the documentation project. This guide uses the resource-based export manifest described in the [manifest reference](https://www.shoalrun.com/content-delivery/manifest.md).

package/agent-docs/publish/content-export.sections/related-reading.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Related reading
 
 ### Reference while working

package/agent-docs/publish/content-export.sections/review-exported-api-material.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Review exported API material
 
 The export preserves the API source-review gate. If its selected API material has no matching review digest, the normal command fails before replacing the previous bundle. Produce a candidate for inspection with:

package/agent-docs/publish/content-export.sections/try-the-help-drawer-example.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## Try the help-drawer example
 
 The package's `examples/help-drawer` directory contains a small application with two help documents, an image, a diagram, reader sections, tabs, a walkthrough, and a custom component. Copy it into a project with Shoalrun installed, then run from that example directory:

package/agent-docs/publish/content-export.sections/what-the-representations-retain.md

@@ -22,6 +22,8 @@ Parent page: [Full Markdown page](/publish/content-export.md)
 
 Keep application help and your documentation website in one content source. `shoalrun export` produces a directory of resolved Markdown, passive HTML fragments, referenced assets, and a manifest. Your application owns the help drawer, onboarding screen, or other interface that displays the content. It doesn't need a Shoalrun browser runtime.
 
+For printable pages and manuals, use [styled PDF export](https://www.shoalrun.com/publish/pdf.md). PDF exports use the site's selection by default and have their own artifact manifest. The HTML and Markdown bundles described here keep their independent selection contract.
+
 ## What the representations retain
 
 Exports resolve snippets, supported components, and API material before rendering. Static output keeps the substantive content of interactive components:

package/agent-docs/publish/pdf.md

@@ -0,0 +1,184 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Prerequisites
+
+Start with a Shoalrun project and an enabled publication. Browser page printing needs no build-time browser or PDF service. For CLI PDF export, install Chrome or Chromium on the machine that generates the file. Shoalrun doesn't download a browser during installation. Set `SHOALRUN_PDF_BROWSER` to the browser executable, or configure `outputs.pdf.executablePath`.
+
+For example, on macOS with Chrome installed in Applications:
+
+```sh
+export SHOALRUN_PDF_BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+
+CLI exports need the configured browser. Endpoint generation needs it on the Node server. The Vercel build adapter supports browser page printing and rejects endpoint mode before building.
+
+## Export a page or publication
+
+Run the page command with the page's stable document ID:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --document guide.start --out pdf/page
+```
+
+Omit `--document` to export a complete publication:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --out pdf/manual
+```
+
+If several publications are enabled, select one explicitly. These product and version values are examples:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --product core --channel production --version v2 --language en --out pdf/core-v2
+```
+
+Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails.
+
+Publication chapters follow navigation order. Eligible pages outside navigation are appended in stable document-ID order and reported in diagnostics. A named export target can supply an explicit document order:
+
+```yaml
+exports:
+  manual:
+    formats: [pdf]
+    documents: [guide.start, guide.configure]
+    pdf:
+      cover: true
+      toc: true
+```
+
+Run that target with `--target manual`. PDF targets contain whole pages and use a separate PDF manifest. Export HTML and Markdown in another invocation when your application needs those representations too.
+
+## Apply print styling
+
+Set defaults under `outputs.pdf`; a target's `pdf` settings override them. Paths resolve from the configuration file that declares them.
+
+```yaml
+outputs:
+  pdf:
+    stylesheet: ./styles/print.css
+    size: Letter
+    margins: { top: 20mm, right: 18mm, bottom: 20mm, left: 18mm }
+    footer: "{title} | {page} / {pages}"
+    logo: ./assets/logo.svg
+    subtitle: Operations manual
+    fonts:
+      - family: Documentation
+        source: ./assets/documentation.woff2
+        weight: "400"
+```
+
+Use a local font that you're allowed to embed. Reference the registered family in your stylesheet:
+
+```css title="styles/print.css"
+:root {
+  --pdf-accent: #245849;
+  --pdf-text: #172722;
+  --pdf-muted: #53665e;
+  --pdf-font: Documentation, Arial, sans-serif;
+  --pdf-code-font: monospace;
+}
+
+h2 { break-after: avoid; }
+.pdf-chapter + .pdf-chapter { break-before: page; }
+```
+
+The stylesheet can customize the cover, contents, chapters, tables, code, and page breaks. It can't load URLs or import other stylesheets; register fonts explicitly. CLI exports require staged local images; remote images fail instead of being fetched. Browser print views load the images referenced by the current page.
+
+Paper sizes are `A4`, `Letter`, `Legal`, `A3`, and `A5`. Margins accept `mm`, `cm`, `in`, or `px`. Header and footer fields accept escaped text with `{title}`, `{page}`, and `{pages}` placeholders; they use a separate small-text layout and don't inherit body CSS. `timeout` bounds rendering to 1,000–120,000 milliseconds; its default is 30,000.
+
+Publication exports enable the cover and linked table of contents by default; a single explicitly requested page omits them. Override `cover` and `toc` when needed. The contents links don't show printed page numbers. `bookmarks` defaults to true, using Chromium's experimental PDF outline support. Verify bookmarks in your browser's output; tagging doesn't establish PDF/UA compliance.
+
+## Offer browser page printing
+
+The action is off by default. For a static host, enable browser printing:
+
+```yaml
+outputs:
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after
+      include: [guide.start, guide.configure]
+```
+
+An enabled mapping defaults to `mode: print`. Omit `include` to enable the action on all eligible pages, or set `exclude` to a list of document IDs. `placement` is `before` or `after` the existing Markdown actions. Set `pdf: false` in a page's frontmatter to suppress the control. Set `outputs.html.pdf: false` to disable it for the site.
+
+This adds shared print scripts, a theme stylesheet, a small settings file, and any configured local fonts or logo. The same assets serve every page. It doesn't generate PDFs or additional print documents for individual pages, and the build doesn't need Chromium. The browser copies the current article into a separate branded print view and opens the print dialog. Readers choose Save as PDF. Allow that view to open if the browser blocks it as a pop-up.
+
+The print view uses `outputs.pdf` styling, including its local stylesheet, fonts, paper settings, and optional cover. Set `outputs.html.pdf.style` to a named export target to reuse only that target's PDF styling. Its document list, publication, and content filter don't change the current page selection. For example, a `page-print` target can set `cover: false` while the manual uses a cover. Browser print views default to no cover or contents unless configured.
+
+Website navigation, controls, and executable content aren't copied into the print view. The original page stays unchanged. The view waits for its fonts and images before opening the dialog, and retains **Print PDF** and **Close** controls afterward. Browser settings can affect backgrounds, pagination, and page furniture. Configured header/footer placeholders use browser CSS page-margin support, which varies by browser.
+
+The browser's own Print command remains available without JavaScript and uses the ordinary site's print CSS. That fallback can be customized with `site.customCss` and `@media print`; it doesn't open the branded view.
+
+## Publish an optional manual download
+
+Generate a complete selected publication with the CLI only when you want a downloadable manual. Keep its export directory outside the site build destination. After generating `pdf/manual/publication.pdf`, build the site and copy the PDF into the deployment output:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+mkdir -p site-dist/downloads
+cp pdf/manual/publication.pdf site-dist/downloads/manual.pdf
+```
+
+Add an ordinary content, header, or footer link to `/downloads/manual.pdf`, and run your site's link checks after copying. This example assumes root hosting; place the file and link under the configured base path when using one. Deploy it with the site. A later site build replaces its output, so repeat the explicit copy as part of your deployment workflow.
+
+Shoalrun doesn't automatically publish CLI export directories or create a full-manual download button. One optional manual file can serve the publication without prebuilding a PDF for every page. Use the same publication and customer profile for the site and manual.
+
+## Offer direct downloads through a Node server
+
+For generation when a reader clicks, use endpoint mode:
+
+```yaml
+outputs:
+  html:
+    pdf:
+      mode: endpoint
+      endpoint: /__shoalrun/pdf
+      label: Download PDF
+```
+
+Build and run the output with `shoalrun serve`. The Node server automatically loads the prepared page inventory. The first request generates its PDF; subsequent requests generate it again. Requests are limited to one active generation and ten generation attempts per minute per server instance. Busy requests receive a retry response. There's no shared PDF cache.
+
+The endpoint accepts only the page's opaque build-selected key. It can't select another profile, accept custom CSS, or print an arbitrary URL. It returns an attachment with `Cache-Control: no-store`. Mount the endpoint behind the same authentication as the site. Build-time audience selection isn't visitor authorization.
+
+Endpoint page downloads use `outputs.pdf` styling and omit the publication cover and contents. Optional `outputs.html.pdf.style` selects a named export target's `pdf` settings, just as it does for browser print views. Only that styling applies; the target's document list, publication, and filter don't change the current page selection.
+
+For a custom Node host, import `loadPdfRuntime` and `createPdfHttpHandler` from `@shoalrun/cli/pdf/server`. Mount the returned Web-standard handler at the runtime's endpoint; use its `authorize` callback or your existing authentication middleware. Keep `pdf-runtime.json` and `__shoalrun/pdf-data` out of public static serving. The built-in Node server protects those paths. Don't upload an endpoint-mode build to a generic static host.
+
+## Check the result
+
+Open `page.pdf` or `publication.pdf` in the export directory. Check the cover, fonts, long tables and code, page breaks, internal links, and bookmarks. Confirm that excluded edition content is absent. The adjacent manifest records publication identity, page order, input digests, and renderer details; it isn't a Content REST representation manifest. A failed export preserves an earlier PDF export directory.
+
+For browser printing, open a page, activate **Print PDF**, and inspect the branded view and native print preview. Confirm that the selected page and release appear and that no page PDFs were generated in the site build. Check that the original page's tabs, details, and reader view remain unchanged.
+
+For an endpoint action, follow **Download PDF** and confirm the selected page downloads. An endpoint link makes a normal same-origin navigation and download request; the server returns a readable error if generation fails.
+
+## HTML, Markdown, and agents
+
+HTML offers the optional browser print button or endpoint download link. Markdown retains the page's documentation and these instructions, without an interactive print control. The browser copies semantic article content into its print view. It shows tab panels and reader sections with their context and expands details without changing the source page. Browser-only controls and active elements aren't copied. CLI and endpoint PDF rendering expand those components into labeled static content. Reader views don't exclude their sections; use build filters and feature requirements for exclusion. Math retains its rendered expression, and code retains its text.
+
+Agents can run the same export command with explicit publication coordinates and profile, then read the PDF artifact manifest to identify the selection. PDFs are separate delivery artifacts: enabling them doesn't add a new Content REST representation or a public link to every publication export.

package/agent-docs/publish/pdf.sections/apply-print-styling.md

@@ -0,0 +1,65 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Apply print styling
+
+Set defaults under `outputs.pdf`; a target's `pdf` settings override them. Paths resolve from the configuration file that declares them.
+
+```yaml
+outputs:
+  pdf:
+    stylesheet: ./styles/print.css
+    size: Letter
+    margins: { top: 20mm, right: 18mm, bottom: 20mm, left: 18mm }
+    footer: "{title} | {page} / {pages}"
+    logo: ./assets/logo.svg
+    subtitle: Operations manual
+    fonts:
+      - family: Documentation
+        source: ./assets/documentation.woff2
+        weight: "400"
+```
+
+Use a local font that you're allowed to embed. Reference the registered family in your stylesheet:
+
+```css title="styles/print.css"
+:root {
+  --pdf-accent: #245849;
+  --pdf-text: #172722;
+  --pdf-muted: #53665e;
+  --pdf-font: Documentation, Arial, sans-serif;
+  --pdf-code-font: monospace;
+}
+
+h2 { break-after: avoid; }
+.pdf-chapter + .pdf-chapter { break-before: page; }
+```
+
+The stylesheet can customize the cover, contents, chapters, tables, code, and page breaks. It can't load URLs or import other stylesheets; register fonts explicitly. CLI exports require staged local images; remote images fail instead of being fetched. Browser print views load the images referenced by the current page.
+
+Paper sizes are `A4`, `Letter`, `Legal`, `A3`, and `A5`. Margins accept `mm`, `cm`, `in`, or `px`. Header and footer fields accept escaped text with `{title}`, `{page}`, and `{pages}` placeholders; they use a separate small-text layout and don't inherit body CSS. `timeout` bounds rendering to 1,000–120,000 milliseconds; its default is 30,000.
+
+Publication exports enable the cover and linked table of contents by default; a single explicitly requested page omits them. Override `cover` and `toc` when needed. The contents links don't show printed page numbers. `bookmarks` defaults to true, using Chromium's experimental PDF outline support. Verify bookmarks in your browser's output; tagging doesn't establish PDF/UA compliance.

package/agent-docs/publish/pdf.sections/check-the-result.md

@@ -0,0 +1,33 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Check the result
+
+Open `page.pdf` or `publication.pdf` in the export directory. Check the cover, fonts, long tables and code, page breaks, internal links, and bookmarks. Confirm that excluded edition content is absent. The adjacent manifest records publication identity, page order, input digests, and renderer details; it isn't a Content REST representation manifest. A failed export preserves an earlier PDF export directory.
+
+For browser printing, open a page, activate **Print PDF**, and inspect the branded view and native print preview. Confirm that the selected page and release appear and that no page PDFs were generated in the site build. Check that the original page's tabs, details, and reader view remain unchanged.
+
+For an endpoint action, follow **Download PDF** and confirm the selected page downloads. An endpoint link makes a normal same-origin navigation and download request; the server returns a readable error if generation fails.

package/agent-docs/publish/pdf.sections/export-a-page-or-publication.md

@@ -0,0 +1,61 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Export a page or publication
+
+Run the page command with the page's stable document ID:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --document guide.start --out pdf/page
+```
+
+Omit `--document` to export a complete publication:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --out pdf/manual
+```
+
+If several publications are enabled, select one explicitly. These product and version values are examples:
+
+```sh
+npx --no-install shoalrun export docs.config.yaml --format pdf --product core --channel production --version v2 --language en --out pdf/core-v2
+```
+
+Pass `--profile customer.yaml` when exporting a [customer edition](https://www.shoalrun.com/publish/deployment-profiles.md). PDF selection uses the target's `contentFilter`, or the site's `site.contentFilter` when the target doesn't specify one. Product, version, language, page access policy, and feature requirements apply before rendering. A missing or excluded explicitly requested page fails.
+
+Publication chapters follow navigation order. Eligible pages outside navigation are appended in stable document-ID order and reported in diagnostics. A named export target can supply an explicit document order:
+
+```yaml
+exports:
+  manual:
+    formats: [pdf]
+    documents: [guide.start, guide.configure]
+    pdf:
+      cover: true
+      toc: true
+```
+
+Run that target with `--target manual`. PDF targets contain whole pages and use a separate PDF manifest. Export HTML and Markdown in another invocation when your application needs those representations too.

package/agent-docs/publish/pdf.sections/html-markdown-and-agents.md

@@ -0,0 +1,31 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## HTML, Markdown, and agents
+
+HTML offers the optional browser print button or endpoint download link. Markdown retains the page's documentation and these instructions, without an interactive print control. The browser copies semantic article content into its print view. It shows tab panels and reader sections with their context and expands details without changing the source page. Browser-only controls and active elements aren't copied. CLI and endpoint PDF rendering expand those components into labeled static content. Reader views don't exclude their sections; use build filters and feature requirements for exclusion. Math retains its rendered expression, and code retains its text.
+
+Agents can run the same export command with explicit publication coordinates and profile, then read the PDF artifact manifest to identify the selection. PDFs are separate delivery artifacts: enabling them doesn't add a new Content REST representation or a public link to every publication export.

package/agent-docs/publish/pdf.sections/offer-browser-page-printing.md

@@ -0,0 +1,49 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Offer browser page printing
+
+The action is off by default. For a static host, enable browser printing:
+
+```yaml
+outputs:
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after
+      include: [guide.start, guide.configure]
+```
+
+An enabled mapping defaults to `mode: print`. Omit `include` to enable the action on all eligible pages, or set `exclude` to a list of document IDs. `placement` is `before` or `after` the existing Markdown actions. Set `pdf: false` in a page's frontmatter to suppress the control. Set `outputs.html.pdf: false` to disable it for the site.
+
+This adds shared print scripts, a theme stylesheet, a small settings file, and any configured local fonts or logo. The same assets serve every page. It doesn't generate PDFs or additional print documents for individual pages, and the build doesn't need Chromium. The browser copies the current article into a separate branded print view and opens the print dialog. Readers choose Save as PDF. Allow that view to open if the browser blocks it as a pop-up.
+
+The print view uses `outputs.pdf` styling, including its local stylesheet, fonts, paper settings, and optional cover. Set `outputs.html.pdf.style` to a named export target to reuse only that target's PDF styling. Its document list, publication, and content filter don't change the current page selection. For example, a `page-print` target can set `cover: false` while the manual uses a cover. Browser print views default to no cover or contents unless configured.
+
+Website navigation, controls, and executable content aren't copied into the print view. The original page stays unchanged. The view waits for its fonts and images before opening the dialog, and retains **Print PDF** and **Close** controls afterward. Browser settings can affect backgrounds, pagination, and page furniture. Configured header/footer placeholders use browser CSS page-margin support, which varies by browser.
+
+The browser's own Print command remains available without JavaScript and uses the ordinary site's print CSS. That fallback can be customized with `site.customCss` and `@media print`; it doesn't open the branded view.