@heroiclands/package-build 23.1.0 → 23.2.0

package/docs/api.md

@@ -98,26 +98,21 @@ console.log(addressSlug({ type: "weapongear", shortcode: "dagger" }));
 
 ### `engine.ids`
 
-Deterministic document ids, derived by hashing rather than stored, so compile passes that cannot see each other's output still agree on an id. Also holds the pack-name vocabulary — which content type compiles into which conventional pack and document type — and the retired/renamed type tables every type-keyed lookup normalizes through first.
-
-| Export                 | Signature                                       | Returns                                                        | Use it when                                                                                |
-| ---------------------- | ----------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `makeId`               | `makeId(namespace, value)`                      | `string` — a 16-character hexadecimal Foundry id               | deriving a stable id from a namespace and a value, e.g. a heading id when none is supplied |
-| `MAP_TYPES`            | `const MAP_TYPES`                               | —                                                              | enumerating the content types that compile into a Foundry `Scene`                          |
-| `isMapType`            | `isMapType(type)`                               | `boolean`                                                      | asking whether a content note's type compiles into a Scene                                 |
-| `MAP_SUBTYPES`         | `const MAP_SUBTYPES`                            | —                                                              | reading the map subTypes, each of which carries an exported Scene                          |
-| `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                                       |
-| `RENAMED_TYPES`        | `const RENAMED_TYPES`                           | —                                                              | looking up what a renamed content type is now called                                       |
-| `currentType`          | `currentType(type)`                             | the current spelling                                           | normalizing a type to its current spelling before any keyed lookup                         |
-| `renamedTypeMessage`   | `renamedTypeMessage(retired, current, where)`   | `string` — the finding message                                 | building the one message every reporter of a renamed type shares                           |
-| `ITEM_PACK`            | `const ITEM_PACK`                               | —                                                              | naming the pack every open-set item type compiles into by default                          |
-| `packForType`          | `packForType(type)`                             | `{pack, docType}`                                              | resolving the pack and document type an item type's documents live in                      |
-| `compendiumUuid`       | `compendiumUuid(packageId, type, id, packName)` | `string` — `Compendium.<packageId>.<pack>.<DocumentType>.<id>` | composing a document's full compendium UUID in the one place it is spelled                 |
-| `pageUuid`             | `pageUuid(entryUuid, pageId)`                   | `string` — the page's UUID                                     | composing the UUID of a JournalEntry page                                                  |
+Deterministic document ids, derived by hashing rather than stored, so compile passes that cannot see each other's output still agree on an id. Also holds the pack-name vocabulary — which content type compiles into which conventional pack and document type.
+
+| Export           | Signature                                       | Returns                                                        | Use it when                                                                                |
+| ---------------- | ----------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `makeId`         | `makeId(namespace, value)`                      | `string` — a 16-character hexadecimal Foundry id               | deriving a stable id from a namespace and a value, e.g. a heading id when none is supplied |
+| `MAP_TYPES`      | `const MAP_TYPES`                               | —                                                              | enumerating the content types that compile into a Foundry `Scene`                          |
+| `isMapType`      | `isMapType(type)`                               | `boolean`                                                      | asking whether a content note's type compiles into a Scene                                 |
+| `MAP_SUBTYPES`   | `const MAP_SUBTYPES`                            | —                                                              | reading the map subTypes, each of which carries an exported Scene                          |
+| `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                 |
+| `ITEM_PACK`      | `const ITEM_PACK`                               | —                                                              | naming the pack every open-set item type compiles into by default                          |
+| `packForType`    | `packForType(type)`                             | `{pack, docType}`                                              | resolving the pack and document type an item type's documents live in                      |
+| `compendiumUuid` | `compendiumUuid(packageId, type, id, packName)` | `string` — `Compendium.<packageId>.<pack>.<DocumentType>.<id>` | composing a document's full compendium UUID in the one place it is spelled                 |
+| `pageUuid`       | `pageUuid(entryUuid, pageId)`                   | `string` — the page's UUID                                     | composing the UUID of a JournalEntry page                                                  |
 
 ### `engine.formatGenerated`
 
@@ -131,32 +126,31 @@ can write the result directly without introducing formatting drift.
 
 ### `engine.systemBlock`
 
-The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the block, the shared top level, and a retiring position in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
-
-| Export                      | Signature                                           | Returns                                | Use it when                                                                                                                                          |
-| --------------------------- | --------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                             | —                                      | naming the key inside a system block whose contents are the system's own vocabulary                                                                  |
-| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                   | —                                      | mapping a system-block key to the document property it becomes                                                                                       |
-| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                            | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                                                                          |
-| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                           | —                                      | enumerating every key any system block may carry                                                                                                     |
-| `setPath`                   | `setPath(target, dotted, value)`                    | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                                                                                      |
-| `systemBlock`               | `systemBlock(fm, block)`                            | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed                                                               |
-| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                     | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                                                                          |
-| `systemData`                | `systemData(fm, block)`                             | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                                                                        |
-| `blockField`                | `blockField(fm, block, key, defaultValue)`          | the value                              | reading a key from one system's block, falling back to the top level                                                                                 |
-| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`          | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block                                                           |
-| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`       | the value                              | reading a property a system block may override, else the shared top-level one                                                                        |
-| `resolveDataProperty`       | `resolveDataProperty(fm, block, key, defaultValue)` | `{value, from}`                        | resolving a shared `data:` key every type accepts — a system override, then shared `data`, then a top-level value — and reporting which one answered |
-| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)`   | the value                              | `resolveDataProperty`'s value alone, in the same order                                                                                               |
-| `legacyKeyOf`               | `legacyKeyOf(field)`                                | `string \| undefined`                  | finding the key a field is authored at inside a system block                                                                                         |
-| `retiredTopLevelKey`        | `retiredTopLevelKey(field)`                         | `string \| undefined`                  | finding the bare top-level key a `data:`-sourced field is being swept off                                                                            |
-| `authoredKey`               | `authoredKey(name)`                                 | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it                                                        |
-| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`                 | `{value, from}`                        | resolving one declared field against a note, in the declared source order                                                                            |
-| `systemDataPaths`           | `systemDataPaths(data, prefix)`                     | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                                                                       |
-| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`           | `string[]`                             | finding authored paths a system's published schema does not declare                                                                                  |
-| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                  | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes                                                        |
-| `claimedPaths`              | `claimedPaths(fields)`                              | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`                                                                   |
-| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                   | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                                                                              |
+The per-system frontmatter block: how one note feeds more than one game system through properties named after that system (`<system>.system`, `<system>.type`, `<system>.img`, `<system>.items` on actors). Resolves a field's value through the destination, the block and the declared shared source in that order, and merges an authored `<system>.system` onto a compiler-built one without disturbing what the builder already wrote.
+
+| Export                      | Signature                                           | Returns                                | Use it when                                                                                                                  |
+| --------------------------- | --------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `SYSTEM_DATA_KEY`           | `const SYSTEM_DATA_KEY`                             | —                                      | naming the key inside a system block whose contents are the system's own vocabulary                                          |
+| `BLOCK_DOCUMENT_PROPERTIES` | `const BLOCK_DOCUMENT_PROPERTIES`                   | —                                      | mapping a system-block key to the document property it becomes                                                               |
+| `BLOCK_DIRECTIVES`          | `const BLOCK_DIRECTIVES`                            | —                                      | recognizing a build directive (e.g. `pack`) that names no document property                                                  |
+| `SYSTEM_BLOCK_KEYS`         | `const SYSTEM_BLOCK_KEYS`                           | —                                      | enumerating every key any system block may carry                                                                             |
+| `setPath`                   | `setPath(target, dotted, value)`                    | `object` — `target`, for chaining      | writing a value at a dotted path in a document's `system` block                                                              |
+| `systemBlock`               | `systemBlock(fm, block)`                            | `Record<string, unknown> \| undefined` | reading one system's whole block off a note, or nothing when it is absent or malformed                                       |
+| `carriesSystemBlock`        | `carriesSystemBlock(fm, block)`                     | `boolean`                              | deciding whether a pack that declares a system should compile a note at all                                                  |
+| `systemData`                | `systemData(fm, block)`                             | `Record<string, unknown>`              | reading a system block's `system` sub-block, `{}` when absent                                                                |
+| `blockField`                | `blockField(fm, block, key, defaultValue)`          | the value                              | reading a key from one system's block, falling back to the top level                                                         |
+| `sharedProperty`            | `sharedProperty(fm, source, defaultValue)`          | the value                              | reading a shared top-level property by a possibly-dotted path, blind to every system block                                   |
+| `blockProperty`             | `blockProperty(fm, block, key, defaultValue)`       | the value                              | reading a property a system block may override, else the shared top-level one                                                |
+| `resolveDataProperty`       | `resolveDataProperty(fm, block, key, defaultValue)` | `{value, from}`                        | resolving a shared `data:` key every type accepts — a system override, then shared `data` — and reporting which one answered |
+| `blockDataProperty`         | `blockDataProperty(fm, block, key, defaultValue)`   | the value                              | `resolveDataProperty`'s value alone, in the same order                                                                       |
+| `inBlockKey`                | `inBlockKey(field)`                                 | `string \| undefined`                  | finding the key a field is authored at inside a system block — none for a name that is a path into `data:`                   |
+| `authoredKey`               | `authoredKey(name)`                                 | `string`                               | reading a shared source as the key an author writes, without the `data:` container holding it                                |
+| `resolveFieldValue`         | `resolveFieldValue(field, fm, ...)`                 | `{value, from}`                        | resolving one declared field against a note, in the declared source order                                                    |
+| `systemDataPaths`           | `systemDataPaths(data, prefix)`                     | `string[]`                             | listing every path a note authors under `<system>.system`, containers included                                               |
+| `undeclaredPaths`           | `undeclaredPaths(data, declared, prefix)`           | `string[]`                             | finding authored paths a system's published schema does not declare                                                          |
+| `unknownBlockKeys`          | `unknownBlockKeys(fm, block, ...)`                  | `string[]`                             | finding keys directly under a system block that neither this format nor the system recognizes                                |
+| `claimedPaths`              | `claimedPaths(fields)`                              | `Set<string>`                          | listing the exact `system` paths a field declaration writes, for `mergeSystemData`                                           |
+| `mergeSystemData`           | `mergeSystemData(built, fm, ...)`                   | `object` — `built`, for chaining       | merging a note's `<system>.system` verbatim onto a built `system` block                                                      |
 
 ### `engine.codeFences`
 
