@heroiclands/package-build 25.6.3 → 25.7.0

package/docs/api.md

@@ -193,16 +193,18 @@ Whether a content tree has anything to compile. The pack build's worst failure i
 
 The consuming repository's resolved `package-build.config.yaml`: the content package, the Foundry package and its kind, every path, the `_stats` identity, item-type membership and the pack list — read on call rather than hoisted at import, so importing this package never requires a configuration to exist.
 
-| Export              | Signature                            | Returns                       | Use it when                                                                          |
-| ------------------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------ |
-| `CONFIG_BASENAME`   | `const CONFIG_BASENAME`              | —                             | naming the stem every consuming repository declares its build under                  |
-| `CONFIG_FILENAMES`  | `const CONFIG_FILENAMES`             | —                             | listing the file names a configuration may be written as                             |
-| `findConfigFile`    | `findConfigFile(from)`               | `string \| undefined`         | finding the nearest configuration file at or above a directory                       |
-| `resolveConfigFile` | `resolveConfigFile(...)`             | `{path, fromCwd, fromModule}` | asking which configuration file a build launched here would read, without loading it |
-| `locateConfigError` | `locateConfigError(err, configPath)` | the decorated error           | attaching the position of the key a configuration error names                        |
-| `configFromData`    | `configFromData(data, configPath)`   | `ContentBuildConfig`          | turning a parsed YAML configuration into the frozen one the engine reads             |
-| `loadPackConfig`    | `loadPackConfig()`                   | `ContentBuildConfig`          | reading the consuming repository's resolved, frozen configuration                    |
-| `packConfigPath`    | `packConfigPath()`                   | `string`                      | naming the file `loadPackConfig` resolved the configuration from, for a diagnostic   |
+| Export              | Signature                            | Returns                       | Use it when                                                                                      |
+| ------------------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `CONFIG_BASENAME`   | `const CONFIG_BASENAME`              | —                             | naming the stem every consuming repository declares its build under                              |
+| `CONFIG_FILENAMES`  | `const CONFIG_FILENAMES`             | —                             | listing the file names a configuration may be written as                                         |
+| `findConfigFile`    | `findConfigFile(from)`               | `string \| undefined`         | finding the nearest configuration file at or above a directory                                   |
+| `resolveConfigFile` | `resolveConfigFile(...)`             | `{path, fromCwd, fromModule}` | asking which configuration file a build launched here would read, without loading it             |
+| `locateConfigError` | `locateConfigError(err, configPath)` | the decorated error           | attaching the position of the key a configuration error names                                    |
+| `configFromData`    | `configFromData(data, configPath)`   | `ContentBuildConfig`          | turning a parsed YAML configuration into the frozen one the engine reads                         |
+| `loadPackConfig`    | `loadPackConfig()`                   | `ContentBuildConfig`          | reading the consuming repository's resolved, frozen configuration                                |
+| `packConfigPath`    | `packConfigPath()`                   | `string`                      | naming the file `loadPackConfig` resolved the configuration from, for a diagnostic               |
+| `readPackConfig`    | `readPackConfig(configPath)`         | `ContentBuildConfig`          | reading the configuration one named file declares, unmemoised                                    |
+| `withPackConfig`    | `withPackConfig(config, fn, file?)`  | what `fn` returns             | running work, asynchronous included, with `config` as the configuration `loadPackConfig` answers |
 
 ### `engine.packRouter`
 
@@ -621,12 +623,11 @@ The npm-installed Graphviz runtime draws SVG maps. The `.dot` source stays besid
 
 The map from each place, drawn for the site: `package-build site build` draws the map from every place of this package given a **From here** section — with the site's base, so every name links through it — and sets each drawing inline in that section, where its place names stay links. `site.maps: false` gives no place the section, and nothing is drawn.
 
-| Export                | Signature                                               | Returns            | Use it when                                                                                                     |
-| --------------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `SITE_MAP_DIR`        | `const SITE_MAP_DIR`                                    | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
-| `inlineSvg`           | `inlineSvg(svg)`                                        | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
-| `drawSiteMaps`        | `drawSiteMaps({ records, foreignIndex, config, base })` | `{maps, findings}` | drawing the map from every place given a **From here** section, keyed by the file name the section names        |
-| `inlineDrawingFigure` | `inlineDrawingFigure(svg, alt)`                         | `string`           | the one HTML block the website sets an inline drawing in, with no blank line to end it early                    |
+| Export         | Signature                                                               | Returns            | Use it when                                                                                                     |
+| -------------- | ----------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `SITE_MAP_DIR` | `const SITE_MAP_DIR`                                                    | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
+| `inlineSvg`    | `inlineSvg(svg)`                                                        | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
+| `drawSiteMaps` | `drawSiteMaps({ records, foreignIndex, config, base, only?, outDir? })` | `{maps, findings}` | drawing the map from every place given a **From here** section, keyed by the file name the section names        |
 
 ### `engine.systems`
 
