@heroiclands/package-build 25.5.5 → 25.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @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**

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/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`
 
@@ -1519,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.              |

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

@@ -258,8 +258,8 @@ 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, secret block or fenced
-div is a finding at the marker's line and column.
+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
 
@@ -1538,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:
 

package/docs/content-format.md

@@ -96,6 +96,8 @@ markers scoped to each note. Definition lists use a term followed by one or
 more `: definition` lines. See [footnotes and definition lists](authoring/links-and-markup.md#footnotes-and-definition-lists)
 for examples and placement in journals, web pages, and books.
 
+A query selects notes by property, tag or address, never by where a note's file sits: a fence that names `file.path`, `file.folder` or `file.name` is an error at the reference, and a note moved between folders changes no query's answer.
+
 An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
 Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
@@ -203,7 +205,44 @@ The [first-note guide](authoring/first-note.md) shows the build commands and how
 
 Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](authoring/frontmatter.md#place-governments).
 
-A region may list its settlements in a table under `## Settlements` — name, market, people and holder, one row each — tagged with the holding model it is written in. A row links the settlement's note where one exists, and `package-build lint` holds the two to agreement. See [a region's settlements table](reference/format-details.md#a-regions-settlements-table).
+A region declares its table in `data.settlements: { rows, tail }`. The rows
+carry the settlement's `population` and numeric `market`, and either `place`
+(the existing note's Address, default type `place`) or `name` (plain text where
+no note exists), never both. Where the region's culture holds land, a row's
+optional `heldBy` names what holds it by Address (an affiliation or a being,
+default type `affiliation`), and what that note is says how the land is held: a
+temple, a lineage, the city, a kin group. A people who hold no land state no
+`heldBy`, and their table has no Held by column. Optional `for` states why the
+settlement exists. `tail` is the sentence stating what the table leaves out.
+
+The guard reads indexed rows. A linked row's population and market agree with
+its note, and every settlement note covered through `parents` has one row in
+the nearest declaring region. `government` states who governs; it never supplies
+who holds the land. HTML, Foundry and Typst render the declared table once.
+A body table under `## Settlements` is an error at its header, naming
+`data.settlements`; no facts are read from it.
+
+```yaml
+data:
+  settlements:
+    rows:
+      - place: ashford
+        market: 4
+        population: 3400
+        heldBy: affiliation-crown
+        for: the ford on the drove road
+      - name: Weyshott
+        market: 2
+        population: 420
+        heldBy: being-aldwyn
+        for: the manor's mill
+      - name: Cold Hatch
+        market: 1
+        population: 60
+    tail: Some four hundred further villages lie in the vale, none of them named here.
+```
+
+See [a region's settlements table](reference/format-details.md#a-regions-settlements-table).
 
 A being states its gender, frame and appearance in words from one closed vocabulary: `data.gender`, `data.frame`, and `data.appearance.eye_color`, `hair_color`, `skin_color` and `complexion` each take only the words listed for them, and any other value is an error at the value. `complexion` is a list, required once a being states an appearance. `data.appearance.extra_features` lists the being's visible physical marks, each a short plain description of one, and an entry stating a colour, a skin condition or anything that is not a mark is an error. See [a being's look](reference/format-details.md#a-beings-look).
 

package/docs/diagnostics.md

@@ -303,8 +303,8 @@ The optional [book page break](authoring/links-and-markup.md#book-page-breaks)
 uses only `--- {.page-break}` between blocks at the note's top level.
 Other classes, ids or attributes on an attributed `---` line receive findings
 at their opening brace. A `.page-break` on `***` or `___` receives a finding
-at the marker. A marker inside a list, block quote, alert, secret block or
-fenced div receives `a page break stands between blocks at the top level of a
+at the marker. A marker inside a list, block quote, alert, footnote definition,
+secret block or fenced div receives `a page break stands between blocks at the top level of a
 note`, at that marker's line and column. Missing surrounding blank lines
 receive the same placement finding. Code blocks and complete verse divs are
 literal and receive no page-break findings.

package/docs/guides/reference-pages.md

@@ -134,7 +134,10 @@ its language's code. It also has ASCII-folded `nameAscii` and `formsAscii`, the
 listed forms by language, for searching names typed without diacritics, and
 `lang`, the language the note is in, derived as
 [a note's language](../reference/format-details.md#a-notes-language) describes.
-A language note that `languages:` names carries its code as `languageCode`. Asset files under `assets/icons`, `assets/images`, and
+A language note that `languages:` names carries its code as `languageCode`.
+An affiliation carries `officeHolders`, each of its offices that a living
+being holds with those beings' Addresses, derived as
+[office holders](../reference/format-details.md#type-affiliation) describes. Asset files under `assets/icons`, `assets/images`, and
 `assets/audio` have records in the same index, identified by an `asset` block.
 The index is disposable build output; regenerate it from the authored tree
 when the content changes.

package/docs/guides/site.md

@@ -244,7 +244,7 @@ notes' sources. A page is reachable when an authored link leads to it:
 The links the build generates do not make a page reachable. These are the
 Related card, the previous and next links, the infobox links, and the sections
 generated after a note's text (Within, Governed by, Governed places,
-Chronology, Events, Accounts, What followed, In song and story). Each is drawn
+Office holders, Chronology, Events, Accounts, What followed, In song and story). Each is drawn
 without a link to a page outside the reachable set, and a section left with
 nothing under it is not drawn. An infobox value that names an unreachable page
 is set as plain text. So is a link in a dictionary or glossary entry, whether