@heroiclands/package-build 25.5.4 → 25.6.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @heroiclands/package-build
 
+## 25.6.0
+
+**Changes to act on**
+
+- Note queries and a language note's `scope` select notes by property, tag or address; a query that reads `file.path`, `file.folder` or `file.name`, or a scope that lists `paths`, is an error at its position.
+- A scenario no longer takes `data.status`, and a note that still writes it fails the build; mark an unfinished scenario with the `draft` tag instead.
+- A region's settlement table comes from its frontmatter on the website, in Foundry and in books, and a table still written in the body must move there. It needs no holding-model tag, and shows a Held by column only where a row names its holder by address.
+
+**New**
+
+- Places can be districts, such as a city's quarter or a kingdom's shire, standing within a settlement or a region and falling under its government unless they name their own.
+- Places can be routes, such as a road, a pass or a sea lane, with the journeys along them.
+- An affiliation's page lists who holds each of its offices, drawn from the living beings that name the office, and the content index carries the same list.
+- A being can hold several posts in one body by listing them under `office`.
+- Gear can be marked `unique: true` for a one-of-a-kind item; such an item's note must link a place or a being.
+- A language or spelling guide can declare a written mark of kind `quality`, for a mark that changes which vowel is said rather than how long it is held.
+- A quotation typed with `<<` and `>>` draws no raw-HTML warning.
+
+## 25.5.5
+
+**Languages and scripts**
+
+- Ch'alish P'ilam Ceremonial text passes character checks and is recognized as native script alongside Common.
+- Core vocabulary reports name the languages left unmeasured, including when no language opts into coverage.
+- Generated NPC names capitalize their name words for English prose while keeping connecting words as written.
+- Distinct source names keep their authored spelling under the culture's language code, except when the selected pattern draws English words.
+- The language reference explains that Roman inventories list language additions and refuse shared punctuation and whitespace in the list.
+- A language can supply one list of given names for everyone; NPC generation draws from it for every gender.
+
+**Verse**
+
+- Metre checks allow multi-syllable function words to go unstressed, so lines can scan without placing a beat on every particle or pronoun.
+- Verse inside blockquotes and nested lists keeps its line breaks, stanza boundaries and indentation, with findings located at the authored text.
+- Verse metre checks count a linked name's visible words without adding beats from its address.
+
+**Rendering and sites**
+
+- A book can break the page at a chosen point with `--- {.page-break}`.
+- Website previews start immediately, keep the last successful pages available during rebuilds, and report progress while building pages and search.
+
 ## 25.5.4
 
 **Builds and commands**

package/README.md

@@ -53,6 +53,13 @@ repository’s setup installs the two canonical shell hooks; it installs no
 pre-push hook. Run `npm test` and the other checks directly, or use
 `package-build ci` for a container run.
 
