@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/agent-docs/cli.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Node.js 22.12 or newer. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm, then run commands as `npx --no-install shoalrun <command>`. Framework contributors can build the source checkout and run `node framework/dist/cli.js <command>` from its root.
 
@@ -244,6 +244,16 @@ These commands print configuration and API operation details for inspection.
 
 `operation inspect` compiles the whole project without writing a site. When the operation isn't found in the selected publications, it prints `"status": "missing-variant"` and still exits with code 0. Put flags after the optional config path. An unknown or repeated flag fails before the project is compiled.
 
+## Validate code reference snapshots
+
+`references check` validates a converter's snapshot without invoking Python, running a converter, or building the site:
+
+```sh
+shoalrun references check ./reference/python.json
+```
+
+Success prints JSON with `status: "ok"`, `programmingLanguage`, and the symbol count. Invalid schema fields, duplicate IDs, missing symbol targets, or cyclic parents fail with exit code 1. See [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for extraction and [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the snapshot contract.
+
 ## Audit a project and API sources
 
 ### `check`

package/agent-docs/cli.sections/audit-a-project-and-api-sources.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/author-pages.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/build-and-serve.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/inspect-config-and-operations.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/npm-scripts-in-this-repository.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.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) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

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

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/start-a-project.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/cli.sections/validate-code-reference-snapshots.md

@@ -0,0 +1,41 @@
+---
+id: reference.cli
+title: CLI reference
+summary: Commands, arguments, defaults, output, and errors.
+type: reference
+area: authoring
+subarea: authoring-command-line
+canonical: /cli
+---
+
+# CLI reference
+
+> 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) > Commands > CLI reference
+
+**Updated: 2026-11-07.**
+
+Parent page: [Full Markdown page](/cli.md)
+
+The public `@shoalrun/cli` package supplies the `shoalrun` command. It needs Node.js 22.12 or newer. Follow [Getting started](https://www.shoalrun.com/start.md) to install it from npm, then run commands as `npx --no-install shoalrun <command>`. Framework contributors can build the source checkout and run `node framework/dist/cli.js <command>` from its root.
+
+Commands that return data print JSON to standard output. On an error, the CLI prints `{"status":"error","message":"..."}` to standard error and exits with code 1. A config argument defaults to `docs.config.yaml` in the current directory unless noted.
+
+[Diagrams](https://www.shoalrun.com/author/components/diagrams.md) render without a browser: Pele handles Mermaid syntax, and D2 handles D2 source. Development installs include Puppeteer for browser UI tests; production package installs don't need it.
+
+Since 0.1.0-alpha.18
+
+Product selectors, `dev --profile`, and `get_publications` discovery add product-aware workflows. Existing productless commands keep their publication scope.
+
+## Validate code reference snapshots
+
+`references check` validates a converter's snapshot without invoking Python, running a converter, or building the site:
+
+```sh
+shoalrun references check ./reference/python.json
+```
+
+Success prints JSON with `status: "ok"`, `programmingLanguage`, and the symbol count. Invalid schema fields, duplicate IDs, missing symbol targets, or cyclic parents fail with exit code 1. See [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for extraction and [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for the snapshot contract.

package/agent-docs/cli.sections/working-tree-authoring-tools.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > CLI reference
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/cli.md)
 

package/agent-docs/config/apis.md

@@ -17,10 +17,14 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > API and audit
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Configure OpenAPI sources, generated references, focused contracts, and local validation. 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.
 
+## `codeReferences`
+
+Register converter snapshots for code API references independently of OpenAPI sources. Each catalog can choose `layout: symbols`, `classes`, or `modules`, and optionally add a `singlePage` reference. See [Code API reference settings](https://www.shoalrun.com/api-docs/code-reference-settings.md) for source bindings, symbol selection, metadata, and the converter contract.
+
 ## `apis`
 
 A mapping from API ID to its source and operations. See [API references](https://www.shoalrun.com/publish/api-references.md) and [focused contracts](https://www.shoalrun.com/api-docs/focused-contracts.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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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/config.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Configuration reference > Overview
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 A project's configuration starts at `docs.config.yaml`. The CLI looks for that name by default, and `shoalrun scaffold -n` searches parent directories for it. For a guided workflow, start with [Configure your project](https://www.shoalrun.com/configuration.md). For complete working projects, see [Example configs](https://www.shoalrun.com/config/examples.md).
 
@@ -29,7 +29,7 @@ Each reference below contains the field definitions, defaults, validation rules,
 | [Site and theme settings](https://www.shoalrun.com/config/site.md)                 | `site`, `theme`                                                                                                                       |
 | [Publications and routing settings](https://www.shoalrun.com/config/publishing.md) | `publications`, `navigation`, `redirects`                                                                                             |
 | [Authoring and content settings](https://www.shoalrun.com/config/content.md)       | `authoring`, `frontmatter`, `variables`, `snippets`, `templates`, `callouts`, `badges`, `cookbooks`, `relationships`, `readerFilters` |
-| [API and audit settings](https://www.shoalrun.com/config/apis.md)                  | `apis`, `audit`                                                                                                                       |
+| [API and audit settings](https://www.shoalrun.com/config/apis.md)                  | `apis`, `codeReferences`, `audit`                                                                                                     |
 | [Search and integration settings](https://www.shoalrun.com/config/integrations.md) | `search`, `mcp`, `analytics`                                                                                                          |
 | [Output and export settings](https://www.shoalrun.com/config/outputs.md)           | `metadata`, `exports`, `outputs`                                                                                                      |
 

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-07.**
 
 `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.19
+npm install --save-exact @shoalrun/cli@1.0.0
 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-07.**
 
 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-07.**
 
 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-07.**
 
 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-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/related-reading.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Configure and customize > Configure your project
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/separate-config-inheritance-from-page-metadata.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-07.**
 
 Parent page: [Full Markdown page](/configuration.md)
 

package/agent-docs/configuration.sections/share-defaults-through-extends.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-07.**
 
 Parent page: [Full Markdown page](/configuration.md)