@heroiclands/package-build 25.6.2 → 25.7.0

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>]
+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,9 +2780,44 @@ 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
+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.
+
+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
+segments (`.` or `..`), or doubled slashes, and reject credentials, queries,
+fragments, whitespace and backslashes.
+Invalid overrides fail before output is replaced. A site declaring
+`site.sitemaps` must still be served at `/`.
+
 **EXIT STATUS**
 
-1 if `package.json` declares no `homepage`, or one that does not end
+1 if a runtime URL override is invalid. 1 if `package.json` declares no `homepage`, or one that does not end
 `/<contentPackage>/`; if the site declares no title, description or `assets`
 host; or if the navigation has not been fetched (`package-build deps fetch`
 fills the cache and is named in the message). 1 if any gate fires — no
@@ -2774,6 +2829,15 @@ findings of severity `warning` included.
 
 **EXAMPLES**
 
+```bash
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/pr/thalorna/123/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+```
+
 ```
 $ package-build site build
 […] indexing content

package/docs/configuration.md

@@ -974,23 +974,24 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                 | Type     | Default                                      |
-| ------------------- | -------- | -------------------------------------------- |
-| `site.base`         | string   | `""`                                         |
-| `site.title`        | string   | `""`, required when no manifest title exists |
-| `site.assets`       | string   | `""`, but required for `site build`          |
-| `site.description`  | string   | `""`, but required for `site build`          |
-| `site.packages`     | string[] | `[]`                                         |
-| `site.pass`         | string   | `""`                                         |
-| `site.passOptions`  | object   | `{}`                                         |
-| `site.notfound`     | object   | `null`                                       |
-| `site.search`       | boolean  | `true`                                       |
-| `site.maps`         | boolean  | `true`                                       |
-| `site.sections`     | object   | `{}`                                         |
-| `site.feed`         | string   | `""`                                         |
-| `site.tags`         | boolean  | `false`                                      |
-| `site.sitemaps`     | string[] | `[]`, and only at the root of an origin      |
-| `site.mergeIndexes` | string[] | `[]`                                         |
+| Key                 | Type     | Default                                       |
+| ------------------- | -------- | --------------------------------------------- |
+| `site.base`         | string   | `""`                                          |
+| `site.title`        | string   | `""`, required when no manifest title exists  |
+| `site.assets`       | string   | `""`; `site build` derives a CDN when omitted |
+| `site.description`  | string   | `""`, but required for `site build`           |
+| `site.packages`     | string[] | `[]`                                          |
+| `site.pass`         | string   | `""`                                          |
+| `site.passOptions`  | object   | `{}`                                          |
+| `site.notfound`     | object   | `null`                                        |
+| `site.search`       | boolean  | `true`                                        |
+| `site.maps`         | boolean  | `true`                                        |
+| `site.sections`     | object   | `{}`                                          |
+| `site.feed`         | string   | `""`                                          |
+| `site.tags`         | boolean  | `false`                                       |
+| `site.sitemaps`     | string[] | `[]`, and only at the root of an origin       |
+| `site.mergeIndexes` | string[] | `[]`                                          |
+| `site.inputs`       | string   | `""`; optional local input-provider module    |
 
 The authored content tree determines which pages reach the web. `site` is
 framing: which named pass bundle
@@ -1016,7 +1017,7 @@ renders it under the deployment root `build/site/`, at
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, search, maps, sections, feed, tags, sitemaps, mergeIndexes).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, search, maps, sections, feed, tags, sitemaps, mergeIndexes, inputs).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -1029,17 +1030,18 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
-`package-build site build` refuses a configuration with no `site.assets` at
-all — there is no defensible default, because the theme
-resolves every relative asset against it:
+`package-build site build` resolves its effective asset host from `--assets`,
+an explicit `--root`, or configured `site.assets`, in that order. If none is
+provided, it derives `https://cdn.internal.heroiclands.org` from the default
+root. Every relative asset resolves against that effective host.
 
-> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
-
-`package-build cdn publish` uploads the package's pictures under the same
-host, at `<site.assets>/<contentPackage>/icons/<basename>` and
-`…/images/<basename>`, which is the address the website gives each one. The
-bucket behind the CDN is served at `site.assets`, so an object's key is its
-path below this value.
+`package-build cdn publish --dest cloudflare` manually uploads pictures under
+this host, at `<site.assets>/<contentPackage>/icons/<basename>` and
+`…/images/<basename>`. The R2 bucket is served at `site.assets`, so an object's
+key is its path below this value. The default `--dest internal` instead publishes
+the same keys to atlas, served at `https://cdn.internal.heroiclands.org`; its set
+sources use that internal origin regardless of configured `site.assets`.
+Publication is separate from site building and deployment.
 
 The site settings carry the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