@@ -245,18 +239,17 @@ Which note types a configuration compiles at all, and the two findings that foll
 
 Folders, authored as notes rather than bespoke `*-folders.yaml` configuration, so a folder's parent is an address the link resolver already understands, its id is derived like any other document's, and an unclaimed folder is a finding like any other unclaimed note.
 
-| Export                   | Signature                                             | Returns                                         | Use it when                                                                           |
-| ------------------------ | ----------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `FOLDER_TYPE`            | `const FOLDER_TYPE`                                   | —                                               | naming the note type a folder is authored as                                          |
-| `FOLDER_ID_NAMESPACE`    | `const FOLDER_ID_NAMESPACE`                           | —                                               | naming the id namespace a derived folder id is hashed under                           |
-| `DEFAULT_PARENT`         | `const DEFAULT_PARENT`                                | —                                               | naming the key a per-pack `parent` map uses for "everywhere else"                     |
-| `bareAddress`            | `bareAddress(value)`                                  | `string \| null`                                | stripping wikilink brackets and a label off an authored `parent` value                |
-| `folderAddress`          | `folderAddress(pkg, shortcode)`                       | `string` — `<pkg>-none-folder-<shortcode>`      | composing the canonical address of a folder note                                      |
-| `folderDocId`            | `folderDocId(pkg, shortcode)`                         | `string` — the folder's 16-character Foundry id | deriving the Foundry `_id` a folder note's documents file under                       |
-| `collectFolderNotes`     | `collectFolderNotes(notes, pkg)`                      | `FolderNote[]`                                  | collecting every folder note in a content tree, in walk order                         |
-| `buildFolderNoteIndex`   | `buildFolderNoteIndex(folders)`                       | `{byKey, folders, resolve, ancestorsOf, ...}`   | indexing folder notes by every form an author may address one by, checking invariants |
-| `folderDocument`         | `folderDocument(folder, parent, documentType, stats)` | `object` — the Folder document                  | compiling the Foundry `Folder` document one folder note produces for one pack         |
-| `assertNoDeclaredFolder` | `assertNoDeclaredFolder(fm, ...)`                     | throws                                          | refusing a note that declares the retired `folder:` spelling                          |
+| Export                 | Signature                                             | Returns                                         | Use it when                                                                           |
+| ---------------------- | ----------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `FOLDER_TYPE`          | `const FOLDER_TYPE`                                   | —                                               | naming the note type a folder is authored as                                          |
+| `FOLDER_ID_NAMESPACE`  | `const FOLDER_ID_NAMESPACE`                           | —                                               | naming the id namespace a derived folder id is hashed under                           |
+| `DEFAULT_PARENT`       | `const DEFAULT_PARENT`                                | —                                               | naming the key a per-pack `parent` map uses for "everywhere else"                     |
+| `bareAddress`          | `bareAddress(value)`                                  | `string \| null`                                | stripping wikilink brackets and a label off an authored `parent` value                |
+| `folderAddress`        | `folderAddress(pkg, shortcode)`                       | `string` — `<pkg>-none-folder-<shortcode>`      | composing the canonical address of a folder note                                      |
+| `folderDocId`          | `folderDocId(pkg, shortcode)`                         | `string` — the folder's 16-character Foundry id | deriving the Foundry `_id` a folder note's documents file under                       |
+| `collectFolderNotes`   | `collectFolderNotes(notes, pkg)`                      | `FolderNote[]`                                  | collecting every folder note in a content tree, in walk order                         |
+| `buildFolderNoteIndex` | `buildFolderNoteIndex(folders)`                       | `{byKey, folders, resolve, ancestorsOf, ...}`   | indexing folder notes by every form an author may address one by, checking invariants |
+| `folderDocument`       | `folderDocument(folder, parent, documentType, stats)` | `object` — the Folder document                  | compiling the Foundry `Folder` document one folder note produces for one pack         |
 
 ### `engine.contentPackage`
 
@@ -276,32 +269,9 @@ Which content package a note belongs to: the repository's configured `contentPac
 | `searchableFrontmatter`   | `searchableFrontmatter(fm, configured)` | frontmatter with the derived package present | making a note's package visible to a generated table search, though no note declares one |
 | `assertNoDeclaredPackage` | `assertNoDeclaredPackage(fm, ...)`      | throws                                       | refusing a note that declares `package:` at all, present or empty                        |
 
-### `engine.retiredFields`
-
-Frontmatter fields a note may no longer declare — `draft:`, a top-level `aliases:`, `section:`, a top-level `traits:` block, and any field with a renamed spelling or in-block position — each refused by presence alone, naming the file and line and saying what to write instead.
-
-| Export                        | Signature                                        | Returns                  | Use it when                                                                                        |
-| ----------------------------- | ------------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------- |
-| `draftRetiredMessage`         | `draftRetiredMessage(file)`                      | `string`                 | building the one message shared by the compile-time refusal and the frontmatter lint for `draft:`  |
-| `assertNoDraftField`          | `assertNoDraftField(fm, ...)`                    | throws                   | refusing a note that declares `draft:` at all                                                      |
-| `aliasesRetiredMessage`       | `aliasesRetiredMessage(file)`                    | `string`                 | building the shared message for a top-level `aliases:`                                             |
-| `assertNoAliasesField`        | `assertNoAliasesField(fm, ...)`                  | throws                   | refusing a note that declares a top-level `aliases:`                                               |
-| `declaresRetiredAliasesField` | `declaresRetiredAliasesField(fm)`                | `boolean`                | checking whether a note declares the retired top-level `aliases:`, distinct from `name.aliases`    |
-| `sectionRetiredMessage`       | `sectionRetiredMessage(file)`                    | `string`                 | building the shared message for `section:`                                                         |
-| `assertNoSectionField`        | `assertNoSectionField(fm, ...)`                  | throws                   | refusing a note that declares `section:` at all                                                    |
-| `traitsRetiredMessage`        | `traitsRetiredMessage(file)`                     | `string`                 | building the shared message for a top-level `traits:` block, stating where each key moved          |
-| `assertNoTraitsField`         | `assertNoTraitsField(fm, ...)`                   | throws                   | refusing a note that declares a top-level `traits:` block at all                                   |
-| `locateFrontmatterKey`        | `locateFrontmatterKey(absPath, key, value, ...)` | `{line?, column?}`       | finding a frontmatter key's position in a note's file, by reading it                               |
-| `RETIRED_FIELD_ALIASES`       | `const RETIRED_FIELD_ALIASES`                    | —                        | looking up the current field name a retired spelling was renamed to                                |
-| `retiredAliasMessage`         | `retiredAliasMessage(retired, current, file)`    | `string`                 | building the shared message for a note writing a renamed field                                     |
-| `legacyKeyMessage`            | `legacyKeyMessage(block, field, file)`           | `string`                 | building the message for a field written at its legacy in-block position                           |
-| `retiredTopLevelMessage`      | `retiredTopLevelMessage(field, file)`            | `string`                 | building the message for a field written at the top-level key `data:` gathered it off              |
-| `declaresRetiredAlias`        | `declaresRetiredAlias(fm, current)`              | `boolean`                | checking whether a note writes the retired spelling of a field, in either region `sohlField` reads |
-| `readAliasedField`            | `readAliasedField(fm, current)`                  | the value or `undefined` | reading a field that has a retired spelling, the current name winning                              |
-
 ### `engine.runtimeOnlyFields`
 
-Schema fields a note may never author, because the document writes them during play rather than at compile time — a permanent part of a type's schema that is simply not content, distinct from a retired field, which a note may not author either but for a different reason.
+Schema fields a note may never author, because the document writes them during play rather than at compile time — a permanent part of a type's schema that is simply not content.
 
 | Export                      | Signature                                    | Returns       | Use it when                                                                                  |
 | --------------------------- | -------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------- |
@@ -429,15 +399,15 @@ The infobox declarations this toolchain ships, one per system, and the single ca
 
 Drawing a declared infobox: HTML for separate Foundry pages appended after authored pages, Typst panels after each note’s authored body in the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
 
-| Export                 | Signature                                   | Returns   | Use it when                                                              |
-| ---------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------ |
-| `infoboxTypstPreamble` | `infoboxTypstPreamble()`                    | `string`  | emitting the panel definitions the book's bodies call, once per document |
-| `infoboxesToHtml`      | `infoboxesToHtml(boxes, options)`           | `string`  | drawing the boxes as `<details>` disclosures, open by default            |
-| `infoboxesToTypst`     | `infoboxesToTypst(boxes, options)`          | `string`  | drawing the boxes as panels that break between their sections            |
-| `linkToHtml`           | `linkToHtml(value)`                         | `string`  | drawing a link value as an anchor on its URL                             |
-| `linkToTypst`          | `linkToTypst(value, links, labelFor, site)` | `string`  | drawing a link value as a cross-reference into the book                  |
-| `linkToUuid`           | `linkToUuid(value)`                         | `string`  | drawing a link value as a Foundry document reference                     |
-| `sectionHasContent`    | `sectionHasContent(section)`                | `boolean` | deciding whether a section holds anything worth drawing                  |
+| Export                 | Signature                                              | Returns   | Use it when                                                                                                |
+| ---------------------- | ------------------------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------- |
+| `infoboxTypstPreamble` | `infoboxTypstPreamble()`                               | `string`  | emitting the panel definitions the book's bodies call, once per document                                   |
+| `infoboxesToHtml`      | `infoboxesToHtml(boxes, options)`                      | `string`  | drawing the boxes as `<details>` disclosures, open by default                                              |
+| `infoboxesToTypst`     | `infoboxesToTypst(boxes, options)`                     | `string`  | drawing the boxes as panels that break between their sections                                              |
+| `linkToHtml`           | `linkToHtml(value)`                                    | `string`  | drawing a link value as an anchor on its URL                                                               |
+| `linkToTypst`          | `linkToTypst(value, links, labelFor, site, elsewhere)` | `string`  | drawing a link value as a cross-reference into the book, or as a book and page when another book prints it |
+| `linkToUuid`           | `linkToUuid(value)`                                    | `string`  | drawing a link value as a Foundry document reference                                                       |
+| `sectionHasContent`    | `sectionHasContent(section)`                           | `boolean` | deciding whether a section holds anything worth drawing                                                    |
 
 ### `engine.noteState`
 