+The repository's `vitest.config.ts` limits both `npm test` and `npm run
+test:watch` to two workers, with Vitest's isolated fork pool. CI runs the same
+`npm test` command. This bounds concurrent test files on the shared runner,
+including files that start CLI subprocesses, load SQL databases, or emit
+TypeScript declarations. Keep this bound when reproducing CI failures locally;
+a percentage of the host's CPUs does not reserve resources for other jobs.
+
 ## Documentation
 
 The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md). This toolchain does not build its own site or book.

package/assets/styles/content-base.css

@@ -17,7 +17,7 @@
  *
  * It carries what every package's compiled content needs to read in Foundry as
  * it does in the preview and on the site: definition lists, verse, alerts,
- * inline spoilers, marked names, unresolved links, captioned blocks and
+ * inline spoilers, unresolved links, captioned blocks and
  * highlighted code. Every
  * class the Foundry renderer emits is styled here or exempted by name in
  * `tests/base-styles.test.ts`. A package keeps its own stylesheet for its own

package/bin/content-commands.mjs

@@ -1289,7 +1289,12 @@ function lintCommand() {
                 // Text marked with a language, a font or a map, checked against
                 // the languages this package declares, the faces it installed
                 // and the maps its notes declare.
-                const runs = runContext(config, records);
+                const runs = runContext(config, records, {
+                    referenceName: (target) => {
+                        const hit = index.resolveAddress(target) ?? index.manifestHit(target);
+                        return hit?.fm?.name?.full ?? hit?.name;
+                    },
+                });
                 const loaderLocations = new Set(
                     (runs.encodingFindings ?? []).map((one) =>
                         JSON.stringify([one.file, one.line, one.column, one.message]),
@@ -2346,7 +2351,11 @@ function siteBuildCommand() {
                 const config = argv[CONTENT_CONFIG] ?? loadPackConfig();
                 const root = path.resolve(config.rootDir, argv.out ?? DEPLOY_ROOT);
                 const out = siteDirectory(config, root);
-                const result = await buildPackageSite({ config, out });
+                const result = await buildPackageSite({
+                    config,
+                    out,
+                    progress: (message) => log.info(message),
+                });
                 // A note in error is written as its page shows it, and the
                 // build fails without indexing a site that is not to be
                 // deployed.
@@ -2374,6 +2383,7 @@ function siteBuildCommand() {
                     base: siteBase(config),
                     out: root,
                     search: config.site.search,
+                    progress: (message) => log.info(message),
                 });
                 if (search) {
                     log.info(
@@ -2429,8 +2439,10 @@ function siteServeCommand() {
                     host: argv.host,
                     port: argv.port,
                     report: (event) => {
-                        if (event.kind === "error") reportFailure(event.error);
-                        else if (event.kind === "failed") {
+                        if (event.kind === "progress") log.info(event.message);
+                        else if (event.kind === "error") {
+                            if (!event.fatal) reportFailure(event.error);
+                        } else if (event.kind === "failed") {
                             if (event.built) reportSiteBuild(event.built);
                             for (const finding of event.findings ?? []) emitDiagnostic(finding);
                         } else {
@@ -2444,11 +2456,22 @@ function siteServeCommand() {
                     },
                 });
                 log.info(`serving ${served.url} — interrupt to stop`);
-                await new Promise((resolve) => {
-                    process.once("SIGINT", resolve);
-                    process.once("SIGTERM", resolve);
+                let interrupt;
+                const interrupted = new Promise((resolve) => {
+                    interrupt = resolve;
+                    process.once("SIGINT", interrupt);
+                    process.once("SIGTERM", interrupt);
                 });
-                await served.close();
+                try {
+                    await Promise.race([interrupted, served.done]);
+                } catch (err) {
+                    reportFailure(err);
+                    process.exitCode = 1;
+                } finally {
+                    process.removeListener("SIGINT", interrupt);
+                    process.removeListener("SIGTERM", interrupt);
+                    await served.close();
+                }
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -3467,6 +3490,7 @@ function newNpc(config, argv) {
             profile,
             names,
             language: languageKey,
+            languageCode: code,
             seed: argv.seed,
             currentDate: config.currentDate,
             dateContext: reckoningContext(index),

package/docs/api.md

@@ -496,13 +496,15 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 
 What lies within a place and which affiliation explicitly governs it — read off `data.parents` and resolved explicit `data.government` across this package and every fetched index, inverted into the lists a note's generated **Within**, **Governed by** and **Governed places** sections show — and the population-based government advisory `package-build lint` runs on a place.
 
-| Export                 | Signature                                                      | Returns                 | Use it when                                                                                                                                        |
-| ---------------------- | -------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `holdingsNode`         | `holdingsNode(fm, { title, url, package, system, canonical })` | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation                                     |
-| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)`                           | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                                         |
-| `holdingsPages`        | `holdingsPages(nodes, { governmentNodes })`                    | `Map<string, Holdings>` | inverting `parents` and resolved explicit `government` into each node's sorted lists, keyed by its `url`, for every node with a `url` and an entry |
-| `shortcodesOf`         | `shortcodesOf(value)`                                          | `string[]`              | the shortcodes a `parents` value names — bare or qualified Addresses — empties dropped and repeats collapsed                                       |
-| `checkGovernment`      | `checkGovernment(note)`                                        | `object[]`              | warning at `data.population` for positive population with no own `data.government` key; explicit null means anarchy                                |
+| Export                       | Signature                                                      | Returns                 | Use it when                                                                                                                                        |
+| ---------------------------- | -------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `holdingsNode`               | `holdingsNode(fm, { title, url, package, system, canonical })` | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation                                     |
+| `foreignHoldingsNodes`       | `foreignHoldingsNodes(foreignIndex)`                           | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                                         |
+| `holdingsPages`              | `holdingsPages(nodes, { governmentNodes })`                    | `Map<string, Holdings>` | inverting `parents` and resolved explicit `government` into each node's sorted lists, keyed by its `url`, for every node with a `url` and an entry |
+| `shortcodesOf`               | `shortcodesOf(value)`                                          | `string[]`              | the shortcodes a `parents` value names — bare or qualified Addresses — empties dropped and repeats collapsed                                       |
+| `checkGovernment`            | `checkGovernment(note)`                                        | `object[]`              | warning at `data.population` for positive population with no `data.government` key, own or inherited; explicit null means anarchy                  |
+| `inheritDistrictGovernments` | `inheritDistrictGovernments(records, { foreignRecord })`       | `void`                  | giving each district record that states no `data.government` the value of its nearest parent that states one, as the content index does            |
+| `governmentInherited`        | `governmentInherited(record)`                                  | `boolean`               | asking whether a district record's `data.government` came from a parent rather than its own note                                                   |
 
 An entry carries the listed note's `title`, its `address` in the `note` system, its `type` and `subType`, and its `url` where the note has one. A node with no `url` — a stub — is listed by others and carries no list of its own. Records passed as `governmentNodes` take part in government alone, never in geography.
 
