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

package/agent-docs/publish/pdf.sections/offer-direct-downloads-through-a-node-server.md

@@ -0,0 +1,46 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Offer direct downloads through a Node server
+
+For generation when a reader clicks, use endpoint mode:
+
+```yaml
+outputs:
+  html:
+    pdf:
+      mode: endpoint
+      endpoint: /__shoalrun/pdf
+      label: Download PDF
+```
+
+Build and run the output with `shoalrun serve`. The Node server automatically loads the prepared page inventory. The first request generates its PDF; subsequent requests generate it again. Requests are limited to one active generation and ten generation attempts per minute per server instance. Busy requests receive a retry response. There's no shared PDF cache.
+
+The endpoint accepts only the page's opaque build-selected key. It can't select another profile, accept custom CSS, or print an arbitrary URL. It returns an attachment with `Cache-Control: no-store`. Mount the endpoint behind the same authentication as the site. Build-time audience selection isn't visitor authorization.
+
+Endpoint page downloads use `outputs.pdf` styling and omit the publication cover and contents. Optional `outputs.html.pdf.style` selects a named export target's `pdf` settings, just as it does for browser print views. Only that styling applies; the target's document list, publication, and filter don't change the current page selection.
+
+For a custom Node host, import `loadPdfRuntime` and `createPdfHttpHandler` from `@shoalrun/cli/pdf/server`. Mount the returned Web-standard handler at the runtime's endpoint; use its `authorize` callback or your existing authentication middleware. Keep `pdf-runtime.json` and `__shoalrun/pdf-data` out of public static serving. The built-in Node server protects those paths. Don't upload an endpoint-mode build to a generic static host.

package/agent-docs/publish/pdf.sections/prerequisites.md

@@ -0,0 +1,37 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Prerequisites
+
+Start with a Shoalrun project and an enabled publication. Browser page printing needs no build-time browser or PDF service. For CLI PDF export, install Chrome or Chromium on the machine that generates the file. Shoalrun doesn't download a browser during installation. Set `SHOALRUN_PDF_BROWSER` to the browser executable, or configure `outputs.pdf.executablePath`.
+
+For example, on macOS with Chrome installed in Applications:
+
+```sh
+export SHOALRUN_PDF_BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+
+CLI exports need the configured browser. Endpoint generation needs it on the Node server. The Vercel build adapter supports browser page printing and rejects endpoint mode before building.

package/agent-docs/publish/pdf.sections/publish-an-optional-manual-download.md

@@ -0,0 +1,39 @@
+---
+id: guide.pdf-export
+title: Export styled PDFs
+summary: Export a page or publication as a PDF and offer an optional page download.
+type: how-to
+area: publishing
+subarea: publishing-builds
+canonical: /publish/pdf
+---
+
+# Export styled PDFs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > Export styled PDFs
+
+**Updated: 2026-11-06.**
+
+**Available since: 0.1.0-beta.1.**
+
+Parent page: [Full Markdown page](/publish/pdf.md)
+
+Offer **Print PDF** on a static site using the visitor's browser. Site builds generate no page PDFs or extra print documents. When you want a downloadable full manual, export it explicitly through the CLI with your own fonts, colors, paper size, and print layout. A Node host can also offer direct page PDF downloads on request.
+
+## Publish an optional manual download
+
+Generate a complete selected publication with the CLI only when you want a downloadable manual. Keep its export directory outside the site build destination. After generating `pdf/manual/publication.pdf`, build the site and copy the PDF into the deployment output:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+mkdir -p site-dist/downloads
+cp pdf/manual/publication.pdf site-dist/downloads/manual.pdf
+```
+
+Add an ordinary content, header, or footer link to `/downloads/manual.pdf`, and run your site's link checks after copying. This example assumes root hosting; place the file and link under the configured base path when using one. Deploy it with the site. A later site build replaces its output, so repeat the explicit copy as part of your deployment workflow.
+
+Shoalrun doesn't automatically publish CLI export directories or create a full-manual download button. One optional manual file can serve the publication without prebuilding a PDF for every page. Use the same publication and customer profile for the site and manual.

package/agent-docs/publish.md

@@ -36,6 +36,8 @@ Review the generated HTML, Markdown, and `dist/documents.json`. A build replaces
 
 Choose a hosting route based on the artifacts and server features your site needs.
 
