@heroiclands/package-build 20.3.1 → 20.5.0

package/content-config.mjs

@@ -22,7 +22,6 @@
  * packageKind: systems
  * compatibility: { minimum: "14.359", verified: "14.364" }
  * stats:
- *     systemId: sohl
  *     lastModifiedBy: sohlbuilder00000
  * itemBuilders: sohl
  * skipDirectories: [Templates]
@@ -42,44 +41,105 @@
  * a consumer's config is data, and the compilers read it.
  *
  * **This module validates; it does not load.** `engine/pack-config.mjs` is what
- * finds a repository's configuration and reads it, and it is where the three
+ * finds a repository's configuration and reads it, and it is where the four
  * fields absent from the YAML above are derived: `rootDir` (the directory the
- * file sits in), `stats.systemVersion` (the adjacent `package.json`), and the
- * `itemBuilders` table the name `sohl` stands for. All three are I/O or code,
- * and this module is deliberately neither — which is also why a consumer whose
- * item-builder registry is its own writes `package-build.config.mjs`, calling
- * `defineConfig` below directly with a `rootDir` of `import.meta.dirname`.
- * Both forms end here, so both are validated and frozen identically.
+ * file sits in), `foundryPackage` and `stats.systemVersion` (the adjacent
+ * `package.json`), and the `itemBuilders` table the name `sohl` stands for. All
+ * four are I/O or code, and this module is deliberately neither — which is also
+ * why a consumer whose item-builder registry is its own writes
+ * `package-build.config.mjs`, calling `defineConfig` below directly with a
+ * `rootDir` of `import.meta.dirname`. Both forms end here, so both are
+ * validated and frozen identically.
  *
  * **`rootDir` anchors every path**, so the build reads the same files whatever