@@ -531,16 +533,18 @@ What trade a settlement supports (`data.market`): the six-step scale, stated onc
 
 ### `engine.settlementTables`
 
-A region's settlements table — a markdown table under `## Settlements` on a `place` note, one row per settlement with its market, its people and its holder — held to its declared columns, to the holding model the region's tags name, and to the notes its rows link. `package-build lint` runs it as part of the `place` check; a note with no such table is not read.
+A region declares its rows in indexed `data.settlements`. The guard checks populations, markets, holders and regional coverage, and refuses authored body tables. Every publishing surface uses the same generated table, retaining the canonical `#settlements` heading or filling the author's existing section.
 
-| Export                   | Signature                                | Returns                                 | Use it when                                                                                                       |
-| ------------------------ | ---------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `HOLDING_MODELS`         | `const HOLDING_MODELS`                   | `readonly object[]`                     | the holding models in order, each its `tag`, the `holder` its Held by cell names, and whether a `person` may hold |
-| `SETTLEMENT_COLUMNS`     | `const SETTLEMENT_COLUMNS`               | `readonly object[]`                     | the table's columns in header order, each its `name` and whether it is `required`                                 |
-| `SETTLEMENTS_HEADING`    | `const SETTLEMENTS_HEADING`              | `string`                                | the level-two heading text a settlements table stands under                                                       |
-| `SETTLEMENT_TABLE_RULES` | `const SETTLEMENT_TABLE_RULES`           | `readonly object[]`                     | the rules in order, each its `name` — the prefix its findings carry — and what it `describe`s                     |
-| `findSettlementTables`   | `findSettlementTables(raw)`              | `{ heading: number, tables: object[] }` | reading a note's settlements tables, each with its header, its rows' cells and their 1-based lines and columns    |
-| `checkSettlementTables`  | `checkSettlementTables(note, { index })` | `object[]`                              | linting a place note's settlements tables against the corpus the index holds                                      |
+| Export                    | Signature                                                           | Returns             | Use it when                                                                                                                     |
+| ------------------------- | ------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `SETTLEMENT_COLUMNS`      | `const SETTLEMENT_COLUMNS`                                          | `readonly object[]` | the table's columns in header order, each its `name` and whether it is `required`; an optional one appears when a row states it |
+| `SETTLEMENTS_HEADING`     | `const SETTLEMENTS_HEADING`                                         | `string`            | the generated settlements heading                                                                                               |
+| `SETTLEMENT_TABLE_RULES`  | `const SETTLEMENT_TABLE_RULES`                                      | `readonly object[]` | the rules in order, each its `name` — the prefix its findings carry — and what it `describe`s                                   |
+| `settlementMarkdown`      | `settlementMarkdown(record)`                                        | `string`            | rendering indexed rows as the shared table                                                                                      |
+| `assertSettlementRecords` | `assertSettlementRecords(records, { fileOf, rawOf, foreignIndex })` | `void`              | refusing invalid indexed rows before publication                                                                                |
+| `SETTLEMENTS_FIELD`       | `const SETTLEMENTS_FIELD`                                           | `object`            | the vocabulary declaration for rows and tail                                                                                    |
+| `SETTLEMENT_ROW_FIELDS`   | `const SETTLEMENT_ROW_FIELDS`                                       | `readonly object[]` | the closed row declaration                                                                                                      |
+| `checkSettlementTables`   | `checkSettlementTables(note, { index })`                            | `object[]`          | linting a place note's settlements tables against the corpus the index holds                                                    |
 
 ### `engine.mapPlaces`
 
