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

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.0-beta.1 — 2026-11-05
+
+- Add custom code-fence highlighting with local TextMate JSON grammars and aliases.
+- Export [styled page or publication PDFs](https://www.shoalrun.com/publish/pdf) with custom fonts, covers, contents,
+  and page layouts. CLI and optional Node downloads require Chrome or Chromium.
+- Add configurable branded Print PDF buttons for static sites using the
+  reader's browser.
+- Add the `shoalrun-pdf` agent skill, runnable examples, and configuration guides.
+- Harden private runtime paths and print asset loading.
+
+Upgrade to CLI `0.1.0-beta.1` and rebuild. Page printing is off by default;
+manual downloads require an explicit export and deployment.
+
 ## 0.1.0-alpha.19 — 2026-11-05
 
 - Give your coding agent the `shoalrun-brand` skill to match a documentation

package/README.md

@@ -2,14 +2,14 @@
 
 Shoalrun builds a documentation website, Markdown pages, and application content from the same Markdown and MDX source. People can browse the site; applications and agents can read stable documents, sections, and snippet instances. Native components keep essential instructions and API details readable in both HTML and Markdown.
 
-This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This alpha is distributed through the public npm registry. Installation requires no npm account or package token.
+This package provides the `shoalrun` CLI, starter projects, agent skills, and offline documentation. It requires Node.js 22.12 or newer. This beta is distributed through the public npm registry. Installation requires no npm account or package token.
 
 ## Install
 
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-beta.1
 ```
 
 ## Create and preview a site
@@ -53,6 +53,16 @@ Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a
 
 Check controls and interactive states as well as article text: a dark header can contain light inputs, menus, and search results. Palette validation doesn't check arbitrary project CSS. See [themes and fonts](https://www.shoalrun.com/styling/themes), the [CSS reference](https://www.shoalrun.com/author/css), and [deployment profiles](DEPLOYMENT-PROFILES.md).
 
+## Export styled PDFs
+
+Export a page with `shoalrun export docs.config.yaml --format pdf --document guide.start --out pdf/page`, or omit `--document` for a complete selected publication. PDF exports respect publication coordinates, customer profiles, and the target's content filter (falling back to the site's filter). Set shared fonts, local print CSS, paper size, margins, cover, linked contents, and page numbering under `outputs.pdf`; named export targets can override those settings.
+
+PDF generation needs an installed Chrome/Chromium executable, selected through `SHOALRUN_PDF_BROWSER` or `outputs.pdf.executablePath`. Ordinary package installation doesn't download a browser. PDF rendering runs offline with page scripts disabled.
+
+Enable `outputs.html.pdf: { mode: print }` for a **Print PDF** page action on a static site. The browser fills a separate branded print view with the current article and uses `outputs.pdf` styling. Scripts, theme CSS, settings, and configured fonts/logo are shared across pages; builds generate no page PDFs or extra print documents and need no Chromium for this action. The action is off by default; an enabled mapping defaults to print mode. Configure its label, placement, include/exclude IDs, and optional `style` target; `pdf: false` suppresses a page. The original page remains unchanged. Native browser printing remains a fallback using website print CSS.
+
+Generate a full manual with the CLI only when you want a downloadable PDF, then deliberately add it and its link to the static deployment. Explicit `{ mode: endpoint }` offers on-demand PDF downloads through the Node server; optional `style` selects a named target's PDF settings without changing page selection. Vercel supports print mode. Keep endpoint-mode private inputs behind the Node server or equivalent authenticated custom handler, never in generic public static serving. See [the runnable PDF example](examples/pdf/README.md).
+
 ## Independently versioned products
 
 Projects can give each product its own version catalog and default version. Product publications carry a product, channel, version, and language; routes, document links, navigation, search, and content exports retain that scope. Existing projects without product catalogs keep their publication identities and routes.
@@ -111,7 +121,7 @@ Agents can discover product scopes through MCP `get_publications` before searchi
 
 ## Work with an agent
 
-Shoalrun works with your existing coding agent. Its packaged skills cover setup, page authoring, components, recipes, and walkthroughs. Use `skills list` to discover the skills included with your installed version:
+Shoalrun works with your existing coding agent. Its packaged skills cover setup, page authoring, components, recipes, walkthroughs, branding, and styled PDF exports. Use `skills list` to discover the skills included with your installed version:
 
 ```sh
 npx --no-install shoalrun skills list
@@ -336,14 +346,14 @@ with a Hero replaces the standard page header and does not display its dates.
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@0.1.0-alpha.19 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-beta.1 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.
 
 ## Status and development
 
-This alpha may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
+This beta may change configuration and output formats between releases. No compatibility promise or maintained older release line is offered yet. Creating and previewing a basic site does not require a model provider or Chrome. Optional provider-backed features require their own configuration.
 
 Shoalrun is maintainer-led and does not accept unsolicited pull requests at this time. The [repository development instructions](https://github.com/shoalrun/shoalrun#develop-the-framework) explain how to build and test your own checkout or fork.
 

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

@@ -26,17 +26,19 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Branding guidance and safer hosted chat](https://www.shoalrun.com/changelog/branding-security.md) — ID: change.branding-security. changelog-entry; 936 tokens. Match your documentation to your brand with an agent skill, and bind hosted-chat visitor checks to the intended site.
 
+- [Styled PDFs and custom code languages](https://www.shoalrun.com/changelog/pdf-custom-languages.md) — ID: change.pdf-custom-languages. changelog-entry; 487 tokens. Print branded pages, export a complete PDF manual, and highlight your own code language.
+
 - [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
 
 - [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 468 tokens. Reviewed agent drafts, search improvements, and answer context.
 
 - [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 384 tokens. Project discovery and captured working-tree validation.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1407 tokens. Compiler, CLI, and reader changes.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1472 tokens. Compiler, CLI, and reader changes.
 
 - [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1147 tokens. MCP hosting, analytics, and shared component content.
 
-- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1095 tokens. Navigation sections, reader controls, layouts, and browser analytics.
+- [Navigation, page layouts, and browser analytics](https://www.shoalrun.com/changelog/2026-10-16-navigation-layouts.md) — ID: change.navigation-layouts. changelog-entry; 1093 tokens. Navigation sections, reader controls, layouts, and browser analytics.
 
 - [Search results and tooltips](https://www.shoalrun.com/changelog/2026-10-18-search-and-tooltips.md) — ID: change.search-and-tooltips. changelog-entry; 675 tokens. Indexed search and hover and focus tooltips.
 
@@ -46,4 +48,4 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 821 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
 
-- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1850 tokens. Current capabilities, planned features, and known limits.
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1918 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "27e393134027da5587c4102f6d4a4e9598f2bed5",
-  "siteBuildId": "3ca70f64a4b3562b2c51fd6a4a6beceb3578705d2fc545b7788589aebd0e6ff5",
-  "manifestDigest": "2fb2a205cf322384919c7546e0626c42de82c34cfcdc2f5e244c92968993fd03",
-  "indexDigest": "66cbcb506a60f1a1588e76135ab195c1491cb69337526f21979aed936d4478c5",
-  "packageIntegrity": "sha512-UMknmhUPoDv6tSOUlIjfeEuOHANy/+pEouq8wGEXlAxN9uRaVqcO/bSRcXQkLZvWLIolLcqkFDRjAUzVNimFDA=="
+  "sourceCommit": "01614c57a52c0157fb48fc12f434962f27f704e7",
+  "siteBuildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f",
+  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132",
+  "indexDigest": "090e6b3f4bd7c9968b75b609a695e6ebd6f596a66135db41968c3905258a25d6",
+  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
 }

package/agent-docs/about.md

@@ -1,7 +1,7 @@
 ---
 id: guide.about
 title: About Shoalrun
-summary: Learn what Shoalrun is exploring and where the alpha stands.
+summary: Learn what Shoalrun is exploring and where the beta stands.
 type: overview
 area: project
 subarea: project-overview
@@ -12,7 +12,7 @@ canonical: /about
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-10-27.**
+**Updated: 2026-11-06.**
 
 I'm CT Smith, and I'm building Shoalrun cause there's no such thing as a perfect doc tool. I have opinions, undirected rage, and curiosity about doc-building tools. I built my first documentation generator back in 2015. It was based on Jekyll and relied heavily (probably too heavily) on general templating and... you guessed it... *page metadata*.
 
@@ -42,7 +42,7 @@ API content follows the same approach. Local OpenAPI files can supply reference
 
 I'm building Shoalrun for tinkerers like me, who will never be fully satisfied with a mass market docs tool. Docs are never one-size-fits-all, on any level.
 
-You can try the alpha CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
+You can try the beta CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
 
 yee haw forever,
 

package/agent-docs/author/agent-overview.md

@@ -20,7 +20,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Tools overview
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 **Status: Experimental.**
 
@@ -40,7 +40,7 @@ Existing checked plan/apply commands remain available for clients that need them
 
 Compiler checks establish structural validity. They don't establish factual accuracy, clear writing, or a successful reader task. Review the diff, supporting evidence, and rendered documentation before using your project's release process.
 
-Local previews serve the exact captured build and show its freshness. Review reports list task scope, affected HTML/Markdown, findings, checks, and dependencies. The portable authoring skill guides this working-tree workflow. Independent author trials remain separate from these checks. Install the alpha CLI through [Getting started](https://www.shoalrun.com/start.md).
+Local previews serve the exact captured build and show its freshness. Review reports list task scope, affected HTML/Markdown, findings, checks, and dependencies. The portable authoring skill guides this working-tree workflow. Independent author trials remain separate from these checks. Install the beta CLI through [Getting started](https://www.shoalrun.com/start.md).
 
 ## Related reading
 

package/agent-docs/author/components/code-blocks.md

@@ -16,7 +16,7 @@ Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/na
 
 Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Code blocks
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 Fenced code is ordinary Markdown rather than an MDX component. It belongs in the component reference because authors use it beside components to show commands, configuration, and payloads.
 
@@ -70,6 +70,51 @@ To use a theme you know from your editor, set `theme` to a bundled Shiki theme n
 
 The built-in grammars are JSON, YAML, shell, JavaScript, TypeScript, Python, HTML, CSS, MDX, Markdown, HTTP, XML, SQL, Go, Java, Ruby, C#, PHP, and Rust. Shiki also recognizes loaded aliases such as `sh` and `js`. Unknown or unlabeled code stays plain. JSON-compatible API examples use JSON highlighting; text media currently use plain text.
 
+### Add your language's grammar
+
+Since 0.1.0-beta.1
+
+Use `languages` with Shiki to add a custom language without writing a highlighter adapter. Give it an ID, a local TextMate JSON grammar, and optional aliases:
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    highlighting:
+      provider: shiki
+      languages:
+        - id: custompy
+          grammar: ./grammars/custompy.tmLanguage.json
+          aliases: [cpy]
+```
+
+For example, this small grammar adds two illustrative keywords before using Python's bundled syntax rules:
+
+```json title="grammars/custompy.tmLanguage.json"
+{
+  "scopeName": "source.custompy",
+  "patterns": [
+    { "name": "keyword.control.custompy", "match": "\\b(?:publish|unless)\\b" },
+    { "include": "source.python" }
+  ]
+}
+```
+
+Use `custompy` or `cpy` as the fence language:
+
+````md
+```custompy
+def welcome(name):
+    unless name is None:
+        publish "Hello, " + name
+```
+````
+
+The grammar path is relative to the config file that declares it, including imported fragments. Use a local JSON file no larger than 4 MiB; XML `.tmLanguage` files aren't supported. The grammar needs a `scopeName` and a `patterns` array. Choose a distinct scope name, and don't reuse a bundled language ID or alias. IDs and aliases use lowercase letters, digits, underscores, or hyphens and start with a letter.
+
+The grammar is a build dependency. `dev` watches it, and isolated authoring validation captures it. Changing the rules rebuilds the colors; a missing or malformed grammar fails the build without replacing valid output. Registrations are isolated between projects built in the same process. Grammar files aren't copied into the browser's assets.
+
+This adds syntax colors to website HTML, not language validation or autocomplete. Filenames remain labels; they don't choose a grammar. The Markdown twin keeps the original code and language ID. Retain applicable license notices when using or adapting an existing grammar.
+
 ### Choose plain code
 
 ```yaml

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

@@ -87,6 +87,7 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 | `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
 | `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
 | `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `pdf`                  | boolean         | Optional     | Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.                                                                                                    |
 | `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.

package/agent-docs/author/frontmatter-reference.sections/categorize-connect-and-present-the-page.md

@@ -57,6 +57,7 @@ By default, `product`, `area`, and `subarea` are optional, nonempty string categ
 | `layout`               | string          | Optional     | HTML page layout: docs (default), wide (no page outline, full content width), landing (no sidebar or outline; a Hero replaces the page header), or splash (full-bleed marketing page built from Hero and Section blocks).                                                   |
 | `showNavigationTabs`   | boolean         | Optional     | Show the HTML navigation section bar when tabs are configured. Defaults to true for docs and wide layouts, false for landing and splash. Does not change agent discovery or section membership.                                                                             |
 | `showVerified`         | boolean         | Optional     | Show an authored verified date in the HTML page header. Defaults to true. False hides it only in HTML; Markdown and manifest dates remain unchanged. Does not assign a verification date.                                                                                   |
+| `pdf`                  | boolean         | Optional     | Controls the optional page print/PDF action. False suppresses its control and endpoint inputs; true follows the site setting. Site builds do not generate per-page PDFs.                                                                                                    |
 | `image`                | string          | Optional     | Local .png or .jpg shown in link previews for this page, relative to the page file; replaces the generated share image. Best at 1200×630.                                                                                                                                   |
 
 Projects can opt into built-in category enforcement with `frontmatter.taxonomy`. It declares areas and their allowed subareas, optional required fields, and optional explicit-field requirements for authored pages. Its `multiple` list permits arrays for selected category fields; otherwise each field allows one value. Defaults and enforced values still apply; generated API references use resolved categories. Definitions appear in the document manifest and constrain the generated frontmatter schema. Omit taxonomy or set it to false to preserve optional category behavior.

package/agent-docs/author/workspace.md

@@ -20,11 +20,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Write with agents > Check edits
 
-**Updated: 2026-11-05.**
+**Updated: 2026-11-06.**
 
 **Status: Experimental.**
 
-Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the alpha package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key aren't required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
+Use this procedure from your documentation project directory, containing `docs.config.yaml`, with `@shoalrun/cli` installed. [Getting started](https://www.shoalrun.com/start.md) explains how to install the beta package from npm. You need Node.js 22.12 or newer; a framework source checkout and a separate authoring provider key aren't required. Your coding agent uses its own model and file tools. Replace the example page path with your project's path.
 
 Framework contributors can instead build the source checkout and run `node framework/dist/cli.js <command>` from its root. The examples below use the installed package.
 

package/agent-docs/author/writing-style.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.**
 
 This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
 
@@ -42,7 +42,7 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
 | Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
 | Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
 | Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
-| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+| Changelog entry | Understand a dated change.                     | A short capability summary, links to the feature guides, and required upgrade or migration actions. Claim a release only with release evidence.                                         |
 
 Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
 
@@ -54,6 +54,12 @@ Run customer commands from a project with the pinned npm package installed, usin
 
 These are editorial shapes, not a reason to add empty boilerplate. Follow the [template rules](https://www.shoalrun.com/author/templates.md) and adapt the outline to the reader's need. Headings in a page body start at level two because the renderer supplies the title. Don't add step numbers to authored headings. For a procedure with titled steps, use the [Steps component](https://www.shoalrun.com/author/components/steps.md); it supplies the numbering in HTML and Markdown.
 
+## Release notes
+
+Keep release notes short and factual. Name what readers can do, link each feature heading to its guide, and state the exact upgrade or rebuild action. Prefer a brief paragraph per feature; leave configuration examples and detailed behavior in the linked documentation.
+
+Include before/after explanations only when readers upgrading from a published release need them. Omit development history, discarded designs, implementation walkthroughs, test counts, and generic recaps. Expand when a migration or security action needs explanation. Release-note summaries link to feature guides for HTML, Markdown, and agent details instead of repeating those sections.
+
 ## Voice and explanations
 
 Use natural contractions such as “don't,” “can't,” “it's,” and “you're.” Keep expanded forms when emphasis or clarity needs them. Preserve exact commands, configuration values, API fields, error messages, and quotations. Vale's `Shoalrun.Contractions` rule flags common expanded forms for review; contractions themselves are accepted.
@@ -107,7 +113,7 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Don't hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+Don't hide an essential instruction inside decoration. Component references and guides that explain a presentation feature need an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
 
 A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.
 

package/agent-docs/author/writing-style.sections/adapt-this-example.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/author/writing-style.sections/choose-components-by-reader-need.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)
 
@@ -39,6 +39,6 @@ Choose the structure that helps readers use the information or complete the task
 
 Introduce every table with a sentence explaining what readers should use it for. Never place a table directly after a heading. The formatting check enforces this rule with `DocShape.TableIntroduction`.
 
-Don't hide an essential instruction inside decoration. Every page documenting a component or presentation feature needs an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
+Don't hide an essential instruction inside decoration. Component references and guides that explain a presentation feature need an **HTML, Markdown, and agents** section, or an existing clearly named equivalent. Explain what HTML shows or lets readers do, what Markdown retains or omits, and how an agent gets the information needed for the task. Include limitations and keyboard or JavaScript behavior when relevant. Check both rendered outputs.
 
 A page that merely uses a callout, link, or Steps component needs the section only when that use changes access to information. Avoid generic claims that both formats are identical: explain the actual representation. Cookbook pages must distinguish their recipe links from the complete instructions in the linked recipes or a downloaded selection.

package/agent-docs/author/writing-style.sections/evidence-and-uncertainty.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/author/writing-style.sections/example-audience-and-scope.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/author/writing-style.sections/feature-availability.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/author/writing-style.sections/ingredients-recipes-and-cookbooks.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/author/writing-style.sections/page-purpose-and-structure.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)
 
@@ -36,7 +36,7 @@ Choose the page type by the reader's goal and the actual content. Keep one prima
 | Ingredient      | Reuse one task step in several recipes.        | Required inputs and prerequisites, one action with its instructions, named outputs, and an observable check. Keep the step independent of any recipe's position or neighboring wording. |
 | Recipe          | Complete one task from a known starting state. | Outcome, prerequisites, ordered actions, failure guidance, and a final success check. Include everything needed to follow the published page on its own.                                |
 | Cookbook        | Choose between complete recipes.               | Explain who each path is for, what it needs, and what it produces; link to the published recipe pages. State whether choices are alternatives or can be combined.                       |
-| Changelog entry | Understand a dated change.                     | User-visible behavior, scope, migration when needed, and limitations. Say when a change concerns the private prototype; claim a release only with release evidence.                     |
+| Changelog entry | Understand a dated change.                     | A short capability summary, links to the feature guides, and required upgrade or migration actions. Claim a release only with release evidence.                                         |
 
 Use **Before you begin**, **Check the result**, and **Next steps** for recurring task sections when revising a procedure. Keep action headings specific to the task. Existing tutorials can retain established headings when tools or incoming fragments depend on them. A short procedure may put prerequisites in its introduction; omit sections that add no useful information.
 

package/agent-docs/author/writing-style.sections/procedures-and-examples.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/author/writing-style.sections/related-reading.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/author/writing-style.sections/release-notes.md

@@ -0,0 +1,30 @@
+---
+id: reference.writing-style
+title: Example writing guide
+summary: Adapt this site's writing guide for your own documentation and agent
+  instructions.
+type: reference
+area: authoring
+subarea: authoring-writing
+canonical: /author/writing-style
+---
+
+# Example writing guide
+
+> 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) > Authoring reference > Example writing guide
+
+**Updated: 2026-11-06.**
+
+Parent page: [Full Markdown page](/author/writing-style.md)
+
+This page is an example of a project writing guide. The rules below are the house style for Shoalrun's own documentation site, and authors and agents use them through project instructions. Shoalrun doesn't automatically apply these rules to other projects.
+
+## Release notes
+
+Keep release notes short and factual. Name what readers can do, link each feature heading to its guide, and state the exact upgrade or rebuild action. Prefer a brief paragraph per feature; leave configuration examples and detailed behavior in the linked documentation.
+
+Include before/after explanations only when readers upgrading from a published release need them. Omit development history, discarded designs, implementation walkthroughs, test counts, and generic recaps. Expand when a migration or security action needs explanation. Release-note summaries link to feature guides for HTML, Markdown, and agent details instead of repeating those sections.

package/agent-docs/author/writing-style.sections/review-a-draft.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/author/writing-style.sections/reviewed-writing-examples.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/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/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,7 +16,7 @@ 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.
 
@@ -30,6 +30,14 @@ Updates to Shoalrun and its documentation. Each entry identifies the affected ve
 
   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/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.19
+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.19
+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