@heroiclands/package-build 22.15.1 → 22.16.0

package/docs/api.md

@@ -1,3 +1,10 @@
+---
+shortcode: api
+name: { full: "API reference" }
+type: doc
+subType: reference
+---
+
 # API reference
 
 `@heroiclands/package-build` exposes its programmatic surface through
@@ -111,6 +118,16 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 | `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`
+
+`formatGenerated(text, filepath)` returns a promise for text formatted with
+the Prettier configuration that applies to the destination path. Generators
+can write the result directly without introducing formatting drift.
+
+| Export            | Signature                         | Returns           | Use it when                   |
+| ----------------- | --------------------------------- | ----------------- | ----------------------------- |
+| `formatGenerated` | `formatGenerated(text, filepath)` | `Promise<string>` | writing a generated text file |
+
 ### `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.
@@ -146,7 +163,7 @@ Where code lives in a markdown body, so a rewriter can leave it alone. Every bui
 | Export                | Signature                                                  | Returns                         | Use it when                                                                                  |
 | --------------------- | ---------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------- |
 | `FENCE_LINE`          | `const FENCE_LINE`                                         | —                               | matching a fence line, capturing its indent, marker, and info string                         |
-| `parseHeaderArgs`     | `parseHeaderArgs(info)`                                    | `{language, args}`              | reading a fence's info string as org-babel header arguments                                  |
+| `parseHeaderArgs`     | `parseHeaderArgs(info)`                                    | `{language, args, problems}`    | reading a fence's language and braced attributes                                             |
 | `codeRegions`         | `codeRegions(markdown, ...)`                               | `Array<{start, end}>`           | getting every code region in a markdown body as character offsets                            |
 | `replaceOutsideCode`  | `replaceOutsideCode(markdown, pattern, replacer, options)` | `string` — the rewritten body   | running `String.prototype.replace` while skipping anything inside code                       |
 | `matchAllOutsideCode` | `matchAllOutsideCode(markdown, pattern, options)`          | `Array<RegExpMatchArray>`       | running `String.prototype.matchAll` while skipping anything inside code                      |
@@ -335,6 +352,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | Export                    | Signature                                    | Returns                                  | Use it when                                                                                  |
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `DRAFT_TAG`               | `const DRAFT_TAG`                            | —                                        | naming the declared tag that marks a note as unfinished                                      |
+| `GM_TAG`                  | `const GM_TAG`                               | —                                        | naming the declared tag that marks a GM-only note                                            |
 | `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                        | looking up, per content type, its `data:` field list and its closed `subType` values         |
 | `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`               | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere |
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |
@@ -343,6 +361,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
+| `isGmNote`                | `isGmNote(fm)`                               | `boolean`                                | checking whether a note is restricted to GM-facing output                                    |
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
 | `assertVocabularyCharset` | `assertVocabularyCharset(vocabulary, where)` | throws                                   | refusing a vocabulary declaration whose type or subType breaks the address charset           |
@@ -423,7 +442,7 @@ The three states of a note — **stub**, **draft**, **full** — and the one obs
 | `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
 | `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
 | `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
-| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting the prose a reader meets, with a wikilink counting as the one word it renders                                     |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words     |
 
 ### `engine.draftNotice`
 
@@ -471,7 +490,7 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 
 ### `engine.holdings`
 
-What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the tenure check `content-build lint` runs on a place.
+What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the tenure check `package-build lint` runs on a place.
 
 | Export                 | Signature                            | Returns                 | Use it when                                                                                                                  |
 | ---------------------- | ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -485,7 +504,7 @@ What lies within a place, who holds it, and what an affiliation holds — read o
 
 ### `engine.populations`
 
-Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `content-build lint` runs all four as warnings.
+Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `package-build lint` runs all four as warnings.
 
 | Export                  | Signature                                | Returns                | Use it when                                                                                                  |
 | ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -545,7 +564,7 @@ The geometry of the map from a place and of the chart from one, as arithmetic ov
 
 ### `engine.mapDot`
 
-The drawings of `content-build map` as DOT text, sharing one style table: shape, colour and size by `subType`, an anomaly overriding colour alone, every label a `name.full`, every tooltip an address, and a `URL` where the place carries one so the SVG's names are links.
+The drawings of `package-build map` as DOT text, sharing one style table: shape, colour and size by `subType`, an anomaly overriding colour alone, every label a `name.full`, every tooltip an address, and a `URL` where the place carries one so the SVG's names are links.
 
 | Export       | Signature                                          | Returns  | Use it when                                                                                                      |
 | ------------ | -------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -567,7 +586,7 @@ The npm-installed Graphviz runtime draws SVG maps and supplies the plain positio
 
 ### `engine.mapBuild`
 
-`content-build map` as a function: drawings written under an output directory, with each `.dot` beside its `.svg` and tree anomalies returned as findings.
+`package-build map` as a function: drawings written under an output directory, with each `.dot` beside its `.svg` and tree anomalies returned as findings.
 
 | Export          | Signature                                                                                                                    | Returns               | Use it when                                                                   |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
@@ -578,7 +597,7 @@ The npm-installed Graphviz runtime draws SVG maps and supplies the plain positio
 
 ### `engine.siteMaps`
 
-The map from each place, drawn for the site: `content-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. `site.maps: false` draws none.
+The map from each place, drawn for the site: `package-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. `site.maps: false` draws none.
 
 | Export         | Signature                                               | Returns            | Use it when                                                                                                     |
 | -------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -612,6 +631,7 @@ The neutral day spelling is `<year>.<day>[:HHMMSS]`. The pure conversion functio
 | ------------------------- | ---------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
 | `CANONICAL_EPOCH`         | `const CANONICAL_EPOCH`                                    | —                                      | naming where the canonical axis's own year 1 sits                               |
 | `canonicalYear`           | `canonicalYear(year, epoch?)`                              | `number` — the signed year on the axis | converting a year written in one reckoning to the number everything compares on |
+| `eraYear`                 | `eraYear(canonical, epoch?)`                               | signed era year without zero           | printing a canonical year in a chosen reckoning                                 |
 | `dateSortKey`             | `dateSortKey(year, month, day)`                            | `number`                               | ordering mixed-precision dates against a single number                          |
 | `calendarStructure`       | `calendarStructure(calendar)`                              | `{months}` — `null` where unstated     | reading the months a calendar keeps, before phrasing a finding                  |
 | `daysInMonth`             | `daysInMonth(calendar, month)`                             | `number` — `null` where unstated       | bounding a written day against the month it names                               |
@@ -627,23 +647,65 @@ The neutral day spelling is `<year>.<day>[:HHMMSS]`. The pure conversion functio
 
 ### `engine.noteDates`
 
-A date on a note is one authored string. `<year>.<day>[:HHMMSS]` names a calendar-neutral day; `VR(720/5/14)` names an era marker and a date in that era's calendar. A marker is resolved from calendar notes in the corpus and contributes a canonical year, day, and sort key. Print `text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. Unmarked slash dates and the addressed era qualifier are also accepted by the parser; a caller supplies the corpus marker map and world year length when it needs a marker resolved.
+A date on a note is one authored string. `<year>.<day>[:HHMMSS]` names a calendar-neutral day; `datefrom vrcal 23 Taranis 326 VR` names a calendar, a named month, and an era. Either form may begin with `~` for an approximate date. A resolved calendar date carries a canonical year, day, span and sort key. Print `prose ?? text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. `resolvedDateFields` supplies identical derived records to JSONL and generated page frontmatter.
+
+| Export                  | Signature                                        | Returns                                            | Use it when                                                    |
+| ----------------------- | ------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------- |
+| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`                             | —                                                  | naming the literal that says a date is not recorded            |
+| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`                        | —                                                  | matching the date grammar directly                             |
+| `DATEFROM_PATTERN`      | `const DATEFROM_PATTERN`                         | —                                                  | recognizing a named calendar conversion in frontmatter         |
+| `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`                    | —                                                  | checking that a string is an era qualifier a date could carry  |
+| `parseNoteDate`         | `parseNoteDate(value, options)`                  | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned   |
+| `eraCovering`           | `eraCovering(date, eras, daysPerYear)`           | one era or `null`; throws on overlap               | selecting the era covering a resolved date's full precision    |
+| `formatNoteDate`        | `formatNoteDate(date, era, daysPerYear)`         | `{era, year, month, day, text, prose}` or `null`   | printing a resolved date in a chosen era or its authored form  |
+| `formatDateInCalendar`  | `formatDateInCalendar(date, reference, context)` | printable record or `null`                         | selecting a calendar's era and printing a resolved date in it  |
+| `calendarEras`          | `calendarEras(reference, context)`               | ordered era records                                | resolving an addressed calendar or one of its eras             |
+| `resolvedDateFields`    | `resolvedDateFields(fm, context)`                | map of normalized dates                            | deriving being and lore event date records for index and pages |
+
+### `engine.dateConversion`
+
+The exact-day conversion functions use the corpus reckoning context. A calendar with several eras requires an era in the named date. They reject dates outside the selected calendar and gaps between its eras. Approximate input keeps its `~` prefix in the result.
+
+| Export             | Signature                                           | Returns               | Use it when                                   |
+| ------------------ | --------------------------------------------------- | --------------------- | --------------------------------------------- |
+| `dateFromCalendar` | `dateFromCalendar(reference, value, context)`       | canonical date string | converting one calendar day to the world axis |
+| `dateToCalendar`   | `dateToCalendar(reference, canonicalDate, context)` | calendar date string  | expressing one canonical day in a calendar    |
+
+### `engine.calendarChoice`
+
+`checkCalendarChoice(note, { index })` checks that an explicitly selected calendar Address on a being or place resolves to a calendar note.
+
+| Export                | Signature                            | Returns  | Use it when                                     |
+| --------------------- | ------------------------------------ | -------- | ----------------------------------------------- |
+| `checkCalendarChoice` | `checkCalendarChoice(note, options)` | findings | validating a being's or place's chosen calendar |
+
+### `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 |
+
+### `engine.markdownExpressions`
+
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
 