@@ -1277,6 +1278,36 @@ The deployed layout of a package's pictures, and which of them ship. A Foundry p
 | `stagePackageAssets`      | `stagePackageAssets({ assetsBase, contentPackage, stageDir, title, transform, shippingLicenses })` | `{staged, excluded, findings, manifest}`                                        | staging a package's shipped pictures flat and writing `asset-sets/default.json`; nothing is staged when `findings` is non-empty |
 | `rowsStagingPictureRoots` | `rowsStagingPictureRoots(rows, { rootDir, assetsBase })`                                           | `{index, from, root}[]`                                                         | finding `packageBuild.assets` rows that would copy a picture root around the filter                                             |
 
+### CDN publication transports
+
+Import `@heroiclands/package-build/engine/cdn-publish` directly. `planCdnPublish`
+collects the same asset records and shipping selection as staging, applies the
+provided transform, and builds destination-relative keys plus a named set whose
+sources use its `host` argument. It does not upload anything.
+
+`publishToCdn(plan, { store, dryRun, log })` accepts a destination-independent
+store with async `size(key)`, `read(key)`, optional `write(key, body, contentType)`
+and a safe `describe` string. It validates every planned relative key before
+reading or writing, skips pictures by size, compares set bytes, and withholds the
+set after a picture failure. `dryRun` never calls `write`.
+
+`internalStore({ destination, fetch, transfer })` combines public HTTPS reads at
+`INTERNAL_CDN_HOST` with rsync writes, defaulting to `INTERNAL_CDN_DESTINATION`
+(`atlas:/srv/preview/cdn`). An explicit SSH alias may target `alias:cdn` for the
+forced-rrsync receiver. Writes stage only the supplied bytes in temporary regular
+files, invoke rsync without deletion, and clean up after success or failure.
+`fetch` and `transfer(args)` can be supplied for isolated tests; the default
+transfer executes rsync with batch SSH and strict host-key checking.
+
+`s3Store(credentials)` retains signed S3/R2 requests. `publicStore(host, fetch)`
+provides read-only HTTP comparisons. `CANONICAL_CDN_ORIGIN`, exported from
+`engine/site-config`, names the owned public CDN origin used by pathname
+projection. Its single definition lives in the leaf `engine/site-origins` module
+to avoid a cycle through site configuration and content rendering.
+The CLI owns environment loading and
+`--dest` selection; site builds never call a publisher. See
+[CDN publication](commands.md#package-build-cdn-publish) for operator access.
+
 ### `engine.assetReferences`
 
 Every asset reference in a compiled document states the asset's address: an `<img>` carries `data-asset`, and a path field's address sits in `flags.<system>.assets` on the document holding it, nested to mirror the field's path. A reference to a picture its package does not ship compiles to that package's stand-in and keeps the excluded address.
@@ -1357,6 +1388,16 @@ configuration and incremental render state stay in the calling thread. Every
 update is prepared in a separate output tree, then installed between HTTP
 requests so readers receive complete files.
 
+`buildPackageSite` invokes configured `site.inputs` before content work. The
+module's default export has the `SiteInputsProvider` contract:
+`({config}) => {navigation, files}` or a promise of that object. It receives the
+immutable effective configuration; `navigation` uses `NavigationEntry[]`, and
+`files` is `Record<string, string>` of relative output paths to UTF-8 text.
+Provider files are validated against unsafe paths, symlinks and builder-owned
+output before output replacement, written after the renderer's clearing step,
+and recorded in `written.files`. Without a provider, cached navigation remains
+required. See [local site inputs](configuration.md#local-site-inputs).
+
 ### `engine.contentRender`
 
 `createRenderer(target, options?)` builds the one markdown-it configuration every target renders through. `target` is `"foundry"`, `"web"`, `"preview"` or `"book"`. The renderer holds the configured parser (`md`), the names of the plugins installed (`plugins`), and three functions: `prepare` writes the constructs markdown-it has no syntax for — marked text, captioned items, named blocks, verse and alerts — as HTML between blank lines; `render` prepares and renders to HTML; `renderInline` renders one inline run. The `book` target parses only, and its Typst stage reads the tokens.
@@ -1407,9 +1448,17 @@ locate it in the complete source. LF and CRLF retain their authored lengths.
 
 `previewIndex({ config, records, foreign? })` builds what [`renderPreview`](#enginesitepreview) takes as `index`: the link index, the asset address space, the languages' maps, the icon registry and an `expand` function that resolves a buffer's links, embeds, expressions and figure numbers as the website does. `records` are the content index's records and `foreign` the dependencies' indexes. Build it once per index and reuse it for every render.
 
-| Export         | Signature                                    | Returns                                | Use it when                                                              |
-| -------------- | -------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
-| `previewIndex` | `previewIndex({ config, records, foreign })` | `{ runs, icons, lookupAsset, expand }` | An editor holds a content index and wants the preview to render with it. |
+| Export              | Signature                                         | Returns                                | Use it when                                                               |
+| ------------------- | ------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| `previewIndex`      | `previewIndex({ config, records, foreign })`      | `{ runs, icons, lookupAsset, expand }` | An editor holds a content index and wants the preview to render with it.  |
+| `recordSiteContext` | `recordSiteContext({ config, records, foreign })` | `{ site, assets, events, runs }`       | Resolving a page against content-index records instead of a content tree. |
+
+`recordSiteContext` places every note that publishes a page at the URL the
+site gives it: the homepage at the package root, a note `site.sections` names
+at its section, and every other note at its address. `anchorsOf(record)` may
+answer a note's anchors as its page emits them, generated sections included;
+answering nothing keeps the record's own. `pages` maps each page's URL to its
+record.
 
 ### `engine.sitePreview`
 
@@ -1589,16 +1638,16 @@ A list item opened with `[ ]` or `[x]`, reported. The format has no checkbox: a
 
 One authored pathname, and the four addresses it resolves to. A note names a file once — in `img:`, in `data.portrait:`, in the body of a markdown image — and the first segment says which package owns it when an `assets/` follows. Every surface derives its own address from that one statement: the path inside a Foundry install, the file in the owning repository's tree, the address the website serves, and where the book stages its copy.
 
-| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                                                                          |
-| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                                                                          |
-| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                                                                     |
-| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.                                                    |
-| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.                                                     |
-| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves.                                                  |
-| `assetPathnameKey`      | `function assetPathnameKey(src, config)`      | {string\|null} The pathname, or `null` for an address naming no asset record to look up.           | The pathname one authored image address keys an asset's role and pixel size under, whichever form it was written in. |
-| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory.                                                  |
-| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.                                                      |
+| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                                                                                                           |
+| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                                                                                                           |
+| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                                                                                                      |
+| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.                                                                                     |
+| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.                                                                                      |
+| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves; canonical Heroic Lands CDN assets use effective site.assets in the web form only. |
+| `assetPathnameKey`      | `function assetPathnameKey(src, config)`      | {string\|null} The pathname, or `null` for an address naming no asset record to look up.           | The pathname one authored image address keys an asset's role and pixel size under, whichever form it was written in.                                  |
+| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory.                                                                                   |
+| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.                                                                                       |
 
 ### `engine.contentLinks`
 
@@ -1654,7 +1703,8 @@ Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLa
 | `convertNoteWikilinks`    | `convertNoteWikilinks(body, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap })` | `{{markdown: string, unresolved: Array<object>}}`                                                                                                                                                                                         | Converts the wikilinks in one note's markdown, reporting any that have no target in the content tree.                                                                                                |
 | `expandNoteTables`        | `function expandNoteTables(body,`                                                                           | `{{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}` The body with every table expanded, and where each emitted line came from — which is what lets a diagnostic about the expanded body name an authored position. | Expand prepared SQL tables in one note's markdown, before wikilinks are resolved — so a generated cell may itself be a wikilink.                                                                     |
 | `folderFilename`          | `function folderFilename(name, id)`                                                                         | —                                                                                                                                                                                                                                         | Builds a compendium-source filename for a folder JSON document: `folder_Name_id.json` with non-alphanumeric runs replaced by underscores.                                                            |
-| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories, sources, renderDescription })`                                | generator yielding `{frontmatter, body, description, raw, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                         | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
+| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories, sources, renderDescription, parse })`                         | generator yielding `{frontmatter, body, description, raw, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                         | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
+| `walkMarkdownFiles`       | `walkMarkdownFiles(rootDir, { skipDirectories })`                                                           | generator yielding each `.md` file's absolute path                                                                                                                                                                                        | listing the files `walkMarkdownTree` reads, in its order, without reading them                                                                                                                       |
 
 `buildContentLinkIndex` accepts `{ config?, records, sqlTables?, foreign? }`.
 `records` is the required, supplied content corpus. The optional prepared
@@ -1665,9 +1715,12 @@ so glossary word links resolve to their dictionary entries.
 `renderDescription` option defaults to true; false leaves `description` empty
 while retaining authored body and positions. `walkMarkdownTree` accepts a
 selected `sources` map in walk order and the same rendering option, also true
-by default. Index collection explicitly omits unused rendered descriptions.
-`indexRecordsFor` accepts that selected map, a `syntax` projection function
-and a captured `foreignIndex`. These adapters do not retain state globally.
+by default, and a `parse` function called as `parseMarkdownFile` is, for a
+caller answering from earlier parses. Index collection explicitly omits unused
+rendered descriptions. `indexRecordsFor` accepts that selected map, a `syntax`
+projection function, a captured `foreignIndex` and a `cache` of earlier
+parses and per-note records, the one [`./note-page`](#note-page) keeps. These
+adapters do not retain state globally.
 
 The physical wrappers `lintContentCharset`, `lintContentHtml`,
 `lintContentIcons`, `lintContentImages` and `lintContentTaskLists` accept an
@@ -2152,6 +2205,138 @@ Where HM3 records the template priority — one statement (`data.templatePriorit
 | `HM3_DEFAULT_ITEM_ART` | `const HM3_DEFAULT_ITEM_ART` | —                                 | reading the full map of default item artwork keyed by **note** type (not document subtype) for HM3 items |
 | `hm3DefaultItemArt`    | `hm3DefaultItemArt(type)`    | `string` — the default image path | getting the default art path for an HM3 item's note type, throwing when the type is unknown              |
 
+### `engine.sitePage`
+
+One content page, from its note to its body HTML. The site build renders every
+page through these functions, and [`./note-page`](#note-page) renders a single
+note through the same ones. Nothing here reads a file.
+
+| Export                      | Signature                                | Returns                                            | Use it when                                                                                  |
+| --------------------------- | ---------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `parseNote`                 | `parseNote(source, file, ctx)`           | `{fm, body, bodyLine} \| null`                     | reading a note's frontmatter and body from its text, addresses decoded                       |
+| `contentPage`               | `contentPage(note, ctx)`                 | `{page?, fmLinks, addressFinding?} \| null`        | deciding whether a note publishes a page, and building it                                    |
+| `inlineDrawingFigure`       | `inlineDrawingFigure(svg, alt)`          | `string`                                           | the one HTML block the website sets an inline drawing in, with no blank line to end it early |
+| `pageFrontmatter`           | `pageFrontmatter(page, options)`         | `object`                                           | the frontmatter a page publishes with                                                        |
+| `pageTitle`                 | `pageTitle(page)`                        | `string`                                           | the title a page publishes under                                                             |
+| `resolveArtFields`          | `resolveArtFields(data, webSrc, artSrc)` | `void`                                             | rewriting a page's artwork addresses into the URLs the website serves                        |
+| `isPlainObject`             | `isPlainObject(value)`                   | `boolean`                                          | asking whether a value is a mapping a field may be read from                                 |
+| `renderSitePage`            | `renderSitePage(page, options)`          | `{markdown, figures, data, resolved, …Errors}`     | expanding one page with the passes the site writer uses                                      |
+| `resolveSitePass`           | `resolveSitePass(name, options)`         | `{beforeLinks?: Function}`                         | resolving `site.pass` to its bundle                                                          |
+| `sitePageDecorator`         | `sitePageDecorator(config, index)`       | `Function`                                         | adding the site's infobox and being metadata to a page's frontmatter                         |
+| `siteBodyRenderer`          | `siteBodyRenderer(config)`               | `(markdown, {runs, figures}) => string`            | rendering an expanded page body to the HTML the site writer receives                         |
+| `pageDiagnostics`           | `pageDiagnostics(result, rawOf)`         | `Array<{file, line?, column?, severity, message}>` | turning a page render's findings into located diagnostics                                    |
+| `frontmatterLinkDiagnostic` | `frontmatterLinkDiagnostic(finding)`     | `{file, severity, message}`                        | reporting a wikilink authored in frontmatter                                                 |
+| `addressDiagnostic`         | `addressDiagnostic(finding)`             | `{file, severity, message}`                        | reporting a note whose page has no address                                                   |
+
+`renderSitePage` takes `drawing`, a function from the file name a generated
+**From here** section names to that drawing's SVG text, and sets the drawing
+inline when it answers. The site build answers with the maps it drew.
+
+## `./note-page`
+
+One note, rendered to the body HTML its site page carries, for a preview that
+reads like the published page: links as their labels and unresolved ones
+marked, `.name` spans in bold, query fences evaluated into tables, inline verse
+broken onto its lines and the generated sections a page carries.
+
+```js
+import { renderNoteFile } from "@heroiclands/package-build/note-page";
+
+const { html, styles, findings, cache } = await renderNoteFile("assets/content/Lore/Tides.md", {
+  root: "/path/to/repository",
+});
+```
+
+| Export           | Signature                                                 | Returns                                      | Use it when                                                   |
+| ---------------- | --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `renderNoteFile` | `renderNoteFile(path, { root?, cache?, prepareTables? })` | `Promise<{ html, styles, findings, cache }>` | rendering a saved note of a repository as its site page shows |
+
+`path` is the note, relative to `root` or absolute; `root` is the repository
+or any directory inside it, the working directory by default. The note is read
+from disk, so what is rendered is what is saved. `renderNoteFile` loads the
+repository's `package-build.config.yaml` and its dependencies' fetched indexes,
+derives the content tree's index records as every build does, answers the
+note's own queries and generated sections over them as `package-build site
+build` does, and renders the note through the site build's own page render.
+The repository's configuration answers every read of the configuration made
+during the call, wherever the caller stands. Nothing has to be built first: no
+content index and no site.
+
+The page resolves against the notes it links as their own pages emit them.
+The note is rendered once to learn which of the package's pages it looks up,
+and those notes' query answers and generated sections are prepared beside its
+own, so a link to a generated section such as `#fromhere` resolves, and a
+cross-note `{{ref}}` finds the target's figures, numbered as its page numbers
+them. A place's **From here** drawing is drawn for that place alone, in a
+scratch directory under the system's temporary directory that is removed once
+the drawing is read, and set inline as the site sets it.
+
+**The cache.** The records and the note's answers are kept in
+`build/cache/note-page/` under the repository root, and reused while every
+input they were derived from is unchanged. Nothing is reused otherwise: each
+stored answer is keyed by a hash of its inputs, which are
+
+- package-build's version and the bytes of its own modules, the Node.js
+  version and the DuckDB version;
+- the configuration file's bytes and the resolved configuration;
+- the bytes of every fetched dependency index, and the installed
+  `@heroiclands/fonts` version and manifest;
+- every note's path and the hash of its text, and the package's asset records.
+
+The dependencies' indexes and the configuration are read between two
+readings of those inputs, which are read again after the records are derived
+and around preparing any query answers the store lacks. When any reading
+differs, something changed while it was read: nothing is stored, and the whole
+render is done again from the start, the configuration resolved and the note's
+place in the tree checked afresh, so a retry answers as a fresh call would and
+a store always holds what was derived from the bytes its key names. After
+three such attempts the call throws. The cache holds two stores, each
+replaced whole by renaming a complete file over it. `notes.v8` keeps each note's parse, keyed by its text, and the
+records derived from that note alone, keyed also by what the tree gives every
+note: the setting date and calendars, the addresses the notes declare and the
+asset records. `tree.v8` keeps the whole tree's records, keyed by every input,
+and beside them the query answers of each note a render has needed. So a second render of an
+unchanged tree reads the records and the answers; a changed note re-derives
+its own records and re-runs the passes that read the whole tree; a changed
+address, calendar, asset, dependency index, configuration or toolchain
+re-derives every note. A store that cannot be read, that was written for
+other inputs, or that holds an entry of the wrong shape, down to each table
+result, inline answer, page-list result and parse inside it, is derived again
+and overwritten. Deleting the directory loses
+only time. `cache: false` derives everything and reads and writes nothing.
+`prepareTables` prepares the query answers, `prepareTreeSqlTables` from
+`engine/sql-tables.mjs` by default; a host may wrap it to time or observe the
+preparation.
+
+`html` is the body before the site writer minifies it and before it unlinks
+links to pages its homepage cannot reach. Set it in
+`<div class="single-content"><div class="single-body">…</div></div>` with
+`styles`, the CSS the site theme applies to a page body, to show it as the page
+does. `styles` carries the theme's reset, body typography and ordinary link
+rules scoped to `.single-content`, so the body reads as the page does whatever
+the host's own styles, and sets the root font size on `:root`, since the
+theme measures its lengths in `rem`. Each finding is `{ file, line?, column?, severity, message }` and prints
+through `formatDiagnostic` as `file:line:column: severity: message`. `cache`
+says what the cache answered: `tree` is `"hit"` when the tree's records were
+reused whole, `"miss"` when they were derived, and `"off"` without the cache;
+`notes` counts the notes whose own records were derived again; `tables` is
+`"hit"` when the answers of the note and of every note it links were all
+reused, `"miss"` when any was prepared, and `"off"` without the cache.
+
+It throws when there is no configuration at or above `root`; when the file is
+not a note of the content tree (outside `paths.content`, in a skipped
+directory, or not Markdown); when a dependency's index has not been fetched or
+cannot be read, naming `package-build deps fetch`; when a note of the tree
+cannot be indexed, as the content-index build reports it; and when the
+configuration, fonts or dependency indexes keep changing while they are read,
+three times over. A finding in the
+rendered note itself is returned in `findings`, never thrown.
+
+`prepareTreeSqlTables(contentBase, { only })`, with one note's file or a
+collection of them, answers those notes' directives and generated sections and
+no other note's; its queries still read the whole corpus, so each note's
+results equal its results in a preparation of the whole tree.
+
 ## `./preview`
 
 Import the buffer-only renderer directly without loading the build pipeline:
@@ -2193,21 +2378,21 @@ const config = defineConfig({
 });
 ```
 
-| Export                     | Signature                                      | Returns                                                    | Use it when                                                                                                                                                                                                                              |
-| -------------------------- | ---------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defineConfig`             | `defineConfig(config)`                         | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
-| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`                          | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
-| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`                     | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
-| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`                           | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                      |
-| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`                      | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
-| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)`             | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
-| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`                    | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
-| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`                          | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
-| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`                 | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
-| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`                 | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
-| `publishesContentPages`    | `publishesContentPages(config)`                | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
-| `siteBase`                 | `siteBase(config)`                             | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                          |
-| `siteBuildConfig`          | `siteBuildConfig(config, { baseUrl, assets })` | `ContentBuildConfig`                                       | applying optional runtime site URLs to a frozen effective configuration; the caller first validates the authored homepage with `checkHomepage`; the CLI uses it before index/body preflight                                              |
+| Export                     | Signature                                            | Returns                                                    | Use it when                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineConfig`             | `defineConfig(config)`                               | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                                                                                                                                 |
+| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`                                | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two)                                                                                                            |
+| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`                           | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                                                                                                                                |
+| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`                                 | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                                                                                                                                 |
+| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`                            | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                                                                                                                                      |
+| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)`                   | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                                                                                                                              |
+| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`                          | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                                                                                                                           |
+| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`                                | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                                                                                                                                   |
+| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`                       | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                                                                                                                           |
+| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`                       | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                                                                                                                                         |
+| `publishesContentPages`    | `publishesContentPages(config)`                      | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                                                                                                                             |
+| `siteBase`                 | `siteBase(config)`                                   | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                                                                                                                                     |
+| `siteBuildConfig`          | `siteBuildConfig(config, { root, baseUrl, assets })` | `ContentBuildConfig`                                       | selecting internal www by default, explicit root-derived CDN over configured assets, and low-level baseUrl/assets over derived values; exposes effective homepage/site.base/site.assets without changing authored configuration; the caller first validates the authored homepage with `checkHomepage`; the CLI uses it before index/body preflight |
 
 ## `./config`
 
@@ -2638,6 +2823,10 @@ preparation and kept separate.
 `prepareTreeSqlTables` retains the complete record membership when opening a
 public database, so derived citations can distinguish hidden notes from
 unknown addresses. Only public records contribute rendered sources and links.
+`prepareTreeSqlTables(contentBase, { only })`, with one note's file, answers
+that note's directives and generated sections and no other note's; its queries
+still read the whole corpus, so its results equal that note's in a preparation
+of the whole tree.
 
 | Export                 | Contract                                                                                                                     |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |

package/docs/commands.md

@@ -1324,13 +1324,17 @@ package leaves out as a named asset set.
 **SYNOPSIS**
 
 ```
-package-build cdn publish --set <file> --name <display name> [--dry-run]
+package-build cdn publish [--dest internal|cloudflare] --set <file> --name <display name> [--dry-run]
 ```
 
 **DESCRIPTION**
 
-The one writer to `<site.assets>/<contentPackage>/`. It is run by hand, or by
-a manually dispatched workflow; no build or release runs it.
+Publication is manual and separate from site building and deployment. No build
+or release runs it. `--dest internal` is the default: pictures go to
+`atlas:/srv/preview/cdn`, served at `https://cdn.internal.heroiclands.org`.
+`--dest cloudflare` uses the existing R2 bucket served at configured `site.assets`
+(normally `https://cdn.heroiclands.org`). Each destination uses the same planner,
+transforms, object keys and publication rules.
 
 Every icon and image under the package's picture roots is uploaded flat, as
 `icons/<basename>` or `images/<basename>` — shipped and left-out pictures
@@ -1339,11 +1343,10 @@ site build gives it. `packageBuild.assetTransform` runs on each file exactly
 as `package-build assets` runs it, so a picture on the CDN holds the bytes the
 staged package holds. SVG is served as `image/svg+xml`.
 
-The bucket is served at `site.assets`, so an object's key is its path below
-that address: `thalorna/images/thorn.webp` is
+An object's key is its path below the selected CDN origin. For Cloudflare, `thalorna/images/thorn.webp` is
 `https://cdn.heroiclands.org/thalorna/images/thorn.webp`.
 
-`--set` names the set file, written at `<site.assets>/<contentPackage>/<file>`.
+`--set` names the set file, written at `<selected CDN origin>/<contentPackage>/<file>`.
 It lists only the pictures the package leaves out — an address a set does not
 list resolves to the shipped copy — chosen by the same rule the stage applies,
 `packageBuild.shippingLicenses` included. Its shape is the shipped set's, with
@@ -1380,9 +1383,32 @@ does not have, and a note naming left-out art that is not on the CDN when the
 run ends, are warnings at the note's line and column: an art slot under
 `data:`, an embed, or a body image.
 
-**Credentials.** The store is an S3-compatible bucket — Cloudflare R2 for
-`cdn.heroiclands.org` — signed with AWS Signature Version 4. Its settings are
-read from the environment, after `.env.local` and `.env` are loaded:
+**Internal access.** Install `rsync` and OpenSSH on the publishing machine.
+The default uses your ordinary `atlas` SSH account, which must have write access
+to `/srv/preview/cdn`. Keys come from your SSH configuration or agent; the command
+uses batch mode and requires an already verified host key with
+`StrictHostKeyChecking=yes`. It uses only rsync's receiver protocol, keeps keys out
+of arguments and logs, and never deletes existing CDN objects. Transfer failures
+report the exit code and a bounded, sanitized receiver diagnostic; local staging
+failures name the operation and filesystem error code. Commands, key material and
+full child-process errors are omitted.
+
+For an existing restricted publisher credential, configure an SSH alias with its
+`User preview-publish`, `IdentityFile` and verified `UserKnownHostsFile`. Then set
+`CDN_INTERNAL_DESTINATION=your-alias:cdn` in the environment or `.env.local`.
+The deployed forced command `rrsync -wo -munge /srv/preview` accepts that relative
+destination; do not repeat `/srv/preview` for this account. The override accepts
+only an SSH host alias followed by `:cdn` or `:/srv/preview/cdn`. It changes the
+connection, not the public origin. This command neither installs credentials nor
+changes server permissions.
+
+Internal skip checks and set comparisons read the selected internal CDN over
+HTTPS. An internal dry run uses only those reads: no SSH connection, temporary
+staging or R2 credentials. The CDN must be reachable from the LAN or VPN.
+
+**Cloudflare credentials.** With `--dest cloudflare`, the store is the existing
+S3-compatible bucket, signed with AWS Signature Version 4. Its settings are read
+from the environment, after `.env.local` and `.env` are loaded:
 
 | Variable                | What it is                                                                |
 | ----------------------- | ------------------------------------------------------------------------- |
@@ -1391,46 +1417,35 @@ read from the environment, after `.env.local` and `.env` are loaded:
 | `CDN_ACCESS_KEY_ID`     | The access key id of a token that can write the bucket.                   |
 | `CDN_SECRET_ACCESS_KEY` | That token's secret. Never printed.                                       |
 
-Setting some but not all of them is an error naming the missing ones. With
-none set, `--dry-run` compares against the public CDN at `site.assets`
-instead, read-only, and an upload is refused.
-
-A workflow calls the command the same way, passing the four values as named
-secrets in the step's environment:
-
-```yaml
-- run: npx package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
-  env:
-    CDN_ENDPOINT: ${{ secrets.CDN_ENDPOINT }}
-    CDN_BUCKET: ${{ secrets.CDN_BUCKET }}
-    CDN_ACCESS_KEY_ID: ${{ secrets.CDN_ACCESS_KEY_ID }}
-    CDN_SECRET_ACCESS_KEY: ${{ secrets.CDN_SECRET_ACCESS_KEY }}
-```
+Setting some but not all of them is an error naming the missing ones. With none
+set, `--dest cloudflare --dry-run` compares against `site.assets` read-only, and an
+upload is refused. Internal publication ignores all four R2 settings.
 
 **OPTIONS**
 
-| Option      | Type    | Default | Description                                                                 |
-| ----------- | ------- | ------- | --------------------------------------------------------------------------- |
-| `--set`     | string  | —       | Required. The set file's name under the package's CDN root, a `.json` file. |
-| `--name`    | string  | —       | Required. The set's display name.                                           |
-| `--dry-run` | boolean | `false` | List what would upload and what is skipped; write nothing.                  |
+| Option      | Type    | Default    | Description                                                                 |
+| ----------- | ------- | ---------- | --------------------------------------------------------------------------- |
+| `--dest`    | string  | `internal` | `internal` for atlas; `cloudflare` for the configured R2 bucket.            |
+| `--set`     | string  | —          | Required. The set file's name under the package's CDN root, a `.json` file. |
+| `--name`    | string  | —          | Required. The set's display name.                                           |
+| `--dry-run` | boolean | `false`    | List what would upload and what is skipped; write nothing.                  |
 
 **EXIT STATUS**
 
 1 when a picture's file has no address, when a picture fails to upload, when
-`--set` is `default.json` or a path, when `site.assets` is undeclared, and
-when an upload has no store configured. Warnings about notes do not change
+`--set` is `default.json` or a path, when Cloudflare `site.assets` is undeclared, when an internal destination or
+planned relative key is unsafe, and when an upload lacks access to its store. Warnings about notes do not change
 it. Otherwise 0.
 
 **EXAMPLES**
 
 ```
 $ package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
-Dry run: comparing 582 pictures against https://cdn.heroiclands.org, read-only.
+Dry run: comparing 582 pictures against https://cdn.internal.heroiclands.org, read-only.
   would upload thalorna/icons/anvilbdg.svg (969 bytes)
   …
   would upload thalorna/alt-art.json (582 assets)
-Would upload 582, skipped 0, failed 0; https://cdn.heroiclands.org/thalorna/alt-art.json lists 582 left-out pictures (would change).
+Would upload 582, skipped 0, failed 0; https://cdn.internal.heroiclands.org/thalorna/alt-art.json lists 582 left-out pictures (would change).
 
 $ package-build cdn publish --set default.json --name Shipped
 package-build: `--set default.json` is refused: `default.json` is the shipped set's name, the fallback every other set is read against. Name the set for its art
@@ -2685,7 +2700,7 @@ it for search.
 **SYNOPSIS**
 
 ```
-package-build site build [--out <dir>] [--base-url <url>] [--assets <url>]
+package-build site build [--root <domain>] [--out <dir>] [--base-url <url>] [--assets <url>]
 ```
 
 **DESCRIPTION**
@@ -2748,6 +2763,11 @@ out in the [site guide](guides/site.md#search).
 
 The site's address, title and menu are read before the tree is, so a missing
 `homepage` or a cold navigation cache fails with the last good site in place.
+With [`site.inputs`](configuration.md#local-site-inputs), a local module supplies
+the selected navigation and text artifacts instead of reading the navigation
+cache. It receives the effective configuration, runs before content rendering,
+and may reject canonical navigation drift. Its files are validated before
+output replacement and written after the renderer clears the site.
 Every gate is then checked and reported, and the run stops at the first that
 fires, ordered so the report names the cause rather than its symptoms — an
 unusable dependency manifest, reported after the links that failed because of
@@ -2760,6 +2780,13 @@ run fails before the search index is built.
 
 `--out <dir>` — the directory that is deployed. Defaults to `build/site`.
 
+`--root <domain>` — domain for the build's addresses, defaulting to
+`internal.heroiclands.org`. The site uses `https://www.<domain>` with the
+package's existing homepage path. An explicit root also selects
+`https://cdn.<domain>` over configured `site.assets`; omitting this flag keeps
+configured assets, or derives the CDN when none are configured. Supply a plain
+DNS domain without a scheme, path, port, credentials, query or fragment.
+
 `--base-url <url>` — the absolute HTTP(S) address of this build. Its pathname
 becomes the effective `site.base`, and must end with `/`; `/` serves the site
 at the origin's root. Pages, local links, theme files, script fonts and search
@@ -2768,8 +2795,18 @@ all use that prefix. Output lands under `<out>/<pathname>/`.
 `--assets <url>` — the absolute HTTP(S) asset root for this build. It may
 include a path; trailing slashes are trimmed.
 
-Both options are optional and independent. Without them, the build uses the
-authored `homepage`, `site.base` and `site.assets`. Overrides apply in memory
+Explicit `--base-url` overrides the root-derived site URL, including its path;
+explicit `--assets` overrides both root-derived and configured assets. These
+low-level flags are independent and may be combined with `--root`. Cached
+navigation links on the canonical Heroic Lands www origin and the brand's
+license link use the effective site origin. External links and authored content
+links keep their addresses. Asset references on the exact canonical
+`https://cdn.heroiclands.org` origin use the effective asset root, preserving
+the path, query and fragment. Other image origins stay unchanged.
+The build only writes local output; it neither
+uploads nor fetches missing dependencies or assets.
+
+Overrides apply in memory
 before preflight and rendering; they never rewrite `package.json` or
 `package-build.config.yaml`. The authored homepage must still pass its usual
 validation. Both URLs require plain paths without percent escapes, dot