@@ -1284,6 +1286,55 @@ site:
   mergeIndexes: [sohl, thalorna, kethira, harnensemble]
 ```
 
+[`site build --root <domain>`](commands.md#package-build-site-build) selects
+`https://www.<domain>` while preserving the homepage path. Its default domain
+is `internal.heroiclands.org`. Explicit `--root` replaces configured `site.assets`
+with `https://cdn.<domain>`; without the flag the configured asset host stays,
+or the derived CDN is used if no asset host is configured. Explicit `--base-url`
+and `--assets` independently take precedence over these derived values.
+The effective configuration exposes the chosen address as `homepage`, its path
+as `site.base`, and the asset host as `site.assets`. The authored configuration
+stays unchanged and must be valid. A root-website integration uses these resolved
+inputs rather than deriving hosts itself; canonical source-navigation drift
+checks remain against the original navigation before projecting its URLs.
+`readCachedNavigation(effectiveConfig)` projects only canonical Heroic Lands
+www links onto the effective homepage origin; `siteSettings` does the same for
+the brand license link. Neither function writes the cache or changes external
+attribution links.
+
+### Local site inputs
+
+`site.inputs` optionally names a local module relative to `rootDir`, such as
+`utils/site-inputs.mjs`. Use a plain relative path without dot segments,
+backslashes or symlinks. Its default export is a function taking `{config}`,
+the immutable effective configuration after root and URL overrides. The function
+may return a promise and must return `{navigation, files}`:
+
+```js
+export default async function ({ config }) {
+  const navigation = [{ name: "Home", url: new URL("/", config.homepage).href }];
+  return { navigation, files: { "nav.json": JSON.stringify(navigation) + "\n" } };
+}
+```
+
+The navigation uses the existing `{name, url, children?}` shape. A provider
+supplies selected URLs itself; the example reads the effective homepage instead
+of deriving hosts. A root website can compare its committed canonical navigation
+against its canonical roster before returning selected-origin navigation. A
+thrown drift finding stops the build before output is replaced. Without this
+key the builder continues to require the navigation cache from `deps fetch`.
+
+`files` maps relative output paths to UTF-8 strings. Paths use plain ASCII
+letters, numbers, dots, underscores and hyphens within segments, with each
+segment beginning with a letter or number. Absolute paths, dot segments,
+symlinks, case collisions and file/directory collisions are refused. A provider
+cannot claim HTML, theme/static assets, fonts, search/tag trees, page paths,
+feeds, sitemap files, robots or deployment headers. All files are validated
+before output replacement, then written inside the package site's output after
+the renderer clears it. Their paths are included in `written.files`.
+This prepares build inputs and text artifacts; it is not a shell command or a
+publication hook.
+
 ### What the site build reads
 
 `package-build site build` composes the site's settings from sources the
@@ -1291,17 +1342,17 @@ repository already states, a few constants of the organisation, and the
 navigation `deps fetch` cached. Every value has one source, and that source is
 where it is edited:
 
-| Setting              | Derived from                                                                                                                                          |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| base URL             | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                   |
-| title                | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                   |
-| `params.description` | `site.description`, which is required                                                                                                                 |
-| `params.author`      | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                              |
-| `params.cdnBaseURL`  | `site.assets`, which is required                                                                                                                      |
-| `params.brand`       | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                     |
-| `params.notfound`    | `site.notfound`; absent when undeclared                                                                                                               |
-| `params.scriptFonts` | the installed script fonts' stylesheet, present only when the package delivers fonts                                                                  |
-| menu                 | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as its `children` |
+| Setting              | Derived from                                                                                                                                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| base URL             | Effective `homepage` from `siteBuildConfig`; authored `package.json` `homepage` first passes `checkHomepage`                                                                                                 |
+| title                | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                                                                          |
+| `params.description` | `site.description`, which is required                                                                                                                                                                        |
+| `params.author`      | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                                                                                     |
+| `params.cdnBaseURL`  | `site.assets`, which is required                                                                                                                                                                             |
+| `params.brand`       | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                                                                            |
+| `params.notfound`    | `site.notfound`; absent when undeclared                                                                                                                                                                      |
+| `params.scriptFonts` | the installed script fonts' stylesheet, present only when the package delivers fonts                                                                                                                         |
+| menu                 | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, with canonical owned URLs projected onto the effective homepage origin, a dropdown's entries as its `children` |
 
 The site build reads the navigation from the cache only. A cold cache is an
 error naming the command that fills it:
@@ -1317,11 +1368,9 @@ the same way when it is absent:
 
 > ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
 
-`params.cdnBaseURL` reads from `site.assets`, and the theme resolves every
-relative asset against it, so a configuration declaring none fails the site
-build the same way:
-
-> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+`params.cdnBaseURL` reads the effective `site.assets` chosen by the build
+resolver, and the theme resolves every relative asset against it. Direct
+`siteSettings` callers must supply that effective asset host.
 
 Nothing else is configurable. A site is its homepage and its pages: the
 homepage is the package root and every note is a page. A tag is a field a

package/docs/guides/release-and-deploy.md

@@ -133,23 +133,34 @@ the other actions and environment variables.
 
 ## Publish pictures to the CDN
 
-The website draws every picture a package has from
-`<site.assets>/<contentPackage>/`, and the art a Foundry package leaves out
-reaches a world from there as a named asset set. `package-build cdn publish`
-is the one command that writes there:
+Run `package-build cdn publish` manually after pictures or their provenance change.
+It uploads every icon and image flat, applies the stage's transformations, skips
+pictures already present at the same size, and writes a named set listing the
+pictures the Foundry package leaves out. Site builds and releases do not publish
+pictures.
+
+The default destination is atlas at `https://cdn.internal.heroiclands.org`:
 
 ```bash
 package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
 package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
 ```
 