@@ -1329,12 +1333,30 @@ content tree can also compile into Foundry compendium packs.
 | `renderPages`         | `function renderPages(pages, options)`           | `{{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}`                                                   | Renders every page.                                                                                                        |
 | `resolveSitePass`     | `function resolveSitePass(name, options)`        | `{{beforeLinks?: Function}}` The bundle.                                                                                                             | Resolves `site.pass` to its bundle.                                                                                        |
 | `sitePageDecorator`   | `sitePageDecorator(config, index)`               | Function                                                                                                                                             | Add the site's infobox and being metadata to a rendered page.                                                              |
-| `buildSite`           | `buildSite({ config, sqlTables })`               | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null, site?: object}}` | Collects, checks and renders a content tree's pages, and reports what it found; returns each page for the site's renderer. |
+| `buildSite`           | `buildSite({ config, sqlTables, progress })`     | `{{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null, site?: object}}` | Collects, checks and renders a content tree's pages, and reports what it found; returns each page for the site's renderer. |
 
 `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.
 
+`buildSite`, `engine/site-render.mjs`'s `buildPackageSite` and `writeSite`, and
+`engine/site-root.mjs`'s `writeSiteRoot` accept an optional `progress(message)`
+callback for phase summaries. It receives prose, independently of findings.
+
+`engine/site-serve.mjs`'s `serveSite({ config, out, root?, host?, port?, search?,
+year?, report? })` resolves with `{ url, settled, close, done }` when HTTP listens,
+before the initial build. Await `settled()` to wait for that build and queued
+edits, and `close()` to stop watching and serving. `done` resolves on close;
+an unexpected HTTP failure rejects it and stops the watchers. Its `report` callback
+receives `progress` events with a `message`, alongside `built`, `page`,
+`theme`, `failed` and `error` events; a fatal HTTP error has `fatal: true`.
+Failed builds are reported through that
+callback and leave the previous output in service. HTTP runs in a separate
+thread so synchronous rendering does not stall requests; the resolved
+configuration and incremental render state stay in the calling thread. Every
+update is prepared in a separate output tree, then installed between HTTP
+requests so readers receive complete files.
+
 ### `engine.contentRender`
 
 `createRenderer(target, options?)` builds the one markdown-it configuration every target renders through. `target` is `"foundry"`, `"web"`, `"preview"` or `"book"`. The renderer holds the configured parser (`md`), the names of the plugins installed (`plugins`), and three functions: `prepare` writes the constructs markdown-it has no syntax for — marked text, captioned items, named blocks, verse and alerts — as HTML between blank lines; `render` prepares and renders to HTML; `renderInline` renders one inline run. The `book` target parses only, and its Typst stage reads the tokens.
@@ -1362,6 +1384,16 @@ complete source. Reference-only positions contribute no work shape. A wholly
 reference-only body carries its references in `model.notes`, rendered once
 outside native-font wrappers without a verse row or label.
 
+Verse regions retain the authored `body` and its absolute `bodyStart` and
+`bodyEnd`. Their `logicalBody` excludes Markdown list and blockquote prefixes;
+`bodyOffsets` maps each logical UTF-16 position, including the exclusive end,
+back to an authored body offset. `parseVerse(logicalBody, {sourceOffsets:
+bodyOffsets, footnotes})` returns the whole model in authored body coordinates:
+line bounds and character offsets, stanza and canto bounds, boundaries, layout
+ranges and findings all use that map. Omitted prefixes are layout ranges, so
+Roman and native projections exclude them. Add `bodyStart` to a model offset to
+locate it in the complete source. LF and CRLF retain their authored lengths.
+
 | Export           | Signature                          | Returns                                                      | Use it when                                                                              |
 | ---------------- | ---------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
 | `createRenderer` | `createRenderer(target, options?)` | `{ target, md, plugins, prepare, render, renderInline }`     | Rendering a note body for one target with the rules every target shares.                 |
@@ -1446,17 +1478,17 @@ The charset authored content is held to, so a book can choose its face. The pack
 
 ### `engine.romanCharacters`
 
-Exact permitted Roman source characters for configured languages, before script
-encoding. Inventories come from `data.roman` on each language's own note.
+A configured language's Roman additions to the shared punctuation standard,
+before script encoding. Inventories come from `data.roman` on each language's own note.
 
-| Export                    | Signature                                    | Returns                       | Use it when                                                                                                                                                          |
-| ------------------------- | -------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `isRomanWhitespace`       | `isRomanWhitespace(char)`                    | `boolean`                     | recognizing standard spaces and ASCII tab or line whitespace                                                                                                         |
-| `romanInventoryProblems`  | `romanInventoryProblems(value)`              | `string[]`                    | checking NFC, repeated characters and forbidden whitespace or controls in a literal inventory                                                                        |
-| `romanInventoriesOf`      | `romanInventoriesOf(records, languages)`     | `Map<string, RomanInventory>` | looking up a configured language's own inventory by name or BCP 47 tag                                                                                               |
-| `romanTextProblems`       | `romanTextProblems(text, inventory, stream)` | `{offset, message}[]`         | validating standard Roman punctuation and language additions with exact UTF-16 offsets; pass a `stream` state to continue sentences and quotations from earlier runs |
-| `romanPunctuationState`   | `romanPunctuationState()`                    | `{sentenceStart, quotes}`     | starting a stream of runs whose sentences and quotations continue from one run to the next                                                                           |
-| `romanUnclosedQuotations` | `romanUnclosedQuotations(quotes)`            | `{offset, message}[]`         | reporting the quotations still open where a stream of runs ends                                                                                                      |
+| Export                    | Signature                                    | Returns                       | Use it when                                                                                                                                                              |
+| ------------------------- | -------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isRomanWhitespace`       | `isRomanWhitespace(char)`                    | `boolean`                     | recognizing standard spaces and ASCII tab or line whitespace                                                                                                             |
+| `romanInventoryProblems`  | `romanInventoryProblems(value)`              | `string[]`                    | checking NFC, repeats and forbidden whitespace, controls, standard punctuation, literal markers, semicolons, colons, English double quotes and setting-script characters |
+| `romanInventoriesOf`      | `romanInventoriesOf(records, languages)`     | `Map<string, RomanInventory>` | looking up a configured language's own inventory by name or BCP 47 tag                                                                                                   |
+| `romanTextProblems`       | `romanTextProblems(text, inventory, stream)` | `{offset, message}[]`         | validating standard Roman punctuation and language additions with exact UTF-16 offsets; pass a `stream` state to continue sentences and quotations from earlier runs     |
+| `romanPunctuationState`   | `romanPunctuationState()`                    | `{sentenceStart, quotes}`     | starting a stream of runs whose sentences and quotations continue from one run to the next                                                                               |
+| `romanUnclosedQuotations` | `romanUnclosedQuotations(quotes)`            | `{offset, message}[]`         | reporting the quotations still open where a stream of runs ends                                                                                                          |
 
 ### `engine.pathCharset`
 
