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

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # 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
+  site to your brand. It guides the agent through choosing colors and fonts,
+  adding your logo, and applying theme settings and CSS. It also checks search
+  results, menus, buttons, keyboard focus, and mobile layouts for readability.
+  Read it with `shoalrun skills read shoalrun-brand`.
+- Make hosted chat verify where a visitor check came from. Turnstile responses
+  must match a trusted hostname and, when configured, the expected action.
+  A session pass from a different hostname/action policy no longer skips the
+  check, even when the deployments share a secret. Changing the policy
+  invalidates existing passes. Upgrade the CLI, then rebuild and
+  redeploy hosted chat to apply these protections.
+- Keep local and hosted test previews working with Turnstile's published test
+  keys. Local preview checks the actual dummy-token response; the documentation
+  site's hosted preview requires test credentials and a separate usage store.
+- Check development dependencies as well as production dependencies in both
+  repositories during a coordinated release. Update the documentation site's
+  browser tools and affected dependencies to remove the identified security
+  advisories without forcing incompatible package versions.
+- Add security headers to the documentation site that restrict framing to the
+  same origin and set an explicit referrer policy. Deployment checks now reject
+  responses missing the required headers. A broader Content Security Policy
+  starts in report-only mode so browser violations can be reviewed before
+  enforcement; it doesn't yet block scripts. These are site-owned settings,
+  not new defaults imposed on customer sites.
+- Refresh the repository and package READMEs with product versions, customer
+  editions, branding, application content delivery, and agent workflows. Update
+  the hosted-chat guide with hostname checks, optional actions, session passes,
+  and preview configuration.
+
 ## 0.1.0-alpha.18 — 2026-11-04
 
 - Add authored page availability ranges with `since` and `through` version

package/README.md

@@ -1,25 +1,17 @@
 # Shoalrun
 
-Shoalrun turns Markdown and MDX into a documentation website and Markdown pages from the same content. People can browse the site; agents can read the Markdown. Native components such as steps, tabs, and API references preserve their content in both formats.
+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.18
+npm install --save-dev --save-exact @shoalrun/cli@0.1.0-beta.1
 ```
 
-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.18 --@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.
-
 ## Create and preview a site
 
 Run these commands from the directory where you installed the package:
@@ -38,11 +30,44 @@ npx --no-install shoalrun dev my-docs/docs.config.yaml my-docs/site-dist --port
 
 Stop the existing preview with Ctrl-C before starting the development server on the same port. Choose **Explore the starter**, the first item in the left navigation, to find component examples, diagrams, reader views, themes, and generated API references. The service and API hosts are fictional; replace them before sending requests. Choose `--starter minimal` for a smaller starting point or `--starter api-docs` for a focused OpenAPI example. All three starters build without provider credentials.
 
+## What you can build
+
+The [features overview](https://www.shoalrun.com/features) describes the complete authoring and delivery workflow. Start with the part you need:
+
+| Need | Capability |
+| --- | --- |
+| A documentation site | Pages, navigation, local preview, themes, palettes, fonts, and project CSS. |
+| Reusable procedures | Recipes, shared ingredients, and cookbooks that help readers choose a complete task. |
+| API reference | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
+| Several product releases | Independent product versions and defaults, publication routes, and a header publication selector. |
+| Customer editions | External profiles, SKU revisions, feature grants, and conditional pages or sections. |
+| Application help | HTML and Markdown exports, stable page/section/snippet references, static and REST clients, and instance-safe mounting. |
+| Agent discovery | Markdown twins, compact linked indexes, read-only MCP tools, bundled skills, and offline references. |
+| Search and answers | Browser keyword search, optional semantic retrieval, and hosted documentation chat with shared limits. |
+
+Local builds and keyword search need no provider credentials. Semantic retrieval and generated answers use separately configured services; credentials stay server-side. Reader filters are browsing controls, not authorization. Customer profiles select output during compilation; private-edition hosting remains your responsibility.
+
+## Match your brand
+
+Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a theme preset and configure `theme.palette`, `theme.mode`, and `theme.fonts`. Use `site.customCss` for changes beyond those settings. Customer profiles can supply deployment-owned branding without storing customer records in the shared source.
+
+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.
 
-Available since `0.1.0-alpha.18`.
+Product catalogs and profile-aware development preview are available since `0.1.0-alpha.18`. The product names and versions below are an example configuration.
 
 The header publication dropdown groups the published releases by product. It hides language labels when the edition has one language; set `site.publicationSelector.showLanguage: true` or `false` to override that display without changing publication identity.
 
@@ -87,7 +112,7 @@ publications:
 The shared configuration must declare `profiles.manifest`, which defines the known features and SKU revisions. Each selected publication must be enabled by that configuration. Preview the customer edition directly:
 
 ```sh
-npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/acme.yaml --port 8770
+npx --no-install shoalrun dev docs.config.yaml site-dist --profile customers/example.yaml --port 8770
 ```
 
 The development server compiles the selected edition and watches its profile, SKU manifest, and declared assets, including files outside the project. Editing the profile rebuilds the edition and removes output that is no longer selected. The preview identifies the last successful edition. If a rebuild fails, it keeps that output and displays the failure on existing and newly opened pages. Reader views remain browsing controls; customer profile selection applies during compilation to HTML, Markdown, navigation, and indexes.
@@ -96,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 explain how to set up a site, edit pages, and develop components:
+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
@@ -105,7 +130,7 @@ npx --no-install shoalrun skills read shoalrun-setup
 
 Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
 
-The usual editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
+The editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
 ```sh
 npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
@@ -113,7 +138,7 @@ npx --no-install shoalrun docs baseline --out .shoalrun/task-baseline.json
 npx --no-install shoalrun docs validate --baseline .shoalrun/task-baseline.json
 ```
 
-Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements—the starter does not define them for you.
+Validation returns a report path. Pass that path to `shoalrun docs review` and `shoalrun docs preview`. Snapshot validation can render affected draft pages while preserving their draft access; ordinary site builds exclude drafts. Supply your own project writing and review requirements. Configured checks and custom plugins execute trusted project code; a validation copy is not an operating-system sandbox.
 
 ## Find documentation
 
@@ -297,18 +322,6 @@ The limit applies to each index response, not an entire multi-step reading sessi
 An individual title or summary too large to fit an index produces an explicit
 build error rather than silently dropping content.
 
-## 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.
-
-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.
-
-Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
-
-## License
-
-Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.
-
 ## Verification dates
 
 Set `verified` only after checking a page's technical claims. It is separate from
@@ -327,3 +340,25 @@ in HTML only; Markdown and manifest metadata retain it. Set
 `frontmatter.defaults.showVerified: false` in project configuration for a shared
 default, then override it with `showVerified: true` on individual pages. A layout
 with a Hero replaces the standard page header and does not display its dates.
+
+## Upgrade from the earlier private registry
+
+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-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 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.
+
+Pin an exact package version and read the [changelog](CHANGELOG.md) before upgrading. Rebuild and check HTML, Markdown, links, and any application consuming exported content before deploying. See the [contribution policy](https://github.com/shoalrun/shoalrun/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/shoalrun/shoalrun/blob/main/SECURITY.md) for reporting problems and project trust boundaries.
+
+## License
+
+Copyright 2026 Casey Smith. This package is licensed under [Apache-2.0](LICENSE). Your authored site content keeps its own license. Built sites contain runtime assets and may contain copied template text; retain applicable licenses and third-party notices when distributing them.

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

@@ -24,17 +24,21 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Smaller hosted search and Ask functions](https://www.shoalrun.com/changelog/2026-11-04-runtime-packaging.md) — ID: change.2026-11-04-runtime-packaging. changelog-entry; 647 tokens. Rebuild hosted docs with alpha.17 to reduce deployment files while keeping semantic search and Ask available.
 
+- [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; 1337 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.
 
@@ -44,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": "201a4e562b70414e26ecba7c2488ba899550f06b",
-  "siteBuildId": "41390a172a8dbd578761e016a1c5890718f0b06c37f90b40769f585f75fd71ec",
-  "manifestDigest": "b0996def2c34eaafbb41b5ab5b3ca0e78a370a620ffb4b8bfe53bc6248300d05",
-  "indexDigest": "ed3b6ccce7e13cb3d038707a22430a76367522344d879a166d2764d445c16e06",
-  "packageIntegrity": "sha512-91enZzr2NCzCFo8OXfEZWjI7SQD+FVlFtEwRD30UKaMD3OBjgVY0wBgZyvVULXMUoZkdbyOj/OpdfDw/Tkk1ww=="
+  "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)