@heroiclands/package-build 22.1.1 → 22.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @heroiclands/package-build
 
+## 22.3.0
+
+### Minor Changes
+
+- a79b33a: **A note may declare `pack: none`.** The universal `pack` key accepts one more value: `none` says the note publishes to the site and compiles into no Foundry document. Such a note is walked, published as a page, present in the content index with an address and no UUID, and addressable by wikilink like any other — on the web the link reaches the page, and in a compiled journal the reader gets the link's text with no document to open. Every pack compiler passes over it without a finding. It is accepted only on a type whose sole document is the JournalEntry its prose becomes (`doc`, `place`, `lore`, `scenario`) and refused by name on a type that compiles an Item, an Actor, a Macro, a Scene or an Adventure, naming the document it would drop. It is read per system like any other `pack:`, and a configured pack may not be called `none`.
+  
+  **`site.trees` and `site.readmeSections` are refused.** A page is a note in the content tree, and there is no second mechanism for mounting a directory of markdown beside it. A configuration declaring either key fails with a message saying so. A package that mounted a directory of pages moves them into `assets/content/` as `doc` notes — each with a `shortcode` and `pack: none` — rewrites their relative links as wikilinks, and declares the section that lists them under `site.sections`. The `sohlKb` site pass no longer rewrites repository-relative links, and its `blob` option has no reader.
+
+## 22.2.0
+
+### Minor Changes
+
+- 241451e: **`schema.json` is a release asset, not a committed file.** `package-build schema` writes `build/schema.json` instead of the repository root, and `--check` is gone — there is no committed copy left to compare against. `package-build release` publishes `schema.json` beside the archive and the manifest, the way it already publishes the content index, whenever the staged tree carries one.
+  
+  To keep publishing a schema: drop the committed `schema.json` and any lint step that runs `package-build schema --check`; add `{ from: build/schema.json, to: schema.json }` to `packageBuild.assets`, and run `package-build schema` before `package-build assets` in the build chain so the release never ships one older than the source it was cut from.
+- 483b630: **`content-build site` refuses to generate a configuration with no `site.assets`.** The theme resolves every relative asset — the brand logo, the 404 hero, every CDN-resolved image — against `site.assets`, and there is no defensible default: a package that built a site with the key absent published every one of those as a broken relative path. Declare `site.assets` — the `https://` host every package's imagery is served from — in `package-build.config.yaml` for any package that publishes a site.
+- 985f599: **A package now describes itself once for Foundry and once for the site.** Foundry's package browser wants a pitch — HTML, any length — and a site's `<meta name="description">` wants one plain sentence; deriving both from `package.json`'s `description` forced one string onto both. Declare `packageBuild.manifest.descriptionHtml` in `package-build.config.yaml` for the Foundry pitch (HTML allowed, emitted as the manifest's `description`) and `site.description` for the site's meta description (plain text, required for `content-build site`). `package.json`'s own `description` is read by neither any more — a warning names both keys when one is still declared — and the field can be deleted.
+
 ## 22.1.1
 
 ### Patch Changes

package/CONTENT.md

@@ -488,6 +488,17 @@ pack: mysteries
   type one system maps and another does not stays silent for the system that
   declines it.
 
+- **`pack: none` compiles the note into no document, on purpose.** The note is
+  walked, published as a page, present in the content index with an address
+  and no UUID, and addressable by wikilink; every pass passes over it without
+  a finding, and the finding above says nothing about it. It is accepted only
+  on a type whose sole document is the JournalEntry its prose becomes — a
+  `doc`, say — and refused by name on a type that compiles an Item, an Actor,
+  a Macro, a Scene or an Adventure, where it would drop that document. A
+  configured pack may not be called `none`. This is how a page of developer
+  documentation lives in the content tree beside everything else: it is a
+  note like any other, and it reaches no compendium.
+
 **The configuration is found by walking up from the working directory, and from
 the installed package only if that finds nothing.** `engine/pack-config.mjs`
 climbs from `process.cwd()` first, so a build reads the tree it was run in —
