@heroiclands/package-build 23.8.0 → 23.10.0

package/docs/api.md

@@ -426,7 +426,14 @@ Drawing a declared infobox: HTML for separate Foundry pages appended after autho
 
 ### `engine.noteState`
 
-The three states of a note — **stub**, **draft**, **full** — and the one observable fact they rest on. A note whose body is empty is a stub: it carries its facts into the index and is queryable there, and it has no page, no address and no link target. Nothing is stored: the ladder is derived once in the SQL `entries` view and no note can assert its own state.
+The three states of a note — **stub**, **draft**, **full** — describe its page
+content. A stubbable note with an empty body and no generated Dictionary or
+Glossary content is a stub: its facts remain queryable in the index, but it
+has no page, address or link target. `isStubNote` recognizes nonempty lexical
+frontmatter as generated content, so collectors retain the resulting page.
+That lexical frontmatter supplies content without an authored body.
+The ladder is derived in the SQL `entries` view; a note cannot assert its own
+state.
 
 | Export                | Signature                                   | Returns                                 | Use it when                                                                                                                                               |
 | --------------------- | ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -458,12 +465,12 @@ What a draft note says about itself, in one sentence, on every surface it reache
 
 ### `engine.stubLint`
 
-Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. A `folder` note is held only to the nonempty rule: any body, placeholder or short, passes with or without `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
+Nonempty `data.words` on a `skill`/`language` note, or `data.glossary` on a culture or affiliation, supplies content without an authored body. Absent or empty arrays supply no such exemption. Every other typed note must have a nonempty body: empty and whitespace-only bodies are errors regardless of description or `draft` tag, including `folder` and `homepage`. Nonempty placeholder-only bodies still produce errors, including on lexical notes. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. A `folder` note is held only to the nonempty rule: any body, placeholder or short, passes with or without `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing.
 
-| Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
-| ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `SHORT_BODY_WORDS` | `const SHORT_BODY_WORDS`                                   | `number`                                            | reading the word count below which an unmarked body is asked whether it is a draft            |
-| `lintNoteStates`   | `lintNoteStates(contentBase, { records, contentPackage })` | `{findings, counts, byType, oldestDrafts, summary}` | checking a tree's states and counting the ladder, from the corpus the command already derived |
+| Export             | Signature                                                          | Returns                                             | Use it when                                                                                   |
+| ------------------ | ------------------------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `SHORT_BODY_WORDS` | `const SHORT_BODY_WORDS`                                           | `number`                                            | reading the word count below which an unmarked body is asked whether it is a draft            |
+| `lintNoteStates`   | `lintNoteStates(contentBase, { records, contentPackage, parsed })` | `{findings, counts, byType, oldestDrafts, summary}` | checking a tree's states and counting the ladder, from the corpus the command already derived |
 
 ### `engine.placeRelations`
 