-| Export                  | Signature                       | Returns                                            | Use it when                                                   |
-| ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
-| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`            | —                                                  | naming the literal that says a date is not recorded           |
-| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`       | —                                                  | matching the date grammar directly                            |
-| `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`   | —                                                  | checking that a string is an era qualifier a date could carry |
-| `parseNoteDate`         | `parseNoteDate(value, options)` | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned  |
+| Export                      | Signature                                  | Returns                | Use it when                                     |
+| --------------------------- | ------------------------------------------ | ---------------------- | ----------------------------------------------- |
+| `renderMarkdownExpressions` | `renderMarkdownExpressions(body, options)` | `{markdown, findings}` | expanding authored expressions in prose         |
+| `sqlQueriesInMarkdown`      | `sqlQueriesInMarkdown(body)`               | query strings          | preparing inline SQL alongside generated tables |
 
 ### `engine.reckoningMarkers`
 
-The corpus registry maps each declared marker to exactly one era and its calendar. An era start may use the canonical axis or a marker already resolvable from the corpus; duplicate markers and cycles are findings.
+The corpus registry maps every declared era to its calendar and each marker to exactly one era. Era starts may use the canonical axis or another declared era. Within one calendar, starts increase; the next start bounds the preceding era unless an explicit end leaves a gap. The first era also covers dates before its start and counts them with negative years. Later eras accept only forward year counts. Unknown eras, duplicate markers, invalid bounds, overlapping eras and dependency cycles are findings. Short qualifiers are ambiguous when they name eras in several packages; a full address selects one. This registry governs note dates; calendar definitions emitted for Foundry retain their consumer format.
 
-| Export                    | Signature                                     | Returns                            | Use it when                                                 |
-| ------------------------- | --------------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
-| `resolveReckoningMarkers` | `resolveReckoningMarkers(index, daysPerYear)` | `{markers, findings}`              | resolving authored era markers and their starts             |
-| `reckoningContext`        | `reckoningContext(index)`                     | `{markers, daysPerYear, findings}` | sharing one resolved date context across checks on a corpus |
+| Export                    | Signature                                     | Returns                                  | Use it when                                                 |
+| ------------------------- | --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
+| `resolveReckoningMarkers` | `resolveReckoningMarkers(index, daysPerYear)` | `{eras, markers, findings}`              | resolving authored eras, their markers, and their bounds    |
+| `reckoningContext`        | `reckoningContext(index)`                     | `{eras, markers, daysPerYear, findings}` | sharing one resolved date context across checks on a corpus |
 
 ### `engine.calendarNotes`
 
@@ -672,7 +734,7 @@ A calendar is a `lore` note with `subType: calendar`, declaring the months it ke
 calendar files under `build/calendars/`. Each calendar produces a definition
 and an import envelope containing that same definition. The command line entry
 point is `package-build calendars --calendaria-version <version>`; run
-`content-build content-index` first. The generated import envelope carries a
+`package-build content-index` first. The generated import envelope carries a
 fixed ISO `exportedAt` sentinel so repeated builds of unchanged source emit
 identical bytes.
 
@@ -761,52 +823,52 @@ The shortcodes a note declares it used to be published under. A package's `(type
 
 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.                                                        |
+| `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`
 
 Emitting this package's cross-package link manifest. `engine/content-address.mjs` owns the address _grammar_ — how a key is version is read, how a foreign file resolves. This module owns the _pass_: walking a content tree and deriving, for every note it publishes, the addresses that entry states. The two halves were split across the format module and a hand-written script in each consuming repository, which is how the two scripts came to differ in ways nobody chose — one routes its UUIDs through the pack router and one does not, and neither knew.
 
-| Export                  | Signature                                               | Returns                                                                                                                    | Use it when                                                   |
-| ----------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `LEAD_ANCHOR`           | `const LEAD_ANCHOR`                                     | —                                                                                                                          | The reserved anchor name for a journal's **first** page.      |
-| `anchorsOf`             | `function anchorsOf(entryUuid, entryId, body, name)`    | {Record<string, string>} The anchors.                                                                                      | Every page of a note's journal, as `anchorName → whole UUID`. |
-| `entriesForNote`        | `function entriesForNote(fm, name, address, body, ctx)` | {Array<object>} One or two entries, in {@link buildManifest}'s shape.                                                      | The manifest entries a single note produces.                  |
-| `collectFoundryEntries` | `function collectFoundryEntries(contentBase, ctx)`      | {{entries: Array<object>, notes: number, skipped: Array<{file: string, reason: string}>}}                                  | Every note this package publishes, as manifest entries.       |
-| `foundryIdentities`     | `function foundryIdentities(config`                     | {{contentPackage: string, foundryPackageId: string, packRouter: object, web: boolean, skipDirectories: readonly string[]}} | The identities an emission runs against, from configuration.  |
-| `entryContext`          | `function entryContext(config`                          | {{contentPackage: string, foundryPackageId: string, packRouter: object, web: boolean, skipDirectories: readonly string[]}} | The identities an emission runs against, from configuration.  |
+| Export                  | Signature                                               | Returns                                                                                                                      | Use it when                                                   |
+| ----------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `LEAD_ANCHOR`           | `const LEAD_ANCHOR`                                     | —                                                                                                                            | The reserved anchor name for a journal's **first** page.      |
+| `anchorsOf`             | `function anchorsOf(entryUuid, entryId, body, name)`    | {Record<string, string>} The anchors.                                                                                        | Every page of a note's journal, as `anchorName → whole UUID`. |
+| `entriesForNote`        | `function entriesForNote(fm, name, address, body, ctx)` | {Array<object>} One or two entries, in {@link buildManifest}'s shape.                                                        | The manifest entries a single note produces.                  |
+| `collectFoundryEntries` | `function collectFoundryEntries(contentBase, ctx)`      | `{{entries: Array<object>, notes: number, skipped: Array<{file: string, reason: string}>}}`                                  | Every note this package publishes, as manifest entries.       |
+| `foundryIdentities`     | `function foundryIdentities(config`                     | `{{contentPackage: string, foundryPackageId: string, packRouter: object, web: boolean, skipDirectories: readonly string[]}}` | The identities an emission runs against, from configuration.  |
+| `entryContext`          | `function entryContext(config`                          | `{{contentPackage: string, foundryPackageId: string, packRouter: object, web: boolean, skipDirectories: readonly string[]}}` | The identities an emission runs against, from configuration.  |
 
 ### `engine.contentIndex`
 
 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 })`            | `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 |
 
 `engine.contentIndex` also re-exports eight names from neighbouring leaf modules, at this same import path:
 
@@ -874,24 +936,27 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 ### `engine.siteBuild`
 