- * directory it was launched from (#1508).
+ * directory it was launched from.
  *
  * The Foundry floor is declared here as top-level `compatibility`, and the
  * shipped manifest is generated *from* this file. That reverses an older rule —
  * configuration named where the manifest was and read the floor back out of it —
  * which was right while the manifest was hand-authored and became a round trip
- * through a generated artifact once it was not (#50, package-build#9).
+ * through a generated artifact once it was not.
  *
  * @module
  */
 
+import fs from "node:fs";
 import path from "node:path";
+import YAML from "yaml";
 
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
+import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
 
 /**
- * The two kinds of Foundry package a content module can be built into. The
- * value is also the directory Foundry installs the package under, which is why
- * it is plural.
+ * What kind of package this is.
+ *
+ * `systems` and `modules` are the two Foundry answers, and the value is also
+ * the directory Foundry installs the package under, which is why they are
+ * plural. `documentation` is the answer "not a Foundry package at all": it
+ * publishes a site and a book from its notes, installs into no Foundry data
+ * directory and compiles no compendium.
  *
  * @satisfies {readonly PackageKind[]}
  */
-export const PACKAGE_KINDS = /** @type {const} */ (["systems", "modules"]);
+export const PACKAGE_KINDS = /** @type {const} */ (["systems", "modules", "documentation"]);
+
+/**
+ * The kind that compiles no Foundry documents.
+ *
+ * Spelled once and read wherever a pass asks whether it applies, so the
+ * validator, the CLI and the compile passes cannot come to disagree about what
+ * the value means.
+ *
+ * @type {string}
+ */
+export const DOCUMENTATION_KIND = "documentation";
+
+/**
+ * Whether this package compiles Foundry documents at all.
+ *
+ * The one question every Foundry-side reader asks — the manifest writer, to
+ * decide whether there is a package for Foundry to install, and the pack
+ * compilers, to decide whether there is anything to compile.
+ *
+ * @param {{packageKind: string}} config - A resolved configuration.
+ * @returns {boolean} Whether the package compiles Foundry documents.
+ */
+export function compilesFoundryDocuments(config) {
+    return config.packageKind !== DOCUMENTATION_KIND;
+}
+
+/**
+ * Every key a documentation package may not declare, and why.
+ *
+ * The value of the kind is as much in what it refuses as in what it accepts. A
+ * key here cannot mean anything in a package that compiles nothing and installs
+ * nowhere, so it fails at load naming the key — the loader resolves that name
+ * to a line and a column — rather than being read and ignored, which is the
+ * failure this contract exists to prevent.
+ *
+ * `foundryPackage` is on the list for the same reason as the rest, and is the
+ * one the YAML loader would otherwise supply: it derives the id from the
+ * adjacent `package.json`, and there is no Foundry package here to carry one.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const DOCUMENTATION_REFUSES = Object.freeze({
+    packs: "compiles no compendium, so there are no packs to declare",
+    itemBuilders: "compiles no items, so there is no item-type registry to name",
+    docs: "compiles no items, so there are no item-field reference pages to frame",
+    compatibility:
+        "installs into no Foundry data directory, so there is no Foundry core range to support",
+    relationships: "is not a Foundry package, so it stands in no relationship to one",
+    systems: "compiles no documents, so it ships content for no game system",
+    requiresSystem: "compiles no documents, so there is no game system to gate its packs on",
+    stats: "compiles no documents, so there is no `_stats` block to stamp",
+    foundryPackage: "is not a Foundry package, so it has no Foundry package id",
+});
 
 /**
  * The directories the build reads from and writes to, relative to `rootDir`,
@@ -92,7 +152,7 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
     // Where `content-index` writes this package's note index. Under `build/`
     // because it is derived and disposable — regenerating it costs a
     // frontmatter parse — and emphatically not under `stage`, which is mirrored
-    // into a Foundry data root (#224).
+    // into a Foundry data root.
     contentIndex: "build/content-index",
     packJson: "build/packs-json",
     stage: "build/stage/packs",
@@ -100,7 +160,7 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
     // Where a dependency declaring `itemCatalog: true` is unpacked. Under
     // `build/` because it is derived, disposable, and version-keyed.
     foreignCache: "build/cache/foreign",
-    // Where a dependency's published content index is fetched to (#239). A
+    // Where a dependency's published content index is fetched to. A
     // sibling of the item catalogue rather than a subdirectory of it: the two
     // are fetched for different dependency sets — a catalogue only where
     // `itemCatalog: true` is declared, an index for *every* declared
@@ -112,7 +172,7 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
 /**
  * The Foundry document types a compendium pack may hold. This is the set the
  * toolchain is able to compile a pack of; a document type Foundry supports but
- * this toolchain does not compile is deliberately absent (see #1501 — playlists
+ * this toolchain does not compile is deliberately absent (playlists
  * and roll tables are out of scope).
  *
  * @satisfies {readonly PackDocumentType[]}
@@ -139,15 +199,11 @@ export const PACK_DOCUMENT_TYPES = /** @type {const} */ ([
  * key is **refused**, at the line it was written on, with a message that says
  * the mechanism is gone rather than naming a value to correct.
  *
- * **What `landing` did (#204).** It named which note addressed a whole section
+ * **`landing` is one such key.** It named which note addressed a whole section
  * rather than a page within one — a *landing page*, which therefore had no slug
- * of its own. #203 retired the second of its two rules and #204 retired the
- * concept both rules chose between: a section is a Hugo content directory that
- * the note format does not carry, a page's address names no directory, and so
- * no note lands anything. The key outlived its mechanism by one release only
- * because both publishing consumers still declared the then-true
- * `landing: readme`, and neither breaking them over a correct statement nor
- * accepting the key in silence was acceptable. Neither declares it now.
+ * of its own. There are no sections to address: a section is a Hugo content
+ * directory the note format does not carry, a page's address names no
+ * directory, and so no note lands anything.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -168,7 +224,7 @@ export const RETIRED_ADDRESS_KEYS = Object.freeze({
  * `thalorna`, whose site is nothing but its content. It is not the package's
  * own mount point: where the package itself is served is the consuming build's
  * knowledge, held in `PACKAGE_BASE` (`engine/content-address.mjs`) and prefixed at
- * resolve time, so it is never recorded here (#1465).
+ * resolve time, so it is never recorded here.
  *
  * It is the whole scheme: `landing`, the key that named which note addressed a
  * whole section, is retired with the sections themselves — see
@@ -183,7 +239,7 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
  *
  * Every HeroicLands package publishes something: a top-level, human-authored
  * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
- * module is, which system it needs and how to install it (#50). So there is no
+ * module is, which system it needs and how to install it. So there is no
  * value here meaning *no web presence at all* — homepage-only is the **floor**,
  * and the default.
  *
@@ -235,7 +291,7 @@ export function publishesContentPages(config) {
 }
 
 /**
- * @typedef {"systems" | "modules"} PackageKind
+ * @typedef {"systems" | "modules" | "documentation"} PackageKind
  */
 
 /**
@@ -251,7 +307,7 @@ export function publishesContentPages(config) {
  * type** receives its document. The two are orthogonal, and both are needed
  * once a repository groups same-type documents editorially — which it may have
  * to, since a compendium UUID carries its pack name and collapsing such a
- * layout breaks every stored reference (#1566).
+ * layout breaks every stored reference.
  *
  * @typedef {object} PackSpec
  * @property {string} name              Pack name — the manifest `name`, and the
@@ -317,7 +373,7 @@ export function publishesContentPages(config) {
  *                                       Inbound, and fetched rather than
  *                                       committed.
  * @property {string} [metadataCache]    Where a dependency's published content
- *                                       index is fetched to (#239). Inbound,
+ *                                       index is fetched to. Inbound,
  *                                       for *every* declared dependency, not
  *                                       only those supplying a catalogue.
  */
@@ -473,13 +529,13 @@ export function publishesContentPages(config) {
  * `fields` is what makes the type documentable: a builder function says
  * nothing about the vocabulary it consumes, so a consumer that declares its
  * fields can generate its own authoring reference and check its own notes,
- * while one that does not is simply undocumented rather than broken (#22).
+ * while one that does not is simply undocumented rather than broken.
  *
  * @typedef {((fm: object) => object)|{system: (fm: object) => object, img?: string, fields?: readonly object[]}} ItemBuilderEntry
  */
 
 /**
- * One **registry** of a declared set, and the system it belongs to (#58).
+ * One **registry** of a declared set, and the system it belongs to.
  *
  * A repository shipping content for two systems declares one of these per
  * system: the accepted type vocabulary is their union, and a type both declare
@@ -501,10 +557,20 @@ export function publishesContentPages(config) {
  * @property {string} contentPackage        Content package name — the address
  *                                          namespace every note in this
  *                                          repository is published under.
- * @property {string} foundryPackage        Foundry package id, as it appears in
+ * @property {string} [foundryPackage]      Foundry package id, as it appears in
  *                                          `system.json` / `module.json`.
- * @property {PackageKind} packageKind      Whether the package is a system or a module.
- * @property {StatsSpec} stats              Identity stamped into every document's `_stats`.
+ *                                          Refused by a `documentation`
+ *                                          package, which ships no Foundry
+ *                                          package.
+ * @property {PackageKind} packageKind      Whether the package is a system, a
+ *                                          module, or documentation — the kind
+ *                                          that publishes a site and a book
+ *                                          while compiling nothing.
+ * @property {StatsSpec} [stats]            Identity stamped into every
+ *                                          document's `_stats`. Required of a
+ *                                          package that compiles documents, and
+ *                                          refused by a `documentation` one,
+ *                                          which compiles none.
  * @property {Record<string, ItemBuilderEntry>|readonly ItemRegistrySpec[]} [itemBuilders]
  *                                          The consumer's
  *                                          item-type registry: each content `type`
@@ -518,14 +584,13 @@ export function publishesContentPages(config) {
  *                                          two systems declares a **list** of
  *                                          `{ system, builders }` registries
  *                                          instead, and the accepted type
- *                                          vocabulary is their union (#58).
+ *                                          vocabulary is their union.
  * @property {PackSpec[]} packs             Packs to compile. More than one entry
  *                                          may share a `type`: a note then names
  *                                          the pack it belongs in with its
  *                                          `pack:` frontmatter, and one pack of
  *                                          the type is marked `default: true` to
- *                                          receive the notes that name none
- *                                          (#1566).
+ *                                          receive the notes that name none.
  * @property {PathsInput} [paths]           Layout overrides. See {@link DEFAULT_PATHS}.
  * @property {string[]} [skipDirectories]   Directory names the content walk ignores
  *                                          wherever they appear (e.g. Obsidian's
@@ -554,12 +619,20 @@ export function publishesContentPages(config) {
  * @typedef {object} ContentBuildConfig
  * @property {string} rootDir
  * @property {string} contentPackage
- * @property {string} foundryPackage
+ * @property {string|null} foundryPackage  `null` for a `documentation`
+ *                                     package, which ships no Foundry package.
  * @property {PackageKind} packageKind
- * @property {string} assetRoot        Derived: the served Foundry asset root,
- *                                     `<packageKind>/<foundryPackage>/assets`.
+ * @property {string|null} assetRoot   Derived, and **conditional**: the served
+ *                                     Foundry asset root,
+ *                                     `<packageKind>/<foundryPackage>/assets`,
+ *                                     for a package Foundry installs — and
+ *                                     `null` for a `documentation` package,
+ *                                     which Foundry serves no files for. See
+ *                                     {@link module:engine/helpers.resolveImg},
+ *                                     the one reader of it.
  * @property {Readonly<ResolvedPaths>} paths
- * @property {Readonly<StatsSpec>} stats
+ * @property {Readonly<StatsSpec>|null} stats  `null` for a `documentation`
+ *                                     package, which stamps no `_stats`.
  * @property {Readonly<Record<string, Function>>} itemBuilders  Derived: the
  *                                     `system` builder of each entry, whichever
  *                                     of the two spellings declared it.
@@ -571,12 +644,11 @@ export function publishesContentPages(config) {
  *                                     the frontmatter fields each entry
  *                                     declared. Sparse, like `itemArt` — a type
  *                                     absent here compiles normally and is
- *                                     simply undocumented (#22).
+ *                                     simply undocumented.
  * @property {Readonly<Record<string, Readonly<Record<string, Function>>>>} itemBuildersBySystem
  *                                     Derived: the same builders, kept per
  *                                     declaring system. `{}` for the single
- *                                     registry form, which names no system
- *                                     (#58).
+ *                                     registry form, which names no system.
  * @property {Readonly<Record<string, Readonly<Record<string, string>>>>} itemArtBySystem
  *                                     Derived: the default art, per system.
  * @property {Readonly<Record<string, Readonly<Record<string, readonly object[]>>>>} itemFieldsBySystem
@@ -589,13 +661,17 @@ export function publishesContentPages(config) {
  *                                     {@link ContentBuildConfigInput.itemBuilders},
  *                                     unioned across every declared registry, so
  *                                     the accepted item types and the builder
- *                                     tables are one list (#1504).
+ *                                     tables are one list.
  * @property {ReadonlySet<string>} docEntryTypes   Derived: every type whose prose
  *                                     compiles into a JournalEntry of its own —
  *                                     the item types, plus `macro`, plus the map
  *                                     types. The one set the compilers and the
  *                                     link-manifest emitter both read.
  * @property {readonly string[]} skipDirectories
+ * @property {import("./engine/content-icons.mjs").IconRegistry} icons  The
+ *                                     fonts this package ships and the names it
+ *                                     draws from them; empty when it declares
+ *                                     none.
  * @property {readonly Readonly<ResolvedPackSpec>[]} packs
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
@@ -618,9 +694,11 @@ const CONFIG_KEYS = [
     "itemBuilders",
     "paths",
     "skipDirectories",
+    "icons",
     "packs",
     "docs",
     "site",
+    "pdf",
     "compatibility",
     "relationships",
     "systems",
@@ -644,6 +722,9 @@ const SITE_KEYS = [
     "backfillSections",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
+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: "" });
 const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
@@ -668,7 +749,7 @@ const STATS_KEYS = ["lastModifiedBy"];
  * How the loader hands {@link defineConfig} the system version it resolved.
  *
  * A **Symbol**, deliberately. `stats.systemVersion` is refused from an authored
- * configuration (#48), but the value still has to reach here from the loader —
+ * configuration, but the value still has to reach here from the loader —
  * which is the half that may do I/O, and which reads a system package's version
  * out of the adjacent `package.json`. A string key would be a second spelling of
  * the refused one, forgeable from YAML and reachable by `rejectUnknownKeys`; a
@@ -692,7 +773,7 @@ function isPlainObject(value) {
  * The dotted path is carried on the error as `field` as well as spelled into
  * the message, because the message alone is a good description and a bad
  * locator: the loader that read the file can resolve that path to a line and
- * column, and does (`locateConfigError` in `engine/pack-config.mjs`, #95).
+ * column, and does (`locateConfigError` in `engine/pack-config.mjs`).
  * Attaching it here rather than formatting here is what keeps this module
  * free of I/O — it is the leaf an `.mjs` configuration imports, so it may not
  * reach for the file it is validating.
@@ -739,14 +820,15 @@ function requireNonEmptyString(value, field) {
  * It is the first segment of every canonical address this repository publishes
  * (`package-system-type-shortcode`, so `sohl-none-doc-gear`), and an address is
  * read by counting hyphen-separated segments. So the value carries two
- * obligations that the rest of the configuration does not, and #59 asks for
+ * obligations that the rest of the configuration does not, and asks for
  * both to be **enforced rather than assumed** — the alternative is a package
  * whose addresses are simply unreadable, reported nowhere and discovered as
  * links that resolve to nothing.
  *
- * 1. _Alphanumeric_, so the hyphen stays purely a separator. `harn-adventures`
- *    was the one violator, and its keys read as one segment too many and failed
- *    as a `null` return from `readCanonicalKey` — a silence, not an error.
+ * 1. _Lowercase alphanumeric_ (`ADDRESS_SEGMENT_PATTERN`), so the hyphen stays
+ *    purely a separator. `harn-adventures` was the one violator, and its keys
+ *    read as one segment too many and failed as a `null` return from
+ *    `readCanonicalKey` — a silence, not an error.
  * 2. _Not a note type_, because a written address is a **partial** one: the
  *    shorter forms drop segments from the left, so `skill-clmb` and
  *    `sohl-skill-clmb` are both addresses and position alone no longer says
@@ -754,9 +836,9 @@ function requireNonEmptyString(value, field) {
  *    by asking whether the name is a known package, and a name in both
  *    vocabularies makes one target readable two ways with no defensible pick.
  *    Keeping the two disjoint is what lets a name be taken at face value; that
- *    the package and the type are no longer *adjacent* segments (#59 put the
- *    system between them) changes nothing, because the hazard was never
- *    adjacency — it is that a short form omits the slots in between.
+ *    the package and the type are not *adjacent* segments, the system sitting
+ *    between them, changes nothing: the hazard is not adjacency, it is that a
+ *    short form omits the slots in between.
  *    One such collision is structural and cannot be fixed — `sohl` is both a
  *    content package and a system id, because Foundry requires a system
  *    package's id to *be* its system id, and `sohl-sohl-skill-clmb` is the
@@ -775,11 +857,12 @@ function requireContentPackage(value, docEntryTypes) {
     if (!isAddressSegment(pkg)) {
         fail(
             "contentPackage",
-            `is \`${pkg}\`, which is not alphanumeric. It is the first ` +
+            `is \`${pkg}\`, which is not lowercase alphanumeric ` +
+                `(${ADDRESS_SEGMENT_PATTERN.source}). It is the first ` +
                 `segment of every address this package publishes ` +
                 `(\`${pkg}-<system>-<type>-<shortcode>\`), and an address is read by ` +
                 `counting hyphen-separated segments — so anything outside ` +
-                "`[A-Za-z0-9]` here makes those addresses unreadable rather " +
+                "that here makes those addresses unreadable rather " +
                 "than merely ugly. `harn-adventures` became `harnadventures`",
         );
     }
@@ -850,7 +933,7 @@ function optionalString(value, field) {
 function normalizePack(value, where, nested = false) {
     if (!isPlainObject(value)) fail(where, "must be an object");
     const pack = /** @type {Record<string, unknown>} */ (value);
-    // Retired with the YAML it named (#260). Refused explicitly rather than
+    // Retired with the YAML it named. Refused explicitly rather than
     // left to the unknown-key check, because the useful thing to say is not
     // "no such key" but where the folders went: they are notes, and a pack
     // materialises the ones its documents reference.
@@ -955,6 +1038,128 @@ function normalizePack(value, where, nested = false) {
     return Object.freeze(normalized);
 }
 
+/**
+ * A package's icon registry — the fonts it ships and the names it draws from
+ * them.
+ *
+ * **Nothing is supplied by default.** A registry entry is a promise that a
+ * glyph will render, and only the package shipping the font can keep it: the
+ * Game-Icons webfont is built by a consumer from its own templates, and Font
+ * Awesome reaches neither the knowledgebase nor a printed page unless somebody
+ * puts it there. A toolchain that shipped a starter table would be promising on
+ * a consumer's behalf, and a name like `victory-star-tester` is one game
+ * system's vocabulary besides.
+ *
+ * So a package declares both halves, and a package that declares neither names
+ * no icons at all.
+ *
+ * **Two spellings, one shape.** The value is either the registry itself:
+ *
+ * ```yaml
+ * icons:
+ *     families:
+ *         fontawesome: { class: fa, styles: [solid, regular, brands], describe: Font Awesome Free }
+ *     icons:
+ *         being: { style: solid, icon: user, label: being }
+ * ```
+ *
+ * or a **path to a file holding it**, relative to this configuration:
+ *
+ * ```yaml
+ * icons: assets/icon-registry.yaml
+ * ```
+ *
+ * The file form is the one a real package wants. A registry is derived from
+ * what the interface actually draws, so it is generated rather than hand-kept —
+ * and a generated document inlined into a hand-edited configuration is a merge
+ * conflict on every regeneration. Kept beside it, the generator owns one file
+ * and the configuration owns the other.
+ *
+ * Validated with {@link module:engine/content-icons.checkIconRegistry}, whose
+ * findings are warnings everywhere else and a **refusal** here: elsewhere the
+ * question is whether one note is wrong, and here it is whether the table every
+ * note is read against is.
+ *
+ * @param {unknown} value - The authored `icons:` value.
+ * @param {string} rootDir - The configuration's own directory, which a relative
+ *   path is resolved against.
+ * @returns {import("./engine/content-icons.mjs").IconRegistry} The frozen
+ *   registry.
+ */
+function normalizeIcons(value, rootDir) {
+    if (value === undefined) return EMPTY_ICON_REGISTRY;
+
+    let declared = value;
+    let where = "icons";
+    if (typeof value === "string") {
+        if (!value.trim()) fail("icons", "is empty — name a file, or write the registry inline");
+        const file = path.resolve(rootDir, value);
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        } catch {
+            fail("icons", `names ${value}, which cannot be read from ${rootDir}`);
+        }
+        try {
+            declared = YAML.parse(text);
+        } catch (err) {
+            fail("icons", `names ${value}, which is not readable YAML: ${err.message}`);
+        }
+        // A finding says which *file* is wrong, not which key of this one.
+        where = value;
+        if (declared === null || declared === undefined) {
+            fail("icons", `names ${value}, which is empty`);
+        }
+    }
+
+    if (!isPlainObject(declared)) {
+        fail(
+            "icons",
+            "must be a registry — `families` and `icons` — or a path to a file holding one",
+        );
+    }
+
+    const families = declared.families ?? {};
+    const icons = declared.icons ?? {};
+    if (!isPlainObject(families)) fail(`${where}.families`, "must be a mapping of name to family");
+    if (!isPlainObject(icons)) fail(`${where}.icons`, "must be a mapping of name to icon entry");
+
+    for (const name of Object.keys(icons)) {
+        // The name a note writes between the colons. Checked here rather than
+        // left to the note, because an entry nothing can name is a silent
+        // no-op: every use of it reports "no such icon" and the table says
+        // otherwise.
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+            fail(
+                `${where}.icons.${name}`,
+                "is not a name a note can write — `:icon-…:` takes lowercase " +
+                    "letters, digits and hyphens, the charset an address segment uses",
+            );
+        }
+    }
+
+    const defaultFamily = declared.defaultFamily;
+    if (defaultFamily !== undefined) {
+        if (typeof defaultFamily !== "string" || !(defaultFamily in families)) {
+            fail(
+                `${where}.defaultFamily`,
+                `names \`${defaultFamily}\`, which is not one of the declared families`,
+            );
+        }
+    }
+
+    const findings = checkIconRegistry({ families, icons, defaultFamily }, where);
+    if (findings.length) {
+        fail("icons", findings.map((finding) => finding.message).join("; "));
+    }
+
+    return Object.freeze({
+        families: Object.freeze(families),
+        defaultFamily,
+        icons: Object.freeze(icons),
+    });
+}
+
 /**
  * Resolve the layout a consumer supplies against its `rootDir`, filling every
  * unnamed directory from {@link DEFAULT_PATHS}.
@@ -994,7 +1199,9 @@ function normalizePaths(value, rootDir) {
 }
 
 /**
- * @param {unknown} value
+ * @param {unknown} value - The authored `stats:` block.
+ * @param {{systemId: string, systemVersion: string}} derived - The package-wide
+ *   system and the version it stamps against, both derived by the caller.
  * @returns {Readonly<StatsSpec>}
  */
 function normalizeStats(value, derived) {
@@ -1002,7 +1209,7 @@ function normalizeStats(value, derived) {
     const input = /** @type {Record<string, unknown>} */ (value);
 
     // **`systemId` and `systemVersion` are derived, and authoring a derived
-    // value is an error rather than an override (#48).** `systems:` is the
+    // value is an error rather than an override.** `systems:` is the
     // single source: it says which systems this package stamps against, and
     // `requiresSystem` — or a lone declared system — says which one the
     // package-wide block takes. A system package answers for itself.
@@ -1115,7 +1322,7 @@ function normalizeDocs(value) {
  * One section's landing metadata — what a section says about itself on the
  * `_index.md` this build generates for it.
  *
- * A generated landing is the *only* place a section can speak, and since #204 it
+ * A generated landing is the *only* place a section can speak, and it
  * is the only place a section **exists**: a content page is addressed
  * `(type, shortcode)` and written flat under the mount, so no page creates a
  * directory and nothing else makes `<prefix><section>/` answer. This is
@@ -1127,18 +1334,18 @@ function normalizeDocs(value) {
  * written fourteen to twenty times per build against a contract every package
  * and every section shares. Unbounded there, a mistyped `descrption:` publishes
  * into front matter, is read by nobody, and says nothing to anyone — which is
- * the failure #91 was filed about, moved one step downstream where no build can
+ * the same failure, moved one step downstream where no build can
  * see it. So the keys are named here, and the writers emit what this produced
- * rather than transcribing a second list of their own (#91).
+ * rather than transcribing a second list of their own.
  *
  * `banner` and `description` are optional — the hero images are external assets
  * and not every section has one, and a section may reasonably have nothing to
  * add to its title. Each is left off entirely rather than written as
  * `undefined`, which is not a value YAML can carry.
  *
- * **`listType` / `listSubType` say what the section lists**
- * (heroiclands-hugo-theme#50). Since #204 a section's directory holds nothing
- * but the `_index.md` written here, so a layout reading Hugo's `.Pages` finds
+ * **`listType` / `listSubType` say what the section lists.** A section's
+ * directory holds nothing but the `_index.md` written here, so a layout
+ * reading Hugo's `.Pages` finds
  * no members and renders an empty landing. The membership survives in this map
  * and nowhere a theme can reach it, so the landing states it and a layout
  * substitutes the equivalent `site.RegularPages` query — the same one `sohl`'s
@@ -1155,7 +1362,7 @@ function normalizeDocs(value) {
  * Both are checked as **address segments**, which is the trap this came from:
  * a section is named for the URL a consumer chose and a subType is an address
  * segment, and the two need not agree — `/sohl/kb/user-guide/` is the section,
- * `userguide` the subType (#207). Copying the section's name into the
+ * `userguide` the subType. Copying the section's name into the
  * declaration would select no page at all, and an empty landing reported by
  * nobody is the failure being fixed. A `listSubType` with no `listType` is
  * refused for the same reason: a subType is only distinguishing *within* a
@@ -1184,7 +1391,7 @@ function normalizeSectionMeta(value, where) {
         if (!isAddressSegment(segment)) {
             fail(
                 `${where}.${key}`,
-                `is \`${segment}\`, which is not alphanumeric. It names a ` +
+                `is \`${segment}\`, which is not lowercase alphanumeric. It names a ` +
                     "content type or subType, and those are address segments " +
                     `(${ADDRESS_SEGMENT_PATTERN.source}) — not the section's ` +
                     "own name, which is a URL this site chose and need not " +
@@ -1309,6 +1516,114 @@ function normalizeSite(value) {
     });
 }
 
+/**
+ * The `pdf` section — the book the content tree is published as.
+ *
+ * A third surface beside the packs and the website, and the one that is a
+ * **selection** rather than a rendering of everything: `document:` names the
+ * tree that says which notes the volume carries and in what order, because a
+ * book is an editorial act where a site is an index. That file is the
+ * consumer's, parsed by {@link module:engine/pdf-toc.parseDocumentTree}, and
+ * nothing about its shape is validated here — this block says only where it is.
+ *
+ * **Nothing here is an address or a brand.** The title, the subtitle, the front
+ * matter and the faces are every one of them the publishing repository's to
+ * choose, which is the whole reason they are configuration: the engine that
+ * sets the book must be able to set somebody else's book.
+ *
+ * **Declaring the block is not the switch.** Whether a PDF is built at all is
+ * `publish.site` — `content` builds one, `homepage` does not — so a package
+ * cannot end up with two switches that disagree about whether it publishes its
+ * content tree. See {@link publishesContentPages}.
+ *
+ * @param {unknown} value - The `pdf` block, or `undefined`.
+ * @param {string} rootDir - The repository root configured paths resolve against.
+ * @returns {Readonly<object>|null} It, frozen; `null` when the block is absent.
+ */
+function normalizePdf(value, rootDir) {
+    if (value === undefined) return null;
+    if (!isPlainObject(value)) fail("pdf", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, PDF_KEYS, "pdf.");
+
+    // Both required, and required together: a document with no tree has nothing
+    // to print, and a tree with no title produces a file whose name and cover
+    // say nothing about what a reader downloaded.
+    const title = requireNonEmptyString(input.title, "pdf.title");
+    const document = requireNonEmptyString(input.document, "pdf.document");
+
+    const front = [];
+    if (input.front !== undefined) {
+        if (!Array.isArray(input.front)) fail("pdf.front", "must be a list of markdown files");
+        input.front.forEach((entry, i) => {
+            front.push(requireNonEmptyString(entry, `pdf.front[${i}]`));
+        });
+    }
+
+    let fonts = EMPTY_PDF_FONTS;
+    if (input.fonts !== undefined) {
+        if (!isPlainObject(input.fonts)) fail("pdf.fonts", "must be a mapping");
+        const declared = /** @type {Record<string, unknown>} */ (input.fonts);
+        rejectUnknownKeys(declared, PDF_FONT_KEYS, "pdf.fonts.");
+        fonts = Object.freeze({
+            // Family *names*, not files: the renderer asks the font stack for a
+            // family, and `path` is where it may look beyond the system's own.
+            serif:
+                declared.serif === undefined ?
+                    ""
+                :   requireNonEmptyString(declared.serif, "pdf.fonts.serif"),
+            sans:
+                declared.sans === undefined ?
+                    ""
+                :   requireNonEmptyString(declared.sans, "pdf.fonts.sans"),
+            mono:
+                declared.mono === undefined ?
+                    ""
+                :   requireNonEmptyString(declared.mono, "pdf.fonts.mono"),
+            path:
+                declared.path === undefined ?
+                    ""
+                :   path.resolve(rootDir, requireNonEmptyString(declared.path, "pdf.fonts.path")),
+        });
+    }
+
+    // Family name to the font file carrying its glyphs, for `:icon-…:`. A file
+    // rather than a codepoint, because the font's own tables are the only
+    // trustworthy source of which glyph a name resolves to — see
+    // {@link module:engine/content-icons}, which states the style and the name
+    // and deliberately holds no codepoints.
+    const iconFonts = {};
+    if (input.iconFonts !== undefined) {
+        if (!isPlainObject(input.iconFonts)) {
+            fail("pdf.iconFonts", "must be a mapping of icon family to font file");
+        }
+        for (const [family, file] of Object.entries(input.iconFonts)) {
+            iconFonts[family] = path.resolve(
+                rootDir,
+                requireNonEmptyString(file, `pdf.iconFonts.${family}`),
+            );
+        }
+    }
+
+    return Object.freeze({
+        title,
+        subtitle:
+            input.subtitle === undefined ?
+                ""
+            :   requireNonEmptyString(input.subtitle, "pdf.subtitle"),
+        document: path.resolve(rootDir, document),
+        out: input.out === undefined ? "" : requireNonEmptyString(input.out, "pdf.out"),
+        front: Object.freeze(front.map((f) => path.resolve(rootDir, f))),
+        fonts,
+        iconFonts: Object.freeze(iconFonts),
+        // Where the Typst binary is, when it is not simply `typst` on PATH.
+        // Named rather than bundled: a native compiler would put a
+        // platform-specific binary in the dependency tree of three repositories
+        // that mostly do not build books.
+        binary: input.binary === undefined ? "" : requireNonEmptyString(input.binary, "pdf.binary"),
+    });
+}
+
 /**
  * Validate a Foundry version range.
  *
@@ -1339,40 +1654,7 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
 }
 
 /**
- * Validate the declared relationships.
- *
- * Only as far as this package needs to read them: enough that a system
- * relationship can be found and its `verified` version trusted. The rest is
- * passed through for the manifest generator to emit.
- *
- * @param {unknown} value - The `relationships` block, or `undefined`.
- * @returns {Readonly<Relationships>} It, frozen; `{}` when absent.
- */
-/**
- * The systems this package can stamp content against — declaration only (#48).
- *
- * **Declaring is not requiring, and that separation is the whole point.** The
- * only place to state a system version used to be `relationships.systems`, and
- * that list is a *restriction*: Foundry's `supportsSystem` drops a module from
- * any world whose system it does not name. So a module shipping content for two
- * systems — `harn-ensemble` ships an HM3 pack, a SoHL pack and a system-neutral
- * journals pack — had to choose between naming its systems and remaining
- * loadable, and choosing the second meant stamping no system version at all on
- * content that certainly has one.
- *
- * Naming a system here restricts nothing. {@link normalizeRequiresSystem} is
- * what restricts, and it is separate and optional.
- *
- * Each entry carries the same `compatibility` shape a relationship does, and
- * `verified` is what a pack stamps: `_stats.systemVersion` records what the
- * content was *built against*, not the floor it tolerates.
- *
- * @param {unknown} value - The declared `systems:` mapping.
- * @returns {Readonly<Record<string, Readonly<object>>>} Frozen; `{}` when absent.
- */
-/**
- * The **package-wide** system, or `null` where the configuration names none
- * (#48).
+ * The **package-wide** system, or `null` where the configuration names none.
  *
  * A *system* package is its own system, which is true by construction and needs
  * no declaration. A *module* takes the one it requires, or the one system it
@@ -1387,13 +1669,13 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
  * exists to remove. Several entries have no single answer and get none.
  *
  * **Written once and read twice**, which is why it is a function rather than the
- * expression it used to be: the value stamped into `stats.systemId` and the
+ * expression: the value stamped into `stats.systemId` and the
  * value a pack's `system:` is validated against are the same fact, and two
  * spellings of it would be free to disagree about exactly the case that has no
  * answer.
  *
  * @param {object} parts - The resolved pieces of the configuration.
- * @param {string} parts.packageKind - `systems` or `modules`.
+ * @param {string} parts.packageKind - One of {@link PACKAGE_KINDS}.
  * @param {unknown} parts.foundryPackage - The package id.
  * @param {string|null} parts.requiresSystem - The declared gate, if any.
  * @param {Readonly<Record<string, object>>} parts.systems - The `systems:` block.
@@ -1416,6 +1698,28 @@ function packageWideSystemId({
     return null;
 }
 
+/**
+ * The systems this package can stamp content against — declaration only.
+ *
+ * **Declaring is not requiring, and that separation is the whole point.** The
+ * only other place to state a system version is `relationships.systems`, and
+ * that list is a *restriction*: Foundry's `supportsSystem` drops a module from
+ * any world whose system it does not name. So a module shipping content for two
+ * systems — `harn-ensemble` ships an HM3 pack, a SoHL pack and a system-neutral
+ * journals pack — had to choose between naming its systems and remaining
+ * loadable, and choosing the second meant stamping no system version at all on
+ * content that certainly has one.
+ *
+ * Naming a system here restricts nothing. {@link normalizeRequiresSystem} is
+ * what restricts, and it is separate and optional.
+ *
+ * Each entry carries the same `compatibility` shape a relationship does, and
+ * `verified` is what a pack stamps: `_stats.systemVersion` records what the
+ * content was *built against*, not the floor it tolerates.
+ *
+ * @param {unknown} value - The declared `systems:` mapping.
+ * @returns {Readonly<Record<string, Readonly<object>>>} Frozen; `{}` when absent.
+ */
 function normalizeSystems(value) {
     if (value === undefined || value === null) return Object.freeze({});
     if (!isPlainObject(value)) fail("systems", "must be a mapping of id to spec");
@@ -1458,7 +1762,7 @@ function normalizeSystems(value) {
 }
 
 /**
- * The one system this package refuses to load without, or `null` (#48).
+ * The one system this package refuses to load without, or `null`.
  *
  * The gate half of the split. Naming a system here emits
  * `relationships.systems` for it, which is what Foundry's `supportsSystem`
@@ -1479,6 +1783,16 @@ function normalizeRequiresSystem(value) {
     return requireNonEmptyString(value, "requiresSystem");
 }
 
+/**
+ * Validate the declared relationships.
+ *
+ * Only as far as this package needs to read them: enough that a system
+ * relationship can be found and its `verified` version trusted. The rest is
+ * passed through for the manifest generator to emit.
+ *
+ * @param {unknown} value - The `relationships` block, or `undefined`.
+ * @returns {Readonly<Relationships>} It, frozen; `{}` when absent.
+ */
 function normalizeRelationships(value) {
     if (value === undefined) return Object.freeze({});
     if (!isPlainObject(value)) fail("relationships", "must be a mapping");
@@ -1557,7 +1871,7 @@ function normalizePackageBuild(value) {
  * The registry is *code* a consumer supplies — the only place the configuration
  * carries any — because the type list and the builder table have to be the same
  * list. They were two, and `trait` sat in the whitelist for a release with no
- * builder behind it (#1504).
+ * builder behind it.
  *
  * **An entry may be written two ways**, and the difference is only whether the
  * type brings default art:
@@ -1637,12 +1951,11 @@ function normalizeOneRegistry(value, at) {
 }
 
 /**
- * The declared item-builder registries, and the vocabulary their union gives
- * (#58).
+ * The declared item-builder registries, and the vocabulary their union gives.
  *
  * **One registry is a ceiling, not a default.** The accepted type list is the
  * registry's keys, which is what makes a type impossible to accept without a
- * builder behind it (#1504) — and, with one registry, impossible to accept a
+ * builder behind it — and, with one registry, impossible to accept a
  * type a *second* system declares. A tree feeding two systems has both:
  * `spell`, `invocation` and `psionic` are HM3's, `mysticalability` and
  * `projectile` are SoHL's, and `skill` is both systems' under one name and
@@ -1768,7 +2081,7 @@ function normalizeItemBuilders(value) {
 }
 
 /**
- * The publishing mode, refusing the boolean this setting used to be.
+ * The publishing mode, refusing a boolean.
  *
  * A boolean is refused rather than mapped onto the nearest mode, because the
  * reading `false` invited — *this package has no web presence* — is exactly the
@@ -1827,7 +2140,7 @@ function normalizePublish(value) {
     // A retired key is refused by name, ahead of the vocabulary check: reported
     // as merely unrecognized it would read as a misspelling of the one key that
     // survives, and the author would correct the spelling rather than learn
-    // that the mechanism is gone (#215).
+    // that the mechanism is gone.
     for (const key of Object.keys(address)) {
         if (Object.hasOwn(RETIRED_ADDRESS_KEYS, key)) {
             fail(`publish.address.${key}`, RETIRED_ADDRESS_KEYS[key]);
@@ -1847,7 +2160,7 @@ function normalizePublish(value) {
     }
     if (prefix.startsWith("/")) {
         // A leading slash would make the recorded address package-absolute,
-        // which is exactly the site-absolute shape #1465 removed.
+        // which is exactly the site-absolute shape this avoids.
         fail("publish.address.prefix", "must not begin with a slash");
     }
 
@@ -1895,12 +2208,48 @@ export function defineConfig(config) {
         fail("packageKind", `must be one of: ${PACKAGE_KINDS.join(", ")}`);
     }
 
-    if (!Array.isArray(input.packs)) fail("packs", "must be an array");
-    if (input.packs.length === 0) fail("packs", "must declare at least one pack");
-    const packs = input.packs.map((pack, index) => normalizePack(pack, `packs[${index}]`));
+    // A documentation package compiles nothing and installs nowhere, so every
+    // key that describes a Foundry package is refused by name — ahead of the
+    // checks below, which each assume a Foundry package is being described.
+    const documentation = packageKind === DOCUMENTATION_KIND;
+    if (documentation) {
+        for (const [key, why] of Object.entries(DOCUMENTATION_REFUSES)) {
+            if (input[key] === undefined) continue;
+            fail(key, `is refused in a \`${DOCUMENTATION_KIND}\` package, which ${why}`);
+        }
+        // Publishing is what a documentation package is *for*, so the floor
+        // every other package may sit at is not available to it: `homepage`
+        // would leave a package that publishes one authored page, builds no
+        // book, and compiles nothing at all.
+        if (!isPlainObject(input.publish)) {
+            fail(
+                "publish",
+                `is required in a \`${DOCUMENTATION_KIND}\` package: publishing ` +
+                    "the content tree is the whole of what it does. Write " +
+                    "`publish: {site: content}`",
+            );
+        }
+        const mode = /** @type {Record<string, unknown>} */ (input.publish).site;
+        if (mode !== "content") {
+            fail(
+                "publish.site",
+                `must be \`content\` in a \`${DOCUMENTATION_KIND}\` package — ` +
+                    "`homepage` fences the content surfaces off, and a package " +
+                    "that compiles nothing and publishes nothing from its tree " +
+                    "would produce a single authored page and no book",
+            );
+        }
+    }
+
+    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");
+    }
+    const declaredPacks = Array.isArray(input.packs) ? input.packs : [];
+    const packs = declaredPacks.map((pack, index) => normalizePack(pack, `packs[${index}]`));
 
     // One list, so the compile order and the directory list cannot disagree —
-    // they used to be `PACK_CONFIGS` and `SOURCE_PACKS`, maintained apart (#1508).
+    // as `PACK_CONFIGS` and `SOURCE_PACKS` they would be maintained apart.
     const packDirectories = packs.flatMap((pack) => [
         pack.name,
         ...pack.companions.map((companion) => companion.name),
@@ -1913,7 +2262,7 @@ export function defineConfig(config) {
         seen.add(name);
     }
 
-    // ── systems: declaring, and requiring, are separate decisions (#48) ──────
+    // ── systems: declaring, and requiring, are separate decisions ──────
     const systems = normalizeSystems(input.systems);
     const requiresSystem = normalizeRequiresSystem(input.requiresSystem);
     const declaredSystems = new Set(Object.keys(systems));
@@ -1934,7 +2283,7 @@ export function defineConfig(config) {
     // A name that resolves to nothing is a build error rather than a
     // fall-through, in the spirit the rest of this file already follows: a pack
     // stamping a system nobody declared would stamp `undefined`, which is the
-    // plausible lie #43 was about.
+    // plausible lie.
     if (requiresSystem !== null && !declaredSystems.has(requiresSystem)) {
         fail(
             "requiresSystem",
@@ -1951,14 +2300,14 @@ export function defineConfig(config) {
         // verified version `statsForPack` reads, or this package's own
         // package-wide system, whose stats answer for every pack of it.
         //
-        // This used to be skipped entirely when `systems:` was empty or absent
+        // Skipping this entirely when `systems:` is empty or absent
         // — `declaredSystems.size &&` guarded it — which left the case the
         // comment above was written about wide open. `harn-ensemble` declares
         // `system: sohl` and `system: hm3` on its packs, no `systems:` block,
         // and no package-wide system, so every pack fell through to a
         // package-wide stat that is null: 2,513 compiled actors stamped
         // `_stats.systemId: null` in a pack that says `system: sohl` on the
-        // line above. That is the plausible lie #43 was about, reached by the
+        // line above. That is the plausible lie, reached by the
         // one path this check did not cover, and the `requiresSystem` check ten
         // lines up already refuses its own version of it in as many words.
         if (!declaredSystems.has(pack.system) && pack.system !== packageWide) {
@@ -1994,7 +2343,7 @@ export function defineConfig(config) {
 
     // Several packs of one document type are allowed — editorial grouping of
     // same-type documents is ordinary Foundry practice, and collapsing such a
-    // layout breaks every stored compendium UUID (#1566). What is not allowed
+    // layout breaks every stored compendium UUID. What is not allowed
     // is two candidates for the same undeclared note.
     const defaultsByType = new Map();
     for (const pack of packs) {
@@ -2018,7 +2367,10 @@ export function defineConfig(config) {
         requireNonEmptyString(name, `skipDirectories[${index}]`),
     );
 
-    const foundryPackage = requireNonEmptyString(input.foundryPackage, "foundryPackage");
+    // Refused above for a documentation package, so there is nothing to read
+    // and nothing to derive an asset root or a package-wide system from.
+    const foundryPackage =
+        documentation ? null : requireNonEmptyString(input.foundryPackage, "foundryPackage");
 
     const {
         itemBuilders,
@@ -2029,12 +2381,12 @@ export function defineConfig(config) {
         itemFieldsBySystem,
         itemTypesBySeveralSystems,
     } = normalizeItemBuilders(input.itemBuilders);
-    // The union across every declared registry (#58) — the flat table already
+    // The union across every declared registry — the flat table already
     // holds every key any of them declares, so this stays "the registry's keys"
-    // rather than becoming a second list to keep in step (#1504).
+    // rather than becoming a second list to keep in step.
     const itemTypes = Object.freeze(new Set(Object.keys(itemBuilders)));
     // Every note that compiles into a *system-bearing* document publishes its
-    // prose as a documentation JournalEntry, and that includes actors (#337).
+    // prose as a documentation JournalEntry, and that includes actors.
     // A being was the one such note with no `none` address — its only address
     // named the Actor — so nothing a prose link wrote could land on its page.
     // `doc` stays out for the reason that actually applies to it: its single
@@ -2050,37 +2402,50 @@ export function defineConfig(config) {
         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.
-        assetRoot: `${packageKind}/${foundryPackage}/assets`,
+        //
+        // **Conditional on the kind.** `documentation` names no directory
+        // Foundry serves, and there is no package id to put under one either, so
+        // the derivation would read `documentation/null/assets` — an address
+        // that resolves nowhere and would be written into every compiled `img`.
+        // `null` says the package has no asset root instead, and
+        // {@link module:engine/helpers.resolveImg} — the only reader — refuses
+        // rather than rooting a path against nothing.
+        assetRoot: documentation ? null : `${packageKind}/${foundryPackage}/assets`,
         paths: normalizePaths(input.paths, rootDir),
-        // The package-wide system, derived (#48). A **system** package is its
+        // The package-wide system, derived. A **system** package is its
         // own system, which is true by construction and needs no declaration. A
         // **module** takes the one it requires, or the one system it declares
         // when there is exactly one; with several and no gate there is no
         // package-wide answer, and each pack carries its own.
-        stats: normalizeStats(input.stats, {
-            systemId: packageWideSystemId({
-                packageKind,
-                foundryPackage,
-                requiresSystem,
-                systems,
-                relationshipSystems,
-            }),
-            // Derived here where the answer is pure data — the `verified` of
-            // whichever system the package-wide block takes — and supplied by
-            // the loader otherwise. The loader is the half that may do I/O, and
-            // the two cases needing it are a *system* package (its own
-            // `package.json` version) and a module still deriving from
-            // `relationships.systems`.
-            systemVersion:
-                (() => {
-                    const id =
-                        requiresSystem ??
-                        (Object.keys(systems).length === 1 ? Object.keys(systems)[0] : null);
-                    return id ? (systems[id]?.compatibility?.verified ?? null) : null;
-                })() ??
-                (isPlainObject(input.stats) ? input.stats[DERIVED_SYSTEM_VERSION] : null) ??
-                null,
-        }),
+        stats:
+            documentation ? null : (
+                normalizeStats(input.stats, {
+                    systemId: packageWideSystemId({
+                        packageKind,
+                        foundryPackage,
+                        requiresSystem,
+                        systems,
+                        relationshipSystems,
+                    }),
+                    // Derived here where the answer is pure data — the `verified` of
+                    // whichever system the package-wide block takes — and supplied by
+                    // the loader otherwise. The loader is the half that may do I/O, and
+                    // the two cases needing it are a *system* package (its own
+                    // `package.json` version) and a module still deriving from
+                    // `relationships.systems`.
+                    systemVersion:
+                        (() => {
+                            const id =
+                                requiresSystem ??
+                                (Object.keys(systems).length === 1 ?
+                                    Object.keys(systems)[0]
+                                :   null);
+                            return id ? (systems[id]?.compatibility?.verified ?? null) : null;
+                        })() ??
+                        (isPlainObject(input.stats) ? input.stats[DERIVED_SYSTEM_VERSION] : null) ??
+                        null,
+                })
+            ),
         itemBuilders,
         itemArt,
         itemFields,
@@ -2097,10 +2462,12 @@ export function defineConfig(config) {
         itemTypes,
         docEntryTypes,
         skipDirectories: Object.freeze(skipDirectories),
+        icons: normalizeIcons(input.icons, rootDir),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),
         docs: normalizeDocs(input.docs),
         site: normalizeSite(input.site),
+        pdf: normalizePdf(input.pdf, rootDir),
         compatibility: normalizeCompatibility(input.compatibility, "compatibility"),
         relationships: normalizeRelationships(input.relationships),
         systems,