-It uploads every icon and image flat, transformed as the stage transforms
-them, skips what the CDN already holds at the same size, and writes
-`<site.assets>/<contentPackage>/alt-art.json` listing the left-out pictures.
-Run it after the pictures or their provenance change; it is not part of a
-build or a release.
+Connect to the LAN or VPN. Install rsync and use your verified `atlas` SSH account
+with write access to `/srv/preview/cdn`. SSH configuration or your SSH agent supplies
+the key; unknown host keys fail. For a configured forced-rrsync publisher alias,
+set `CDN_INTERNAL_DESTINATION=your-alias:cdn`; its relative path is required by the
+restricted receiver. The command does not provision keys or change permissions.
+An internal dry run only reads HTTPS; it never opens SSH or uses R2 credentials.
+
+To publish to the public CDN, select Cloudflare explicitly:
+
+```bash
+package-build cdn publish --dest cloudflare --set alt-art.json --name "Thalorna — illustrated"
+```
 
-The bucket's credentials go in `.env.local` beside the stage paths:
+This retains the existing R2 transport and configured `site.assets` origin,
+normally `https://cdn.heroiclands.org`. The bucket's credentials go in `.env.local`:
 
 ```dotenv
 CDN_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
@@ -158,10 +169,11 @@ CDN_ACCESS_KEY_ID=<access key id>
 CDN_SECRET_ACCESS_KEY=<secret access key>
 ```
 
-A dry run with none of them set compares against the public CDN instead. A
-dispatched workflow passes the same four values as named secrets. See the
-[command reference](../commands.md#package-build-cdn-publish) for the set
-file's shape, the refusals and the exit status.
+With none of those settings present, `--dest cloudflare --dry-run` compares against
+`site.assets` read-only. Both destinations use the same keys and sets; neither
+deletes existing shared CDN objects. See the
+[command reference](../commands.md#package-build-cdn-publish) for SSH setup,
+set shape, refusals and exit status.
 
 ## Publish a package-build npm version
 

package/docs/guides/site.md

@@ -306,6 +306,59 @@ The terminal reports indexing, rendering, writing and search indexing as they
 start, including page counts where available. Progress is on stdout;
 diagnostics retain their file, line and column on stderr.
 
+Build locally for the internal site or a public release with the selected root:
+
+```bash
+package-build site build --root internal.heroiclands.org
+package-build site build --root heroiclands.org
+```
+
+These select `https://www.internal.heroiclands.org` and
+`https://cdn.internal.heroiclands.org`, or `https://www.heroiclands.org` and
+`https://cdn.heroiclands.org`, retaining the package's path. Without `--root`,
+the site defaults to the internal www origin and keeps configured `site.assets`
+(or derives the internal CDN if none is configured). An explicit root overrides
+the configured asset host. Build and publication are separate: this command
+writes local output, reads cached dependencies, and never uploads or fetches
+missing assets. Shared navigation and the brand license follow the selected
+site origin; external attribution and authored content links retain their URLs.
+Asset references to the exact canonical `https://cdn.heroiclands.org` origin
+also use the effective asset root, retaining their path, query and fragment;
+external image hosts keep their addresses. This happens during normal asset
+resolution and leaves authored files unchanged.
+
+A site that generates its own navigation can declare
+[`site.inputs`](../configuration.md#local-site-inputs). Its local module receives
+the selected addresses in the effective configuration and returns its menu plus
+text files such as `nav.json`. The builder renders that menu and writes those
+files together, so one build command prepares the complete site. A canonical
+roster check belongs in that module before it returns deployment-specific URLs;
+a drift finding leaves the last built site in place.
+
+For a pull request preview, include the whole prefix:
+
+```bash
+package-build site build \
+    --base-url https://www.internal.heroiclands.org/pr/thalorna/123/thalorna/ \
+    --assets https://cdn.internal.heroiclands.org
+```
+
+This build writes to `build/site/pr/thalorna/123/thalorna/`. Its local
+links, theme files, script fonts and search stay under that prefix; its images
+use the supplied asset root. `--out` changes the deployment directory above the
+prefix. Explicit `--base-url` takes precedence over the root-derived site
+address, and explicit `--assets` takes precedence over both the root-derived and
+configured asset host. Both URL options are optional and independent, and require absolute
+HTTP(S) URLs. The base URL's path ends with `/`; the asset root may include a
+path and has trailing slashes trimmed. Use plain paths without percent escapes,
+dot segments (`.` or `..`), or doubled slashes, credentials, queries or fragments.
+
+The options apply to this build only. Authored `package.json` and YAML stay
+unchanged, and the authored homepage still has to match the configured site.
+Invalid overrides fail before replacing output. A site with `site.sitemaps`
+requires a base URL at the origin's root. See the
+[command reference](../commands.md#package-build-site-build) for URL validation.
+
 ```bash
 package-build site serve
 ```