-Publishing a content tree as a website. Compiling a content tree into compendium packs is `content-build package compile`. Publishing the _same tree_ as a website was a script each consumer wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of them identical — and the copies drifted in ways neither repository could see. `sohl-thalorna` reimplemented four things this package already exported, not because it needed different behaviour but because its script predates the extraction. That is the failure a command removes: a consumer cannot accidentally reimplement one.
-
-| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                                                           |
-| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                                                            |
-| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.                                             |
-| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                                                               |
-| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.                                                      |
-| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                                                                     |
-| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                                                                  |
-| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.                                                          |
-| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                                                                |
-| `pageDestination`     | `function pageDestination(page, { bundle })`      | —                                                                                                                                      | Where a page is written, relative to the output root: flat, or as a leaf bundle when it carries a file beside itself. |
-| `renderSitePage`      | `renderSitePage(page, options)`                   | `{body, data, resolved, tableErrors, secretErrors, wikiErrors, imageErrors}`                                                           | Transform one page with the same passes the site writer uses.                                                         |
-| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                                                                        |
-| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                                                                   |
-| `sitePageDecorator`   | `sitePageDecorator(config, index)`                | Function                                                                                                                               | Add the site's infobox and being metadata to a rendered page.                                                         |
-| `buildSite`           | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
+Publishing a content tree as a website. `collectContentPages` gathers authored
+pages and link findings, while `collectHomepages` gathers package homepages.
+`writeHomepages` places those homepages at each package's site root. The same
+content tree can also compile into Foundry compendium packs.
+
+| Export                | Signature                                         | Returns                                                                                                                                  | Use it when                                                                                                           |
+| --------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | `{{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}`                                                               | The content tree's pages, and what could not be addressed.                                                            |
+| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | `{{pages: object[], addressFindings: object[]}}` The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.                                             |
+| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                    | Writes each homepage as the package root's `_index.md`.                                                               |
+| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                          | The integrity gates a site build runs before it writes anything.                                                      |
+| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                       | The gate result of a build that ran none of them.                                                                     |
+| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                        | Whether any gate produced a finding.                                                                                  |
+| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                             | The universe a generated table searches, grouped by package.                                                          |
+| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                       | The frontmatter a page publishes with.                                                                                |
+| `pageDestination`     | `function pageDestination(page, { bundle })`      | —                                                                                                                                        | Where a page is written, relative to the output root: flat, or as a leaf bundle when it carries a file beside itself. |
+| `renderSitePage`      | `renderSitePage(page, options)`                   | `{body, data, resolved, tableErrors, secretErrors, wikiErrors, imageErrors}`                                                             | Transform one page with the same passes the site writer uses.                                                         |
+| `renderPages`         | `function renderPages(pages, options)`            | `{{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}`                                       | Renders and writes every page.                                                                                        |
+| `resolveSitePass`     | `function resolveSitePass(name, options)`         | `{{beforeLinks?: Function}}` The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                                                                   |
+| `sitePageDecorator`   | `sitePageDecorator(config, index)`                | Function                                                                                                                                 | Add the site's infobox and being metadata to a rendered page.                                                         |
+| `buildSite`           | `buildSite({ config, sqlTables })`                | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}`    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
 
 ### `engine.sitePreview`
 
@@ -923,96 +988,96 @@ try {
 
 Linting a content tree's **addresses** — the rules every package's notes are authored against, wherever those notes live. These rules do not live in a consumer's `utils/`, which has two consequences and no upside. `thalorna` and `kethira` notes were checked by nothing at all, so the packages most likely to carry authoring mistakes were the ones nothing inspected. And one rule with two implementations can disagree without anything detecting it, which the canonical-separator handling already did once on each side.
 
-| Export              | Signature                                                                                      | Returns                                                                                                                                                                                               | Use it when                                                            |
-| ------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `SHORTCODE_PATTERN` | `const SHORTCODE_PATTERN`                                                                      | —                                                                                                                                                                                                     | The shape every `shortcode` must match: ASCII letters and digits only. |
-| `isValidShortcode`  | `function isValidShortcode(value)`                                                             | {boolean} `true` when it matches {@link SHORTCODE_PATTERN}.                                                                                                                                           | Whether a value is a well-formed shortcode.                            |
-| `lintContentTree`   | `lintContentTree(contentBase, { skipDirectories, contentPackage, config, records, problems })` | {{findings: Array<{file: string, line?: number, column?: number, severity: "error"\|"warning", message: string}>, notes: number, keys: number}} The findings, and what was inspected to produce them. | Lint every address in a content tree.                                  |
+| Export              | Signature                                                                                      | Returns                                                                                                                                                                                                 | Use it when                                                            |
+| ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `SHORTCODE_PATTERN` | `const SHORTCODE_PATTERN`                                                                      | —                                                                                                                                                                                                       | The shape every `shortcode` must match: ASCII letters and digits only. |
+| `isValidShortcode`  | `function isValidShortcode(value)`                                                             | {boolean} `true` when it matches {@link SHORTCODE_PATTERN}.                                                                                                                                             | Whether a value is a well-formed shortcode.                            |
+| `lintContentTree`   | `lintContentTree(contentBase, { skipDirectories, contentPackage, config, records, problems })` | `{{findings: Array<{file: string, line?: number, column?: number, severity: "error"\|"warning", message: string}>, notes: number, keys: number}}` The findings, and what was inspected to produce them. | Lint every address in a content tree.                                  |
 
 ### `engine.contentCharset`
 
 The charset authored content is held to, so a book can choose its face. The packs and the website render in whatever font the reader's browser or Foundry supplies, and a glyph nobody has is somebody else's problem. **A book is not that.** A PDF embeds the faces it sets, so every character in the corpus is a claim on the book's typeface — and the claim is silent, which is what makes it expensive.
 
-| Export               | Signature                                  | Returns                                                                                                                                                                | Use it when                                                                |
-| -------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `isLetterTier`       | `function isLetterTier(cp)`                | {boolean} Whether Tier 1 admits it.                                                                                                                                    | Tier 1 — the letters, and the two whitespace characters a file is made of. |
-| `TYPOGRAPHY`         | `const TYPOGRAPHY`                         | —                                                                                                                                                                      | Tier 2 — typography, enumerated one codepoint at a time.                   |
-| `NOTATION`           | `const NOTATION`                           | —                                                                                                                                                                      | Tier 3 — the notation the rules and price tables are written in.           |
-| `isAllowedCodePoint` | `function isAllowedCodePoint(cp)`          | {boolean} Whether it is allowed outside a code fence.                                                                                                                  | Whether the charset admits a code point anywhere in a note.                |
-| `isDiagramCodePoint` | `function isDiagramCodePoint(cp)`          | {boolean} Whether a fence may carry it.                                                                                                                                | Whether a code point is diagram furniture, admitted inside a fence only.   |
-| `refusalFor`         | `function refusalFor(cp)`                  | {string} A clause naming what it is and what to do instead.                                                                                                            | The reason a code point is refused.                                        |
-| `decomposedRuns`     | `function decomposedRuns(text)`            | {Array<{sequence: string, composed: string, index: number}>} Each offending run, in the order it appears.                                                              | Every non-NFC run in a string, with the composed form it should have been. |
-| `checkText`          | `function checkText(text, file)`           | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} What is wrong, in file order.                                              | Check one file's text against the charset and the normalization rule.      |
-| `lintContentCharset` | `function lintContentCharset(contentBase,` | {{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}} The findings, and how many files produced them. | Walk a content tree and check every authored file in it.                   |
+| Export               | Signature                                  | Returns                                                                                                                                                                  | Use it when                                                                |
+| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `isLetterTier`       | `function isLetterTier(cp)`                | {boolean} Whether Tier 1 admits it.                                                                                                                                      | Tier 1 — the letters, and the two whitespace characters a file is made of. |
+| `TYPOGRAPHY`         | `const TYPOGRAPHY`                         | —                                                                                                                                                                        | Tier 2 — typography, enumerated one codepoint at a time.                   |
+| `NOTATION`           | `const NOTATION`                           | —                                                                                                                                                                        | Tier 3 — the notation the rules and price tables are written in.           |
+| `isAllowedCodePoint` | `function isAllowedCodePoint(cp)`          | {boolean} Whether it is allowed outside a code fence.                                                                                                                    | Whether the charset admits a code point anywhere in a note.                |
+| `isDiagramCodePoint` | `function isDiagramCodePoint(cp)`          | {boolean} Whether a fence may carry it.                                                                                                                                  | Whether a code point is diagram furniture, admitted inside a fence only.   |
+| `refusalFor`         | `function refusalFor(cp)`                  | {string} A clause naming what it is and what to do instead.                                                                                                              | The reason a code point is refused.                                        |
+| `decomposedRuns`     | `function decomposedRuns(text)`            | {Array<{sequence: string, composed: string, index: number}>} Each offending run, in the order it appears.                                                                | Every non-NFC run in a string, with the composed form it should have been. |
+| `checkText`          | `function checkText(text, file)`           | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} What is wrong, in file order.                                                | Check one file's text against the charset and the normalization rule.      |
+| `lintContentCharset` | `function lintContentCharset(contentBase,` | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` The findings, and how many files produced them. | Walk a content tree and check every authored file in it.                   |
 
 ### `engine.contentIcons`
 
 Naming an interface icon in a note, without drawing it there. The user guide describes Foundry's interface, and it did so by pasting Unicode lookalikes of the icons the sheets actually draw: `☆` for the improve flag, `✎` for the formula editor, `◆` in the success-value table, `★★★` for mastery. The system renders every one of those with **Font Awesome** — a `fa-regular fa-star`, a `fa-solid fa-pen-to-square` — so the note and the screen it describes were drawing different pictures, and drifting apart with every sheet change.
 
-| Export                | Signature                                    | Returns                                                                                                                               | Use it when                                                                   |
-| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `EMPTY_ICON_REGISTRY` | `const EMPTY_ICON_REGISTRY`                  | —                                                                                                                                     | The registry a package that declares none gets: nothing at all.               |
-| `familyOf`            | `function familyOf(entry, registry`          | {string\|undefined} The family name, or nothing when neither the entry nor the registry says.                                         | The family an entry draws from, named or defaulted.                           |
-| `ICON_SIZES`          | `const ICON_SIZES`                           | —                                                                                                                                     | The sizes a note may ask for, and what each means on a page.                  |
-| `ICON_ATTRIBUTES`     | `const ICON_ATTRIBUTES`                      | —                                                                                                                                     | The attribute names a note may write, and how each is validated.              |
-| `parseIconAttributes` | `function parseIconAttributes(raw)`          | {{attrs: Record<string, string>, problems: string[]}} What was written, and what cannot be honoured.                                  | Read the brace of an icon token.                                              |
-| `ICON_PATTERN`        | `const ICON_PATTERN`                         | —                                                                                                                                     | The shape a note writes, and the one this module claims.                      |
-| `resolveIcon`         | `function resolveIcon(name, registry`        | {object\|null} The entry, or `null` when the registry does not declare it.                                                            | Look one name up.                                                             |
-| `iconHtml`            | `function iconHtml(entry, attrs`             | {string} An `<i>` element.                                                                                                            | The HTML the journals and the website emit — what the system already renders. |
-| `iconsIn`             | `function iconsIn(text)`                     | {Array<{name: string, index: number, raw: string}>} What it names.                                                                    | Every icon a string names, in the order written.                              |
-| `lintIcons`           | `function lintIcons(text, file, registry`    | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} The unknown names.                        | Report every icon a tree names that its registry does not declare.            |
-| `checkIconRegistry`   | `function checkIconRegistry(registry, where` | {Array<{severity: "warning", message: string}>} What is wrong with it.                                                                | What is wrong with a package's declared registry.                             |
-| `lintContentIcons`    | `function lintContentIcons(contentBase,`     | {{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}} What it found. | Walk a content tree and report every icon name its registry does not declare. |
-| `iconPlugin`          | `function iconPlugin(registry`               | {(md: object) => void} A markdown-it plugin.                                                                                          | A markdown-it plugin rendering `:icon-name:` inline.                          |
+| Export                | Signature                                    | Returns                                                                                                                                 | Use it when                                                                   |
+| --------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `EMPTY_ICON_REGISTRY` | `const EMPTY_ICON_REGISTRY`                  | —                                                                                                                                       | The registry a package that declares none gets: nothing at all.               |
+| `familyOf`            | `function familyOf(entry, registry`          | {string\|undefined} The family name, or nothing when neither the entry nor the registry says.                                           | The family an entry draws from, named or defaulted.                           |
+| `ICON_SIZES`          | `const ICON_SIZES`                           | —                                                                                                                                       | The sizes a note may ask for, and what each means on a page.                  |
+| `ICON_ATTRIBUTES`     | `const ICON_ATTRIBUTES`                      | —                                                                                                                                       | The attribute names a note may write, and how each is validated.              |
+| `parseIconAttributes` | `function parseIconAttributes(raw)`          | `{{attrs: Record<string, string>, problems: string[]}}` What was written, and what cannot be honoured.                                  | Read the brace of an icon token.                                              |
+| `ICON_PATTERN`        | `const ICON_PATTERN`                         | —                                                                                                                                       | The shape a note writes, and the one this module claims.                      |
+| `resolveIcon`         | `function resolveIcon(name, registry`        | {object\|null} The entry, or `null` when the registry does not declare it.                                                              | Look one name up.                                                             |
+| `iconHtml`            | `function iconHtml(entry, attrs`             | {string} An `<i>` element.                                                                                                              | The HTML the journals and the website emit — what the system already renders. |
+| `iconsIn`             | `function iconsIn(text)`                     | {Array<{name: string, index: number, raw: string}>} What it names.                                                                      | Every icon a string names, in the order written.                              |
+| `lintIcons`           | `function lintIcons(text, file, registry`    | {Array<{file: string, line: number, column: number, severity: "warning"\|"error", message: string}>} Findings for names and syntax.     | Report every icon a tree names that its registry does not declare.            |
+| `checkIconRegistry`   | `function checkIconRegistry(registry, where` | {Array<{severity: "warning", message: string}>} What is wrong with it.                                                                  | What is wrong with a package's declared registry.                             |
+| `lintContentIcons`    | `function lintContentIcons(contentBase,`     | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` What it found. | Walk a content tree and report every icon name its registry does not declare. |
+| `iconPlugin`          | `function iconPlugin(registry`               | {(md: object) => void} A markdown-it plugin.                                                                                            | A markdown-it plugin rendering `:icon name:` inline.                          |
 
 ### `engine.contentHtml`
 
-Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cannot say, a note does not say — it gets a construct every surface can render, the way `:icon-…:` replaces a pasted glyph.
+Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cannot say, a note does not say — it gets a construct every surface can render, the way `:icon …:` replaces a pasted glyph.
 
-| Export            | Signature                               | Returns                                                                                                                                                            | Use it when                                                    |
-| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
-| `HTML_TAG`        | `const HTML_TAG`                        | —                                                                                                                                                                  | A raw HTML tag, opening, closing or self-closing.              |
-| `htmlMessage`     | `function htmlMessage(tag)`             | {string} The message, unpunctuated at the end as a finding is.                                                                                                     | What a note carrying raw HTML is told.                         |
-| `checkHtml`       | `function checkHtml(body, file,`        | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} One finding per tag, in source order.                                  | Every raw HTML tag in one note's body.                         |
-| `lintContentHtml` | `function lintContentHtml(contentBase,` | {{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}} The findings, and how many files were read. | Walk a content tree and report raw HTML in every note's prose. |
+| Export            | Signature                               | Returns                                                                                                                                                              | Use it when                                                    |
+| ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `HTML_TAG`        | `const HTML_TAG`                        | —                                                                                                                                                                    | A raw HTML tag, opening, closing or self-closing.              |
+| `htmlMessage`     | `function htmlMessage(tag)`             | {string} The message, unpunctuated at the end as a finding is.                                                                                                       | What a note carrying raw HTML is told.                         |
+| `checkHtml`       | `function checkHtml(body, file,`        | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} One finding per tag, in source order.                                    | Every raw HTML tag in one note's body.                         |
+| `lintContentHtml` | `function lintContentHtml(contentBase,` | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` The findings, and how many files were read. | Walk a content tree and report raw HTML in every note's prose. |
 
 ### `engine.contentEmbeds`
 
 `![[address|label]]` — the wikilink that renders a picture where it stands. An embed is the wikilink the syntax module defines, with `!` meaning _render it here_, and the syntax supplying the default type `image`. It resolves to an ordinary markdown image before any surface renders it, so the figure, the staging list and the directive all come from the image machinery that already exists. An embed reaches asset types only.
 
-| Export               | Signature                                | Returns                                                                                                                                                          | Use it when                                                     |
-| -------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `EMBED_DEFAULT_TYPE` | `const EMBED_DEFAULT_TYPE`               | —                                                                                                                                                                | The type a bare shortcode takes, supplied by the syntax itself. |
-| `EMBED_PATTERN`      | `const EMBED_PATTERN`                    | —                                                                                                                                                                | An embed, as authored, with the directive it may carry.         |
-| `embedsIn`           | `function embedsIn(body)`                | {ParsedEmbed[]} One entry per embed.                                                                                                                             | Every embed in one body, in source order.                       |
-| `resolveEmbed`       | `function resolveEmbed(index, embed)`    | {{pathname: string}\|{reason: string, target: string, type?: string}} The authored pathname, or the finding.                                                     | What one embed resolves to, or why it does not.                 |
-| `embedProblems`      | `function embedProblems(embed)`          | {Array<{link: string, offset: number, message: string}>} One entry per defect.                                                                                   | What is wrong with one embed's directive or placement.          |
-| `resolveEmbeds`      | `function resolveEmbeds(body, ctx)`      | {{markdown: string, unresolved: Array<object>, problems: Array<object>}} The body, the embeds that named nothing, and the directives that could not be honoured. | Rewrite every embed into the image each surface renders.        |
-| `checkEmbeds`        | `function checkEmbeds(body, file, opts)` | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.                    | Every defect in one note's embeds, located.                     |
+| Export               | Signature                                | Returns                                                                                                                                                            | Use it when                                                     |
+| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| `EMBED_DEFAULT_TYPE` | `const EMBED_DEFAULT_TYPE`               | —                                                                                                                                                                  | The type a bare shortcode takes, supplied by the syntax itself. |
+| `EMBED_PATTERN`      | `const EMBED_PATTERN`                    | —                                                                                                                                                                  | An embed, as authored, with the directive it may carry.         |
+| `embedsIn`           | `function embedsIn(body)`                | {ParsedEmbed[]} One entry per embed.                                                                                                                               | Every embed in one body, in source order.                       |
+| `resolveEmbed`       | `function resolveEmbed(index, embed)`    | `{{pathname: string}\|{reason: string, target: string, type?: string}}` The authored pathname, or the finding.                                                     | What one embed resolves to, or why it does not.                 |
+| `embedProblems`      | `function embedProblems(embed)`          | {Array<{link: string, offset: number, message: string}>} One entry per defect.                                                                                     | What is wrong with one embed's directive or placement.          |
+| `resolveEmbeds`      | `function resolveEmbeds(body, ctx)`      | `{{markdown: string, unresolved: Array<object>, problems: Array<object>}}` The body, the embeds that named nothing, and the directives that could not be honoured. | Rewrite every embed into the image each surface renders.        |
+| `checkEmbeds`        | `function checkEmbeds(body, file, opts)` | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.                      | Every defect in one note's embeds, located.                     |
 
 ### `engine.contentImages`
 
-An image saying how wide it is and where it sits. A directive in the curly-attribute convention Pandoc and Kramdown use supplies a width class, a named `size:`, and a `float:` position. The named size sets a maximum display width for each surface.
-
-| Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
-| --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
-| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts.                                  |
-| `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
-| `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
-| `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
-| `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                        | What is wrong with an image's address, or `""` when nothing is.              |
-| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], size: string, float: string, problems: string[]}} What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
-| `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                         | The classes a figure carries, from a parsed directive.                       |
-| `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                       | Text going inside an HTML attribute or between tags.                         |
-| `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                        | One image as the `<figure>` both HTML surfaces render.                       |
-| `standsAlone`         | `function standsAlone(text, start, end)`        | {boolean} Whether the match is a block of its own.                                                                                             | Whether a match sits alone in its own paragraph.                             |
-| `imagesIn`            | `function imagesIn(body)`                       | {Array<{alt: string, src: string, title: string, directive: string, index: number, length: number, block: boolean}>} One entry per image.      | Every image in one body, with its directive and its position.                |
-| `imageSourcesIn`      | `function imageSourcesIn(body)`                 | {string[]} The addresses, with repeats.                                                                                                        | Every image address one body names, in order of appearance.                  |
-| `checkImages`         | `function checkImages(body, file,`              | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.  | Every defect in one note's images.                                           |
-| `lintContentImages`   | `function lintContentImages(contentBase,`       | {{findings: Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>, files: number}} What it found. | Walk a content tree and report every image it cannot render as authored.     |
-| `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                 | Rewrite every block image in a body into the figure the website publishes.   |
-| `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                   | A markdown-it plugin that reads an image's directive and renders its figure. |
+An image saying how wide it is and where it sits. A directive in the curly-attribute convention Pandoc and Kramdown use supplies a width class, a named `size`, and a `float` position. The named size sets a maximum display width for each surface.
+
+| Export                | Signature                                       | Returns                                                                                                                                          | Use it when                                                                  |
+| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                                | The width classes an image may carry, and what each means to a renderer.     |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                                | The named sizes an image directive accepts.                                  |
+| `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                                | The `float` positions an image may take, and where each puts it.             |
+| `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                                | The class every figure carries, whatever its width or position.              |
+| `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                                | A markdown image, with the directive it may carry.                           |
+| `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                          | What is wrong with an image's address, or `""` when nothing is.              |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | `{{classes: string[], size: string, float: string, problems: string[]}}` What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
+| `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                           | The classes a figure carries, from a parsed directive.                       |
+| `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                         | Text going inside an HTML attribute or between tags.                         |
+| `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                          | One image as the `<figure>` both HTML surfaces render.                       |
+| `standsAlone`         | `function standsAlone(text, start, end)`        | {boolean} Whether the match is a block of its own.                                                                                               | Whether a match sits alone in its own paragraph.                             |
+| `imagesIn`            | `function imagesIn(body)`                       | {Array<{alt: string, src: string, title: string, directive: string, index: number, length: number, block: boolean}>} One entry per image.        | Every image in one body, with its directive and its position.                |
+| `imageSourcesIn`      | `function imageSourcesIn(body)`                 | {string[]} The addresses, with repeats.                                                                                                          | Every image address one body names, in order of appearance.                  |
+| `checkImages`         | `function checkImages(body, file,`              | {Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>} One finding per defect, in source order.    | Every defect in one note's images.                                           |
+| `lintContentImages`   | `function lintContentImages(contentBase,`       | `{{findings: Array<{file: string, line: number, column: number\|undefined, severity: "error", message: string}>, files: number}}` What it found. | Walk a content tree and report every image it cannot render as authored.     |
+| `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                   | Rewrite every block image in a body into the figure the website publishes.   |
+| `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                     | A markdown-it plugin that reads an image's directive and renders its figure. |
 
 ### `engine.pathnames`
 
@@ -1032,13 +1097,13 @@ One authored pathname, and the four addresses it resolves to. A note names a fil
 
 Resolving every link in a content tree, and reporting the ones that land nowhere. Three link defects survive both content builds silently, so neither the pack compilers nor a site build catches them:
 
-| Export               | Signature                                                                                | Returns                                                                                                                                                                                                                      | Use it when                                                   |
-| -------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `anchorsOf`          | `function anchorsOf(body)`                                                               | {Set<string>} The declared anchor slugs.                                                                                                                                                                                     | Every `{#anchor}` a note declares on a heading.               |
-| `buildLinkIndex`     | `buildLinkIndex(contentBase, { config, skipDirectories, sqlTables, records, problems })` | {object} The notes, the index, and the resolvers built over it.                                                                                                                                                              | Read a content tree into the index a link resolves against.   |
-| `auditHomepageLinks` | `function auditHomepageLinks(index)`                                                     | {Array<{note: object, field: string, url: string, text: string, occurrence: number, message: string}>} One finding per defect, `text` and `occurrence` locating it in the note's raw source.                                 | Every defect in the addresses a package homepage carries.     |
-| `auditLinks`         | `function auditLinks(index)`                                                             | {{deadAnchors: object[], deadAddresses: object[], unlabelledLinks: object[], frontmatterLinks: object[], homepageLinks: object[], usedManifest: Set<string>}} The findings, and which addresses a foreign manifest answered. | Every link in a tree that lands nowhere.                      |
-| `walkReachability`   | `function walkReachability(index,`                                                       | {{root: object, reached: Set<object>, orphans: object[]}} The root, everything reached from it, and the corpus members that were not.                                                                                        | Walk a corpus from its root and report what nothing links to. |
+| Export               | Signature                                                                                | Returns                                                                                                                                                                                                                        | Use it when                                                   |
+| -------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| `anchorsOf`          | `function anchorsOf(body)`                                                               | {Set<string>} The declared anchor slugs.                                                                                                                                                                                       | Every `{#anchor}` a note declares on a heading.               |
+| `buildLinkIndex`     | `buildLinkIndex(contentBase, { config, skipDirectories, sqlTables, records, problems })` | {object} The notes, the index, and the resolvers built over it.                                                                                                                                                                | Read a content tree into the index a link resolves against.   |
+| `auditHomepageLinks` | `function auditHomepageLinks(index)`                                                     | {Array<{note: object, field: string, url: string, text: string, occurrence: number, message: string}>} One finding per defect, `text` and `occurrence` locating it in the note's raw source.                                   | Every defect in the addresses a package homepage carries.     |
+| `auditLinks`         | `function auditLinks(index)`                                                             | `{{deadAnchors: object[], deadAddresses: object[], unlabelledLinks: object[], frontmatterLinks: object[], homepageLinks: object[], usedManifest: Set<string>}}` The findings, and which addresses a foreign manifest answered. | Every link in a tree that lands nowhere.                      |
+| `walkReachability`   | `function walkReachability(index,`                                                       | `{{root: object, reached: Set<object>, orphans: object[]}}` The root, everything reached from it, and the corpus members that were not.                                                                                        | Walk a corpus from its root and report what nothing links to. |
 
 ### `engine.webWikilinks`
 
@@ -1051,44 +1116,40 @@ Wikilink resolution for the knowledgebase build. The same authored links the pac
 
 ### `engine.contentTables`
 
-Generated content tables from fenced `dataview` `TABLE` queries. A catalog table (every cloth armour, every animal's abilities) is data that already lives in the frontmatter of the notes it describes. Authoring such a table by hand duplicates that data and guarantees drift, so a content body instead declares what it wants tabulated, in a fenced `dataview` block:
+Prepared SQL content tables are expanded into Markdown before link resolution.
+A query selecting no rows reports an error unless its fence states
+`{allow-empty=true}`.
 
-| Export                | Signature                                                                    | Returns                                                                                                                                                            | Use it when                                                                                                                                                                                                                 |
-| --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `parseDataviewQuery`  | `function parseDataviewQuery(source)`                                        | {{columns: Array<{header: string, expr: object}>, from: object\|null, where: object\|null, sort: Array<{expr: object, descending: boolean}>, limit: number\|null}} | Parse one `dataview` block's query.                                                                                                                                                                                         |
-| `resolveField`        | `function resolveField(doc, path)`                                           | {unknown} `null` when the note has no such field.                                                                                                                  | Resolve a dotted path against a content note.                                                                                                                                                                               |
-| `evaluate`            | `function evaluate(node, doc, self)`                                         | {unknown}                                                                                                                                                          | Evaluate one parsed expression against a note.                                                                                                                                                                              |
-| `selectRows`          | `function selectRows(spec, docs, self)`                                      | {Array<ContentTableDoc>} The matching notes, sorted and limited.                                                                                                   | The notes a query selects, in the order its `SORT` keys give.                                                                                                                                                               |
-| `renderContentTable`  | `function renderContentTable(spec, rows, linkable, self)`                    | {string} The markdown table (no trailing newline).                                                                                                                 | Build the markdown table for one query.                                                                                                                                                                                     |
-| `expandContentTables` | `expandContentTables(markdown, { docs, linkable, source, self, sqlTables })` | `{markdown: string, errors: object[], lineMap: object[], warnings: object[]}`                                                                                      | expanding every fenced `dataview` block in a markdown body; a block that cannot be honoured is left verbatim and reported in `errors` rather than failing the build, and a query matching no note renders as an empty table |
+| Export                | Signature                                              | Returns                                                                       | Use it when                                                |
+| --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `expandContentTables` | `expandContentTables(markdown, { source, sqlTables })` | `{markdown: string, errors: object[], lineMap: object[], warnings: object[]}` | Replace prepared SQL fences and preserve source locations. |
 
 ### `engine.helpers`
 
-Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLands vault is authoritative for compendium item data. Pack compilers walk the vault, read markdown files with YAML frontmatter, and emit Foundry-compatible JSON. These helpers handle the common shape: markdown parsing, frontmatter access (including the nested `sohl:` block), filename generation, and slug normalization.
-
-| Export                    | Signature                                                                                                   | Returns                                                                                                                                                                                                                                 | Use it when                                                                                                                                                                                          |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `md`                      | `const md`                                                                                                  | —                                                                                                                                                                                                                                       | The markdown renderer every surface shares.                                                                                                                                                          |
-| `renderFoundryMarkdown`   | `function renderFoundryMarkdown(body)`                                                                      | `string` — HTML with secret sections for GM passages.                                                                                                                                                                                   | Rendering a note body for a Foundry document.                                                                                                                                                        |
-| `parseMarkdownFile`       | `function parseMarkdownFile(filePath)`                                                                      | —                                                                                                                                                                                                                                       | Parses a markdown file with YAML frontmatter.                                                                                                                                                        |
-| `assertStatedScope`       | `function assertStatedScope(skipDirectories, who)`                                                          | {void}                                                                                                                                                                                                                                  | Refuse a corpus read whose scope its caller did not state.                                                                                                                                           |
-| `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).                                                     |
-| `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.                                                                                                                              |
-| `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.                                                                                                                                              |
-| `statsForPack`            | `function statsForPack(packSystem, config`                                                                  | {object} The `_stats` block for that pack.                                                                                                                                                                                              | The `_stats` block for one pack, stamped with the system that pack is for.                                                                                                                           |
-| `defaultStats`            | `function defaultStats()`                                                                                   | {object} The default `_stats` block, shared by every compiler.                                                                                                                                                                          | The `_stats` block every compiler stamps on an entry it emits, built once.                                                                                                                           |
-| `buildContentLinkIndex`   | `buildContentLinkIndex(contentBase, router, { skipDirectories, config, records, problems })`                | {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.                                                                                                                                                                             | Indexes **every** note in the content tree so any pack compiler can resolve a wikilink to any other document.                                                                                        |
-| `convertNoteWikilinks`    | `convertNoteWikilinks(body, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap })` | {{markdown: string, unresolved: Array<object>}}                                                                                                                                                                                         | Converts the wikilinks in one note's markdown, reporting any that have no target in the content tree.                                                                                                |
-| `collectContentDocs`      | `collectContentDocs(contentBase, { skipDirectories, config, records, problems })`                           | {Array<{fm: object, path: string, tld: string, folder: string, absPath: string}>}                                                                                                                                                       | Every note in the content tree, in the shape the `dataview` table expander searches: its frontmatter plus where it sits in the tree.                                                                 |
-| `expandNoteTables`        | `function expandNoteTables(body,`                                                                           | {{markdown: string, lineMap: Array<{line: number, generated: boolean}>}} The body with every table expanded, and where each emitted line came from — which is what lets a diagnostic about the expanded body name an authored position. | Expand the fenced `dataview` tables in one note's markdown, before wikilinks are resolved — so a generated cell may itself be a wikilink.                                                            |
-| `folderFilename`          | `function folderFilename(name, id)`                                                                         | —                                                                                                                                                                                                                                       | Builds a compendium-source filename for a folder JSON document: `folder_Name_id.json` with non-alphanumeric runs replaced by underscores.                                                            |
-| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories })`                                                            | generator yielding `{frontmatter, body, description, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                            | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
+Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLands vault is authoritative for compendium item data. Pack compilers walk the vault, read markdown files with YAML frontmatter, and emit Foundry-compatible JSON. These helpers handle the common shape: markdown parsing, frontmatter access (including the nested `sohl:` block), filename generation, and slug normalization.
+
+| Export                    | Signature                                                                                                   | Returns                                                                                                                                                                                                                                   | Use it when                                                                                                                                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `md`                      | `const md`                                                                                                  | —                                                                                                                                                                                                                                         | The markdown renderer every surface shares.                                                                                                                                                          |
+| `renderFoundryMarkdown`   | `function renderFoundryMarkdown(body)`                                                                      | `string` — HTML with secret sections for GM passages.                                                                                                                                                                                     | Rendering a note body for a Foundry document.                                                                                                                                                        |
+| `parseMarkdownFile`       | `function parseMarkdownFile(filePath)`                                                                      | —                                                                                                                                                                                                                                         | Parses a markdown file with YAML frontmatter.                                                                                                                                                        |
+| `assertStatedScope`       | `function assertStatedScope(skipDirectories, who)`                                                          | {void}                                                                                                                                                                                                                                    | Refuse a corpus read whose scope its caller did not state.                                                                                                                                           |
+| `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).                                                     |
+| `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.                                                                                                                              |
+| `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.                                                                                                                                              |
+| `statsForPack`            | `function statsForPack(packSystem, config`                                                                  | {object} The `_stats` block for that pack.                                                                                                                                                                                                | The `_stats` block for one pack, stamped with the system that pack is for.                                                                                                                           |
+| `defaultStats`            | `function defaultStats()`                                                                                   | {object} The default `_stats` block, shared by every compiler.                                                                                                                                                                            | The `_stats` block every compiler stamps on an entry it emits, built once.                                                                                                                           |
+| `buildContentLinkIndex`   | `buildContentLinkIndex(contentBase, router, { skipDirectories, config, records, problems })`                | `{{byShortcode: Map, types: Set}}` From `buildWikilinkIndex`.                                                                                                                                                                             | Indexes **every** note in the content tree so any pack compiler can resolve a wikilink to any other document.                                                                                        |
+| `convertNoteWikilinks`    | `convertNoteWikilinks(body, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap })` | `{{markdown: string, unresolved: Array<object>}}`                                                                                                                                                                                         | Converts the wikilinks in one note's markdown, reporting any that have no target in the content tree.                                                                                                |
+| `expandNoteTables`        | `function expandNoteTables(body,`                                                                           | `{{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}` The body with every table expanded, and where each emitted line came from — which is what lets a diagnostic about the expanded body name an authored position. | Expand prepared SQL tables in one note's markdown, before wikilinks are resolved — so a generated cell may itself be a wikilink.                                                                     |
+| `folderFilename`          | `function folderFilename(name, id)`                                                                         | —                                                                                                                                                                                                                                         | Builds a compendium-source filename for a folder JSON document: `folder_Name_id.json` with non-alphanumeric runs replaced by underscores.                                                            |
+| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories })`                                                            | generator yielding `{frontmatter, body, description, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                              | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
 
 ### `engine.itemRegistry`
 
@@ -1137,9 +1198,9 @@ Wikilink resolution for the pack compilers. Content notes link to one another wi
 | `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads an accepted `doc<type>` input alias as its authored type.                                                                                                            |
 | `readQualifier`      | `function readQualifier(target, types, packages, noIndexPackages)`      | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"\|"no-content-index", package?: string} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type or no fetched index; or `null` when it is not an address at all. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
 | `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
-| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                     | Builds the link-resolution tables for a content tree.                                                                                                                      |
+| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | `{{byShortcode: Map<string, object>, types: Set<string>}}` `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                   | Builds the link-resolution tables for a content tree.                                                                                                                      |
 | `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                                          | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
-| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                      | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
+| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | `{{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}}` Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                    | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
 
 ### `engine.wikilinkSyntax`
 
@@ -1161,7 +1222,9 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 
 ### `engine.siteIndex`
 
-**The address index a site build resolves its wikilinks against.** Every consumer that publishes a content tree as a website has to answer the same question — given `[[Something]]`, which page? — and every one of them answered it with its own copy of the same 150 lines. `sohl`'s and `sohl-thalorna`'s site builds still share 147 identical lines of it, comments and indentation aside. This is that shared half, lifted out whole.
+**The address index a site build resolves its wikilinks against.**
+`buildSiteIndex` gathers addressable pages and ambiguity findings. `wikiContext`
+provides the per-page context used when resolving a link such as `[[Something]]`.
 
 | Export              | Signature                                          | Returns                                                                                                                        | Use it when                                                                                                  |
 | ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
@@ -1173,12 +1236,12 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 
 The document tree a PDF is built from, and the plan it resolves to. The packs and the website both render the _whole_ content tree: every note becomes a document and a page, and the three surfaces agreeing about what the content is, is the point. **A book is not that.** It is a selection — a declared structure whose leaves pick notes out of the corpus by a `WHERE` clause, interleaved with prose that may not live in the content tree at all.
 
-| Export              | Signature                                  | Returns                                                                                                                                                              | Use it when                                                        |
-| ------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `PRESENTATION_KEYS` | `const PRESENTATION_KEYS`                  | —                                                                                                                                                                    | Presentation a node may declare, and that its descendants inherit. |
-| `parseDocumentTree` | `function parseDocumentTree(raw,`          | {{nodes: object[], findings: object[]}} The flattened tree and what was wrong with it.                                                                               | Validate the raw tree and flatten it into nodes.                   |
-| `runTreeFilters`    | `async function runTreeFilters(nodes, db,` | {Promise<{selections: Map<string, object[]>, findings: object[]}>}                                                                                                   | Run every filter, and report the ones that would not run.          |
-| `planDocument`      | `function planDocument(nodes,`             | {{entries: object[], links: Map<string, string>, stats: object}} The plan, the address→anchor map inbound wikilinks resolve through, and what the selection came to. | Resolve the flattened tree into the document plan.                 |
+| Export              | Signature                                  | Returns                                                                                                                                                                | Use it when                                                        |
+| ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `PRESENTATION_KEYS` | `const PRESENTATION_KEYS`                  | —                                                                                                                                                                      | Presentation a node may declare, and that its descendants inherit. |
+| `parseDocumentTree` | `function parseDocumentTree(raw,`          | `{{nodes: object[], findings: object[]}}` The flattened tree and what was wrong with it.                                                                               | Validate the raw tree and flatten it into nodes.                   |
+| `runTreeFilters`    | `async function runTreeFilters(nodes, db,` | {Promise<{selections: Map<string, object[]>, findings: object[]}>}                                                                                                     | Run every filter, and report the ones that would not run.          |
+| `planDocument`      | `function planDocument(nodes,`             | `{{entries: object[], links: Map<string, string>, stats: object}}` The plan, the address→anchor map inbound wikilinks resolve through, and what the selection came to. | Resolve the flattened tree into the document plan.                 |
 
 ### `engine.pdfRender`
 
@@ -1217,7 +1280,7 @@ The content tree, built into a book. The I/O half of the PDF surface: it reads t
 | `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.                                   |
+| `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.             |
@@ -1265,29 +1328,29 @@ Macros pack compiler — produces JSON pack files for the "macros" Foundry compe
 
 **Map notes** — the markdown → Foundry `Scene` translation. A map note carries an _essence_: a curated, hand-owned subset of what a Scene record holds, exactly as a weapon note carries a weapon's essence rather than an Item's schema. Everything a Scene needs and nobody should have to author — the canvas defaults, the embedded `Level`, every derived region field — is synthesised here.
 
-| Export                         | Signature                                       | Returns                                                                                    | Use it when                                                                                  |
-| ------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
-| `isMapType`                    | `function isMapType(type)`                      | {boolean} True for a map type.                                                             | Whether a content note's type compiles into a Scene.                                         |
-| `MAP_SUBTYPE_PROFILES`         | `const MAP_SUBTYPE_PROFILES`                    | —                                                                                          | Per-subtype canvas defaults, emitted **explicitly** on every scene.                          |
-| `mapProfile`                   | `function mapProfile(subType)`                  | {object} The profile from {@link MAP_SUBTYPE_PROFILES}.                                    | The canvas profile for a map subType.                                                        |
-| `DEFAULT_LEVEL_ID`             | `const DEFAULT_LEVEL_ID`                        | —                                                                                          | Foundry's own id for the level a scene is created with (`Scene.metadata.defaultLevelId`).    |
-| `regionDocId`                  | `function regionDocId(sceneId, key, pinned)`    | {string} A 16-character Foundry id.                                                        | The id of one region within its scene.                                                       |
-| `behaviorDocId`                | `function behaviorDocId(regionId, key, pinned)` | {string} A 16-character Foundry id.                                                        | The id of one behaviour within its region.                                                   |
-| `regionColor`                  | `function regionColor(key)`                     | {string} A CSS hex colour.                                                                 | A region's highlight colour, derived from its key.                                           |
-| `assertPixelGeometry`          | `function assertPixelGeometry(coords, geom)`    | —                                                                                          | Reject geometry authored in grid squares where pixels belong.                                |
-| `assertGridLocation`           | `function assertGridLocation(at, geom)`         | —                                                                                          | Reject a map pin authored in pixels where grid squares belong.                               |
-| `wallRestrictions`             | `function wallRestrictions(spec, label)`        | {{move: number, sight: number, light: number, sound: number}} The Wall restriction fields. | Compile a wall's `blocks:` / `limits:` lists into Foundry's four numeric restriction fields. |
-| `buildShape`                   | `function buildShape(spec, geom)`               | {object} The Foundry shape record.                                                         | Compile one authored shape into a Foundry shape record.                                      |
-| `REGION_BEHAVIOR_TYPES`        | `const REGION_BEHAVIOR_TYPES`                   | —                                                                                          | The behaviour types a map note may carry (v1).                                               |
-| `BANNED_REGION_BEHAVIOR_TYPES` | `const BANNED_REGION_BEHAVIOR_TYPES`            | —                                                                                          | Behaviour types a map note may **never** carry, and why.                                     |
-| `buildScene`                   | `function buildScene(fm, ctx)`                  | {object} The Scene document, keyed for the pack.                                           | Compile a map note into a Scene document, embedded documents and all.                        |
-| `buildLevel`                   | `function buildLevel(sohl, sceneId, img`        | {object} The Level document, keyed for the pack.                                           | Synthesise the scene's single embedded Level from `img:` / `overlay:`.                       |
-| `buildWalls`                   | `function buildWalls(sohl, geom, ctx)`          | {object[]} The Wall documents.                                                             | Compile the `walls:` and `doors:` blocks into Wall documents.                                |
-| `buildLights`                  | `function buildLights(sohl, geom, ctx)`         | {object[]} The AmbientLight documents.                                                     | Compile the `lights:` block into AmbientLight documents.                                     |
-| `buildTiles`                   | `function buildTiles(sohl, geom, ctx)`          | {object[]} The Tile documents.                                                             | Compile the `tiles:` block into Tile documents.                                              |
-| `buildSounds`                  | `function buildSounds(sohl, geom, ctx)`         | {object[]} The AmbientSound documents.                                                     | Compile the `sounds:` block into AmbientSound documents.                                     |
-| `buildLocations`               | `function buildLocations(sohl, geom, ctx)`      | {object[]} The Note documents.                                                             | Compile the `locations:` block into Note documents — the map pins.                           |
-| `buildRegions`                 | `function buildRegions(sohl, geom, ctx)`        | {object[]} The Region documents.                                                           | Compile the `regions:` block into Region documents with their behaviours.                    |
+| Export                         | Signature                                       | Returns                                                                                      | Use it when                                                                                  |
+| ------------------------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `isMapType`                    | `function isMapType(type)`                      | {boolean} True for a map type.                                                               | Whether a content note's type compiles into a Scene.                                         |
+| `MAP_SUBTYPE_PROFILES`         | `const MAP_SUBTYPE_PROFILES`                    | —                                                                                            | Per-subtype canvas defaults, emitted **explicitly** on every scene.                          |
+| `mapProfile`                   | `function mapProfile(subType)`                  | {object} The profile from {@link MAP_SUBTYPE_PROFILES}.                                      | The canvas profile for a map subType.                                                        |
+| `DEFAULT_LEVEL_ID`             | `const DEFAULT_LEVEL_ID`                        | —                                                                                            | Foundry's own id for the level a scene is created with (`Scene.metadata.defaultLevelId`).    |
+| `regionDocId`                  | `function regionDocId(sceneId, key, pinned)`    | {string} A 16-character Foundry id.                                                          | The id of one region within its scene.                                                       |
+| `behaviorDocId`                | `function behaviorDocId(regionId, key, pinned)` | {string} A 16-character Foundry id.                                                          | The id of one behaviour within its region.                                                   |
+| `regionColor`                  | `function regionColor(key)`                     | {string} A CSS hex colour.                                                                   | A region's highlight colour, derived from its key.                                           |
+| `assertPixelGeometry`          | `function assertPixelGeometry(coords, geom)`    | —                                                                                            | Reject geometry authored in grid squares where pixels belong.                                |
+| `assertGridLocation`           | `function assertGridLocation(at, geom)`         | —                                                                                            | Reject a map pin authored in pixels where grid squares belong.                               |
+| `wallRestrictions`             | `function wallRestrictions(spec, label)`        | `{{move: number, sight: number, light: number, sound: number}}` The Wall restriction fields. | Compile a wall's `blocks:` / `limits:` lists into Foundry's four numeric restriction fields. |
+| `buildShape`                   | `function buildShape(spec, geom)`               | {object} The Foundry shape record.                                                           | Compile one authored shape into a Foundry shape record.                                      |
+| `REGION_BEHAVIOR_TYPES`        | `const REGION_BEHAVIOR_TYPES`                   | —                                                                                            | The behaviour types a map note may carry (v1).                                               |
+| `BANNED_REGION_BEHAVIOR_TYPES` | `const BANNED_REGION_BEHAVIOR_TYPES`            | —                                                                                            | Behaviour types a map note may **never** carry, and why.                                     |
+| `buildScene`                   | `function buildScene(fm, ctx)`                  | {object} The Scene document, keyed for the pack.                                             | Compile a map note into a Scene document, embedded documents and all.                        |
+| `buildLevel`                   | `function buildLevel(sohl, sceneId, img`        | {object} The Level document, keyed for the pack.                                             | Synthesise the scene's single embedded Level from `img:` / `overlay:`.                       |
+| `buildWalls`                   | `function buildWalls(sohl, geom, ctx)`          | {object[]} The Wall documents.                                                               | Compile the `walls:` and `doors:` blocks into Wall documents.                                |
+| `buildLights`                  | `function buildLights(sohl, geom, ctx)`         | {object[]} The AmbientLight documents.                                                       | Compile the `lights:` block into AmbientLight documents.                                     |
+| `buildTiles`                   | `function buildTiles(sohl, geom, ctx)`          | {object[]} The Tile documents.                                                               | Compile the `tiles:` block into Tile documents.                                              |
+| `buildSounds`                  | `function buildSounds(sohl, geom, ctx)`         | {object[]} The AmbientSound documents.                                                       | Compile the `sounds:` block into AmbientSound documents.                                     |
+| `buildLocations`               | `function buildLocations(sohl, geom, ctx)`      | {object[]} The Note documents.                                                               | Compile the `locations:` block into Note documents — the map pins.                           |
+| `buildRegions`                 | `function buildRegions(sohl, geom, ctx)`        | {object[]} The Region documents.                                                             | Compile the `regions:` block into Region documents with their behaviours.                    |
 
 ### `engine.scenes`
 
@@ -1376,14 +1439,12 @@ The SoHL-specific half of the toolchain: the knowledge of the Song of Heroic Lan
 Every module beneath `./sohl` is also reachable as its own entry point, e.g. `@heroiclands/package-build/sohl/being-info`.
 
 ```js
-import { isBeing, GEAR_TYPE_TO_KEY, deriveBeingInfo } from "@heroiclands/package-build/sohl";
+import { isBeing, GEAR_TYPE_TO_KEY } from "@heroiclands/package-build/sohl";
 
 console.log(isBeing({ type: "being" }));
 // -> true
 console.log(GEAR_TYPE_TO_KEY.weapongear);
 // -> "weapons"
-console.log(deriveBeingInfo({ items: [] }, new Map()));
-// -> { items: [] }
 ```
 
 ### `sohl.itemBuilders`
@@ -1448,15 +1509,14 @@ The `sohl` knowledgebase's own body pass: a rewrite driven by a TypeDoc symbol m
 
 ### Flat exports (not under a namespace)
 
-| Export                  | Signature                      | Returns                           | Use it when                                                                                                                                                                                       |
-| ----------------------- | ------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `DEFAULT_ITEM_ART`      | `const DEFAULT_ITEM_ART`       | —                                 | reading the full map of default item artwork keyed by SoHL Item document subtype — the single source both the compendium builder and the runtime `SohlItem.getDefaultArtwork` read                |
-| `defaultItemArt`        | `defaultItemArt(type)`         | `string` — the default image path | getting the default art path for a document subtype, throwing (fail-fast) rather than defaulting silently when the type is unknown                                                                |
-| `AFFILIATION_STANDINGS` | `const AFFILIATION_STANDINGS`  | —                                 | reading the closed set of stances an authored `relation` map may use between two affiliations                                                                                                     |
-| `BEING_TYPE`            | `const BEING_TYPE`             | —                                 | the one note `type` value (`"being"`) whose pages carry a being info block; the retired `character`/`creature` spellings are deliberately not accepted here                                       |
-| `GEAR_TYPE_TO_KEY`      | `const GEAR_TYPE_TO_KEY`       | —                                 | mapping a gear note type (`weapongear`, `armorgear`, …) to the sidebar heading it displays under (`weapons`, `armor`, …)                                                                          |
-| `isBeing`               | `isBeing(fm)`                  | `boolean`                         | checking whether a note's frontmatter describes a being, using the one shared definition instead of a per-repository copy                                                                         |
-| `deriveBeingInfo`       | `deriveBeingInfo(sohl, index)` | `object\|null\|undefined`         | deriving a being's info-block fields (`skills`, `gear`, `spells`, `talents`) from its raw embedded `sohl.items[]`, resolved against a content index; authored values always win over derived ones |
+| Export                  | Signature                     | Returns                           | Use it when                                                                                                                                                                        |
+| ----------------------- | ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEFAULT_ITEM_ART`      | `const DEFAULT_ITEM_ART`      | —                                 | reading the full map of default item artwork keyed by SoHL Item document subtype — the single source both the compendium builder and the runtime `SohlItem.getDefaultArtwork` read |
+| `defaultItemArt`        | `defaultItemArt(type)`        | `string` — the default image path | getting the default art path for a document subtype, throwing (fail-fast) rather than defaulting silently when the type is unknown                                                 |
+| `AFFILIATION_STANDINGS` | `const AFFILIATION_STANDINGS` | —                                 | reading the closed set of stances an authored `relation` map may use between two affiliations                                                                                      |
+| `BEING_TYPE`            | `const BEING_TYPE`            | —                                 | identifying the note type `"being"`                                                                                                                                                |
+| `GEAR_TYPE_TO_KEY`      | `const GEAR_TYPE_TO_KEY`      | —                                 | mapping each gear note type to its infobox group                                                                                                                                   |
+| `isBeing`               | `isBeing(fm)`                 | `boolean`                         | checking whether a note's frontmatter describes a being                                                                                                                            |
 
 ## `./hm3`
 
@@ -1567,14 +1627,13 @@ const config = defineConfig({
 | `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                                                                                                |
-| `SITE_MODES`               | `const SITE_MODES`                 | —                                                          | reading the publishing modes `publish.site` may name, weakest first                                                                                                                                                                      |
 | `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
-| `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether a resolved configuration publishes the pages its content tree compiles to — the one question the site build and the content index both need answered identically                                                        |
+| `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                                  |
 
 ## `./config`
 
-The per-repository **packaging** configuration — `packageBuild:` within the same `package-build.config.yaml` that `content-config` validates the rest of. Read through the content half's loader rather than a second file, so `packageKind` and `foundryPackage` are stated once. The two halves validate independently but share one document.
+The per-repository **packaging** configuration is the `packageBuild:` section of `package-build.config.yaml`. The content configuration loader reads the same file, so `packageKind` and `foundryPackage` are declared once. The content and packaging validators each check their own keys.
 
 ```js
 // Run from a consuming repository's root, where package-build.config.yaml lives.
@@ -1589,12 +1648,12 @@ console.log(config.stageDir);
 | `DERIVED_MANIFEST_KEYS`     | `const DERIVED_MANIFEST_KEYS`             | —                              | reading which manifest keys a repository may not declare because the build derives them (declaring one is an error naming the key)                                              |
 | `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
 | `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
-| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `content-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
+| `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `package-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
 | `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                          |
 
 ## `./prettier`
 
-The shared Prettier configuration, published as a Prettier config module so an editor's format-on-save agrees with `content-build format`, which already applies these rules without a consumer declaring anything.
+The shared Prettier configuration, published as a Prettier config module so an editor's format-on-save agrees with `package-build format`, which already applies these rules without a consumer declaring anything.
 
 ```js
 // prettier.config.mjs
@@ -1607,7 +1666,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 `content-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 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
@@ -1841,6 +1900,7 @@ console.log(missingSources([["does/not/exist", "x"]]));
 | `missingSources`      | `missingSources(entries, cwd = process.cwd())`                               | `string[]`                         | checking a whole `[source, dest]` list for absent sources up front, so every problem is reported at once rather than one rebuild at a time |
 | `copyTree`            | `copyTree(src, dest, { transform } = {})`                                    | `number` — files written           | recursively copying a file or directory, optionally rewriting each file's content as it's staged instead of copying bytes verbatim         |
 | `stageAssets`         | `stageAssets(entries, { cwd = process.cwd(), transform } = {})`              | `{entries: number, files: number}` | copying every listed `[source, dest]` pair into the stage, refusing to start at all if any source is absent                                |
+| `resetStage`          | `resetStage(root, stageDir)`                                                 | `boolean` — whether stage existed  | clearing the assembled package before a complete build while preserving other generated outputs                                            |
 | `cleanBuildArtifacts` | `cleanBuildArtifacts(root, { extra = [], includeNodeModules = false } = {})` | `string[]` — directories removed   | removing the build artefacts a repository regenerates, safely repeatable since an already-clean directory is not an error                  |
 
 ## `./templates`