@@ -2256,10 +2267,10 @@ note-format knowledge against game-system knowledge, and a homepage carries no
 
 `publish.site` then says how much _else_ is published:
 
-| Mode       | What is published                                                               |
-| ---------- | ------------------------------------------------------------------------------- |
-| `homepage` | The authored homepage, and no other page. **The default, and the floor.**       |
-| `content`  | The homepage plus every page the content tree compiles to, and its extra trees. |
+| Mode       | What is published                                                         |
+| ---------- | ------------------------------------------------------------------------- |
+| `homepage` | The authored homepage, and no other page. **The default, and the floor.** |
+| `content`  | The homepage plus every page the content tree compiles to.                |
 
 There is no value meaning "no web presence": every package publishes its
 homepage. A boolean is refused, with a message naming the mode to write
@@ -2273,8 +2284,8 @@ content_ — journal text, artwork, item descriptions, compiled notes — and a
 announcing the module discloses none of it. Because the failure mode is silent,
 the mode **fences the content surfaces off** rather than trusting a
 configuration to stay empty: in `homepage` mode the tree is never walked for
-pages, and `sections`, `trees`, `landing` and `backfillSections` emit nothing
-even when they are declared.
+pages, and `sections`, `landing` and `backfillSections` emit nothing even when
+they are declared.
 
 That is separate from the **dependency** edge, which such a module also
 declines: being cited by another package is what would stop it being