+For [page printing](https://www.shoalrun.com/publish/pdf.md), static sites use the visitor's browser and generate no page PDFs or extra print documents. Optionally publish a full-manual CLI export as a deliberate download. Direct endpoint downloads need a Node host with Chromium; don't expose their prepared private inputs through generic static serving.
+
 | Hosting route                                        | What to deploy                                                                                                                         |
 | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | [Vercel](https://www.shoalrun.com/publish/vercel.md) | The `.vercel/output/` bundle generated by the installed CLI.                                                                           |

package/agent-docs/reference/agent-skills.md

@@ -19,7 +19,7 @@ Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Commands > Bundled a
 
 **Updated: 2026-11-05.**
 
-Shoalrun ships five portable skill folders under `framework/skills/`. Each folder contains a `SKILL.md` with instructions for an agent that can read files and run the Shoalrun CLI. A skill supplies guidance; it doesn't run a separate authoring service.
+Shoalrun ships portable skill folders under `framework/skills/`. Each folder contains a `SKILL.md` with instructions for an agent that can read files and run the Shoalrun CLI. A skill supplies guidance; it doesn't run a separate authoring service.
 
 These are authoring skills for Shoalrun. The build doesn't create a reader-side skill for each published site. Agents reading a generated site use its Markdown twins, `/llms.txt`, and `/documents.json`. A non-interactive skill builder is a [non-goal](https://www.shoalrun.com/non-goals.md): skill creation and maintenance need guidance from a human expert.
 
@@ -34,12 +34,16 @@ Each skill supplies instructions for a specific part of the authoring workflow.
 | `shoalrun-recipes`          | Write task-oriented how-tos as complete recipes, reuse ingredients where helpful, and configure cookbook choices.                                                                                                          |
 | `shoalrun-component-author` | Create trusted [custom components](https://www.shoalrun.com/author/components/custom.md), validate their schemas and shared content, and review HTML/Markdown parity.                                                      |
 | `shoalrun-walkthrough`      | Turn notes, a tutorial, or project code into a [walkthrough](https://www.shoalrun.com/author/components/walkthroughs.md) that explains code step by step.                                                                  |
+| `shoalrun-brand`            | Apply website branding through themes, fonts, local assets, and CSS, then check contrast and interactive states.                                                                                                           |
+| `shoalrun-pdf`              | Style and export pages or publications as [PDFs](https://www.shoalrun.com/publish/pdf.md), configure optional downloads, and inspect actual PDF output. Includes a print design reference and stylesheet starter.          |
 
 Each folder name matches its skill name. For example, the author skill's entry file is `framework/skills/shoalrun-author/SKILL.md`. Installation locations depend on the agent. [Use the bundled agent skills](https://www.shoalrun.com/contribute/agent-skills.md) describes choosing and invoking one.
 
 ## Workflow behavior
 
-The setup skill uses `shoalrun init` to create a project from the bundled `minimal` or `api-docs` starter, then uses `config validate`, `build`, and `dev` to check the result. The author skill uses stable IDs and project config provenance so edits stay attached to the intended publication. The walkthrough skill chooses a mode and layout, prefers code taken from project files, and checks each step's highlight. The recipes skill starts from a reader goal and success check, reuses ingredient source when useful, and distinguishes authoring from browser selection. All five ask the agent to inspect generated HTML and Markdown. They leave deployment decisions with the site owner.
+The setup skill uses `shoalrun init` to create a project from the bundled `minimal` or `api-docs` starter, then uses `config validate`, `build`, and `dev` to check the result. The author skill uses stable IDs and project config provenance so edits stay attached to the intended publication. The walkthrough skill chooses a mode and layout, prefers code taken from project files, and checks each step's highlight. The recipes skill starts from a reader goal and success check, reuses ingredient source when useful, and distinguishes authoring from browser selection.
+
+The branding skill checks website surfaces and interactive states. The PDF skill checks print layout, exact publication/profile selection, links, fonts, and rendered PDF pages. Static sites use browser page printing; downloadable manuals are optional CLI exports. Direct on-demand PDF downloads need a Node host. The skills ask the agent to inspect the outputs relevant to its task and leave deployment decisions with the site owner.
 
 The author skill starts with project-wide discovery and policy reads, captures a task baseline, and edits ordinary working-tree files. It validates a separate capture and opens the matching snapshot review/preview. Required companions come from project policy; compiler success doesn't waive them. Existing local edits are included in the baseline rather than attributed to the new task. No extra authoring model key is needed. Explicit checked-plan clients can still use [Apply a checked edit plan](https://www.shoalrun.com/author/authoring-agent.md).
 
@@ -51,7 +55,7 @@ The skill is an instruction file, not a compiler feature or an automatic React-t
 
 ## Offline documentation
 
-All five skills can consult Shoalrun's bundled docs through a local, agent-neutral tool:
+The skills can consult Shoalrun's bundled docs through a local, agent-neutral tool:
 
 ```sh
 shoalrun docs search "API reference navigation"