@@ -1491,6 +1523,10 @@ Naming an interface icon in a note, without drawing it there. The user guide des
 
 Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cannot say, a note does not say — it gets a construct every surface can render, the way `:icon …:` replaces a pasted glyph.
 
+`HTML_TAG` excludes the doubled `<<` that opens a typed quotation. A quotation
+written with `<<` and `>>` draws no raw-HTML warning; adjacent real tags retain
+their findings and positions.
+
 | Export            | Signature                               | Returns                                                                                                                                                              | Use it when                                                    |
 | ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
 | `HTML_TAG`        | `const HTML_TAG`                        | —                                                                                                                                                                    | A raw HTML tag, opening, closing or self-closing.              |
@@ -2573,6 +2609,16 @@ 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.
 
+`engine/content-scripts` exposes `runContext(config, records?, {referenceName}?)`.
+It returns the language, encoding and metre context used by run scanning.
+`referenceName(target)` supplies the rendering or validation index's current
+name for an Address, including dependency targets, or `undefined` when none
+resolves. This lookup takes precedence over the local-record fallback and
+belongs only to the returned context; shared cached lexical data does not
+share a lookup between page or audience views. A metre line whose empty link
+label has no resolved spoken text stays unscanned, while the link validator
+reports invalid targets independently.
+
 `buildLinkIndex` and `buildContentLinkIndex` accept an optional `foreign` view
 from the same session; their diagnostic and routed resolver contracts remain
 distinct. `collectAnchors`, `markupAnchorFindings`, `markupFindings`, journal
