@heroiclands/package-build 22.0.2 → 22.1.0

package/content-config.mjs

@@ -175,6 +175,10 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
     // dependency — so nesting one under the other would imply a containment
     // that does not hold.
     metadataCache: "build/cache/metadata",
+    // Where the site navigation heroiclands.org publishes is fetched to.
+    // Beside the other two: it is fetched by the same command and read under
+    // the same complete-marker rule.
+    navigationCache: "build/cache/navigation",
 });
 
 /**
@@ -387,6 +391,8 @@ export function publishesContentPages(config) {
  *                                       index is fetched to. Inbound,
  *                                       for *every* declared dependency, not
  *                                       only those supplying a catalogue.
+ * @property {string} [navigationCache]  Where the site navigation is fetched
+ *                                       to, for the generated Hugo menu.
  */
 
 /**
@@ -401,6 +407,7 @@ export function publishesContentPages(config) {
  * @property {string} unpack
  * @property {string} foreignCache
  * @property {string} metadataCache
+ * @property {string} navigationCache
  */
 
 /**
@@ -578,6 +585,13 @@ export function publishesContentPages(config) {
  *                                          Refused by a `documentation`
  *                                          package, which ships no Foundry
  *                                          package.
+ * @property {string} [homepage]            `package.json`'s own `homepage` —
+ *                                          the site build's `baseURL`. Checked
+ *                                          by `checkHomepage` in
+ *                                          `config.mjs`.
+ * @property {string|{name: string, email?: string, url?: string}} [author]
+ *                                          `package.json`'s own `author`, in
+ *                                          either of npm's forms.
  * @property {PackageKind} packageKind      Whether the package is a system, a
  *                                          module, or documentation — the kind
  *                                          that publishes a site and a book
@@ -637,6 +651,13 @@ export function publishesContentPages(config) {
  * @property {string} contentPackage
  * @property {string|null} foundryPackage  `null` for a `documentation`
  *                                     package, which ships no Foundry package.
+ * @property {string|null} homepage    `package.json`'s own `homepage`,
+ *                                     checked by `checkHomepage` in
+ *                                     `config.mjs`.
+ * @property {Readonly<{name: string, email?: string, url?: string}>|null} author
+ *                                     `package.json`'s own `author`, normalised
+ *                                     from either of npm's forms; `null` when
+ *                                     the package declares none.
  * @property {PackageKind} packageKind
  * @property {string|null} assetRoot   Derived, and **conditional**: the served
  *                                     Foundry asset root,
@@ -705,6 +726,8 @@ const CONFIG_KEYS = [
     "rootDir",
     "contentPackage",
     "foundryPackage",
+    "homepage",
+    "author",
     "packageKind",
     "stats",
     "itemBuilders",
@@ -726,7 +749,6 @@ const SYSTEM_KEYS = ["manifest", "compatibility"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
-    "out",
     "base",
     "assets",
     "packages",
@@ -737,8 +759,14 @@ const SITE_KEYS = [
     "pass",
     "passOptions",
     "backfillSections",
+    "list",
+    "notfound",
+    "hugo",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
+const SITE_LIST_KEYS = ["shortcodes"];
+const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
+const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
 const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "iconFonts", "binary"];
 const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
@@ -753,6 +781,7 @@ const RELATIONSHIP_KEYS = [
     "compatibility",
     "itemCatalog",
 ];
+const AUTHOR_KEYS = ["name", "email", "url"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
 const ITEM_REGISTRY_KEYS = ["system", "builders"];
 const PACK_KEYS = [
@@ -964,6 +993,56 @@ function optionalString(value, field) {
     return value;
 }
 
+/**
+ * npm's `author` field, in either of its two forms.
+ *
+ * `package.json` accepts a single string — `"Name <email> (url)"`, with the
+ * email and the URL both optional — or an object carrying the same three
+ * parts. Both normalise to one shape, so the site build reads one field
+ * instead of branching on which form a repository happened to write.
+ *
+ * @type {RegExp}
+ */
+const AUTHOR_STRING = /^([^<(]*?)\s*(?:<([^>]*)>)?\s*(?:\(([^)]*)\))?\s*$/;
+
+/**
+ * @param {unknown} value - The declared `author`, or `undefined`.
+ * @returns {Readonly<{name: string, email?: string, url?: string}>|null}
+ *   `null` when the package declares none.
+ */
+function normalizeAuthor(value) {
+    if (value === undefined) return null;
+    if (typeof value === "string") {
+        const match = AUTHOR_STRING.exec(value.trim());
+        const name = match?.[1]?.trim();
+        if (!match || !name) {
+            fail(
+                "author",
+                'must be `"Name"`, `"Name <email>"`, `"Name (url)"` or ' +
+                    '`"Name <email> (url)"` — npm\'s own `author` forms',
+            );
+        }
+        return Object.freeze({
+            name: /** @type {string} */ (name),
+            ...(match[2] ? { email: match[2] } : {}),
+            ...(match[3] ? { url: match[3] } : {}),
+        });
+    }
+    if (!isPlainObject(value)) {
+        fail("author", "must be a string or an object with `name`, `email` and `url`");
+    }
+    const author = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(author, AUTHOR_KEYS, "author.");
+    const name = requireNonEmptyString(author.name, "author.name");
+    return Object.freeze({
+        name,
+        ...(author.email !== undefined ?
+            { email: optionalString(author.email, "author.email") }
+        :   {}),
+        ...(author.url !== undefined ? { url: optionalString(author.url, "author.url") } : {}),
+    });
+}
+
 /**
  * @param {unknown} value
  * @param {string} where       Field path used in error messages.
@@ -1504,21 +1583,149 @@ function normalizeSectionMap(value, where) {
     return Object.freeze(out);
 }
 
+/**
+ * Hugo keys a repository may **not** declare under `site.hugo`, because the
+ * site build generates them and would only overwrite what was written.
+ *
+ * The same rule `DERIVED_MANIFEST_KEYS` states for the manifest, for the same
+ * reason: an authored `baseURL` would look authoritative, sit there unread,
+ * and disagree with the site forever. Each key names where its value comes
+ * from. A dotted key names a nested one, and covers everything beneath it —
+ * `params.brand` refuses `params.brand.logo` too — so `site.hugo` reaches only
+ * what the generator does not write.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_HUGO_KEYS = Object.freeze({
+    baseURL: "package.json `homepage`",
+    title: "`packageBuild.manifest.title`",
+    locale: "the organisation's locale, in `engine/site-config.mjs`",
+    publishDir: "`contentPackage`, under the deployment root `build/site`",
+    contentDir: "the fixed content mount, `build/hugo/content`",
+    themesDir: "where `@heroiclands/hugo-theme` is installed",
+    theme: "the installed `@heroiclands/hugo-theme`",
+    disableKinds: "the toolchain, which renders the same kinds on every site",
+    "params.description": "package.json `description`",
+    "params.author": "package.json `author`",
+    "params.cdnBaseURL": "`site.assets`",
+    "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
+    "params.list": "`site.list`",
+    "params.notfound": "`site.notfound`",
+    "markup.goldmark.renderer.unsafe": "the toolchain, whose pages carry raw HTML",
+    menu: "the navigation `content-build deps fetch` caches from heroiclands.org",
+});
+
+/**
+ * The `site.list` block — how a listing page renders.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<{shortcodes: boolean}>} It, frozen, with every default filled.
+ */
+function normalizeSiteList(value) {
+    if (value === undefined) return Object.freeze({ shortcodes: false });
+    if (!isPlainObject(value)) fail("site.list", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, SITE_LIST_KEYS, "site.list.");
+    return Object.freeze({
+        shortcodes: optionalBoolean(input.shortcodes, "site.list.shortcodes", false),
+    });
+}
+
+/**
+ * The `site.notfound` block — the wording of the "page not found" page.
+ *
+ * The theme renders the page for every site; what a repository supplies is
+ * the tagline, the noun the body prose calls the site, and the routes back.
+ * `tagline` and `sitenoun` are required once the block is present: a block
+ * declaring only links would render the theme's generic wording above a list
+ * of this site's routes, which reads as two sites.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<object>|null} It, frozen; `null` when absent.
+ */
+function normalizeSiteNotfound(value) {
+    if (value === undefined) return null;
+    if (!isPlainObject(value)) fail("site.notfound", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, SITE_NOTFOUND_KEYS, "site.notfound.");
+    const out = {
+        tagline: requireNonEmptyString(input.tagline, "site.notfound.tagline"),
+        sitenoun: requireNonEmptyString(input.sitenoun, "site.notfound.sitenoun"),
+    };
+    if (input.heroimage !== undefined) {
+        out.heroimage = requireNonEmptyString(input.heroimage, "site.notfound.heroimage");
+    }
+    if (input.links !== undefined) {
+        if (!Array.isArray(input.links)) fail("site.notfound.links", "must be a list");
+        out.links = Object.freeze(
+            input.links.map((link, i) => {
+                const where = `site.notfound.links[${i}]`;
+                if (!isPlainObject(link)) fail(where, "must be a mapping");
+                const entry = /** @type {Record<string, unknown>} */ (link);
+                rejectUnknownKeys(entry, SITE_NOTFOUND_LINK_KEYS, `${where}.`);
+                return Object.freeze({
+                    title: requireNonEmptyString(entry.title, `${where}.title`),
+                    url: requireNonEmptyString(entry.url, `${where}.url`),
+                    text: requireNonEmptyString(entry.text, `${where}.text`),
+                });
+            }),
+        );
+    }
+    return Object.freeze(out);
+}
+
+/**
+ * The `site.hugo` block — a mapping deep-merged over the generated Hugo
+ * configuration, last.
+ *
+ * The escape hatch for the key nobody anticipated. Every key the generator
+ * writes is refused here by {@link DERIVED_HUGO_KEYS}, naming its source, so
+ * the block cannot grow into a second configuration file.
+ *
+ * @param {unknown} value - The block, or `undefined`.
+ * @returns {Readonly<Record<string, unknown>>} It, frozen; `{}` when absent.
+ */
+function normalizeSiteHugo(value) {
+    if (value === undefined) return Object.freeze({});
+    if (!isPlainObject(value)) fail("site.hugo", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    for (const [dotted, source] of Object.entries(DERIVED_HUGO_KEYS)) {
+        /** @type {unknown} */
+        let at = input;
+        for (const part of dotted.split(".")) {
+            at = isPlainObject(at) ? /** @type {Record<string, unknown>} */ (at)[part] : undefined;
+            if (at === undefined) break;
+        }
+        if (at !== undefined) {
+            fail(
+                `site.hugo.${dotted}`,
+                `is derived from ${source} and must not be declared — it ` +
+                    `would be overwritten, and the two would disagree with ` +
+                    `nothing to say so`,
+            );
+        }
+    }
+    return Object.freeze(structuredClone(input));
+}
+
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
- * Everything here is *framing*: where the Hugo tree is written, what a section
- * is called, which extra trees are published beside the content, and which
- * named pass bundle supplies the repository's own body rewrites. How a page gets
- * its **address** is deliberately not here — that is `publish.address`, shared
- * with the link manifest so the two cannot disagree about where a page is.
+ * Everything here is *framing*: what a section is called, which extra trees
+ * are published beside the content, which named pass bundle supplies the
+ * repository's own body rewrites, and the residue of the generated Hugo
+ * configuration that is genuinely this repository's own. Where the Hugo tree
+ * is written is not a choice: `content-build site` writes it under
+ * `build/hugo/`, and a `site.out` is refused by name. How a page gets its
+ * **address** is deliberately not here either — that is `publish.address`,
+ * shared with the link manifest so the two cannot disagree about where a
+ * page is.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
  */
 function normalizeSite(value) {
     const empty = Object.freeze({
-        out: "",
         base: "",
         assets: "",
         packages: Object.freeze([]),
@@ -1529,10 +1736,23 @@ function normalizeSite(value) {
         pass: "",
         passOptions: Object.freeze({}),
         backfillSections: false,
+        list: Object.freeze({ shortcodes: false }),
+        notfound: null,
+        hugo: Object.freeze({}),
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
     const input = /** @type {Record<string, unknown>} */ (value);
+    // Refused by name, ahead of the vocabulary check: the useful thing to say
+    // is not "no such key" but that the location is fixed.
+    if (input.out !== undefined) {
+        fail(
+            "site.out",
+            "is retired — the site build writes its content mount at " +
+                "`build/hugo/content`, beside the generated `hugo.toml`, and " +
+                "the location is not configurable. Remove the key",
+        );
+    }
     rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     const trees = [];
@@ -1574,7 +1794,6 @@ function normalizeSite(value) {
     }
 
     return Object.freeze({
-        out: input.out === undefined ? "" : requireNonEmptyString(input.out, "site.out"),
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
         packages: Object.freeze(packages),
@@ -1588,6 +1807,9 @@ function normalizeSite(value) {
                 Object.freeze({})
             :   Object.freeze({ ...input.passOptions }),
         backfillSections: optionalBoolean(input.backfillSections, "site.backfillSections", false),
+        list: normalizeSiteList(input.list),
+        notfound: normalizeSiteNotfound(input.notfound),
+        hugo: normalizeSiteHugo(input.hugo),
     });
 }
 
@@ -2328,10 +2550,17 @@ export function defineConfig(config) {
         }
     }
 
-    if (!documentation) {
-        if (!Array.isArray(input.packs)) fail("packs", "must be an array");
-        if (input.packs.length === 0) fail("packs", "must declare at least one pack");
-    }
+    // A Foundry package need not compile anything. A module may ship assets and
+    // nothing else — alternative art for another package is the case, and it is
+    // an ordinary module that installs, is enabled, and supplies files. So
+    // `packs: []` is a package saying it compiles no documents, not a package
+    // that forgot to say which.
+    //
+    // What that leaves uncovered is a tree of notes with no pack to compile them
+    // into, which would be silently ignored. `packs` cannot see the tree, so the
+    // walk reports it: a declared pack that compiles nothing from a non-empty
+    // tree already fails, and so does a note whose `pack:` names none.
+    if (!documentation && !Array.isArray(input.packs)) fail("packs", "must be an array");
     const declaredPacks = Array.isArray(input.packs) ? input.packs : [];
     const packs = declaredPacks.map((pack, index) => normalizePack(pack, `packs[${index}]`));
 
@@ -2486,6 +2715,11 @@ export function defineConfig(config) {
         rootDir,
         contentPackage: requireContentPackage(input.contentPackage, docEntryTypes),
         foundryPackage,
+        // `package.json`'s own address and byline. `homepage` is checked by
+        // `checkHomepage` in `config.mjs`.
+        homepage:
+            input.homepage === undefined ? null : requireNonEmptyString(input.homepage, "homepage"),
+        author: normalizeAuthor(input.author),
         packageKind: /** @type {PackageKind} */ (packageKind),
         // Foundry serves a package's files from `<kind>/<id>/`, so this is the
         // one place `systems/sohl` (or `modules/sohl-thalorna`) is spelled.

package/docs/api.md

@@ -621,8 +621,7 @@ Publishing a content tree as a website. Compiling a content tree into compendium
 | `writeSectionLandings` | `function writeSectionLandings(outRoot,`          | {number} How many landings were written.                                                                                               | Writes the Hugo sections a published tree declares.                           |
 | `pluralTitle`          | `function pluralTitle(name)`                      | {string} The display title.                                                                                                            | A section landing's title, from its directory name — `macro` → `Macros`.      |
 | `resolveSitePass`      | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function, afterLinks?: Function}} The bundle.                                                                          | Resolves `site.pass` to its bundle.                                           |
-| `resolveOutputRoot`    | `function resolveOutputRoot(rootDir, out)`        | {string} The absolute output root.                                                                                                     | The output root, having established that it is safe to delete.                |
-| `buildSite`            | `buildSite({ config, outRoot, sqlTables })`       | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found.    |
+| `buildSite`            | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found.    |
 
 ### `engine.contentLint`
 
@@ -1269,6 +1268,7 @@ const config = defineConfig({
 | `SITE_MODES`               | `const SITE_MODES`                 | —                                                          | reading the publishing modes `publish.site` may name, weakest first                                                                                                                                                                      |
 | `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 a resolved configuration publishes the pages its content tree compiles to — the one question the site build and the content index both need answered identically                                                        |
+| `DERIVED_HUGO_KEYS`        | `const DERIVED_HUGO_KEYS`          | —                                                          | reading which Hugo keys `site.hugo` may not declare because the site build generates them, each naming its source (declaring one is an error naming the key); a dotted key covers everything beneath it                                  |
 
 ## `./config`
 
@@ -1282,11 +1282,12 @@ const config = loadPackageBuildConfig();
 console.log(config.stageDir);
 ```
 
-| Export                      | Signature                           | Returns                        | Use it when                                                                                                                                  |
-| --------------------------- | ----------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`       | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)           |
-| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)` | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk             |
-| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`          | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import |
+| Export                      | Signature                                 | Returns                        | Use it when                                                                                                                                                                     |
+| --------------------------- | ----------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`             | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)                                              |
+| `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
+| `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
+| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `content-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
 
 ## `./prettier`
 
@@ -1488,6 +1489,8 @@ console.log(normalizeRepoUrl("git@github.com:HeroicLands/sohl.git"));
 | ------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ARTIFACTS`                    | `const ARTIFACTS`                                                                   | —                                                                                                                       | reading the two Foundry package kinds (`"system"`, `"module"`) as the artifact name their manifest and release archive are called                                                  |
 | `normalizeRepoUrl`             | `normalizeRepoUrl(repository)`                                                      | `string` — normalised `https://` URL, no trailing slash                                                                 | normalising `package.json`'s `repository` field (object or shorthand string, `git+…git` or plain) to the exact URL Foundry fetches release assets from                             |
+| `BUILT_IN_ASSET_TRANSFORMS`    | `const BUILT_IN_ASSET_TRANSFORMS`                                                   | `Readonly<Record<string, string>>`                                                                                      | the asset transforms this package ships, by the name `packageBuild.assetTransform` writes — `svg-theme` themes an icon to the reader's colour scheme                               |
+| `resolveAssetTransform`        | `resolveAssetTransform(declared, rootDir)`                                          | `string` — an absolute path to import                                                                                   | resolving a declared transform: a built-in name reaches the shipped module, anything else is a path against the repository root                                                    |
 | `HOMEPAGE_ORIGIN`              | `HOMEPAGE_ORIGIN`                                                                   | `string` — the origin every package's homepage is served from                                                           | stating the site origin once, so the address a manifest advertises and the address the configuration documents cannot disagree                                                     |
 | `packageHomepage`              | `packageHomepage(contentPackage)`                                                   | `string` — `<origin>/<contentPackage>/`                                                                                 | deriving the homepage a manifest's `url` points at; throws when given no name rather than advertising `<origin>/undefined/`                                                        |
 | `releaseUrls`                  | `releaseUrls({ repoUrl, homeUrl, version, artifact })`                              | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's addresses — `url` is the homepage a reader follows before installing, while `bugs`, `manifest` and `download` stay on the repository holding the artefacts |

package/docs/commands.md

@@ -260,6 +260,60 @@ package-build: `packageKind: documentation` ships no Foundry package, so there i
 `content-build site`, `content-build pdf`, `package-build bundle check`,
 [Configuration](configuration.md).
 
+### `package-build site-root`
+
+**NAME**
+
+`package-build site-root` — write the deployment's `_headers` and `_redirects`.
+
+**SYNOPSIS**
+
+```
+package-build site-root [--out <dir>]
+```
+
+**DESCRIPTION**
+
+Hugo renders into `<out>/<contentPackage>/`, because the deployment carries the
+`/<contentPackage>/` prefix physically and the routing layer is a
+path-preserving pass-through. The directory that is _uploaded_ is its parent,
+and Cloudflare Pages reads `_headers` and `_redirects` from there and nowhere
+else — a copy inside the prefix is published as a text file and never applied.
+Hugo owns everything under the prefix; this owns what sits beside it.
+
+Two things are written. Indexing is suppressed on every address a deployment
+answers on but nobody advertises — the project's `pages.dev`, the per-deployment
+`pages.dev`, and the custom domain the routing layer fetches — each of which
+would otherwise compete with the canonical URL in search results. And both
+spellings of the prefix root redirect to the landing, with a lifetime pinned on
+the 301, because Pages sets no `Cache-Control` on a redirect it generates and a
+301 without one is cached indefinitely on the most-linked URL there is.
+
+The rules are scoped to those hostnames, so a site deployed under a domain of
+its own stays indexable.
+
+**OPTIONS**
+
+`--out <dir>` — the directory that is deployed. Defaults to `build/site`.
+
+**EXIT STATUS**
+
+1 when `<out>/<contentPackage>/` holds no rendered site, which means the site
+build has not run and writing root files would publish a deployment with nothing
+under the prefix. Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build site-root
+✅ Wrote build/site/_headers.
+✅ Wrote build/site/_redirects.
+```
+
+**SEE ALSO**
+
+`content-build site`, [Configuration](configuration.md).
+
 `package-build lang <action>` asks three independent questions about this
 repository's localization, each blind to what the others see: `check`,
 `coverage` and `hardcoded`, one section below per action.
@@ -933,17 +987,28 @@ content-build deps fetch [--from <zip|dir>] [--id <id>]
 
 **DESCRIPTION**
 
-The only action is `fetch`, which fills the **content index** of every
-declared dependency, and the **item catalogue** of those that additionally
-declare `itemCatalog: true`. Its own command rather than a step of
-`package compile`, so a compile never reaches the network — a build that
-downloads silently is not reproducible and hides a dependency's version
-change behind a passing run. `--from` fills the cache from a locally built
-artifact — a package zip, or the directory it was built from — instead of a
-release, which is what makes testing a dependency change against its
-consumers possible before any of it ships; `--id` names which declared
-dependency `--from` supplies, needed only when the repository declares more
-than one. Writes into the configured foreign-cache directory.
+The only action is `fetch`, which fills three caches under `build/cache/`:
+the **content index** of every declared dependency, the **item catalogue**
+of those that additionally declare `itemCatalog: true`, and the **site
+navigation** — `https://www.heroiclands.org/nav.json`, the header menu
+every package site renders, fetched for every package because every package
+publishes a site. Its own command rather than a step of `package compile`
+or `site`, so neither reaches the network — a build that downloads silently
+is not reproducible and hides a dependency's version change behind a
+passing run. Each cache is stamped complete only once its fetch finishes,
+so a half-finished one reads as cold.
+
+The navigation is fetched first, because every package needs it and it
+depends on nothing a repository declares — so a dependency whose release
+cannot be read stops the run with the navigation already cached.
+
+`--from` fills the cache from a locally built artifact — a package zip, or
+the directory it was built from — instead of a release, which is what makes
+testing a dependency change against its consumers possible before any of it
+ships; `--id` names which declared dependency `--from` supplies, needed only
+when the repository declares more than one. `--from` fills that one
+dependency's caches and nothing else: the navigation is not an artifact of
+any dependency, and is fetched by a plain `deps fetch`.
 
 **OPTIONS**
 
@@ -962,6 +1027,7 @@ including when the repository declares no dependencies at all.
 
 ```
 $ content-build deps fetch
+[…] Fetched the site navigation to build/cache/navigation/nav.json.
 […] No relationship declares `itemCatalog: true`; nothing to fetch.
 […] This package declares no dependencies.
 
@@ -971,7 +1037,7 @@ $ content-build deps fetch --from build/dist/module.zip
 
 **SEE ALSO**
 
-`content-build addresses diff`, [Configuration](configuration.md).
+`content-build site`, `content-build addresses diff`, [Configuration](configuration.md).
 
 ### `content-build docs item-fields`
 
@@ -1461,54 +1527,78 @@ $ content-build content-index
 
 **NAME**
 
-Publish the content tree as a Hugo content mount.
+Build the Hugo source tree from the content tree.
 
 **SYNOPSIS**
 
 ```
-content-build site [--out <dir>]
+content-build site
 ```
 
 **DESCRIPTION**
 
-Publishes the content tree as a Hugo content mount — the sibling of
+Writes the whole Hugo source tree under `build/hugo/` — the sibling of
 `package compile`: the same tree, rendered as pages instead of compiled
 into packs. Everything a consumer would otherwise write for itself happens
 here: the walk, address derivation, the address index, table expansion,
-wikilink resolution, code-fence protection, the foreign-manifest merge and
-the section-landing backfill. Every gate is checked and reported, and the
-run stops at the first that fires, ordered so the report names the cause
+wikilink resolution, code-fence protection, the foreign-manifest merge, the
+section-landing backfill, and the Hugo configuration itself. The consumer's
+script then runs Hugo over the tree — `hugo --source build/hugo` — and this
+command never does.
+
+Three things are written, and nothing outside `build/`:
+
+- `build/hugo/hugo.toml`, generated on every run from `package.json`
+  (`homepage`, `description`, `author`), `package-build.config.yaml`
+  (`packageBuild.manifest.title`, `site.assets`, `site.list`,
+  `site.notfound`, `site.hugo`), the organisation's constants, the installed
+  `@heroiclands/hugo-theme`'s location, and the navigation `deps fetch`
+  cached. Every value's source is listed under
+  [the generated Hugo configuration](configuration.md#the-generated-hugo-configuration).
+- `build/hugo/content/`, the content mount — the homepage at its root, and
+  the content tree's pages below `publish.address.prefix`. Wiped on every
+  run.
+- `publishDir` pointing Hugo at `build/site/<contentPackage>/`, the
+  deployment root `package-build site-root` writes beside. Nothing Hugo
+  reads lands in what is published.
+
+The configuration's sources are read before the output tree is touched, so
+a missing `homepage`, a cold navigation cache or an uninstalled theme fails
+with the previous site intact. 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 it, would otherwise read as a pile of
-broken notes. Reads the content tree named by `paths.content`; writes into
-`--out`, defaulting to the configured `site.out`, which is wiped on every
-run.
+broken notes. Reads the content tree named by `paths.content`.
 
 **OPTIONS**
 
-| Option  | Type   | Default                   | Description                                              |
-| ------- | ------ | ------------------------- | -------------------------------------------------------- |
-| `--out` | string | the configured `site.out` | Write the mount here instead of the configured location. |
+None.
 
 **EXIT STATUS**
 
-1 if `site.out` is unset and `--out` is not given (an unset output would
-resolve to the repository root, which this command refuses to wipe). 1 if
-any gate fires — no homepage or two competing for it, a frontmatter
-wikilink, an address that cannot be derived, a stale or unaddressable
-dependency manifest, an address published twice, a table that failed to
-expand, or a dead wikilink. Otherwise 0.
+1 if `package.json` declares no `homepage`, or one that does not end
+`/<contentPackage>/`; if `packageBuild.manifest.title` is undeclared; if the
+navigation has not been fetched (`content-build deps fetch` fills the cache
+and is named in the message); or if `@heroiclands/hugo-theme` is not
+installed. 1 if any gate fires — no homepage or two competing for it, a
+frontmatter wikilink, an address that cannot be derived, a stale or
+unaddressable dependency manifest, an address published twice, a table that
+failed to expand, or a dead wikilink. Otherwise 0.
 
 **EXAMPLES**
 
 ```
 $ content-build site
-[…] wrote 1 homepage(s) + 1 content page(s) + 0 tree page(s) + 0 landing(s) to build/site
+[…] wrote 1 homepage(s) + 1 content page(s) + 0 tree page(s) + 0 landing(s) to build/hugo/content
+[…] wrote build/hugo/hugo.toml
+
+$ content-build site
+[…] ERROR: the site navigation has not been fetched. Run `content-build deps fetch` first.
 ```
 
 **SEE ALSO**
 
-`content-build package <action> [pack] [entry]`, `content-build pdf`, `content-build content-index [root]`,
+`content-build deps fetch`, `package-build site-root`, `content-build package <action> [pack] [entry]`, `content-build pdf`, `content-build content-index [root]`,
 [Diagnostics](diagnostics.md), [Configuration](configuration.md).
 
 ### `content-build pdf`