@@ -861,45 +868,308 @@ The published content index — the artifact packages exchange addresses through
 
 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`             | `anchorsOf(entryUuid, entryId, body, name, syntax?)`    | {Record<string, string>} The anchors.                                                                                        | Every anchor of a note's journal, as `anchorName → Foundry target`. |
+| `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.        |
+
+A generated dictionary headword maps to its containing page's UUID followed
+by its word fragment. Other authored spans keep their containing-page
+mapping.
+
+### `engine.contentSession`
+
+One invocation's content capture and lazy prepared views. Import the namespace
+from `@heroiclands/package-build/engine`, or import the functions directly from
+`@heroiclands/package-build/engine/content-session`.
+
+| Export                 | Signature                                | Returns                    | Use it when                                    |
+| ---------------------- | ---------------------------------------- | -------------------------- | ---------------------------------------------- |
+| `CONTENT_TARGETS`      | `readonly [index, lint, links, compile]` | the closed execution order | Selecting operations in a shared invocation.   |
+| `createContentSession` | `createContentSession(options?)`         | `Promise<ContentSession>`  | Sharing source work across content operations. |
+
+Options are the resolved `config`, `contentBase`, `assetsBase`,
+`skipDirectories` and compile `router`. Paths and scope default from that
+configuration. The session binds its exact configuration object, canonical
+roots, directory scope and router. `assertContext(options?)` refuses reuse
+with a different bound value. A new invocation, an input edit, a changed
+dependency cache or a changed configuration needs a fresh session; no state
+is persisted or shared across sessions.
+
+The session exposes `config`, `contentBase`, `assetsBase`, `skipDirectories`,
+`router`, physical `inventory`, raw `sources`, derived `records`, authored
+`parsed` notes, preparation `problems` and captured dependency `foreign`
+views. Treat these inputs as read-only. Parsed notes retain exact `raw`
+strings, trimmed `body`, authored `frontmatter` and file coordinates; malformed
+or untyped physical files remain available to raw checks. Derivation and
+publication use their own record projections, including per-system clones.
+
+| Method                    | Result and scope                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `syntax(text)`            | Memoized block, alert and span scanner results for that exact string; a different projection has its own positions. |
+| `sqlTables(audience?)`    | Prepared SQL and generated sections for `all` (default) or `public`, once per audience in this context.             |
+| `linkTables()`            | Source-audience results selected for prose-link checking.                                                           |
+| `audit(kind?)`            | The diagnostic link index for `links` (default) or `lint`; this stays separate from routed native resolution.       |
+| `publication()`           | The complete `PreparedContentIndex`, including source-audience and native bodies.                                   |
+| `compileCorpus()`         | Records, parsed notes, native SQL, scanner projections and the routed compiler link index.                          |
+| `prepare(targets)`        | Prepare selected closed targets in `CONTENT_TARGETS` order before a caller starts a writer; returns the session.    |
+| `assertContext(options?)` | Check configuration, roots, scope and router against the captured context.                                          |
+| `dispose()`               | Invalidate derived views and methods at the end of the invocation.                                                  |
+
+SQL query answers remain local to each audience preparation; their databases
+close inside preparation. The session reuses results without sharing a public
+answer with the complete native corpus. Scanner results are also read-only.
+`prepare` refuses writers when shared source preparation or the existing note
+state preflight fails. Ordinary lint findings add no gate to compilation.
+
+```js
+import { contentSession, contentIndex, compendiums } from "@heroiclands/package-build/engine";
+
+const session = await contentSession.createContentSession({ config });
+try {
+  await session.prepare(["index", "compile"]);
+  contentIndex.emitContentIndex({ config, publication: await session.publication() });
+  await compendiums.compilePacks({ config, session });
+} finally {
+  session.dispose();
+}
+```
+
+### `engine/content-sources.mjs`
+
+Reachable through `@heroiclands/package-build/engine/content-sources`; the
+session uses these physical input adapters without adding a namespace export.
+
+| Export                  | Signature                                                            | Returns                          | Use it when                                                  |
+| ----------------------- | -------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------ |
+| `captureContentSources` | `captureContentSources(contentBase, assetsBase, skipDirectories)`    | `{sources, indexSources, paths}` | Capturing exact text and physical path walks before parsing. |
+| `capturedSources`       | `capturedSources(contentBase, sources, skipDirectories, extensions)` | generator of `[file, raw]`       | Selecting a raw checker's physical scope from captured text. |
+
+`sources` maps absolute text-file paths to `{raw}`. `indexSources` retains the
+index walk's selected Markdown order. `paths` retains `{root, file, name,
+directory}` for each physical walk, including its root identity so overlapping
+content and asset scopes preserve their own filtering and order.
+
+### `engine/first-use.mjs`
+
+Import from `@heroiclands/package-build/engine/first-use`.
+
+| Export                  | Signature                                                               | Returns                  | Use it when                                                                    |
+| ----------------------- | ----------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------ |
+| `createFirstUseChecker` | `createFirstUseChecker({ records, index, catalog?, parsed?, syntax? })` | `checker({ file, raw })` | Checking authored prose against the current corpus's name-marking conventions. |
+
+Construct one checker with the session's read-only `records` and
+`await session.audit("lint")`. Call it for each existing link-index note.
+It performs no I/O and returns `{file, line, column, severity: "warning",
+rules, message}` diagnostics. `rules` is a list of applicable rule names, merged
+into one warning for each occurrence; the message names the full name or
+explicit label that needs attention. Only `.name` spans and authored link
+labels enter name tracking; plain text is not searched. Indexed full names and
+declared aliases share an identity, while other labels use their whole text.
+A whole bold indexed name receives an advisory without entering name tracking.
+Local and captured dependency names and aliases share the same corpus
+context. The command's lint target constructs
+the checker once, uses exact authored `raw` strings and keeps these findings
+advisory. See the [authoring conventions](authoring/links-and-markup.md#marking-names-in-prose).
+
+Supply the invocation's `catalog` to share its full-name and alias lookup with
+the package names report. Optional `parsed` maps absolute files to captured
+`{raw, body, bodyLine?, bodyColumn?}`; `syntax` is the session's scanner
+projection. When the captured raw text matches, the checker rebases the body's
+existing name inventory into its authored raw source coordinates. Standalone
+calls use their supplied raw text.
+
+### `engine/name-markup.mjs`
+
+Import from `@heroiclands/package-build/engine/name-markup`.
+
+| Export            | Signature                                                 | Returns                                        | Use it when                                                                                        |
+| ----------------- | --------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `inlineText`      | `inlineText(tokens)`                                      | `string`                                       | Reading visible name text from actual parsed inline children and their resolved reference context. |
+| `rebaseNameSpans` | `rebaseNameSpans(spans, { raw, bodyLine?, bodyColumn? })` | Copied name spans at original file coordinates | Rebasing a captured body inventory and attribute ranges without parsing it again.                  |
+
+`scanSpans(source)` returns `{spans, names, errors}`. `names` contains the same
+span objects with the exact `name` class, including spans inside links. Each
+span retains `text`, `attrs`, offsets, 1-based line/UTF-16 column and `visible`
+text from actual parsed children. `contentEnd` is the exclusive raw inner-label
+endpoint. `attributePositions` maps each named attribute to `key` and `value`
+ranges with `{start, end, line, column}`. Offsets are 0-based with exclusive
+ends. Rebasing copies these values and leaves the captured inventory unchanged.
+
+The leaf module exports the declaration types `ContentSpan`, `SpanSourceSite`,
+`SpanAttributePosition`, `SpanFinding` and `SpanScan`. The generic rebasing
+helper retains additional fields of the captured span subtype.
+
+`engine/extension-attributes.mjs` exposes the shared attribute grammar:
+
+| Export                     | Signature                                                           | Returns                                       | Use it when                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `parseExtensionAttributes` | `parseExtensionAttributes(source, { idPattern?, positions? } = {})` | `{id, classes, values, problems, positions?}` | Parsing identifiers, ordered classes and named values; `positions: true` retains attribute key/value offsets. |
+
+Attribute-parser positions are ranges within its supplied attribute source;
+the span scanner maps them to Markdown coordinates. The optional range map
+does not change the parsed values.
+
+### `engine/name-rows.mjs`
+
+Import from `@heroiclands/package-build/engine/name-rows`.
+
+| Export         | Signature            | Returns                     | Use it when                                                            |
+| -------------- | -------------------- | --------------------------- | ---------------------------------------------------------------------- |
+| `NAME_COLUMNS` | `const NAME_COLUMNS` | Frozen ordered column names | Reading `owner`, `name`, `type`, `subType`, `line`, `column`.          |
+| `namesRows`    | `namesRows(records)` | `NameRow[]`                 | Projecting own-note occurrences into SQL rows without I/O or mutation. |
+
+Rows preserve record and occurrence order. `owner` is the canonical NOTE page
+derived from the record's canonical Address, including for native Item
+sources; an unaddressable record keeps `null`. Assets and documentation mirrors
+contribute no rows. Each row carries the occurrence's visible `name`, nullable
+`type`/`subType`, and numeric 1-based `line`/UTF-16 `column`. SQL ingestion fixes
+text columns as `VARCHAR` and positions as `BIGINT`, including empty,
+entirely-null and late-supplied classifications.
+
+### `engine/names.mjs`
+
+Import from `@heroiclands/package-build/engine/names`.
+
+| Export                  | Signature                                                      | Returns                           | Use it when                                                                                  |
+| ----------------------- | -------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- |
+| `normalizeName`         | `normalizeName(text)`                                          | `string`                          | Normalizing NFC, apostrophes and whitespace while preserving case.                           |
+| `nameForms`             | `nameForms(text)`                                              | `string[]`                        | Enumerating supported whole-label possessives and regular plurals.                           |
+| `createNameCatalog`     | `createNameCatalog({ records, index })`                        | `NameCatalog`                     | Sharing indexed full-name, alias and resolved Address matching across checks.                |
+| `collectUnwrittenNames` | `collectUnwrittenNames({ records, catalog })`                  | `{groups, firstUse}`              | Grouping every unresolved captured occurrence by supplied classification.                    |
+| `analyzeNameSpans`      | `analyzeNameSpans(spans, { file?, vocabulary?, types? } = {})` | `{names, findings}`               | Validating supplied `data-type` against actual note declarations at attribute-key positions. |
+| `createNamesReport`     | `createNamesReport({ package, records, catalog })`             | `NamesReport`                     | Preparing deterministic current-package unwritten and conflicting groups without I/O.        |
+| `namesReportFinding`    | `namesReportFinding(report, { contentBase? } = {})`            | A located warning, or `undefined` | Formatting one human package advisory with every reported use.                               |
+
+`NameCatalog` provides `recognize(label, preferred?)` and `resolve(target)`;
+indexed full names and declared aliases share canonical identity, and ambiguous
+labels retain every candidate. Dependency names come from the captured link
+index; folder-note identities are excluded. These pure helpers read the
+invocation's existing corpus.
+
+`analyzeNameSpans` accepts actual parsed spans at file coordinates, with
+`visible`, `attrs`, `line`, `column` and optional `attributePositions`. It
+returns valid five-field `MarkedName` entries and supplied-value error findings.
+`vocabulary` defaults to `NOTE_VOCABULARY`; `types` supplies additional bare
+types from configured declarations. Callers propagate findings through their
+existing preparation error channel.
+
+`NamesReport` has `{package, unwritten, conflicts}`. Each unwritten group has
+`{type, subType, names: [{name, uses}]}`. Each conflict has
+`{name, kinds: [{type, subType, uses}]}`. A use has
+`{owner, file, line, column}`, with its file relative to the content root and
+the same NOTE/null owner convention as `namesRows`. Untyped uses are excluded
+from conflicts; matching bare-type/subtype refinements are compatible.
+`namesReportFinding` rebases file paths with `contentBase`, anchors the advisory
+at the earliest reported actual use, and returns no warning for an empty report.
 
 ### `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, parsed })`                                                  | {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, raw, 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, raw, contentPackage, body, bodyLine, manifest })`                           | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                                                                           | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                                                                                |
-| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems, foreignRecord, parsed })` | `Array<Record<string, any>>`                                                                                                                                                                                                                                                  | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file; each note carries its resolved culture as `data.culture` |
-| `resolveCultures`       | `resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems })`                                           | `Array<Record<string, any>>` — the same records                                                                                                                                                                                                                               | writing each note's resolved culture into its record as `data.culture`: its own value, else its parents', else for a polity its seat's and governed places', pooled; parents that disagree give a finding into `problems`, or one thrown Error listing every conflict               |
+Collecting and publishing this package's content index. Records describe note frontmatter, assets, prose and event anchors, and the document targets those notes produce. Dynamic publication prepares the same generated Markdown and scalar expressions as the rendering surfaces, using each source note's audience.
+
+Own-note records carry derived `names` entries in source order as
+`{name, type, subType, line, column}`. Missing classifications are explicit
+`null`; no occurrences gives `[]`. Positions refer to original authored span
+openings, before generated content. Metadata JSONL transports these entries
+to dependency SQL without an additional artifact. This field is reserved for
+derived data, and is not an authored frontmatter key.
+
+`buildIndexRecord` and `indexRecordsForNote` accept `bodyColumn` alongside
+`bodyLine` to locate the authored body's first UTF-16 character. Their optional
+`nameTypes` iterable, also accepted by `collectContentIndex` and
+`indexRecordsFor`, supplies additional bare kinds from configured type
+declarations. `indexRecordsFor` defaults that iterable to the resolved
+configuration's `itemTypes`.
+
+| 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, parsed, sources, syntax, foreignIndex, nameTypes? })`                                    | {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, bodyColumn?, nameTypes?, relPath, absPath, raw, contentPackage, manifest, addressContext })`            | `object[]`                                                                                                                                                                                                               | Derive the note's own record and its documentation record from parsed text.                                                                                                                                                                                                         |
+| `prepareContentIndex`   | `async prepareContentIndex({ contentBase, config, session } = {})`                                                                                          | `Promise<PreparedContentIndex>` — the captured source context and complete expanded bodies, described below                                                                                                              | Prepare dynamic publication without writing files.                                                                                                                                                                                                                                  |
+| `emitContentIndex`      | `emitContentIndex({ contentBase, outDir, config, publication } = {})`                                                                                       | `{{file: string, notes: number, assets: number, records: number, bytes: number, full: number, draft: number, stub: number, dictionary: {file: string, rows: number}, terms: {file: string, rows: number}}}`              | Synchronously publish metadata and the dictionary and terms datafiles; dynamic content requires a complete `publication`.                                                                                                                                                           |
+| `buildIndexRecord`      | `buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, bodyColumn?, nameTypes?, manifest })`                               | `Record<string, any>` — the record, with derived fields sorted deep                                                                                                                                                      | building one note's content-index record; refuses a note that authors a key the index derives itself (`package` among them) before building anything                                                                                                                                |
+| `collectContentIndex`   | `collectContentIndex(contentBase, { contentPackage, skipDirectories, assetsBase, manifest, problems, foreignRecord, parsed, sources, syntax, nameTypes? })` | `Array<Record<string, any>>`                                                                                                                                                                                             | reading a whole content tree into index records, in a total order independent of directory-read order; an item note yields two records (its own and its documentation journal's), and each asset root yields one per file; each note carries its resolved culture as `data.culture` |
+| `resolveCultures`       | `resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems })`                                                                        | `Array<Record<string, any>>` — the same records                                                                                                                                                                          | writing each note's resolved culture into its record as `data.culture`: its own value, else its parents', else for a polity its seat's and governed places', pooled; parents that disagree give a finding into `problems`, or one thrown Error listing every conflict               |
+
+`prepareContentIndex` resolves `contentBase` from the configured `paths.content`
+when omitted. Its `PreparedContentIndex` contains:
+
+| Field            | Value                                                                                                                                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config`         | The resolved configuration object used for preparation.                                                                                            |
+| `contentBase`    | The absolute source root.                                                                                                                          |
+| `records`        | The complete note, documentation and asset records, including hidden providers needed for lineage.                                                 |
+| `parsed`         | A `Map` keyed by absolute note file, holding authored `frontmatter`, `body`, `raw`, `bodyLine` and `bodyColumn`.                                   |
+| `expandedBodies` | A `Map` keyed by absolute note file, holding `markdown`, its body-relative `lineMap` of `{line, generated}` entries, and optional `generatedFrom`. |
+| `foundryBodies`  | A `Map` with the same body shape, prepared against the complete native compendium corpus.                                                          |
+| `syntax`         | Optional session-local scanner projection function; read-only and valid for that session's lifetime.                                               |
+
+Preparation expands SQL tables, page lists, automatic sections and scalar
+expressions. Prose declarations in `expandedBodies` use each source's audience:
+public notes use public providers and usage; GM notes use the complete corpus.
+Automatic lexical sections keep that source audience on every surface.
+Explicit native SQL uses the complete corpus in `foundryBodies`.
+
+Native own and documentation target maps derive their actual page identities
+from `foundryBodies`. Each map contains only prose slugs declared in the
+source-audience body and present in the native body, plus the journal's
+reserved `$lead` target. A prose target present only on the website remains
+valid for website links and prose-link checks; a native link to it is refused.
+Native-only slugs and private heading names stay out of a public source's
+metadata. Event anchors and authored source positions remain attached to their
+sources. A published empty prose-anchor list declares no prose targets,
+including on web-only pages.
+
+Pass the envelope directly to the synchronous emitter:
+
+```js
+const publication = await prepareContentIndex({ config, contentBase });
+const result = emitContentIndex({ publication, outDir });
+```
+
+The emitter defaults `config` and `contentBase` from the envelope. If supplied,
+they must name that same configuration object and source root. It consumes
+`records`, `parsed`, `expandedBodies` and `foundryBodies` without mutating them;
+frozen inputs are valid. Every note requires a parsed source and both body
+entries.
+Missing or mismatched preparation is refused before creating or replacing any
+metadata, dictionary or terms file.
+
+Without `publication`, the synchronous emitter accepts authored bodies and
+pure frontmatter dictionary or glossary sections. Active SQL, page lists,
+scalar expressions, events or other generated sections require
+`prepareContentIndex`. The CLI performs this preparation automatically.
+`indexRecordsFor` and `collectContentIndex` collect authored records and pure
+lexical sections; use preparation and emission to publish dynamic body targets.
+
+On lore and affiliation notes, `data.language` and `data.glossary[].language`
+require a language NOTE Address. Decoding refuses other recognized system
+segments at the authored value, naming the complete
+`<pkg>-note-skill-<shortcode>` to write. A short local form such as
+`skill-provnzlng` is also accepted. See the [glossary language
+rules](reference/format-details.md#dictionaries-and-glossaries).
 
 `engine.contentIndex` also re-exports eight names from neighbouring leaf modules, at this same import path:
 
-| Export                | Signature                        | Returns                                                        | Use it when                                                                                                                                                                                                  |
-| --------------------- | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `collectAnchors`      | `collectAnchors(body, bodyLine)` | `Array<{slug: string, line: number, kind: string}>`            | reading a note body's anchors, each with its kind, shared with the link checker and every build that emits a link                                                                                            |
-| `DERIVED_KEYS`        | `const DERIVED_KEYS`             | —                                                              | reading which keys the content index adds to a record, and which a note therefore may not author itself                                                                                                      |
-| `noteFile`            | `noteFile(contentBase, record)`  | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                                                  |
-| `authoredFrontmatter` | `authoredFrontmatter(record)`    | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading a note's frontmatter back from its index record, its resolved `data.culture` included, so a pass can lint or compile from the index without reasoning about derived keys as if the author wrote them |
-| `isNoteRecord`        | `isNoteRecord(record)`           | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                                                          |
-| `isStub`              | `isStub(record)`                 | `boolean`                                                      | telling a stub — a note with an empty body — apart from a note that publishes a page; asked of the absent address, which is the whole signal                                                                 |
-| `isAssetRecord`       | `isAssetRecord(record)`          | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                                              |
-| `recordPath`          | `recordPath(record)`             | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                                                          |
+| Export                | Signature                                               | Returns                                                        | Use it when                                                                                                                                                                                                  |
+| --------------------- | ------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `collectAnchors`      | `collectAnchors(body, bodyLine, resolveRole?, syntax?)` | `Array<{slug: string, line: number, kind: string}>`            | reading a note body's anchors, each with its kind, shared with the link checker and every build that emits a link                                                                                            |
+| `DERIVED_KEYS`        | `const DERIVED_KEYS`                                    | —                                                              | reading which keys the content index adds to a record, and which a note therefore may not author itself                                                                                                      |
+| `noteFile`            | `noteFile(contentBase, record)`                         | `string` — the note's absolute path                            | composing an index record's `file.path` (recorded relative, for a byte-stable artifact) back into an openable absolute path                                                                                  |
+| `authoredFrontmatter` | `authoredFrontmatter(record)`                           | `Record<string, any>` — the frontmatter without `DERIVED_KEYS` | reading a note's frontmatter back from its index record, its resolved `data.culture` included, so a pass can lint or compile from the index without reasoning about derived keys as if the author wrote them |
+| `isNoteRecord`        | `isNoteRecord(record)`                                  | `boolean`                                                      | telling a note's own record apart from its documentation journal's and from an asset's, when enumerating the corpus                                                                                          |
+| `isStub`              | `isStub(record)`                                        | `boolean`                                                      | telling a stub apart from a note that publishes a page; asked of the absent address, which is the whole signal                                                                                               |
+| `isAssetRecord`       | `isAssetRecord(record)`                                 | `boolean`                                                      | telling a record that addresses a file apart from one that addresses a note; the `asset` block is what marks it                                                                                              |
+| `recordPath`          | `recordPath(record)`                                    | `string` — the path the record names inside its package        | ordering or reporting across both record shapes: a note names the `.md` it was parsed from, an asset the file it is                                                                                          |
 
 ### `engine.assetTypes`
 
@@ -1002,7 +1272,7 @@ content tree can also compile into Foundry compendium packs.
 | `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.                         |
+| `siteGates`           | `siteGates(pages, findings, options)`             | {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.                             |
@@ -1014,6 +1284,10 @@ content tree can also compile into Foundry compendium packs.
 | `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.               |
 
+`siteGates` takes `{ config, records, sqlTables? }`. Pass the prepared
+`sqlTables` map so anchors emitted by automatic dictionary sections are present in the
+index for checking page links.
+
 ### `engine.sitePreview`
 
 `prepareSitePreview({ config })` reads the saved content tree and declared dependency indexes, prepares its SQL corpus, and returns a private preview context. Pass the active note's absolute path and complete buffer text to `render(file, text)`. A successful result has `{ ok: true, markdown, frontmatter, findings: [] }`; a failed result has `{ ok: false, findings }` and no replacement content. Findings identify the source file and carry a line and column when the offending text can be located.
@@ -1176,13 +1450,20 @@ 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, parsed, 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. |
+
+`buildLinkIndex` optionally accepts the `parsed` map captured by `indexRecordsFor`
+alongside the supplied `records` in the same invocation. It reads each entry's
+`raw` string by absolute note path and derives the untrimmed body as usual;
+without a raw string it reads that file. The caller owns this map, and the
+link index leaves it unchanged. This source capture is separate from published
+metadata and has no persistent or cross-invocation cache.
 
 ### `engine.webWikilinks`
 
@@ -1211,7 +1492,7 @@ Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLa
 | ------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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; returns frontmatter, body, rendered description, raw source, and body coordinates.                                                                     |
+| `parseMarkdownFile`       | `parseMarkdownFile(filePath, { addressContext, raw, renderDescription } = {})`                              | —                                                                                                                                                                                                                                         | Parses a markdown file with YAML frontmatter; returns frontmatter, body, rendered description, raw source, and body coordinates.                                                                     |
 | `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.                                                                 |
@@ -1224,11 +1505,44 @@ Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLa
 | `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.                                                                                        |
+| `buildContentLinkIndex`   | `buildContentLinkIndex(contentBase, router?, options?)`                                                     | `{{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, raw, 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 |
+| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories, sources, renderDescription })`                                | generator yielding `{frontmatter, body, description, raw, 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 |
+
+`buildContentLinkIndex` accepts `{ config?, records, sqlTables?, foreign? }`.
+`records` is the required, supplied content corpus. The optional prepared
+`sqlTables` map supplies generated anchors and their Foundry page mappings,
+so glossary word links resolve to their dictionary entries.
+
+`parseMarkdownFile` reads its supplied exact `raw` string when present. Its
+`renderDescription` option defaults to true; false leaves `description` empty
+while retaining authored body and positions. `walkMarkdownTree` accepts a
+selected `sources` map in walk order and the same rendering option, also true
+by default. Index collection explicitly omits unused rendered descriptions.
+`indexRecordsFor` accepts that selected map, a `syntax` projection function
+and a captured `foreignIndex`. These adapters do not retain state globally.
+
+The physical wrappers `lintContentCharset`, `lintContentHtml`,
+`lintContentIcons`, `lintContentImages` and `lintContentTaskLists` accept an
+optional `sources` map of absolute paths to `{raw}`. Their existing extension,
+hidden-path and skip filters still apply; without the map they walk and read
+the tree. `lintPathCharset` accepts optional physical `inventory`, retaining
+walk roots and order. `lintNoteStates` accepts the authored `parsed` map, with
+its existing file reader for missing entries.
+`parseMarkdownFile` accepts LF and CRLF frontmatter delimiters and retains the
+exact source as `raw`. Its trimmed `body` keeps the authored line endings, with
+`bodyLine` and `bodyColumn` locating its first character in that original source.
+
+### `./engine/diagnostics`
+
+The `@heroiclands/package-build/engine/diagnostics` wildcard module provides
+source locations and frontmatter source slicing.
+
+| Export             | Signature               | Returns                                | Use it when                                                                                                              |
+| ------------------ | ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `splitFrontmatter` | `splitFrontmatter(raw)` | `{yaml: string, body: string} \| null` | Split opening LF or CRLF frontmatter into exact YAML and untrimmed body slices, without parsing or rewriting the source. |
 
 ### `engine.itemRegistry`
 
@@ -1384,15 +1698,15 @@ The content tree, built into a book. The I/O half of the PDF surface: it reads t
 
 Journals pack compiler — produces JSON pack files for the "journals" Foundry compendium from markdown notes in the `assets/content/` tree. The content root (`contentBase`) is walked recursively; any `.md` file whose frontmatter declares either `type: doc` or a **doc-carrying type** ({@link sohl.utils.packs.docEntryTypes} — every item type, plus `macro`) is compiled into one JournalEntry document. Each note's body is split on top-level H1 headings; the optional content before the first H1 becomes a lead page, and each subsequent H1 starts a new page named after its heading text. All page bodies are rendered to HTML.
 
-| Export                | Signature                                                                   | Returns                                                                                                                                                                          | Use it when                                                                                                                      |
-| --------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `splitPages`          | `function splitPages(body, leadName`                                        | —                                                                                                                                                                                | Splits a markdown body into pages by top-level H1 headings.                                                                      |
-| `assertUniquePages`   | `function assertUniquePages(rawPages, noteName)`                            | —                                                                                                                                                                                | Two pages in one note that would derive the same id, which the LevelDB packer reports only as an opaque duplicate-key collision. |
-| `assertUniqueAnchors` | `function assertUniqueAnchors(rawPages, noteName)`                          | —                                                                                                                                                                                | The anchor half of {@link assertUniquePages}, under its former name.                                                             |
-| `journalPageId`       | `function journalPageId(entryId, page)`                                     | {string} A 16-character Foundry id.                                                                                                                                              | The id of one page within its entry.                                                                                             |
-| `buildPages`          | `function buildPages(rawPages, entryId, noteName)`                          | {Array<{\_id: string, name: string, type: string, title: {show: boolean, level: number}, text: {format: number, content: string}, \_key: string}>} The page documents, in order. | Compile split pages into JournalEntryPage documents.                                                                             |
-| `buildJournalEntry`   | `buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats })` | {object} The JournalEntry document, keyed for the pack.                                                                                                                          | Assemble one JournalEntry document from a note's converted markdown.                                                             |
-| `Journals`            | `class Journals extends BasePackCompiler`                                   | —                                                                                                                                                                                | not called directly — imported and driven by `engine/generate.mjs` as the "journals" pack compiler                               |
+| Export                | Signature                                                                    | Returns                                                                                                                                                                          | Use it when                                                                                                                      |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `splitPages`          | `splitPages(body, leadName, resolveRole, syntax?)`                           | —                                                                                                                                                                                | Splits a markdown body into pages by top-level H1 headings.                                                                      |
+| `assertUniquePages`   | `function assertUniquePages(rawPages, noteName)`                             | —                                                                                                                                                                                | Two pages in one note that would derive the same id, which the LevelDB packer reports only as an opaque duplicate-key collision. |
+| `assertUniqueAnchors` | `function assertUniqueAnchors(rawPages, noteName)`                           | —                                                                                                                                                                                | The anchor half of {@link assertUniquePages}, under its former name.                                                             |
+| `journalPageId`       | `function journalPageId(entryId, page)`                                      | {string} A 16-character Foundry id.                                                                                                                                              | The id of one page within its entry.                                                                                             |
+| `buildPages`          | `function buildPages(rawPages, entryId, noteName)`                           | {Array<{\_id: string, name: string, type: string, title: {show: boolean, level: number}, text: {format: number, content: string}, \_key: string}>} The page documents, in order. | Compile split pages into JournalEntryPage documents.                                                                             |
+| `buildJournalEntry`   | `buildJournalEntry({ id, name, markdown, leadName, folder, stats, syntax })` | {object} The JournalEntry document, keyed for the pack.                                                                                                                          | Assemble one JournalEntry document from a note's converted markdown.                                                             |
+| `Journals`            | `class Journals extends BasePackCompiler`                                    | —                                                                                                                                                                                | not called directly — imported and driven by `engine/generate.mjs` as the "journals" pack compiler                               |
 
 ### `engine.macros`
 
@@ -1465,28 +1779,28 @@ Adventure pack compiler — `type: bundle` notes → Foundry `Adventure` documen
 
 Pack JSON generation — in-repo Markdown → per-entry JSON (build-only). Reads the authoritative content tree at the configured content root and compiles each pack's entries to per-entry JSON under its build directory (`build/packs-json/<pack>/` in this repository). The JSON is a disposable build intermediate consumed by `build:compiledb` (which turns it into the shipped LevelDB packs) — it is never committed.
 
-| Export                        | Signature                                               | Returns                                                                                                                                                              | Use it when                                                                                                         |
-| ----------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `systemCompilers`             | `function systemCompilers(passes)`                      | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                    | The system-specific compilers, derived from the passes themselves.                                                  |
-| `compilerFor`                 | `function compilerFor(docType, system`                  | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past. | The compiler class a pack of one document type and one system gets.                                                 |
-| `emittedArtFor`               | `function emittedArtFor(type)`                          | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made.             | The art fields a note of one content type reaches its document through, and the document it reaches.                |
-| `packJsonDir`                 | `const packJsonDir`                                     | {string} The pack's JSON directory.                                                                                                                                  | Root of the build-only JSON tree for one pack.                                                                      |
-| `itemPackJsonDirs`            | `function itemPackJsonDirs(config`                      | {string[]} Each Item pack's JSON directory.                                                                                                                          | The generated JSON of **every** configured Item pack — what the actors pass reads its predefined items from.        |
-| `bundleSourceJsonDirs`        | `function bundleSourceJsonDirs(config`                  | {Record<string, string[]>} Each readable pack's JSON directory, by the Foundry document type it holds.                                                               | The compiled JSON a bundle may hold copies of, by document type.                                                    |
-| `orderPassesByDependency`     | `function orderPassesByDependency(packs)`               | {object[]} A new list, in compile order.                                                                                                                             | The passes to run, ordered so that each one follows the output it reads.                                            |
-| `unsatisfiedPassDependencies` | `function unsatisfiedPassDependencies(running, config)` | {string[]} One message per unsatisfiable dependency.                                                                                                                 | The dependencies this run cannot satisfy by ordering, because the pass that would produce them is not in it.        |
-| `emptyPassErrors`             | `function emptyPassErrors(passes)`                      | {string[]} One message per pass that must not have been empty.                                                                                                       | The passes that compiled nothing when they were expected to compile something — a build failure, not a quiet no-op. |
-| `generatePacksJson`           | `async generatePacksJson({ only, config })`             | {Promise<number>} Total error count across the generated packs.                                                                                                      | Generate the build-only JSON for every pack (or one, when `only` is given).                                         |
+| Export                        | Signature                                                         | Returns                                                                                                                                                              | Use it when                                                                                                         |
+| ----------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `systemCompilers`             | `function systemCompilers(passes)`                                | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                    | The system-specific compilers, derived from the passes themselves.                                                  |
+| `compilerFor`                 | `function compilerFor(docType, system`                            | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past. | The compiler class a pack of one document type and one system gets.                                                 |
+| `emittedArtFor`               | `function emittedArtFor(type)`                                    | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made.             | The art fields a note of one content type reaches its document through, and the document it reaches.                |
+| `packJsonDir`                 | `const packJsonDir`                                               | {string} The pack's JSON directory.                                                                                                                                  | Root of the build-only JSON tree for one pack.                                                                      |
+| `itemPackJsonDirs`            | `function itemPackJsonDirs(config`                                | {string[]} Each Item pack's JSON directory.                                                                                                                          | The generated JSON of **every** configured Item pack — what the actors pass reads its predefined items from.        |
+| `bundleSourceJsonDirs`        | `function bundleSourceJsonDirs(config`                            | {Record<string, string[]>} Each readable pack's JSON directory, by the Foundry document type it holds.                                                               | The compiled JSON a bundle may hold copies of, by document type.                                                    |
+| `orderPassesByDependency`     | `function orderPassesByDependency(packs)`                         | {object[]} A new list, in compile order.                                                                                                                             | The passes to run, ordered so that each one follows the output it reads.                                            |
+| `unsatisfiedPassDependencies` | `function unsatisfiedPassDependencies(running, config)`           | {string[]} One message per unsatisfiable dependency.                                                                                                                 | The dependencies this run cannot satisfy by ordering, because the pass that would produce them is not in it.        |
+| `emptyPassErrors`             | `function emptyPassErrors(passes)`                                | {string[]} One message per pass that must not have been empty.                                                                                                       | The passes that compiled nothing when they were expected to compile something — a build failure, not a quiet no-op. |
+| `generatePacksJson`           | `generatePacksJson({ only, config, session, reportPreparation })` | {Promise<number>} Total error count across the generated packs.                                                                                                      | Generate the build-only JSON for every pack (or one, when `only` is given).                                         |
 
 ### `engine.compendiums`
 
 Compendium pack library — compile / unpack / clean LevelDB packs. Wraps `@foundryvtt/foundryvtt-cli` over the packs a consuming repository declares: - {@link compilePacks}: generates each pack's per-entry JSON from the `assets/content/` Markdown into `build/packs-json/<name>/` (via generate.mjs), then builds LevelDB from it; no committed JSON, no vault. - {@link unpackPacks}: extracts a compiled pack back to per-entry JSON, rebuilding folder paths. - {@link cleanPacks}: normalizes/strips extracted JSON.
 
-| Export         | Signature                                                             | Returns | Use it when                                                                                                                          |
-| -------------- | --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `compilePacks` | `async compilePacks({ config, sourcePacks, stageDest, packName })`    | —       | Generates each pack's per-entry JSON from `assets/content/` into `build/packs-json/<name>/`, then builds the LevelDB output from it. |
-| `cleanPacks`   | `async cleanPacks({ config, packDest, packName, entryName })`         | —       | Cleans and formats source JSON files, removing unnecessary permissions and flags and adding the proper spacing.                      |
-| `unpackPacks`  | `async unpackPacks({ packs, config, stageDest, packDest, packName })` | —       | Extracts compiled LevelDB packs back to per-entry JSON, rebuilding the folder hierarchy as directories.                              |
+| Export         | Signature                                                                                | Returns | Use it when                                                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `compilePacks` | `compilePacks({ config, sourcePacks, stageDest, packName, session, reportPreparation })` | —       | Generates each pack's per-entry JSON from `assets/content/` into `build/packs-json/<name>/`, then builds the LevelDB output from it. |
+| `cleanPacks`   | `async cleanPacks({ config, packDest, packName, entryName })`                            | —       | Cleans and formats source JSON files, removing unnecessary permissions and flags and adding the proper spacing.                      |
+| `unpackPacks`  | `async unpackPacks({ packs, config, stageDest, packDest, packName })`                    | —       | Extracts compiled LevelDB packs back to per-entry JSON, rebuilding the folder hierarchy as directories.                              |
 
 ### `engine.regionEvents`
 
@@ -2033,6 +2347,15 @@ The Changesets changelog generator, loaded with `require` — a CommonJS module
 | `getReleaseLine`           | `getReleaseLine(changeset, type, changelogOpts)`                           | `string` — the summary, verbatim, separated from its neighbours by a blank line | writing one changeset's release line with no commit-hash prefix and no bullet                      |
 | `getDependencyReleaseLine` | `getDependencyReleaseLine(changesets, dependenciesUpdated, changelogOpts)` | `string` — always `""`                                                          | satisfying the `ChangelogFunctions` interface; these packages narrate no internal dependency bumps |
 
+`engine/changelog-group.mjs` exports `groupChangelogText(text, { labels })`,
+returning `{ text, findings }`. It groups the newest release's summaries
+within each bump tier, retaining prose, bullets, wrapped continuations,
+nested item content and literal code. Merged labels' opening paragraphs
+combine in source order before their items. Exact duplicate items print
+once; labels follow the configured order, with unlabelled lead items first.
+Earlier release sections stay byte-identical, and grouping the result
+again leaves its text unchanged.
+
 ## `./package.json`
 
 Not a JavaScript module — this subpath entry exists so tooling (bundlers, `import.meta.resolve`, a script reading the installed version) can resolve the package's own `package.json` through Node's package-exports resolution instead of reaching outside the declared export map.
@@ -2046,7 +2369,7 @@ The engine wildcard subpath also exposes the body parsers below. Their figure ex
 | `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`       | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
 | `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`    | Read div and secret fences; generic div records have `name: "div"` and no generated title. Scanning includes poetry errors.                                                                                                            |
 | `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
-| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans and located errors; the renderer preserves inline Markdown in attributed HTML spans.                                                                             |
+| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans, the exact `.name` inventory and located errors, retaining visible text and attribute positions; rendering preserves inline Markdown and permitted attributes.   |
 
 `scanFigures` retains `line` (1-based caption line), `bodyStart`/`bodyEnd` (0-based, exclusive-end target range), and `close` (last consumed target line), plus caption attributes, kind, label and number. Unnumbered captions have an empty label and consume no number. `collectAnchors` discovers heading, caption, div, poem and span identifiers; `markupAnchorFindings(body)` reports collisions involving non-page identifiers; Foundry maps non-page anchors to the actual containing page UUID. An unnumbered `ref` requires `form="title"` or `form="full"`.
 
@@ -2056,7 +2379,7 @@ The engine wildcard subpath also exposes the body parsers below. Their figure ex
 | ---------------- | ----------------------------------------------------------------------------------- |
 | `markupFindings` | Validate complete Markdown source and return diagnostics for the supplied filename. |
 
-`markupFindings(source, file)` masks YAML frontmatter without moving source positions and returns block and alert scanner errors as `{file, line, column, severity, message}` diagnostics. Content lint, Markdown checks and formatting preflight share this validation; malformed files are not rewritten by formatting or Markdown fixes.
+`markupFindings(source, file, syntax?)` masks YAML frontmatter without moving source positions and returns block and alert scanner errors as `{file, line, column, severity, message}` diagnostics. Content lint, Markdown checks and formatting preflight share this validation; malformed files are not rewritten by formatting or Markdown fixes.
 
 `engine/content-alerts.mjs` exposes `ALERT_TYPES`, `scanAlerts(source)` and `renderAlerts(source, target)` and `alertMarkdownPlugin(md)`. The scanner returns `{blocks, errors}`; alert records carry `type`, `id`, `classes`, `attributes`, `title`, `body` and inclusive zero-based `start`/`end` source lines. The renderer produces attributed `aside.alert` wrappers while leaving alert body Markdown in the document's scope. Alert validation and anchor discovery run in site, Foundry and book pipelines.
 
@@ -2069,8 +2392,253 @@ that map as `parsed` for its document passes. `unclaimedNoteFindings` accepts it
 alongside `records`. `locateFrontmatterKey` and `assertNoDeclaredPackage` accept
 `raw` in their options to locate findings without opening the note again.
 
+`buildCompileCorpus`, `generatePacksJson` and `compilePacks` accept an optional
+`session` bound to their resolved configuration, roots, scope and router.
+`prepareContentIndex` also accepts it. Without a session, the existing entry
+points derive their own inputs. Generation and pack compilation accept
+`reportPreparation` (default true); a coordinating caller may set it false
+only after reporting the shared source findings itself.
+
+`buildLinkIndex` and `buildContentLinkIndex` accept an optional `foreign` view
+from the same session; their diagnostic and routed resolver contracts remain
+distinct. `collectAnchors`, `markupAnchorFindings`, `markupFindings`, journal
+`splitPages`, Foundry `anchorsOf` and `buildJournalEntry` accept the optional
+`syntax` function described above. `buildSiteIndex` and `prepareTreeSqlTables`
+accept it in options, and `insertLexicalSections` accepts it in context.
+Prepared per-note SQL results carry it to `expandContentTables`. No scan result
+is reused for a different source projection.
+
 `prepareSqlTables` accepts sources with an optional `authoredSqlBlocks` count,
 set by `joinGeneratedSections`. Subsequent fences are generated event queries
 whose stub-inclusive results are identical; only authored fences receive a
 stub-inclusion comparison. Query answers and comparisons are cached for one
 preparation and kept separate.
+
+`prepareTreeSqlTables` retains the complete record membership when opening a
+public database, so derived citations can distinguish hidden notes from
+unknown addresses. Only public records contribute rendered sources and links.
+
+| Export                 | Contract                                                                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `prepareLinkSqlTables` | Prepare SQL, page-list and automatic lexical sections for link checking, using one preparation per required source audience. |
+
+`engine/sql-tables.mjs` exports `prepareLinkSqlTables(contentBase, options)`.
+Its options are `config`, `skipDirectories`, complete `records`, the shared
+`parsed` map, `foreignIndex` and optional `prepareAudience(audience)` callback. The callback supplies the bound session's existing `public` or `all` preparation. It returns prepared tables with `pageLists`
+and `inline` maps, or `undefined` when no source needs a directive or automatic
+lexical section. Public
+sources use public rows; GM sources use all rows. Query results remain local
+to each audience preparation, and the caller’s records remain complete for
+checking authored references. Unresolved derived citations retain the
+renderer’s plain-label behavior.
+
+`generatedSectionsFor(db, records, contentBase, options?)` accepts complete
+lineage records as `options.all` (default `records`). Its result includes
+`lexical`, a map from note file to `LexicalSection[]`, beside `sections`,
+`views` and `derived`. `attachGeneratedSections(prepared, generated)` places
+those lists on each note's prepared results as `lexical`; body expansion
+inserts them alongside the prepared directives.
+
+## Dictionary and glossary rows
+
+The wildcard engine subpath exposes
+`@heroiclands/package-build/engine/dictionary-rows` for deriving the
+`dictionary` and `terms` SQL relations from content-index records:
+
+| Export                  | Signature                                       | Returns                                     | Use it when                                                             |
+| ----------------------- | ----------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
+| `DICTIONARY_COLUMNS`    | `const DICTIONARY_COLUMNS`                      | A readonly list of column names             | Declaring the schema of a language's dictionary.                        |
+| `TERM_COLUMNS`          | `const TERM_COLUMNS`                            | A readonly list of column names             | Declaring the schema of owner-specific glossary terms.                  |
+| `ETYMOLOGY_KEYS`        | `const ETYMOLOGY_KEYS`                          | A readonly list of keys                     | Reading the structure of a dictionary word's etymology.                 |
+| `dictionaryLetter`      | `dictionaryLetter(text)`                        | `string`                                    | Deriving a heading letter from a sort key.                              |
+| `dictionaryEntryAnchor` | `dictionaryEntryAnchor(language, name)`         | `string`                                    | Deriving the stable entry anchor for a word in a language's dictionary. |
+| `dictionaryAndTermRows` | `dictionaryAndTermRows(records, all = records)` | `{ dictionary: object[], terms: object[] }` | Deriving dictionary words and glossary terms for the selected records.  |
+| `serializeRows`         | `serializeRows(rows)`                           | `string`                                    | Writing deterministic JSON Lines with keys sorted at every depth.       |
+
+`dictionaryEntryAnchor` takes the language's canonical Address and the
+word's form. Its `word-` anchor is derived from the full SHA-256 digest of
+that language and the NFC-normalized form, with case and accents preserved.
+It identifies the word's entry on that language page, including a word
+inherited from an ancestor.
+
+`records` is the selected audience; `all` supplies the complete record set for
+language and ownership resolution. A dictionary word takes its sort key and
+pronunciation from the language's word declaration. A glossary entry can
+supply its own sort key and pronunciation, using the dictionary word's
+values where unstated.
+
+A term naming a dictionary word carries its `class` and a `word` Address
+linking to its dictionary entry. The target is in the resolved language's
+dictionary when that language has own words; otherwise it is in the visible
+language that defines the word. The term's `language` stays resolved to the
+owner or entry's language. Without an entry's `definition`, its `senses`
+contain every dictionary gloss sense with
+an empty `bodies` list. With a definition, that owner's meaning is the sense
+instead. A rank or office of the same owner contributes its distinct
+descriptions after the dictionary senses; the owner's definition replaces
+both. Ranks, offices and terms outside the dictionary carry their source
+bodies. `common` belongs to
+glossary entries and `terms`, with each owner's choice kept on that owner's
+row. The [format
+reference](reference/format-details.md#dictionaries-and-glossaries) defines
+all columns and the rules for culture reach and ranks. The `cultures` list
+records associations for custom queries. Automatic Glossary sections select
+only their owner's explicitly declared `data.glossary` entries. A custom
+view can also select reached rank and office rows, keeping common marks only
+on its owner's own rows.
+
+Dictionary rows carry `plural`, the noun's nonempty explicit plural or its
+listed language's first matching literal suffix replacement, and `verbs`,
+that language's stated `{invariant: true}` or six-person pattern, otherwise
+null. These optional facts use no ancestor grammar and perform no word-rule
+validation. The raw `words` relation's `plural` remains the authored value.
+Dictionary SQL types are projected only for that relation, retaining its
+etymology struct, sense list, usage list and integer depth even when all
+optional grammar values are null.
+
+`@heroiclands/package-build/engine/language-terms` exposes the person
+descriptors used by the schema, SQL pattern type and head table:
+
+| Export               | Signature                  | Returns                        | Use it when                                                                                  |
+| -------------------- | -------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------- |
+| `VERB_PERSON_FIELDS` | `const VERB_PERSON_FIELDS` | Readonly inner-key descriptors | Reading the six present person names, labels and ending-string shapes in presentation order. |
+
+`serializeRows` returns the empty string for no rows; otherwise each object
+occupies one line and the file ends with a newline.
+
+## Dictionary and glossary layouts
+
+`@heroiclands/package-build/engine/dictionary-layout` renders SQL results as
+Markdown for the dictionary or glossary on its owner's note:
+
+| Export                    | Signature                            | Returns                    | Use it when                                                                         |
+| ------------------------- | ------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------- |
+| `LAYOUT_REQUIRED_COLUMNS` | `const LAYOUT_REQUIRED_COLUMNS`      | Required columns by layout | Checking the columns a dictionary or glossary query must select.                    |
+| `COMMON_MARK`             | `const COMMON_MARK`                  | `string`                   | Reading the mark a common glossary entry opens with.                                |
+| `DICTIONARY_ENTRY_CLASS`  | `const DICTIONARY_ENTRY_CLASS`       | `string`                   | Identifying generated headword spans that are native dictionary targets in Foundry. |
+| `dictionaryEntryPlugin`   | `dictionaryEntryPlugin(md)`          | `void`                     | Registering native dictionary headword rendering on the Foundry Markdown parser.    |
+| `renderDictionary`        | `renderDictionary(result, options?)` | `string`                   | Rendering a language's words with classes, etymology, senses and citations.         |
+| `renderGlossary`          | `renderGlossary(result, options?)`   | `string`                   | Rendering an owner's glossary entries, ranks and offices.                           |
+
+`result` is `{ columns: string[], rows: object[] }`. Both layouts require
+`name`, `senses` and `usage`; a missing column throws an error naming it.
+`LayoutOptions` accepts `linkable(ref)`, `sectionLevel`, `addressContext`,
+`labelOf(address)`, `showKey` (`true`, `false` or `"only"`), `pageLanguage`, `pageOwner`,
+`verbs` and `entryAnchors` (default `true`). These control link availability, letter-heading level,
+Address resolution, labels, the abbreviation key and the language whose tag
+is omitted. `entryAnchors` controls canonical dictionary headword targets;
+custom SQL dictionary views set it to `false`, leaving those targets to the
+language's automatic Dictionary section. A dictionary marks nothing common;
+a glossary prints the mark and its explanation when a selected term carries
+`common: true`.
+
+A dictionary entry has a stable word anchor. A glossary headword with a
+`word` Address links to that entry, and its `class` prints beside the language
+tag. Glossary rows sharing a headword and language combine into one entry;
+identical senses print once with all their source bodies. Dictionary-derived
+senses carry no body label. Dictionary entries print their `field` in italic
+parentheses and their etymology in brackets.
+
+Nouns print their optional `plural` beside the class. Each represented
+language's optional `verbs` column supplies one table after the key and
+before the first letter, with empty endings shown as "unchanged". For an
+automatic dictionary, `options.verbs` supplies the owning language's pattern
+even when its own words contain only excluded classes. The existing
+nonempty-own-words gate still applies. `showKey: false` suppresses the key
+and verb table while retaining entries; `showKey: "only"` prints the
+abbreviation key alone. With the default or `showKey: true`, a stated pattern
+still prints when the result needs no abbreviation key. Each head-enabled
+result prints its represented languages' tables independently.
+
+`pageOwner` is the containing page's canonical note Address. A glossary omits
+a sense's body label only when every contributing row belongs to that page
+and attributes the sense solely to itself. Other bodies and shared senses
+keep their labels. Without `pageOwner` or a selected `owner` column, all body
+labels remain.
+
+`DICTIONARY_ENTRY_CLASS` is `"dictionary-entry"`. The Foundry parser's
+`dictionaryEntryPlugin` promotes the marked headword at the start of a
+dictionary paragraph to an inline native H6 heading in a div container. It
+keeps the containing journal page. Site and book rendering retain the
+headword's span and paragraph. `anchorsOf` maps this dictionary target to
+its containing page's UUID with the word fragment; generic authored spans
+keep their containing-page behavior.
+
+## Automatic dictionary and glossary sections
+
+`@heroiclands/package-build/engine/lexical-sections` derives and inserts the
+same automatic lists for the site, Foundry journal, book and published index:
+
+| Export                  | Signature                                              | Returns                               | Use it when                                                       |
+| ----------------------- | ------------------------------------------------------ | ------------------------------------- | ----------------------------------------------------------------- |
+| `LEXICAL_SECTIONS`      | `const LEXICAL_SECTIONS`                               | A frozen list of section declarations | Reading section headings, accepted anchors and frontmatter gates. |
+| `hasLexicalEntries`     | `hasLexicalEntries(frontmatter)`                       | `boolean`                             | Checking whether a note supplies automatic lexical content.       |
+| `lexicalSectionsFor`    | `lexicalSectionsFor(records, all = records)`           | `Map<string, LexicalSection[]>`       | Deriving lists keyed by their owner's canonical Address.          |
+| `insertLexicalSections` | `insertLexicalSections(markdown, sections?, context?)` | `{markdown, lineMap, generatedFrom?}` | Inserting lists while preserving authored text and source lines.  |
+
+Each registry declaration has `slug`, `heading`, `aliases`, `dataKey` and
+`types`, whose entries have `type` and an optional `subType`. The Dictionary
+declaration applies to `skill`/`language` notes with nonempty `data.words`,
+and accepts `dictionary` and `lexicon` heading anchors. The Glossary
+declaration applies to cultures (`lore`/`culture`) and affiliations with
+nonempty `data.glossary`, and accepts `glossary`. `hasLexicalEntries` reads
+these same type and nonempty-array gates; it does not validate the authored
+body.
+
+`records` is the visible audience; `all` supplies complete lineage records.
+Each `LexicalSection` has `slug`, `heading`, `aliases`, a query-shaped
+`result: {columns, rows}` and dictionary-layout `options`. Dictionary rows
+cover the language's full dictionary; glossary rows select its owner's
+explicit entries only, including a rank or office only when named there.
+A qualifying words declaration containing only excluded word classes still
+produces its Dictionary heading, without entries or a key.
+
+`insertLexicalSections` takes the body after authored directives expand.
+Pass the original body as `context.authored` together with the expansion's
+line map, so generated headings cannot select or end an authored section.
+Without `authored`, the helper treats `markdown` as its source. It inserts a
+list at the end of the first matching authored anchored section, after its
+text and before the next authored heading at the same or a higher level.
+Headings inside comments, raw HTML, literal code or named blocks do not select
+sections.
+Without that heading, it appends an H1 with the section's canonical anchor.
+Letter headings sit one level below the containing heading, up to H6. The
+optional context is `{authored?, lineMap?, generatedFrom?}`; the returned line map keeps
+authored positions, marks inserted lines as generated and adjusts the start
+of appended nonlexical sections. It leaves the supplied line-map array
+unchanged.
+
+## Glossary term validation
+
+The wildcard module `@heroiclands/package-build/engine/culture-reach`
+exposes the term lookup used for glossary validation;
+`@heroiclands/package-build/engine/glossary-entries` exposes its findings:
+
+| Export          | Signature                             | Returns                 | Use it when                                                                                     |
+| --------------- | ------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- |
+| `noteTerms`     | `noteTerms(index, note, entry?)`      | `Map<string, string[]>` | Reading eligible dictionary words and reached rank or office descriptions by NFC name.          |
+| `checkGlossary` | `checkGlossary(note, { index } = {})` | `object[]`              | Checking the meanings and language references of a culture's or affiliation's glossary entries. |
+
+`noteTerms` selects words from the entry's resolved language and its
+ancestors; without `entry`, it uses the note's own resolved language. It also
+includes ranks and offices that reach the note. `checkGlossary` returns
+located findings for entries naming no language, duplicate names, invalid
+pronunciations and entries without a definition that match neither a word in
+their resolved language nor a reached rank or office. A definition repeating
+the only sense it replaces produces a warning. With no `index`, the check
+validates only what the note states locally.
+
+## Built-piece resolution
+
+The wildcard engine subpath exposes `pieceGlosses` from
+`@heroiclands/package-build/engine/word-rows`.
+
+| Export         | Signature                | Returns                             | Use it when                                                                  |
+| -------------- | ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------- |
+| `pieceGlosses` | `pieceGlosses(...datas)` | A lookup returning a string or null | Resolving a word's built pieces for lint, word rows or dictionary etymology. |
+
+Pass language `data` objects nearest first, in `lineageChain` order. Each
+language contributes words, affixes and elements, in that order. Words and
+affixes supply `gloss`, including an affix matched by its `front` form. Elements
+supply `sense` and match their `form` and `variants`. Exact matches precede matches without joining hyphens; case and
+accents are preserved. A missing gloss returns `null`.