@@ -695,13 +665,25 @@ The exact-day conversion functions use the corpus reckoning context. `dateFromCa
 
 ### `engine.cultureChoice`
 
-`checkCultureChoice(note, { index })` checks that a being's `data.culture`
-Address resolves to a lore note with `subType: culture`. The being vocabulary
-invokes the check during frontmatter lint.
-
-| Export               | Signature                           | Returns  | Use it when                               |
-| -------------------- | ----------------------------------- | -------- | ----------------------------------------- |
-| `checkCultureChoice` | `checkCultureChoice(note, options)` | findings | validating a being's primary culture note |
+`data.culture` names the people a note belongs to, as a lore note with
+`subType: culture`. `CULTURE_FIELD` is its one declaration, spread into the
+`being`, `place`, `affiliation`, `lore` and `doc` vocabularies.
+`checkCultureChoice(note, { index })` checks that the Address resolves to a
+culture note. `checkCultureSubType(note, { index })` scopes the field by
+subtype: a `doc` of `subType: settingguide` must state it, any other `doc`
+subtype must not, and a `lore` note of `subType: culture` may state only its own
+Address, compared in canonical form. The vocabulary invokes both during
+frontmatter lint, which reads each note from its index record, so both see the
+resolved value: the culture a place or affiliation inherits through
+`data.parents`, written into the record by `resolveCultures`, documented under
+`engine.contentIndex`.
+
+| Export                | Signature                              | Returns   | Use it when                                                                                 |
+| --------------------- | -------------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `CULTURE_FIELD`       | frozen field declaration               | object    | declaring `data.culture` on a type                                                          |
+| `checkCultureChoice`  | `checkCultureChoice(note, options)`    | findings  | validating that a note's culture names a culture note                                       |
+| `checkCultureSubType` | `checkCultureSubType(note, options)`   | findings  | requiring or refusing `data.culture` by the note's subtype                                  |
+| `cultureNamesItself`  | `cultureNamesItself(fm, value, index)` | `boolean` | asking whether a `data.culture` value is the note's own Address, compared in canonical form |
 
 ### `engine.markdownExpressions`
 
@@ -830,22 +812,22 @@ The id a note's document is filed under: its pinned `id:`, when a note authors o
 
 The published content index — the artifact packages exchange addresses through. **A package publishes its own index; a consumer fetches the ones it depends on.** That is the whole mechanism, and it replaces a vendored link manifest that each repository committed a copy of every other repository's file into. Vendoring failed three ways, and only the last is about staleness:
 
-| Export                         | Signature                                                  | Returns                                                                                                                                                                                  | Use it when                                                                                                                 |
-| ------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                        | The relationship kinds that are dependencies, and therefore citable.                                                        |
-| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                             | What a package's content index is called, wherever it is written or fetched.                                                |
-| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                               | Every dependency whose published index this build resolves addresses through.                                               |
-| `noContentIndexPackages`       | `function noContentIndexPackages(config)`                  | {ReadonlySet<string>} The content package names.                                                                                                                                         | Every package a relationship declares `contentIndex: false` on, keyed by the content package name a link into it would use. |
-| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                  | The cache directory for one dependency's index at one version.                                                              |
-| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                        | Whether a dependency's cache is present and complete.                                                                       |
-| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                   | Mark a dependency's cache complete.                                                                                         |
-| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                       | The fetched index files this build resolves foreign addresses against.                                                      |
-| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                   | The same fetched indexes, each paired with the package that published it.                                                   |
-| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                                 | The newest cached version among several version-keyed cache directories.                                                    |
-| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | `{{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}}` The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.                                                |
-| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                                 | Where a dependency's fetched index sits, for naming it in a diagnostic.                                                     |
-| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                                 | Whether a fetched index can still be _addressed_, as distinct from read.                                                    |
-| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                               | One finding, in the standard `file:line:column: severity: message` form.                                                    |
+| Export                         | Signature                                                  | Returns                                                                                                                                                                                  | Use it when                                                                                                                                        |
+| ------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                        | The relationship kinds that are dependencies, and therefore citable; a relationship of another kind declaring `itemCatalog: true` is read as well. |
+| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                             | What a package's content index is called, wherever it is written or fetched.                                                                       |
+| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                               | Every dependency whose published index this build resolves addresses through.                                                                      |
+| `noContentIndexPackages`       | `function noContentIndexPackages(config)`                  | {ReadonlySet<string>} The content package names.                                                                                                                                         | Every package a relationship declares `contentIndex: false` on, keyed by the content package name a link into it would use.                        |
+| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                  | The cache directory for one dependency's index at one version.                                                                                     |
+| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                        | Whether a dependency's cache is present and complete.                                                                                              |
+| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                   | Mark a dependency's cache complete.                                                                                                                |
+| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                       | The fetched index files this build resolves foreign addresses against.                                                                             |
+| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                   | The same fetched indexes, each paired with the package that published it.                                                                          |
+| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                                 | The newest cached version among several version-keyed cache directories.                                                                           |
+| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | `{{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}}` The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.                                                                       |
+| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                                 | Where a dependency's fetched index sits, for naming it in a diagnostic.                                                                            |
+| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                                 | Whether a fetched index can still be _addressed_, as distinct from read.                                                                           |
+| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                               | One finding, in the standard `file:line:column: severity: message` form.                                                                           |
 
 ### `engine.foundryEntries`
 
@@ -864,31 +846,32 @@ Emitting this package's cross-package link manifest. `engine/content-address.mjs
 
 Emitting this package's content index. Every content build already walks the whole note tree and parses every note's frontmatter — the pack compilers, the site build, and the content-table expander each do it — and every one of them throws the result away when it finishes. So nothing outside a build can ask a question about the content: "which beings carry no `kbcat`?", "what does this table actually select?", "did that type rename leave anything behind?" have no answer short of writing a throwaway script that re-walks the tree. Eight dead Bestiary tables shipped for weeks behind exactly that gap.
 