@@ -2922,10 +2968,13 @@ const inferred = encode(data, null, "say", { enc: "aelwsemaronenc" });
 
 Both functions take `(data, language, text, options?)` and return
 `{text, findings}`; encoding with a language also returns source-positioned
-`pieces`. A language key selects its encoding, face and lexical inputs.
-`options.enc` and `options.font` override the encoding and face; `options.verse`
-asks the encoder to interpret verse structure. With `language: null`, `enc` is
-required and only the encoding's rows apply.
+`pieces`. `options.enc` selects a consumer-authored encoding document, which
+supplies its language and font. An explicit language must agree with that
+document; a null or omitted language infers it and uses its lexical inputs.
+`options.font` must agree with the encoding's font; `options.verse` asks the
+encoder to interpret verse structure. An omitted `enc`, or `enc: "default"`,
+preserves the Roman text. Bare conversion without lexical inputs uses the
+pure `encodeText` and `decodeText` functions in `engine/encoding.mjs`.
 
 Language conversion uses the same pure `encodeWithLanguage` and
 `decodeWithLanguage` functions as the build. Recorded native writings and
@@ -2933,7 +2982,7 @@ parts precede encoding rows, and decoding can recover an unmarked word from
 the lexicon. An unknown word gives a positioned finding. A bare refusal
 returns empty text and an error finding. Findings carry `severity`, `message`,
 `offset` (UTF-16), and one-based Unicode-code-point `line` and `column`.
-Invalid data, unknown languages and missing encoding selections throw an
+Invalid data, unknown languages and unknown encoding selections throw an
 error before conversion. `validateData(data)` returns the validated data or
 throws; it opens no files.
 

package/docs/authoring/frontmatter.md

@@ -117,7 +117,7 @@ Write `government: null` for **complete anarchy**. Omitting the key leaves gover
 | Any                   | Explicit `null`     | None; complete anarchy           |
 | Any                   | Affiliation Address | None; the reference must resolve |
 
-These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `parents`, containment and capitals do not supply a government. The generated **Governed by** and **Governed places** sections use only explicit government references.
+These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `parents`, containment and capitals do not supply a government, with one exception: a `district` that omits the key falls under the government of its nearest parent that states one, and is treated as stating that value, so it receives no advisory. An explicit value on the district, `null` included, is its own. The generated **Governed by** and **Governed places** sections use the explicit references and these inherited ones.
 
 ## Publication and summaries
 

package/docs/authoring/links-and-markup.md

@@ -237,6 +237,30 @@ A captioned item inside the section is withheld with it: in Foundry the item's o
 
 The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
+## Book page breaks
+
+Write `--- {.page-break}` on its own line between blocks, with blank lines around it:
+
+```markdown
+The first passage ends here.
+
+--- {.page-break}
+
+The next passage starts on a fresh book page.
+```
+
+The book starts a fresh page without drawing a rule. If the marker already
+falls at the top of a page, it adds no blank page. The website, Foundry and
+both editor preview views omit the marker. Plain `---`, `***` and `___` keep
+their ordinary horizontal rules. Code blocks and verse divs keep the marker
+as literal text.
+
+Only `---` accepts `.page-break`; `*** {.page-break}` and `___ {.page-break}`
+are findings. Other classes, ids and attributes on an attributed `---` line
+are findings too. A page break stands between blocks at the top level of a
+note: putting one inside a list, block quote, alert, footnote definition,
+secret block or fenced div is a finding at the marker's line and column.
+
 ## Captions and numbered references
 
 Write a caption on its own line **before** the item it describes, with a blank line before and after the caption. `:` produces an unnumbered caption; `:@` produces a numbered caption. One or more spaces separate the marker from its text. An optional attribute block at the end accepts an identifier, classes and named attributes:
@@ -424,6 +448,20 @@ Periods inside the first inline span can set indentation; periods in later spans
 are literal. Tabs inside a verse div are errors. The div body is opaque to Markdown block syntax:
 lines beginning `- `, `1. `, `# `, `> ` or four spaces stay verse text.
 