@@ -2293,9 +2304,12 @@ does not reach it.
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the content index reads, so a page and its index record cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
-what a section is called, which extra trees are published beside the content,
-and the residue of the generated Hugo configuration that is this repository's
-own:
+what a section is called, and the residue of the generated Hugo configuration
+that is this repository's own. What the site publishes is the content tree and
+nothing beside it: a page of documentation is a note (`type: doc`, with
+`pack: none` where it compiles into no document), so there is no second
+mechanism for mounting a directory of markdown, and a `trees:` or
+`readmeSections:` key is refused with a message saying so.
 
 ```yaml
 site:
@@ -2307,16 +2321,12 @@ site:
   passOptions:
     apiBase: /sohl/api/
     symbolMap: kb/data/api-symbols.json
-    blob: https://github.com/HeroicLands/…/blob/main/
-  trees:
-    - { from: kb/dev-docs, section: dev-docs }
   sections:
     being:
       title: Beings
       banner: banners/creature.webp
       description: Folk, animals and the things that walk the world.
-  readmeSections:
-    dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
+    reference: { title: Reference, listType: doc, listSubType: reference }
   list: { shortcodes: true }
   notfound:
     tagline: Song of Heroic Lands has no page at
@@ -2330,10 +2340,8 @@ site:
 | `base`             | Where the package is served: the prefix on every rendered `href`, and what a manifest `path` is measured against. It reaches no page's own `url:` — see [A page's URL is its address](#a-pages-url-is-its-address). Defaults to `/<contentPackage>/`. |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                                                                                                                                                                        |
 | `sections`         | The Hugo sections this site declares, and what each says about itself — see below.                                                                                                                                                                    |
-| `readmeSections`   | The same, for a `trees` entry, whose landing comes from its own `README`.                                                                                                                                                                             |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.                                                                                                                                                          |
 | `backfillSections` | Write a bare `_index.md` for any other directory directly under the mount.                                                                                                                                                                            |
-| `trees`            | Extra source trees published beside the content, preserving their source layout below a section.                                                                                                                                                      |
 | `pass`             | A named bundle of this repository's own body rewrites.                                                                                                                                                                                                |
 | `passOptions`      | That bundle's options.                                                                                                                                                                                                                                |
 | `assets`           | The host every package's imagery is served from; the generated `params.cdnBaseURL`.                                                                                                                                                                   |
@@ -2377,12 +2385,6 @@ Whatever the entry may carry is the whole of what the section can say.
 | `listType`    | no       | The content **type** whose pages this section lists.                      |
 | `listSubType` | no       | Narrows that to one **subType**. Only with a `listType`.                  |
 
-`readmeSections` takes the same keys, for a **`trees`** entry: those pages keep
-their source layout below a named section, so the tree's own `README.md` is that
-section's landing. What the section declares wins over what the `README` happens
-to carry — the landing has to match the card that links to it. No content note
-reaches this map any more.
-
 #### Saying what a section lists
 
 A generic list layout has nothing to render, because the membership a section
@@ -2477,15 +2479,9 @@ a site publishes dead `{@link}` tags at exit 0. A map that is read reports
 its symbol count at info level, which is the only way to tell a map that loaded
 from one that loaded empty without reading the emitted HTML.
 
-A bundle supplies up to two hooks, and their order around the shared work is the
-point:
-
-1. `beforeLinks`, on every page, before wikilinks resolve — a `{@link}` tag may
-   sit in prose a wikilink also touches.
-2. `afterLinks`, on pages from an extra tree only — repository-relative links are
-   a property of how those pages are authored, not of content notes.
-
-Both run inside code-fence protection, so neither can rewrite a fenced example.
+A bundle supplies one hook, `beforeLinks`, which runs on every page before
+wikilinks resolve — a `{@link}` tag may sit in prose a wikilink also touches.
+It runs inside code-fence protection, so it cannot rewrite a fenced example.
 
 ### The gates
 
@@ -2499,7 +2495,6 @@ after the links that failed because of it reads as a pile of broken notes.
 | Addresses              | A note with no shortcode to be addressed by, or no section to be filed under.      |
 | Unusable manifest      | A vendored manifest this build cannot read.                                        |
 | Unaddressable manifest | One it can read but cannot look anything up in.                                    |
-| Package conflicts      | One address claimed by two packages.                                               |
 | Tables and wikilinks   | A table directive that cannot be honoured, or a link that lands nowhere.           |
 
 None of them exits the process from inside the library; the command decides. That

package/bin/content-build.mjs

@@ -1561,9 +1561,6 @@ function siteCommand() {
                 for (const f of gates.unaddressable) {
                     console.error(formatUnaddressable(f, loadPackConfig()));
                 }
-                for (const c of gates.conflicts) {
-                    log.error(`address ${c.key} is also published by ${c.package}`);
-                }
                 if (gatesFailed(gates)) {
                     process.exitCode = 1;
                     return;

package/bin/package-build.mjs

@@ -334,9 +334,11 @@ async function formatGenerated(text, filepath) {
  * so the system publishes the field sets as data — the same shape the link
  * manifest already uses for addresses.
  *
- * `--check` fails when the committed copy disagrees with what the source would
- * produce now, because a generated file nothing checks drifts from its
- * generator silently — and this one is read by other repositories.
+ * Writes under `build/`, alongside every other generated artifact: a release
+ * publishes it beside the archive and the manifest (see `package-build
+ * release`), and `packageBuild.assets` carries it into the staged tree from
+ * there. There is nothing committed to compare it against, so there is no
+ * `--check`.
  *
  * @returns {object} The yargs command module.
  */
@@ -344,15 +346,8 @@ function schemaCommand() {
     return {
         command: "schema",
         describe: "Publish this package's DataModel field sets as schema.json",
-        builder: (y) =>
-            y.option("check", {
-                type: "boolean",
-                default: false,
-                describe:
-                    "Fail when the committed schema.json is out of date " +
-                    "rather than rewriting it",
-            }),
-        handler: handler(async (argv) => {
+        builder: (y) => y,
+        handler: handler(async () => {
             const config = loadPackageBuildConfig();
             if (!config.schema.length) {
                 console.log(
@@ -369,25 +364,13 @@ function schemaCommand() {
                 version: pkg.version,
             });
 
-            const out = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
+            const out = path.join(config.rootDir, "build", SCHEMA_ARTIFACT_FILE);
             const text = await formatGenerated(JSON.stringify(artifact), out);
             const counts = Object.entries(artifact.documents)
                 .map(([kind, subtypes]) => `${Object.keys(subtypes).length} ${kind}`)
                 .join(", ");
 
-            if (argv.check) {
-                const current = fs.existsSync(out) ? fs.readFileSync(out, "utf8") : null;
-                if (current !== text) {
-                    die(
-                        `${SCHEMA_ARTIFACT_FILE} does not match what this ` +
-                            `package's data models would produce — regenerate ` +
-                            `it with \`package-build schema\`.`,
-                    );
-                }
-                console.log(`✅ ${SCHEMA_ARTIFACT_FILE} is up to date ` + `(${counts} subtypes).`);
-                return;
-            }
-
+            fs.mkdirSync(path.dirname(out), { recursive: true });
             fs.writeFileSync(out, text, "utf8");
             console.log(
                 `✅ Wrote ${SCHEMA_ARTIFACT_FILE} for ${artifact.system} ` +

package/config.mjs

@@ -91,7 +91,7 @@ const SECTION_KEYS = [
 export const DERIVED_MANIFEST_KEYS = Object.freeze({
     id: "`foundryPackage`, itself derived from package.json `name`",
     version: "package.json `version`",
-    description: "package.json `description`",
+    description: "`packageBuild.manifest.descriptionHtml`",
     url: "package.json `repository`",
     bugs: "package.json `repository`",
     manifest: "package.json `repository` and the release tag",
@@ -152,11 +152,16 @@ const ARTIFACT_OF_KIND = Object.freeze({
  * message, so {@link loadPackageBuildConfig} — the half that knows which file
  * was read — can resolve it to a line and column. This half stays pure.
  *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
  * @param {string} where - Dotted path of the offending key.
  * @param {string} problem - What is wrong with it.
  * @returns {never}
  */
-function fail(where, problem) {
+export function fail(where, problem) {
     throw Object.assign(new TypeError(`package-build config: \`${where}\` ${problem}.`), {
         field: where,
     });

package/content-config.mjs

@@ -73,7 +73,7 @@ import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-char
 import { ASSET_TYPE_NAMES } from "./engine/asset-types.mjs";
 import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
-import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
+import { MAP_TYPES, NO_PACK, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
 
@@ -256,10 +256,10 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.trees` / `site.landing`
- *   emit nothing, and nothing serves a page for its addresses.
+ *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
+ *   and nothing serves a page for its addresses.
  * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase, the extra trees, the section landings.
+ *   knowledgebase and the section landings.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
@@ -759,11 +759,10 @@ const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
     "base",
     "assets",
+    "description",
     "packages",
     "sections",
-    "readmeSections",
     "landing",
-    "trees",
     "pass",
     "passOptions",
     "backfillSections",
@@ -771,7 +770,6 @@ const SITE_KEYS = [
     "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"];
@@ -1078,6 +1076,15 @@ function normalizePack(value, where, nested = false) {
     rejectUnknownKeys(pack, PACK_KEYS, `${where}.`);
 
     const name = requireNonEmptyString(pack.name, `${where}.name`);
+    // A note writes `pack: none` to compile into no document, so a pack of
+    // that name could never be addressed by one.
+    if (name === NO_PACK) {
+        fail(
+            `${where}.name`,
+            `may not be \`${NO_PACK}\` — a note declares \`pack: ${NO_PACK}\` to ` +
+                `compile into no document, so no pack may answer to the name`,
+        );
+    }
     const type = pack.type;
     if (
         typeof type !== "string" ||
@@ -1575,6 +1582,33 @@ function normalizeSiteAssets(value) {
     return assets.replace(/\/+$/, "");
 }
 
+/**
+ * The site's `<meta name="description">`, plain text.
+ *
+ * Foundry's package browser wants a pitch — HTML, any length,
+ * `packageBuild.manifest.descriptionHtml` — and a `<meta>` tag wants one
+ * plain sentence. The two audiences are different enough that one string
+ * cannot serve both, so this is the site's own, checked for markup rather
+ * than trusted to carry none: a value with a `<` in it is refused, naming
+ * `descriptionHtml` as where markup belongs.
+ *
+ * @param {unknown} value - The configured value, or `undefined`.
+ * @returns {string} The description; `""` when unset.
+ */
+function normalizeSiteDescription(value) {
+    if (value === undefined) return "";
+    const description = requireNonEmptyString(value, "site.description");
+    if (description.includes("<")) {
+        fail(
+            "site.description",
+            "contains `<` — this is plain text for the site's " +
+                '`<meta name="description">`; markup belongs in ' +
+                "`packageBuild.manifest.descriptionHtml`",
+        );
+    }
+    return description;
+}
+
 /**
  * A map of section name → landing metadata.
  *
@@ -1616,7 +1650,7 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     disableKinds: "whether any note in the tree carries `tags:`, which the site walk discovers",
     taxonomies: "whether any note in the tree carries `tags:`, which the site walk discovers",
     outputs: "whether any note in the tree carries `tags:`, which the site walk discovers",
-    "params.description": "package.json `description`",
+    "params.description": "`site.description`",
     "params.author": "package.json `author`",
     "params.cdnBaseURL": "`site.assets`",
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
@@ -1722,15 +1756,22 @@ function normalizeSiteHugo(value) {
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
- * 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.
+ * Everything here is *framing*: what a section is called, 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.
+ *
+ * **What the site publishes is the content tree, and nothing beside it.** A
+ * page of documentation is a note — `type: doc`, addressed by its shortcode,
+ * compiling into no document where it says `pack: none` — so there is no
+ * second mechanism for mounting a directory of markdown, and a configuration
+ * that names one (`site.trees`, and the `site.readmeSections` that titled
+ * such a tree's landing) is refused with a message saying where the page
+ * goes instead.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
@@ -1739,11 +1780,10 @@ function normalizeSite(value) {
     const empty = Object.freeze({
         base: "",
         assets: "",
+        description: "",
         packages: Object.freeze([]),
         sections: Object.freeze({}),
-        readmeSections: Object.freeze({}),
         landing: null,
-        trees: Object.freeze([]),
         pass: "",
         passOptions: Object.freeze({}),
         backfillSections: false,
@@ -1764,27 +1804,20 @@ function normalizeSite(value) {
                 "the location is not configurable. Remove the key",
         );
     }
-    rejectUnknownKeys(input, SITE_KEYS, "site.");
-
-    const trees = [];
-    if (input.trees !== undefined) {
-        if (!Array.isArray(input.trees)) fail("site.trees", "must be a list");
-        input.trees.forEach((entry, i) => {
-            const where = `site.trees[${i}]`;
-            if (!isPlainObject(entry)) fail(where, "must be a mapping");
-            const tree = /** @type {Record<string, unknown>} */ (entry);
-            rejectUnknownKeys(tree, SITE_TREE_KEYS, `${where}.`);
-            trees.push(
-                Object.freeze({
-                    from: requireNonEmptyString(tree.from, `${where}.from`),
-                    section: requireNonEmptyString(tree.section, `${where}.section`),
-                    // The tree's own path, POSIX-separated — what a
-                    // repository-relative link inside it is resolved against.
-                    rel: String(tree.from).split(path.sep).join("/"),
-                }),
-            );
-        });
+    // Refused by name too, and ahead of the vocabulary check for the same
+    // reason: a page is a note in the content tree, and the useful thing to
+    // say is where it goes rather than that the key is unknown.
+    for (const key of ["trees", "readmeSections"]) {
+        if (input[key] === undefined) continue;
+        fail(
+            `site.${key}`,
+            "is retired — a page is a note in the content tree. Give each page " +
+                "`type: doc`, a `shortcode` and `pack: none`, file it under " +
+                "`assets/content/`, and declare the section that lists it under " +
+                "`site.sections`",
+        );
     }
+    rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     let packages = [];
     if (input.packages !== undefined) {
@@ -1807,11 +1840,10 @@ function normalizeSite(value) {
     return Object.freeze({
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
+        description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
-        readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),
         landing,
-        trees: Object.freeze(trees),
         pass: input.pass === undefined ? "" : requireNonEmptyString(input.pass, "site.pass"),
         passOptions:
             input.passOptions === undefined ?

package/docs/api.md

@@ -103,6 +103,7 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 | `MAP_TYPES`            | `const MAP_TYPES`                               | —                                                              | enumerating the content types that compile into a Foundry `Scene`                          |
 | `MAP_SUBTYPES`         | `const MAP_SUBTYPES`                            | —                                                              | reading the map subTypes, which differ only in derived canvas defaults                     |
 | `JOURNAL_TYPES`        | `const JOURNAL_TYPES`                           | —                                                              | enumerating content types whose whole document _is_ a JournalEntry                         |
+| `NO_PACK`              | `const NO_PACK`                                 | —                                                              | spelling the `pack:` value (`none`) that routes a note's document into no compendium       |
 | `PACK_BY_TYPE`         | `const PACK_BY_TYPE`                            | —                                                              | looking up the conventional pack name and document type for a content type                 |
 | `RETIRED_TYPES`        | `const RETIRED_TYPES`                           | —                                                              | looking up what a retired content type was replaced by                                     |
 | `assertTypeNotRetired` | `assertTypeNotRetired(type, where)`             | throws                                                         | refusing a note whose type has been retired outright                                       |
@@ -200,6 +201,8 @@ Which pack a note's document lands in, when a document type has more than one co
 | ------------------ | -------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
 | `PackRoutingError` | `class PackRoutingError extends Error` | —                          | catching a note that cannot be routed to any configured pack                                      |
 | `PACK_FIELD`       | `const PACK_FIELD`                     | —                          | naming the frontmatter field a note declares its pack in                                          |
+| `NO_PACK`          | `const NO_PACK`                        | —                          | spelling the `pack:` value (`none`) that routes a note's document into no compendium              |
+| `declaresNoPack`   | `declaresNoPack(fm, system)`           | `boolean`                  | asking, without a router, whether a note declares `pack: none` for one system's document          |
 | `createPackRouter` | `createPackRouter(packs)`              | `{resolve, resolveOrNull}` | building a router for one configured pack list, purely, for testing without a config file on disk |
 | `routerFor`        | `routerFor(config)`                    | the router                 | getting the router for a resolved configuration, built once per configuration                     |
 | `packRouter`       | `packRouter()`                         | the router                 | asking, as every module that emits a UUID does, where a note's document lives                     |
@@ -605,25 +608,23 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 Publishing a content tree as a website. Compiling a content tree into compendium packs is `content-build package compile`. Publishing the _same tree_ as a website was a script each consumer wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of them identical — and the copies drifted in ways neither repository could see. `sohl-thalorna` reimplemented four things this package already exported, not because it needed different behaviour but because its script predates the extraction. That is the failure a command removes: a consumer cannot accidentally reimplement one.
 
-| Export                 | Signature                                         | Returns                                                                                                                                | Use it when                                                                   |
-| ---------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `walkSiteTree`         | `function walkSiteTree(dir, skip`                 | {string[]} Absolute paths.                                                                                                             | Every `.md` file under `dir`, depth-first in directory order.                 |
-| `collectContentPages`  | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                    |
-| `collectTreePages`     | `function collectTreePages(tree, ctx)`            | {{pages: object[], fmLinkFindings: object[]}}                                                                                          | An extra tree's pages — a documentation tree published alongside the content. |
-| `collectHomepages`     | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.     |
-| `writeHomepages`       | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage at its address, below the package's own root.            |
-| `siteGates`            | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.              |
-| `emptyGates`           | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                             |
-| `gatesFailed`          | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                          |
-| `tableUniverse`        | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.                  |
-| `sectionFrontmatter`   | `function sectionFrontmatter(meta)`               | {object} Its front matter, `title` first.                                                                                              | The front matter a section's landing states about itself.                     |
-| `pageFrontmatter`      | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                        |
-| `pageDestination`      | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                         |
-| `renderPages`          | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                                |
-| `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.                                           |
-| `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.    |
+| Export                 | Signature                                         | Returns                                                                                                                                | Use it when                                                                |
+| ---------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `collectContentPages`  | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                 |
+| `collectHomepages`     | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.  |
+| `writeHomepages`       | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage at its address, below the package's own root.         |
+| `siteGates`            | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.           |
+| `emptyGates`           | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                          |
+| `gatesFailed`          | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                       |
+| `tableUniverse`        | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.               |
+| `sectionFrontmatter`   | `function sectionFrontmatter(meta)`               | {object} Its front matter, `title` first.                                                                                              | The front matter a section's landing states about itself.                  |
+| `pageFrontmatter`      | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                     |
+| `pageDestination`      | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                      |
+| `renderPages`          | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                             |
+| `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}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                        |
+| `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`
 
@@ -1138,13 +1139,12 @@ Which of SoHL's facts a note's summary panel carries, and how they group. Read o
 
 ### `sohl.kbPasses`
 
-The `sohl` knowledgebase's own body passes: two rewrites driven by a TypeDoc symbol map and a repository layout only this package has, named from `site.passOptions` the same way an asset transform is named from configuration. Neither rewrite ever fails a build — an unresolved `{@link}` degrades to a code span, and a relative link outside the documentation tree becomes a GitHub blob URL — but building the bundle from a misconfigured `symbolMap` fails loudly before any page renders.
+The `sohl` knowledgebase's own body pass: a rewrite driven by a TypeDoc symbol map only this package has, named from `site.passOptions` the same way an asset transform is named from configuration. The rewrite never fails a build — an unresolved `{@link}` degrades to a code span — but building the bundle from a misconfigured `symbolMap` fails loudly before any page renders.
 
-| Export             | Signature                                 | Returns                                                | Use it when                                                                                                                                                                     |
-| ------------------ | ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveApiLinks`  | `resolveApiLinks(body, symbols, apiBase)` | `string` — the body with every tag resolved            | resolving inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags in a markdown body against the API symbol map                                                          |
-| `rewriteRepoLinks` | `rewriteRepoLinks(body, docRel, options)` | `string` — the body with every relative link rewritten | rewriting a developer doc's repository-relative links so they resolve on the published site (documentation-tree links become routes, everything else becomes a GitHub blob URL) |
-| `sohlKbPass`       | `sohlKbPass(options)`                     | `{beforeLinks: Function, afterLinks: Function}`        | building the `sohl` knowledgebase pass bundle the site renderer calls around wikilink resolution                                                                                |
+| Export            | Signature                                 | Returns                                     | Use it when                                                                                                            |
+| ----------------- | ----------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `resolveApiLinks` | `resolveApiLinks(body, symbols, apiBase)` | `string` — the body with every tag resolved | resolving inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags in a markdown body against the API symbol map |
+| `sohlKbPass`      | `sohlKbPass(options)`                     | `{beforeLinks: Function}`                   | building the `sohl` knowledgebase pass bundle the site renderer calls before wikilink resolution                       |
 
 ### Flat exports (not under a namespace)
 
@@ -1290,6 +1290,7 @@ console.log(config.stageDir);
 | `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 |
+| `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                          |
 
 ## `./prettier`