-| Export                  | Signature                                                                                                          | Returns                                                                                                                                                                                                                                                                       | Use it when                                                                                                                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                                | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well.                                                      | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                |
-| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                                     | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                                                                           | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                 |
-| `asciiName`             | `function asciiName(name)`                                                                                         | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                                                                                | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                   |
-| `asciiAliases`          | `function asciiAliases(aliases)`                                                                                   | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                                                                         | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                       |
-| `serializeContentIndex` | `function serializeContentIndex(records)`                                                                          | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                                                                                | Serialize records as JSON Lines.                                                                                                                                                                                          |
-| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                                              | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                                                                             | The index records for a content tree, without writing anything.                                                                                                                                                           |
-| `indexRecordsForNote`   | `indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext })` | `object[]`                                                                                                                                                                                                                                                                    | Derive the note's own record and its documentation record from parsed text.                                                                                                                                               |
-| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                                                | `{{file: string, notes: number, assets: number, records: number, bytes: number, full: number, draft: number, stub: number}}` Where it was written, how many notes and how many assets it holds, how many records that is in all, its size, and the ladder those notes sit on. | Emit this package's content index.                                                                                                                                                                                        |
-| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })`                    | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                                                                           | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                      |
-| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems })`            | `Array<Record<string, any>>`                                                                                                                                                                                                                                                  | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file |
+| Export                  | Signature                                                                                                              | Returns                                                                                                                                                                                                                                                                       | Use it when                                                                                                                                                                                                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `noteAddress`           | `function noteAddress(frontmatter, contentPackage)`                                                                    | {{slug: string, canonical: string}\|null} `slug` is what goes inside `[[…]]` within this package; `canonical` is the fully qualified key the manifest files the note under, carrying the package and the system as well.                                                      | The address a wikilink writes to reach a note, or `null` when it has none.                                                                                                                                                                                                          |
+| `sortKeysDeep`          | `function sortKeysDeep(value)`                                                                                         | {unknown} The value with every plain object's keys in sorted order.                                                                                                                                                                                                           | Recursively sort an object's keys, so serialization is order-independent.                                                                                                                                                                                                           |
+| `asciiName`             | `function asciiName(name)`                                                                                             | {string\|null} The ASCII form, or `null` when there is no name, or nothing printable survives.                                                                                                                                                                                | A note's display name reduced to printable 7-bit ASCII.                                                                                                                                                                                                                             |
+| `asciiAliases`          | `function asciiAliases(aliases)`                                                                                       | {Array<string>} Possibly empty, never null: a note with no aliases has an empty set of them, which is a fact rather than a missing value, and a consumer iterating it should not have to check first.                                                                         | A note's `name.aliases` reduced to printable 7-bit ASCII, in order.                                                                                                                                                                                                                 |
+| `serializeContentIndex` | `function serializeContentIndex(records)`                                                                              | {string} One compact JSON object per line, newline-terminated.                                                                                                                                                                                                                | Serialize records as JSON Lines.                                                                                                                                                                                                                                                    |
+| `indexRecordsFor`       | `indexRecordsFor({ contentBase, config, skipDirectories, problems })`                                                  | {object[]} One record per note, plus one per documentation entry.                                                                                                                                                                                                             | The index records for a content tree, without writing anything.                                                                                                                                                                                                                     |
+| `indexRecordsForNote`   | `indexRecordsForNote({ frontmatter, body, bodyLine, relPath, absPath, contentPackage, manifest, addressContext })`     | `object[]`                                                                                                                                                                                                                                                                    | Derive the note's own record and its documentation record from parsed text.                                                                                                                                                                                                         |
+| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config })`                                                                    | `{{file: string, notes: number, assets: number, records: number, bytes: number, full: number, draft: number, stub: number}}` Where it was written, how many notes and how many assets it holds, how many records that is in all, its size, and the ladder those notes sit on. | Emit this package's content index.                                                                                                                                                                                                                                                  |
+| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, contentPackage, body, bodyLine, manifest })`                        | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                                                                           | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                                                                                |
+| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems, foreignRecord })` | `Array<Record<string, any>>`                                                                                                                                                                                                                                                  | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file; each note carries its resolved culture as `data.culture` |
+| `resolveCultures`       | `resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems })`                                   | `Array<Record<string, any>>` — the same records                                                                                                                                                                                                                               | writing each note's resolved culture into its record as `data.culture`: its own value, else its parents', else for a polity its seat's and governed places', pooled; parents that disagree give a finding into `problems`, or one thrown Error listing every conflict               |
 
 `engine.contentIndex` also re-exports eight names from neighbouring leaf modules, at this same import path:
 
-| Export                | Signature                        | Returns                                                        | Use it when                                                                                                                                                                      |
-| --------------------- | -------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `collectAnchors`      | `collectAnchors(body, bodyLine)` | `Array<{slug: string, line: number, kind: string}>`            | reading a note body's anchors, each with its kind, shared with the link checker and every build that emits a link                                                                |
-| `DERIVED_KEYS`        | `const DERIVED_KEYS`             | —                                                              | reading which keys the content index adds to a record, and which a note therefore may not author itself                                                                          |
-| `noteFile`            | `noteFile(contentBase, record)`  | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                      |
-| `authoredFrontmatter` | `authoredFrontmatter(record)`    | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading back exactly what a note authored from its index record, so a pass can lint or compile from the index without reasoning about derived fields as if the author wrote them |
-| `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                              |
-| `isStub`              | `isStub(record)`                 | `boolean`                                                      | telling a stub — a note with an empty body — apart from a note that publishes a page; asked of the absent address, which is the whole signal                                     |
-| `isAssetRecord`       | `isAssetRecord(record)`          | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                  |
-| `recordPath`          | `recordPath(record)`             | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                              |
+| Export                | Signature                        | Returns                                                        | Use it when                                                                                                                                                                                                  |
+| --------------------- | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `collectAnchors`      | `collectAnchors(body, bodyLine)` | `Array<{slug: string, line: number, kind: string}>`            | reading a note body's anchors, each with its kind, shared with the link checker and every build that emits a link                                                                                            |
+| `DERIVED_KEYS`        | `const DERIVED_KEYS`             | —                                                              | reading which keys the content index adds to a record, and which a note therefore may not author itself                                                                                                      |
+| `noteFile`            | `noteFile(contentBase, record)`  | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                                                  |
+| `authoredFrontmatter` | `authoredFrontmatter(record)`    | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading a note's frontmatter back from its index record, its resolved `data.culture` included, so a pass can lint or compile from the index without reasoning about derived keys as if the author wrote them |
+| `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                                                          |
+| `isStub`              | `isStub(record)`                 | `boolean`                                                      | telling a stub — a note with an empty body — apart from a note that publishes a page; asked of the absent address, which is the whole signal                                                                 |
+| `isAssetRecord`       | `isAssetRecord(record)`          | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                                              |
+| `recordPath`          | `recordPath(record)`             | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                                                          |
 
 ### `engine.assetTypes`
 
@@ -1160,9 +1143,9 @@ Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLa
 | `assertSuppliedCorpus`    | `function assertSuppliedCorpus(records, who)`                                                               | {void}                                                                                                                                                                                                                                    | Refuse a corpus read whose records its caller did not supply.                                                                                                                                        |
 | `statedTemplatePriority`  | `function statedTemplatePriority(fm, label,`                                                                | {number\|null} The priority, or `null` when the note is not a template or states nothing.                                                                                                                                                 | The template priority a note states, for a system that treats an unstated one as "not a template" rather than as an authoring error.                                                                 |
 | `resolveTemplatePriority` | `function resolveTemplatePriority(fm, label,`                                                               | {number\|undefined} The template priority, or `undefined` when null.                                                                                                                                                                      | Resolve the required `templatePriority` frontmatter for an Item/Actor entry (the archetype contract).                                                                                                |
-| `systemTemplatePriority`  | `function systemTemplatePriority(fm, label)`                                                                | {number\|null} The template priority, or `null` for a document that is not a template.                                                                                                                                                    | The value a document's `system.templatePriority` carries, from the required `templatePriority` frontmatter (`archetype` is the legacy spelling).                                                     |
+| `systemTemplatePriority`  | `function systemTemplatePriority(fm, label)`                                                                | {number\|null} The template priority, or `null` for a document that is not a template.                                                                                                                                                    | The value a document's `system.templatePriority` carries, from the required `templatePriority` frontmatter.                                                                                          |
 | `makeFilename`            | `function makeFilename(name, id)`                                                                           | —                                                                                                                                                                                                                                         | Generates a compendium-source filename: `Name_id.json` with non- alphanumeric runs replaced by underscores.                                                                                          |
-| `resolveImg`              | `function resolveImg(raw, config`                                                                           | {string \| null} the Foundry-relative path; `""` for a deliberate blank, and `null` when the note names no art at all.                                                                                                                    | Translate a content-relative image path into its Foundry-relative form.                                                                                                                              |
+| `resolveImg`              | `function resolveImg(raw, config`                                                                           | {string \| null} the Foundry-relative path, and `null` when the note names no art at all.                                                                                                                                                 | Translate a content-relative image path into its Foundry-relative form.                                                                                                                              |
 | `resolveName`             | `function resolveName(fm, defaultValue`                                                                     | —                                                                                                                                                                                                                                         | Resolves the display name from frontmatter, preferring `name.full`, falling back to `name` (if string), then `defaultValue`.                                                                         |
 | `supportedCoreVersion`    | `function supportedCoreVersion(config`                                                                      | {string} The declared `compatibility.minimum`.                                                                                                                                                                                            | The oldest Foundry core this package supports, stamped into every compiled document as `_stats.coreVersion`.                                                                                         |
 | `buildStats`              | `function buildStats(systemVersion`                                                                         | {object} The `_stats` block.                                                                                                                                                                                                              | Default `_stats` block for compiled compendium entries.                                                                                                                                              |
@@ -1273,20 +1256,21 @@ The document tree a PDF is built from, and the plan it resolves to. The packs an
 
 A note's markdown, and a document plan, rendered as Typst source. **This module emits text and reads nothing.** It takes markdown and a plan and returns a `.typ` document; the filesystem, the note bodies and the compiler that turns the result into a PDF all live in {@link module:engine/pdf-build}. That split is what lets the outline, the table of contents, every anchor and every link destination be asserted in a unit test with no renderer installed — which is most of what a book has to get right, and all of what a test can check without eyes.
 
-| Export                  | Signature                                                                                 | Returns                                                      | Use it when                                                              |
-| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| `escapeTypst`           | `function escapeTypst(text)`                                                              | {string} The same text, inert.                               | Escape literal text for Typst markup.                                    |
-| `escapeTypstString`     | `function escapeTypstString(text)`                                                        | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does. |
-| `labelFor`              | `function labelFor(anchor)`                                                               | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                       |
-| `createParser`          | `function createParser(registry)`                                                         | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                        |
-| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                                                 | {string} Typst markup.                                       | Render markdown as Typst content.                                        |
-| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                   |
-| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                                         | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.     |
-| `iconNamesIn`           | `function iconNamesIn(markdown)`                                                          | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
-| `BOOK_IMAGE_WIDTHS`     | `const BOOK_IMAGE_WIDTHS`                                                                 | —                                                            | The book measure requested by each named image size.                     |
-| `bookTypstPreamble`     | `function bookTypstPreamble()`                                                            | {string} Typst markup.                                       | The Typst definitions the book's page furniture is drawn with.           |
-| `stripHtmlComments`     | `function stripHtmlComments(markdown)`                                                    | {string} The same body, its comments replaced by newlines.   | A markdown body with its HTML comments taken out.                        |
-| `absolutePageUrl`       | `function absolutePageUrl(url, site)`                                                     | {string} An absolute URL a reader of the book can follow.    | A page address as a reader of the book can follow it.                    |
+| Export                  | Signature                                                                                 | Returns                                                      | Use it when                                                                              |
+| ----------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `escapeTypst`           | `function escapeTypst(text)`                                                              | {string} The same text, inert.                               | Escape literal text for Typst markup.                                                    |
+| `escapeTypstString`     | `function escapeTypstString(text)`                                                        | {string} The same value, quotable.                           | Escape a string going inside Typst string quotes, as a `#link` URL does.                 |
+| `labelFor`              | `function labelFor(anchor)`                                                               | {string} A Typst label name.                                 | A Typst label, from a plan anchor.                                                       |
+| `createParser`          | `function createParser(registry)`                                                         | {object} A markdown-it instance.                             | A markdown-it configured to parse, not to render.                                        |
+| `markdownToTypst`       | `function markdownToTypst(markdown, opts`                                                 | {string} Typst markup.                                       | Render markdown as Typst content.                                                        |
+| `renderBook`            | `renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners })` | {string} A complete `.typ` document.                         | The whole book, as one Typst document.                                                   |
+| `resolveDanglingLabels` | `function resolveDanglingLabels(source, findings`                                         | {string} The same document, with no reference left dangling. | Point every internal link at a label the document actually declares.                     |
+| `iconNamesIn`           | `function iconNamesIn(markdown)`                                                          | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.                           |
+| `BOOK_IMAGE_WIDTHS`     | `const BOOK_IMAGE_WIDTHS`                                                                 | —                                                            | The book measure requested by each named image size.                                     |
+| `bookTypstPreamble`     | `function bookTypstPreamble()`                                                            | {string} Typst markup.                                       | The Typst definitions the book's page furniture is drawn with.                           |
+| `stripHtmlComments`     | `function stripHtmlComments(markdown)`                                                    | {string} The same body, its comments replaced by newlines.   | A markdown body with its HTML comments taken out.                                        |
+| `absolutePageUrl`       | `function absolutePageUrl(url, site)`                                                     | {string} An absolute URL a reader of the book can follow.    | A page address as a reader of the book can follow it.                                    |
+| `crossBookReference`    | `function crossBookReference(inner, away)`                                                | {string} Typst markup.                                       | A reference to a note another book prints: the link's words, then the book and the page. |
 
 ### `engine.pdfFonts`
 
@@ -1302,16 +1286,18 @@ Which glyph an icon name resolves to, read from the font that carries it. {@link
 
 The content tree, built into a book. The I/O half of the PDF surface: it reads the configuration, the document tree and the notes, drives the passes the site build already owns, hands the result to {@link module:engine/pdf-render} and runs Typst over what comes back. Everything about _what the book says_ is decided in the pure half; this module is where the filesystem and the compiler live.
 
-| Export            | Signature                                                  | Returns                                                                                         | Use it when                                                          |
-| ----------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `pdfFileName`     | `function pdfFileName(artifact, version)`                  | {string} `<artifact>-<version>.pdf`, or `<artifact>.pdf` unversioned.                           | The file name a downloaded book identifies itself by.                |
-| `buildPdf`        | `async buildPdf({ config, out, version, compile })`        | {Promise<object>} `{ built, reason, findings, typ, pdf, stats }`.                               | Build the book.                                                      |
-| `stagedImagePath` | `function stagedImagePath(src, config)`                    | {{from: string, to: string}\|null} The file, and where under the output directory it is staged. | The file on disk an authored image address names, or `null`.         |
-| `stageBanners`    | `function stageBanners(entries, config, outDir, findings)` | {Map<string, string>} Declared path → the staged file's path, relative to the `.typ`.           | Copy every banner the document tree names into the output directory. |
-| `compileTypst`    | `function compileTypst(typPath, pdfPath, pdf`              | `{{ok: boolean, message: string, findings: object[]}}` What happened.                           | Run Typst over the emitted source.                                   |
-| `typstArgs`       | `function typstArgs(typPath, pdfPath, pdf)`                | {string[]} The arguments, in order.                                                             | The command line the compile runs, as data.                          |
-| `typstWarnings`   | `function typstWarnings(output)`                           | {object[]} One finding per warning the compiler wrote.                                          | The compiler's own warnings, as findings.                            |
-| `BOOK_FONTS_PATH` | `const BOOK_FONTS_PATH`                                    | {string} The directory holding them.                                                            | The faces the book is set in, shipped with this package.             |
+| Export            | Signature                                                                        | Returns                                                                                                                  | Use it when                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| `pdfFileName`     | `function pdfFileName(stem, version)`                                            | {string} `<stem>-<version>.pdf`, or `<stem>.pdf` unversioned.                                                            | The file name a downloaded book identifies itself by.                                            |
+| `buildPdf`        | `async buildPdf({ config, configPath, book, out, version, compile, readPages })` | {Promise<object>} `{ built, reason, findings, imageReports, books }`, each book `{ id, title, built, typ, pdf, stats }`. | Build every declared book, or the one `book` names.                                              |
+| `listBookAssets`  | `function listBookAssets({ config, version, out })`                              | {Array<{id: string, title: string, file: string}>} One entry per book.                                                   | The path each declared book is written to, without building.                                     |
+| `stagedImagePath` | `function stagedImagePath(src, config)`                                          | {{from: string, to: string}\|null} The file, and where under the output directory it is staged.                          | The file on disk an authored image address names, or `null`.                                     |
+| `stageBanners`    | `function stageBanners(entries, config, outDir, findings, treeFile)`             | {Map<string, string>} Declared path → the staged file's path, relative to the `.typ`.                                    | Copy every banner the document tree names into the output directory.                             |
+| `compileTypst`    | `function compileTypst(typPath, pdfPath, pdf`                                    | `{{ok: boolean, message: string, findings: object[]}}` What happened.                                                    | Run Typst over the emitted source.                                                               |
+| `typstArgs`       | `function typstArgs(typPath, pdfPath, pdf)`                                      | {string[]} The arguments, in order.                                                                                      | The command line the compile runs, as data.                                                      |
+| `typstFontArgs`   | `function typstFontArgs(pdf)`                                                    | {string[]} The arguments, in order.                                                                                      | The flags that decide which faces a layout uses, shared by the compile and the page measurement. |
+| `typstWarnings`   | `function typstWarnings(output)`                                                 | {object[]} One finding per warning the compiler wrote.                                                                   | The compiler's own warnings, as findings.                                                        |
+| `BOOK_FONTS_PATH` | `const BOOK_FONTS_PATH`                                                          | {string} The directory holding them.                                                                                     | The faces the book is set in, shipped with this package.                                         |
 
 ### `engine.baseCompiler`
 
@@ -1354,7 +1340,7 @@ Macros pack compiler — produces JSON pack files for the "macros" Foundry compe
 
 ### `engine.exportedScene`
 
-An exported Foundry Scene's compile. A map note carries its Scene as exported from Foundry at `data.scene`; this passes it through, applying `data.fixup`, keying each embedded document that carries an `_id`, and binding pins marked `#anchor` to the note's own journal pages. Nothing else inside the Scene is checked.
+An exported Foundry Scene's compile. A map note carries its Scene as exported from Foundry at `data.scene`; this passes it through, applying its fixups — `data.fixup`, and each map field that declares a Scene property, such as `data.thumbnail` — keying each embedded document that carries an `_id`, and binding pins marked `#anchor` to the note's own journal pages. Nothing else inside the Scene is checked.
 
 | Export               | Signature                                                                              | Returns                            | Use it when                                          |
 | -------------------- | -------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
@@ -1406,18 +1392,18 @@ Adventure pack compiler — `type: bundle` notes → Foundry `Adventure` documen
 
 Pack JSON generation — in-repo Markdown → per-entry JSON (build-only). Reads the authoritative content tree at the configured content root and compiles each pack's entries to per-entry JSON under its build directory (`build/packs-json/<pack>/` in this repository). The JSON is a disposable build intermediate consumed by `build:compiledb` (which turns it into the shipped LevelDB packs) — it is never committed.
 
-| Export                        | Signature                                               | Returns                                                                                                                                                                                                         | Use it when                                                                                                         |
-| ----------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `systemCompilers`             | `function systemCompilers(passes)`                      | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                                                               | The system-specific compilers, derived from the passes themselves.                                                  |
-| `compilerFor`                 | `function compilerFor(docType, system`                  | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past.                                            | The compiler class a pack of one document type and one system gets.                                                 |
-| `emittedArtFor`               | `function emittedArtFor(type)`                          | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made — a retired type, which is reported as retired instead. | The art fields a note of one content type reaches its document through, and the document it reaches.                |
-| `packJsonDir`                 | `const packJsonDir`                                     | {string} The pack's JSON directory.                                                                                                                                                                             | Root of the build-only JSON tree for one pack.                                                                      |
-| `itemPackJsonDirs`            | `function itemPackJsonDirs(config`                      | {string[]} Each Item pack's JSON directory.                                                                                                                                                                     | The generated JSON of **every** configured Item pack — what the actors pass reads its predefined items from.        |
-| `bundleSourceJsonDirs`        | `function bundleSourceJsonDirs(config`                  | {Record<string, string[]>} Each readable pack's JSON directory, by the Foundry document type it holds.                                                                                                          | The compiled JSON a bundle may hold copies of, by document type.                                                    |
-| `orderPassesByDependency`     | `function orderPassesByDependency(packs)`               | {object[]} A new list, in compile order.                                                                                                                                                                        | The passes to run, ordered so that each one follows the output it reads.                                            |
-| `unsatisfiedPassDependencies` | `function unsatisfiedPassDependencies(running, config)` | {string[]} One message per unsatisfiable dependency.                                                                                                                                                            | The dependencies this run cannot satisfy by ordering, because the pass that would produce them is not in it.        |
-| `emptyPassErrors`             | `function emptyPassErrors(passes)`                      | {string[]} One message per pass that must not have been empty.                                                                                                                                                  | The passes that compiled nothing when they were expected to compile something — a build failure, not a quiet no-op. |
-| `generatePacksJson`           | `async generatePacksJson({ only, config })`             | {Promise<number>} Total error count across the generated packs.                                                                                                                                                 | Generate the build-only JSON for every pack (or one, when `only` is given).                                         |
+| Export                        | Signature                                               | Returns                                                                                                                                                              | Use it when                                                                                                         |
+| ----------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `systemCompilers`             | `function systemCompilers(passes)`                      | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                    | The system-specific compilers, derived from the passes themselves.                                                  |
+| `compilerFor`                 | `function compilerFor(docType, system`                  | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past. | The compiler class a pack of one document type and one system gets.                                                 |
+| `emittedArtFor`               | `function emittedArtFor(type)`                          | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made.             | The art fields a note of one content type reaches its document through, and the document it reaches.                |
+| `packJsonDir`                 | `const packJsonDir`                                     | {string} The pack's JSON directory.                                                                                                                                  | Root of the build-only JSON tree for one pack.                                                                      |
+| `itemPackJsonDirs`            | `function itemPackJsonDirs(config`                      | {string[]} Each Item pack's JSON directory.                                                                                                                          | The generated JSON of **every** configured Item pack — what the actors pass reads its predefined items from.        |
+| `bundleSourceJsonDirs`        | `function bundleSourceJsonDirs(config`                  | {Record<string, string[]>} Each readable pack's JSON directory, by the Foundry document type it holds.                                                               | The compiled JSON a bundle may hold copies of, by document type.                                                    |
+| `orderPassesByDependency`     | `function orderPassesByDependency(packs)`               | {object[]} A new list, in compile order.                                                                                                                             | The passes to run, ordered so that each one follows the output it reads.                                            |
+| `unsatisfiedPassDependencies` | `function unsatisfiedPassDependencies(running, config)` | {string[]} One message per unsatisfiable dependency.                                                                                                                 | The dependencies this run cannot satisfy by ordering, because the pass that would produce them is not in it.        |
+| `emptyPassErrors`             | `function emptyPassErrors(passes)`                      | {string[]} One message per pass that must not have been empty.                                                                                                       | The passes that compiled nothing when they were expected to compile something — a build failure, not a quiet no-op. |
+| `generatePacksJson`           | `async generatePacksJson({ only, config })`             | {Promise<number>} Total error count across the generated packs.                                                                                                      | Generate the build-only JSON for every pack (or one, when `only` is given).                                         |
 
 ### `engine.compendiums`
 
@@ -1535,7 +1521,7 @@ Every module beneath `./hm3` is also reachable as its own entry point, e.g. `@he
 import { hm3DefaultItemArt, documentSubtypes } from "@heroiclands/package-build/hm3";
 
 console.log(hm3DefaultItemArt("weapongear"));
-// -> "systems/hm3/images/icons/svg/sword.svg"
+// -> "hm3/assets/icons/sword.svg"
 console.log(documentSubtypes.HM3_TYPE_KEY);
 // -> "type"
 ```
@@ -1631,12 +1617,12 @@ const config = defineConfig({
 | `defineConfig`             | `defineConfig(config)`             | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
 | `PACKAGE_KINDS`            | `const PACKAGE_KINDS`              | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
 | `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`         | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
+| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`               | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                      |
 | `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`          | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
 | `compilesFoundryDocuments` | `compilesFoundryDocuments(config)` | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
 | `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`        | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
 | `DEFAULT_PATHS`            | `const DEFAULT_PATHS`              | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
 | `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`     | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
-| `RETIRED_ADDRESS_KEYS`     | `const RETIRED_ADDRESS_KEYS`       | —                                                          | reading which address-scheme keys a configuration may no longer declare (e.g. `landing`) — declaring one is a refusal, not a silent no-op                                                                                                |
 | `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
 | `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
 | `DERIVED_HUGO_KEYS`        | `const DERIVED_HUGO_KEYS`          | —                                                          | reading which Hugo keys `site.hugo` may not declare because the site build generates them, each naming its source (declaring one is an error naming the key); a dotted key covers everything beneath it                                  |
@@ -1676,7 +1662,7 @@ export { default } from "@heroiclands/package-build/prettier";
 
 ## `./markdownlint`
 
-The shared markdownlint rules, as a markdownlint-cli2 options module, applied without a consumer declaring anything by `package-build markdown`. Exists for an editor's markdownlint extension, and for a consumer that wants to extend rather than replace the set.
+The shared markdownlint rules, as a `.markdownlint-cli2.mjs` options module, applied without a consumer declaring anything by `package-build markdown`. Exists for an editor's markdownlint extension, and for a consumer that wants to extend rather than replace the set.
 
 ```js
 // .markdownlint-cli2.mjs
@@ -1684,9 +1670,9 @@ import shared from "@heroiclands/package-build/markdownlint";
 export default { ...shared, config: { ...shared.config, MD013: true } };
 ```
 
-| Export    | Signature                                                    | Returns                                     | Use it when                                                                                                                                                    |
-| --------- | ------------------------------------------------------------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `default` | `export default { config, globs, ignores, gitignore: true }` | The shared markdownlint-cli2 options object | spreading it into a consumer's own options module to extend rather than replace the shared rules; `config` is frozen, so it must be spread rather than mutated |
+| Export    | Signature                                                    | Returns                                | Use it when                                                                                                                                                    |
+| --------- | ------------------------------------------------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `default` | `export default { config, globs, ignores, gitignore: true }` | The shared markdownlint options object | spreading it into a consumer's own options module to extend rather than replace the shared rules; `config` is frozen, so it must be spread rather than mutated |
 
 ## `./bundle`
 
@@ -1719,31 +1705,36 @@ console.log(dataEnvVar("dev"));
 // -> "FOUNDRYVTT_DEV_DATA"
 ```
 
-| Export                     | Signature                                                                                     | Returns              | Use it when                                                                                                                                                                                 |
-| -------------------------- | --------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DEFAULT_STAGE_PORTS`      | `const DEFAULT_STAGE_PORTS`                                                                   | —                    | reading the host port each conventional stage (`dev`/`qa`/`prod`/`test`) publishes by default, chosen so all four can run at once                                                           |
-| `CONTAINER_PORT`           | `const CONTAINER_PORT`                                                                        | —                    | the fixed port Foundry listens on inside the container                                                                                                                                      |
-| `CACHE_MOUNT`              | `const CACHE_MOUNT`                                                                           | —                    | the path a host-provided download cache is mounted at inside the container                                                                                                                  |
-| `CONTAINER_ACTIONS`        | `const CONTAINER_ACTIONS`                                                                     | —                    | the closed set of actions `package-build container` accepts                                                                                                                                 |
-| `dataEnvVar`               | `dataEnvVar(stage)`                                                                           | `string`             | deriving the environment variable that names a stage's Foundry data root, without hand-tabulating one per stage                                                                             |
-| `containerName`            | `containerName(packageId, stage, base = null)`                                                | `string`             | computing the stable container name a stage runs under, so a signed Foundry licence (bound to the hostname) survives a recreate; pass `base` to share one container/licence across packages |
-| `resolveStagePort`         | `resolveStagePort(stage, { env, stages } = {})`                                               | `number`             | resolving the host port for a stage, honoring `FOUNDRYVTT_<STAGE>_PORT` over a declared or conventional default                                                                             |
-| `resolveFoundryVersion`    | `resolveFoundryVersion(stage, { env, stages, compatibilityMinimum, e2eStage = "test" } = {})` | `string\|null`       | pinning the exact Foundry build a stage runs, deriving the end-to-end stage's pin from the package's own `compatibility.minimum` so the floor is actually exercised                         |
-| `resolveImage`             | `resolveImage({ env, image, version, compatibilityMinimum } = {})`                            | `string`             | resolving the `felddy/foundryvtt` image reference a run uses                                                                                                                                |
-| `resolveWorld`             | `resolveWorld(stage, { env, stages } = {})`                                                   | `string\|null`       | resolving which world a stage auto-launches — `""` declares "never auto-launch", distinct from `null` (leave `FOUNDRY_WORLD` alone)                                                         |
-| `resolveLicenseKey`        | `resolveLicenseKey(stage, env = process.env)`                                                 | `string\|null`       | finding a stage's dedicated Foundry licence key, since Foundry is single-seat and two stages running at once need two keys                                                                  |
-| `resolveDataRoot`          | `resolveDataRoot(stage, { env } = {})`                                                        | `string`             | resolving the local Foundry data root path for a stage, checked for what a bind mount needs                                                                                                 |
-| `passthroughEnv`           | `passthroughEnv(env = process.env)`                                                           | `[string, string][]` | collecting the image's own `FOUNDRY_*`/`CONTAINER_*` environment pairs to pass through (deliberately excludes `CONTAINER_CACHE`, which `dockerRunArgs` sets itself)                         |
-| `dockerRunArgs`            | `dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey })`   | `string[]`           | building the full `docker run` argument vector for a stage's container                                                                                                                      |
-| `runDocker`                | `runDocker(args)`                                                                             | `number`             | running the `docker` CLI with inherited stdio and getting back its exit status                                                                                                              |
-| `captureDocker`            | `captureDocker(args)`                                                                         | `string`             | running `docker` and capturing trimmed stdout, tolerating failure (returns `""`)                                                                                                            |
-| `containerExists`          | `containerExists(name, runningOnly = false)`                                                  | `boolean`            | checking whether a container with exactly this name exists (optionally, only counting a running one)                                                                                        |
-| `runningFoundryContainers` | `runningFoundryContainers(except = "")`                                                       | `string[]`           | listing HeroicLands-convention Foundry containers currently running, to warn about a licence clash before a run starts                                                                      |
-| `clearStaleLock`           | `clearStaleLock(dataRoot, log = () => {})`                                                    | —                    | removing a data-root lock left behind by a container that did not shut down cleanly; only safe to call while the container is stopped                                                       |
-| `resolveContainer`         | `resolveContainer({ stage, config, env = process.env })`                                      | `ResolvedContainer`  | resolving all of a stage's container settings in one call, from the package-build configuration                                                                                             |
-| `startContainer`           | `startContainer(container, { dataRoot, env, log })`                                           | `number`             | starting a stage's container, creating it first if it does not exist                                                                                                                        |
-| `removeContainer`          | `removeContainer(name, log = () => {})`                                                       | —                    | stopping and removing a container, tolerating "not running" and "no such container"                                                                                                         |
-| `containerAction`          | `containerAction({ action, stage, config, env, log })`                                        | `number`             | performing one `CONTAINER_ACTIONS` action for a stage end to end                                                                                                                            |
+| Export                     | Signature                                                                                                  | Returns                        | Use it when                                                                                                                                                                                 |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEFAULT_STAGE_PORTS`      | `const DEFAULT_STAGE_PORTS`                                                                                | —                              | reading the host port each conventional stage (`dev`/`qa`/`prod`/`test`) publishes by default, chosen so all four can run at once                                                           |
+| `CONTAINER_PORT`           | `const CONTAINER_PORT`                                                                                     | —                              | the fixed port Foundry listens on inside the container                                                                                                                                      |
+| `CACHE_MOUNT`              | `const CACHE_MOUNT`                                                                                        | —                              | the path a host-provided download cache is mounted at inside the container                                                                                                                  |
+| `CONTAINER_ACTIONS`        | `const CONTAINER_ACTIONS`                                                                                  | —                              | the closed set of actions `package-build container` accepts                                                                                                                                 |
+| `dataEnvVar`               | `dataEnvVar(stage)`                                                                                        | `string`                       | deriving the environment variable that names a stage's Foundry data root, without hand-tabulating one per stage                                                                             |
+| `containerName`            | `containerName(packageId, stage, base = null)`                                                             | `string`                       | computing the stable container name a stage runs under, so a signed Foundry licence (bound to the hostname) survives a recreate; pass `base` to share one container/licence across packages |
+| `resolveStagePort`         | `resolveStagePort(stage, { env, stages } = {})`                                                            | `number`                       | resolving the host port for a stage, honoring `FOUNDRYVTT_<STAGE>_PORT` over a declared or conventional default                                                                             |
+| `resolveFoundryVersion`    | `resolveFoundryVersion(stage, { env, stages, compatibilityMinimum, e2eStage = "test" } = {})`              | `string\|null`                 | pinning the exact Foundry build a stage runs, deriving the end-to-end stage's pin from the package's own `compatibility.minimum` so the floor is actually exercised                         |
+| `resolveImage`             | `resolveImage({ env, image, version, compatibilityMinimum } = {})`                                         | `string`                       | resolving the `felddy/foundryvtt` image reference a run uses — the pinned build's own tag when a build is pinned                                                                            |
+| `resolveWorld`             | `resolveWorld(stage, { env, stages } = {})`                                                                | `string\|null`                 | resolving which world a stage auto-launches — `""` declares "never auto-launch", distinct from `null` (leave `FOUNDRY_WORLD` alone)                                                         |
+| `resolveLicenseKey`        | `resolveLicenseKey(stage, env = process.env)`                                                              | `string\|null`                 | finding a stage's dedicated Foundry licence key, since Foundry is single-seat and two stages running at once need two keys                                                                  |
+| `resolveDataRoot`          | `resolveDataRoot(stage, { env } = {})`                                                                     | `string`                       | resolving the local Foundry data root path for a stage, checked for what a bind mount needs                                                                                                 |
+| `passthroughEnv`           | `passthroughEnv(env = process.env)`                                                                        | `[string, string][]`           | collecting the image's own `FOUNDRY_*`/`CONTAINER_*` environment pairs to pass through (deliberately excludes `CONTAINER_CACHE`, which `dockerRunArgs` sets itself)                         |
+| `needsFoundryAccount`      | `needsFoundryAccount({ cacheDir, dataRoot, version, licenseKey, fileExists })`                             | `boolean`                      | deciding whether the image needs `FOUNDRY_USERNAME`/`FOUNDRY_PASSWORD`: only when the pinned build's archive is not cached, or the licence must come from the account                       |
+| `dockerRunArgs`            | `dockerRunArgs({ name, image, port, dataRoot, env, cacheDir, version, world, licenseKey, account, user })` | `string[]`                     | building the full `docker run` argument vector for a stage's container; `account: false` withholds the foundryvtt.com account                                                               |
+| `runDocker`                | `runDocker(args)`                                                                                          | `number`                       | running the `docker` CLI with inherited stdio and getting back its exit status                                                                                                              |
+| `captureDocker`            | `captureDocker(args)`                                                                                      | `string`                       | running `docker` and capturing trimmed stdout, tolerating failure (returns `""`)                                                                                                            |
+| `dataRootScriptArgs`       | `dataRootScriptArgs({ image, dataRoot, script, args, user })`                                              | `string[]`                     | building the `docker run` vector for a throwaway container that runs a shell script against a stage's data root, mounted at `/data`                                                         |
+| `runDataRootScript`        | `runDataRootScript(opts)`                                                                                  | `string`                       | running that script and getting its stdout, throwing on a non-zero exit; the way to remove or hand over files that the Foundry container's user owns                                        |
+| `containerTreeRemover`     | `containerTreeRemover({ container, runScript })`                                                           | `(tree, { dataRoot }) => void` | removing a tree beneath a stage's data root that the Foundry container's user owns, as root in a throwaway container; the remover `package-build deploy` passes to `deployStage`            |
+| `containerRemovalCommand`  | `containerRemovalCommand({ image, dataRoot, tree })`                                                       | `string`                       | writing out the `docker run` command that removes such a tree, for a person to paste                                                                                                        |
+| `containerExists`          | `containerExists(name, runningOnly = false)`                                                               | `boolean`                      | checking whether a container with exactly this name exists (optionally, only counting a running one)                                                                                        |
+| `runningFoundryContainers` | `runningFoundryContainers(except = "")`                                                                    | `string[]`                     | listing HeroicLands-convention Foundry containers currently running, to warn about a licence clash before a run starts                                                                      |
+| `clearStaleLock`           | `clearStaleLock(dataRoot, log = () => {})`                                                                 | —                              | removing a data-root lock left behind by a container that did not shut down cleanly; only safe to call while the container is stopped                                                       |
+| `resolveContainer`         | `resolveContainer({ stage, config, env = process.env })`                                                   | `ResolvedContainer`            | resolving all of a stage's container settings in one call, from the package-build configuration                                                                                             |
+| `startContainer`           | `startContainer(container, { dataRoot, env, log })`                                                        | `number`                       | starting a stage's container, creating it first if it does not exist                                                                                                                        |
+| `removeContainer`          | `removeContainer(name, log = () => {})`                                                                    | —                              | stopping and removing a container, tolerating "not running" and "no such container"                                                                                                         |
+| `containerAction`          | `containerAction({ action, stage, config, env, log })`                                                     | `number`                       | performing one `CONTAINER_ACTIONS` action for a stage end to end                                                                                                                            |
 
 ## `./coverage`
 
@@ -1766,7 +1757,7 @@ console.log(keyRootsOf(["SOHL.Item.Name", "SOHL.Actor.Name"]));
 
 ## `./deploy`
 
-Deploying a staged package into a Foundry data directory, always via a staged, atomic swap rather than a write in place — because a running Foundry holds its LevelDB compendium packs open, and replacing pack files underneath a live server corrupts them. The build lands in a sibling `…-staging-<pid>` directory and is renamed into place. Two transports are chosen from the destination string itself: a local path is copied, and a `[user@]host:/path` target is uploaded over SFTP, authenticating through the running SSH agent by default with no secret read from disk. The resolution rules are pure functions over data; the functions that touch a filesystem or network are named for it.
+Deploying a staged package into a Foundry data directory, always via a staged, atomic swap rather than a write in place — because a running Foundry holds its LevelDB compendium packs open, and replacing pack files underneath a live server corrupts them. The build lands in a sibling `…-staging-<pid>` directory and is moved into place. Two transports are chosen from the destination string itself: a local path is copied, and a `[user@]host:/path` target is uploaded over SFTP, authenticating through the running SSH agent by default with no secret read from disk. The resolution rules are pure functions over data; the functions that touch a filesystem or network are named for it.
 
 ```js
 import { isRemoteTarget, parseRemote } from "@heroiclands/package-build/deploy";
@@ -1777,18 +1768,18 @@ console.log(parseRemote("user@example.org:/srv/foundry"));
 // -> { username: "user", host: "example.org", remotePath: "/srv/foundry" }
 ```
 
-| Export            | Signature                                                                                 | Returns                                                           | Use it when                                                                                                                                                |
-| ----------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `STAGE_ENV_MAP`   | `const STAGE_ENV_MAP`                                                                     | —                                                                 | reading the environment variable that names each stage's Foundry data root                                                                                 |
-| `resolveStage`    | `resolveStage(stageArg)`                                                                  | `string`                                                          | normalising a raw stage argument to its trimmed, lowercased form (`""` when absent)                                                                        |
-| `packageSubpath`  | `packageSubpath(packageKind, packageId)`                                                  | `string[]`                                                        | deriving where a package installs beneath a Foundry data root, from its kind and id                                                                        |
-| `isRemoteTarget`  | `isRemoteTarget(target)`                                                                  | `boolean`                                                         | deciding whether a configured destination is a remote SFTP target or a local directory (correctly excluding a Windows drive letter like `C:\Foundry\Data`) |
-| `parseRemote`     | `parseRemote(target)`                                                                     | `{username: string\|undefined, host: string, remotePath: string}` | splitting a `[user@]host:/path` remote target into its parts                                                                                               |
-| `resolveAgent`    | `resolveAgent(env, stageUpper, prefix = "SOHL")`                                          | `string\|undefined`                                               | locating the SSH agent endpoint cross-platform, falling back to a key file when `undefined`                                                                |
-| `buildConnection` | `async buildConnection(stageUpper, remote, { env, prefix = "SOHL" } = {})`                | `Promise<object>`                                                 | assembling an `ssh2-sftp-client` connection config for a stage, defaulting to agent auth so no secret is read from disk                                    |
-| `deployLocal`     | `async deployLocal(srcAbs, destDir)`                                                      | `Promise<void>`                                                   | mirroring a staged build into a local directory via the staged, atomic swap                                                                                |
-| `deployRemote`    | `async deployRemote(conn, srcAbs, remoteDir, { onUpload } = {})`                          | `Promise<void>`                                                   | mirroring a staged build into a remote directory over SFTP, with the same staged swap `deployLocal` performs                                               |
-| `deployStage`     | `async deployStage({ stage, source, packageKind, packageId, env, prefix = "SOHL", log })` | `Promise<{stage: string, destination: string, remote: boolean}>`  | deploying a staged package to one named stage, choosing the transport from the configured destination automatically                                        |
+| Export            | Signature                                                                                             | Returns                                                                                     | Use it when                                                                                                                                                                                                                                                                        |
+| ----------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STAGE_ENV_MAP`   | `const STAGE_ENV_MAP`                                                                                 | —                                                                                           | reading the environment variable that names each stage's Foundry data root                                                                                                                                                                                                         |
+| `resolveStage`    | `resolveStage(stageArg)`                                                                              | `string`                                                                                    | normalising a raw stage argument to its trimmed, lowercased form (`""` when absent)                                                                                                                                                                                                |
+| `packageSubpath`  | `packageSubpath(packageKind, packageId)`                                                              | `string[]`                                                                                  | deriving where a package installs beneath a Foundry data root, from its kind and id                                                                                                                                                                                                |
+| `isRemoteTarget`  | `isRemoteTarget(target)`                                                                              | `boolean`                                                                                   | deciding whether a configured destination is a remote SFTP target or a local directory (correctly excluding a Windows drive letter like `C:\Foundry\Data`)                                                                                                                         |
+| `parseRemote`     | `parseRemote(target)`                                                                                 | `{username: string\|undefined, host: string, remotePath: string}`                           | splitting a `[user@]host:/path` remote target into its parts                                                                                                                                                                                                                       |
+| `resolveAgent`    | `resolveAgent(env, stageUpper, prefix = "SOHL")`                                                      | `string\|undefined`                                                                         | locating the SSH agent endpoint cross-platform, falling back to a key file when `undefined`                                                                                                                                                                                        |
+| `buildConnection` | `async buildConnection(stageUpper, remote, { env, prefix = "SOHL" } = {})`                            | `Promise<object>`                                                                           | assembling an `ssh2-sftp-client` connection config for a stage, defaulting to agent auth so no secret is read from disk                                                                                                                                                            |
+| `deployLocal`     | `async deployLocal(srcAbs, destDir, { removeTree } = {})`                                             | `Promise<{leftovers: LeftoverTree[]}>`                                                      | mirroring a staged build into a local directory via the staged, atomic swap; every previous `<id>.old-<pid>` tree beside it is removed, one the host user is refused is handed to `removeTree`, and one that still cannot be removed is returned in `leftovers` rather than thrown |
+| `deployRemote`    | `async deployRemote(conn, srcAbs, remoteDir, { onUpload } = {})`                                      | `Promise<{leftovers: LeftoverTree[]}>`                                                      | mirroring a staged build into a remote directory over SFTP, with the same staged swap `deployLocal` performs                                                                                                                                                                       |
+| `deployStage`     | `async deployStage({ stage, source, packageKind, packageId, env, prefix = "SOHL", log, removeTree })` | `Promise<{stage: string, destination: string, remote: boolean, leftovers: LeftoverTree[]}>` | deploying a staged package to one named stage, choosing the transport from the configured destination automatically; `removeTree(tree, { dataRoot })` removes a local previous tree the host user is refused                                                                       |
 
 ## `./e2e`
 
@@ -1803,32 +1794,33 @@ console.log(E2E_MODES);
 // -> ["run", "open"]
 ```
 
-| Export                        | Signature                                                                                                | Returns                                        | Use it when                                                                                                                                                 |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `E2E_GM_ID`                   | `const E2E_GM_ID`                                                                                        | —                                              | reading the fixed Gamemaster document id every seeded world carries                                                                                         |
-| `E2E_SCENE_ID`                | `const E2E_SCENE_ID`                                                                                     | —                                              | reading the seeded, pre-activated default scene's id                                                                                                        |
-| `E2E_MODES`                   | `const E2E_MODES`                                                                                        | —                                              | the closed set of modes the suite may run under (`"run"` / `"open"`)                                                                                        |
-| `hashPassword`                | `hashPassword(password, salt)`                                                                           | `string` — the hex hash                        | hashing a password the way Foundry's own `core/auth.mjs` does, to seed a login that actually works                                                          |
-| `resolveE2EWorld`             | `resolveE2EWorld(config, env = process.env)`                                                             | `E2EWorld`                                     | resolving the seeded world's identity from configuration, with an environment override under the repository's own variable prefix                           |
-| `worldManifest`               | `worldManifest({ worldId, worldTitle, worldDescription, systemId, systemVersion, coreVersion })`         | `object` — the world manifest                  | building the `world.json` a seeded world carries                                                                                                            |
-| `gmDocument`                  | `gmDocument({ id, name, password, salt })`                                                               | `object` — the user document                   | building the seeded world's single Gamemaster user document                                                                                                 |
-| `defaultSceneDocument`        | `defaultSceneDocument()`                                                                                 | `object` — the scene document                  | building the one pre-activated scene every seeded world carries                                                                                             |
-| `moduleConfigurationDocument` | `moduleConfigurationDocument(packageId)`                                                                 | `object` — the setting document                | building the world setting that switches a module package on (a module must be activated; a system does not)                                                |
-| `isWorldActive`               | `isWorldActive(body)`                                                                                    | `boolean`                                      | checking whether a `/join` response body shows a world that is actually active, not merely reachable                                                        |
-| `resolveSweepVersion`         | `resolveSweepVersion(argv)`                                                                              | `string` — the exact build, trimmed            | reading the exact Foundry build a sweep was asked to run against; there is deliberately no default                                                          |
-| `parseFastArgs`               | `parseFastArgs(argv, build)`                                                                             | `FastArgs`                                     | parsing the fast loop's CLI arguments against the repository's declared build table, in declaration order                                                   |
-| `seedTestWorld`               | `async seedTestWorld({ config, packageJson, env = process.env, log = () => {} })`                        | `Promise<{worldDir: string, world: E2EWorld}>` | seeding the disposable world into the end-to-end stage's data root, wiping and rewriting the world directory each time                                      |
-| `waitForWorld`                | `async waitForWorld({ url, container, stage, timeoutMs = 180_000, log = () => {} })`                     | `Promise<void>`                                | polling until a seeded world is active, or failing with a diagnosis (a licence failure is detected from the container log, not a timeout)                   |
-| `suiteExecutables`            | `suiteExecutables(command)`                                                                              | `string[]`                                     | reading every executable a suite command needs to exist before it can run at all                                                                            |
-| `findExecutable`              | `findExecutable(name, { cwd, env = process.env } = {})`                                                  | `string\|null`                                 | finding an executable the way the child process would (`node_modules/.bin` first, then `PATH`)                                                              |
-| `missingExecutables`          | `missingExecutables({ command, cwd, env = process.env })`                                                | `string[]`                                     | checking which of a suite command's executables are not there — asked again mid-run, since an install can pull the runner out from under a run in progress  |
-| `freshResults`                | `freshResults({ paths, since, cwd })`                                                                    | `string[]`                                     | finding which declared result paths a suite run actually wrote to since it was spawned (existence alone is not evidence)                                    |
-| `suiteVerdict`                | `suiteVerdict({ status, vanished = [], declared = [], fresh = [] })`                                     | `SuiteVerdict`                                 | deciding what a finished suite run is worth given its exit status and what it left behind; can only ever downgrade a verdict, never upgrade one             |
-| `runSuite`                    | `runSuite({ command, args = [], cwd, results = [], env = process.env, log = () => {} })`                 | `number` — the suite's exit status             | running the repository's suite, bracketed by before/after executable checks and a fresh-results check rather than trusting the exit status alone            |
-| `suiteCommand`                | `suiteCommand(config, mode)`                                                                             | `string[]`                                     | reading the declared suite command for a mode (`"run"` or `"open"`), or failing clearly when none is declared                                               |
-| `e2eRun`                      | `async e2eRun({ config, packageJson, mode = "run", suiteArgs = [], env = process.env, log = () => {} })` | `Promise<number>`                              | running a full, from-scratch end-to-end pass: deploy, reseed, recreate the container, wait, run the suite, tear down (or leave it serving in `"open"` mode) |
-| `e2eFast`                     | `async e2eFast({ config, argv = [], env = process.env, log = () => {} })`                                | `Promise<number>`                              | iterating quickly during development: rebuild what changed, redeploy, cycle the world, wait, re-run                                                         |
-| `e2eSweep`                    | `async e2eSweep({ config, packageJson, argv = [], env = process.env, log = () => {} })`                  | `Promise<number>`                              | running the full suite against a build the repository does not pin, to license moving `compatibility.verified` forward                                      |
+| Export                        | Signature                                                                                                | Returns                                        | Use it when                                                                                                                                                             |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `E2E_GM_ID`                   | `const E2E_GM_ID`                                                                                        | —                                              | reading the fixed Gamemaster document id every seeded world carries                                                                                                     |
+| `E2E_SCENE_ID`                | `const E2E_SCENE_ID`                                                                                     | —                                              | reading the seeded, pre-activated default scene's id                                                                                                                    |
+| `E2E_MODES`                   | `const E2E_MODES`                                                                                        | —                                              | the closed set of modes the suite may run under (`"run"` / `"open"`)                                                                                                    |
+| `hashPassword`                | `hashPassword(password, salt)`                                                                           | `string` — the hex hash                        | hashing a password the way Foundry's own `core/auth.mjs` does, to seed a login that actually works                                                                      |
+| `resolveE2EWorld`             | `resolveE2EWorld(config, env = process.env)`                                                             | `E2EWorld`                                     | resolving the seeded world's identity from configuration, with an environment override under the repository's own variable prefix                                       |
+| `worldManifest`               | `worldManifest({ worldId, worldTitle, worldDescription, systemId, systemVersion, coreVersion })`         | `object` — the world manifest                  | building the `world.json` a seeded world carries                                                                                                                        |
+| `gmDocument`                  | `gmDocument({ id, name, password, salt })`                                                               | `object` — the user document                   | building the seeded world's single Gamemaster user document                                                                                                             |
+| `defaultSceneDocument`        | `defaultSceneDocument()`                                                                                 | `object` — the scene document                  | building the one pre-activated scene every seeded world carries                                                                                                         |
+| `moduleConfigurationDocument` | `moduleConfigurationDocument(packageId)`                                                                 | `object` — the setting document                | building the world setting that switches a module package on (a module must be activated; a system does not)                                                            |
+| `isWorldActive`               | `isWorldActive(body)`                                                                                    | `boolean`                                      | checking whether a `/join` response body shows a world that is actually active, not merely reachable                                                                    |
+| `resolveSweepVersion`         | `resolveSweepVersion(argv)`                                                                              | `string` — the exact build, trimmed            | reading the exact Foundry build a sweep was asked to run against; there is deliberately no default                                                                      |
+| `parseFastArgs`               | `parseFastArgs(argv, build)`                                                                             | `FastArgs`                                     | parsing the fast loop's CLI arguments against the repository's declared build table, in declaration order                                                               |
+| `seedTestWorld`               | `async seedTestWorld({ config, packageJson, env = process.env, log = () => {}, runScript })`             | `Promise<{worldDir: string, world: E2EWorld}>` | seeding the disposable world into the end-to-end stage's data root, replacing the world directory through a throwaway container so the Foundry container's user owns it |
+| `deployForContainer`          | `async deployForContainer({ config, env = process.env, log = () => {}, runScript })`                     | `Promise<void>`                                | deploying the staged package to the end-to-end stage, removing the old install and handing the new one to the Foundry container's user through a throwaway container    |
+| `waitForWorld`                | `async waitForWorld({ url, container, stage, timeoutMs = 180_000, log = () => {} })`                     | `Promise<void>`                                | polling until a seeded world is active, or failing with a diagnosis (a licence failure is detected from the container log, not a timeout)                               |
+| `suiteExecutables`            | `suiteExecutables(command)`                                                                              | `string[]`                                     | reading every executable a suite command needs to exist before it can run at all                                                                                        |
+| `findExecutable`              | `findExecutable(name, { cwd, env = process.env } = {})`                                                  | `string\|null`                                 | finding an executable the way the child process would (`node_modules/.bin` first, then `PATH`)                                                                          |
+| `missingExecutables`          | `missingExecutables({ command, cwd, env = process.env })`                                                | `string[]`                                     | checking which of a suite command's executables are not there — asked again mid-run, since an install can pull the runner out from under a run in progress              |
+| `freshResults`                | `freshResults({ paths, since, cwd })`                                                                    | `string[]`                                     | finding which declared result paths a suite run actually wrote to since it was spawned (existence alone is not evidence)                                                |
+| `suiteVerdict`                | `suiteVerdict({ status, vanished = [], declared = [], fresh = [] })`                                     | `SuiteVerdict`                                 | deciding what a finished suite run is worth given its exit status and what it left behind; can only ever downgrade a verdict, never upgrade one                         |
+| `runSuite`                    | `runSuite({ command, args = [], cwd, results = [], env = process.env, log = () => {} })`                 | `number` — the suite's exit status             | running the repository's suite, bracketed by before/after executable checks and a fresh-results check rather than trusting the exit status alone                        |
+| `suiteCommand`                | `suiteCommand(config, mode)`                                                                             | `string[]`                                     | reading the declared suite command for a mode (`"run"` or `"open"`), or failing clearly when none is declared                                                           |
+| `e2eRun`                      | `async e2eRun({ config, packageJson, mode = "run", suiteArgs = [], env = process.env, log = () => {} })` | `Promise<number>`                              | running a full, from-scratch end-to-end pass: deploy, reseed, recreate the container, wait, run the suite, tear down (or leave it serving in `"open"` mode)             |
+| `e2eFast`                     | `async e2eFast({ config, argv = [], env = process.env, log = () => {} })`                                | `Promise<number>`                              | iterating quickly during development: rebuild what changed, redeploy, cycle the world, wait, re-run                                                                     |
+| `e2eSweep`                    | `async e2eSweep({ config, packageJson, argv = [], env = process.env, log = () => {} })`                  | `Promise<number>`                              | running the full suite against a build the repository does not pin, to license moving `compatibility.verified` forward                                                  |
 
 ## `./lang`
 
@@ -1958,7 +1950,7 @@ The engine wildcard subpath also exposes the body parsers below. Their figure ex
 | Module                       | Exports                                                                                      | Contract                                                                                                                                                                                                                               |
 | ---------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`       | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
-| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`    | Read div and secret fences; info/warn names are retired; generic div records have `name: "div"` and no generated title. Scanning includes poetry errors.                                                                               |
+| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`    | Read div and secret fences; generic div records have `name: "div"` and no generated title. Scanning includes poetry errors.                                                                                                            |
 | `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
 | `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans and located errors; the renderer preserves inline Markdown in attributed HTML spans.                                                                             |