+A verse div may sit inside a blockquote, a list item, or nested combinations of
+both. Write the surrounding container prefix on each line, including blank
+stanza lines. Container markers stay outside the verse text; logical lines,
+indentation and stanza boundaries follow the same rules as a standalone div.
+Findings point to the authored line and column, including its container prefix.
+
+```markdown
+> ::: {.verse}
+> One/..Two
+>
+> Three
+> :::
+```
+
 These two bodies have the same lines and indentation:
 
 ```markdown
@@ -491,13 +529,23 @@ language's stress rules; it reports an error at the line:
 Speaker labels and stage directions (`.speaker` and `.direction`) are presentation
 only: their text is not scanned, and a line containing only those spans is skipped.
 
+Wikilinks contribute only their visible labels to the beat count. An empty label
+(`[[place-ashkarad|]]`) contributes the indexed target's name, including a name
+from a dependency. Address segments, anchors and link attributes contribute no
+beats. If an empty label has no resolved spoken text, the line is not scanned;
+the link check reports invalid targets separately. Empty same-page caption
+references depend on page or book numbering and leave the line unscanned when
+that display text is unavailable.
+
 Beats are counted this way:
 
 - **Syllables** are vowel groups. A vowel is a letter whose base is `a`, `e`,
   `i`, `o` or `u`, and a pair the language lists in
   `data.sounds.syllables.vowelPairs` is one syllable.
-- **Every word of two or more syllables has one beat**, on its stressed
-  syllable. The language's stress rule places it: `two` for a word of two
+- **A word of two or more syllables has one beat**, on its stressed
+  syllable, but may go unstressed when every lexicon class is a function class:
+  any base other than `n`, `v`, `adj`, `num` or `name`. A word with any content
+  class, or no lexicon entry, keeps its beat. The language's stress rule places it: `two` for a word of two
   syllables, `longer` for a word of three or more, and a vowel carrying the
   rule's `mark` is stressed wherever it sits.
 - **A one-syllable noun, verb, adjective, numeral or name has a beat.** A
@@ -506,7 +554,7 @@ Beats are counted this way:
   through `lang=` as it is for the word check, including words inherited from
   its family. All entries for a spelling in the nearest lexicon supply their
   classes. A form the
-  language's own rules derive takes its word's class. A word whose entries differ in class is a
+  language's own rules derive takes its word's class. A one-syllable word with both content and function classes has a
   beat that may be left out.
 - **A one-syllable word the lexicon does not hold is a content word** and has a
   beat. The word check reports the word separately.
@@ -1490,13 +1538,14 @@ Nested frontmatter is addressed exactly as a note writes it: `name.full`, `sohl.
 
 The build adds sections to the end of a note, after everything you wrote, listing what other notes say about it. Each appears only where it has something to list, under a fixed anchor:
 
-| Section           | Anchor           | Lists                                                                |
-| ----------------- | ---------------- | -------------------------------------------------------------------- |
-| Within            | `within`         | on a place, the places whose `parents` name it, grouped by kind      |
-| Governed by       | `governedby`     | on a place, the affiliation its `government` names                   |
-| Governed places   | `governedplaces` | on an affiliation, the places naming it as their `government`        |
-| In song and story | `insongandstory` | the works of literature whose `subjects` name the note or its events |
-| From here         | `fromhere`       | on a place with borders or routes, the map drawn from it             |
+| Section           | Anchor           | Lists                                                                         |
+| ----------------- | ---------------- | ----------------------------------------------------------------------------- |
+| Within            | `within`         | on a place, the places whose `parents` name it, grouped by kind               |
+| Governed by       | `governedby`     | on a place, the affiliation its `government` names                            |
+| Governed places   | `governedplaces` | on an affiliation, the places naming it as their `government`                 |
+| Office holders    | `officeholders`  | on an affiliation, each office's living holders, from the beings that name it |
+| In song and story | `insongandstory` | the works of literature whose `subjects` name the note or its events          |
+| From here         | `fromhere`       | on a place with borders or routes, the map drawn from it                      |
 
 The event sections below sit among them, and the [format reference](../reference/format-details.md#generated-sections) gives the order. Each entry links to the note it names; a note with no page of its own is named in plain text. Replace a section the way you replace an event view, by writing your own with the same anchor: