@heroiclands/package-build 23.2.1 → 23.3.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @heroiclands/package-build
 
+## 23.3.0
+
+### Minor Changes
+
+**Being notes**
+
+- A being's eye, hair and skin colour and its complexion now take words from a fixed list, alongside gender and frame, and any other value fails `package-build lint` naming the accepted words.
+- Variant spellings and empty values are refused too: write `grey` rather than `gray`, and leave a field out when it is unrecorded.
+- A complexion takes one word or a list of them; distinguishing marks stay free text in `extra_features`.
+- The format reference lists every word with what it means.
+
+### Patch Changes
+
+A region can list its settlements in a table under `## Settlements` — name, market, people and holder, one row each — tagged with how its countryside is held: `held`, `endowed`, `registered`, `kin` or `polis`. `package-build lint` checks the table's columns, its market classes and figures, that a holder suits the region's model, and that every linked row agrees with the settlement's own note.
+
+`e2e` now says when the Foundry licence is unsigned, and how to sign it, instead of timing out waiting for a world.
+
+## 23.2.2
+
+### Patch Changes
+
+A book author can list leading words such as "Kingdom of" or "Ritual:" under `pdf.indexHeads`, and the index also files those notes under the rest of the name, so "Kingdom of Targud" is found under Targud.
+
+A book whose Typst is killed, most often by the memory limit, now fails naming the signal instead of an empty reason, and a Typst that exits silently reports its exit code.
+
 ## 23.2.1
 
 ### Patch Changes

package/ci/content-format-reference.mjs

@@ -18,6 +18,7 @@ import { formatGenerated } from "../engine/format-generated.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     BEING_ARCHETYPES,
+    BEING_LOOK_VOCABULARY,
     NOTE_TOP_LEVEL_FIELDS,
     NOTE_VOCABULARY,
     SHARED_DATA_FIELDS,
@@ -236,20 +237,42 @@ const details = fs.readFileSync(detailsPath, "utf8");
 if (!/<!-- archetypes:start -->[\s\S]*?<!-- archetypes:end -->/.test(details)) {
     throw new Error("The archetype reference requires its generation markers");
 }
+if (!/<!-- being-look:start -->[\s\S]*?<!-- being-look:end -->/.test(details)) {
+    throw new Error("The being-look reference requires its generation markers");
+}
 const archetypes = Object.entries(BEING_ARCHETYPES)
     .map(([name, meaning]) => `- ${name}: ${meaning}`)
     .join("\n");
+// One table per field of a being's look, every word with its label and meaning,
+// written from the declaration the lint closes each field to.
+const beingLook = Object.entries(BEING_LOOK_VOCABULARY)
+    .flatMap(([field, words]) => [
+        `**\`data.${field}\`**`,
+        "",
+        "| Word | Label | Meaning |",
+        "| --- | --- | --- |",
+        ...words.map(
+            ({ value, label, describe }) => `| \`${value}\` | ${cell(label)} | ${cell(describe)} |`,
+        ),
+        "",
+    ])
+    .join("\n");
 const updatedDetails = await formatGenerated(
-    details.replace(
-        /<!-- archetypes:start -->[\s\S]*?<!-- archetypes:end -->/,
-        `<!-- archetypes:start -->\n${archetypes}\n<!-- archetypes:end -->`,
-    ),
+    details
+        .replace(
+            /<!-- archetypes:start -->[\s\S]*?<!-- archetypes:end -->/,
+            `<!-- archetypes:start -->\n${archetypes}\n<!-- archetypes:end -->`,
+        )
+        .replace(
+            /<!-- being-look:start -->[\s\S]*?<!-- being-look:end -->/,
+            `<!-- being-look:start -->\n\n${beingLook}\n<!-- being-look:end -->`,
+        ),
     detailsPath,
 );
 if (process.argv.includes("--check")) {
     if (details !== updatedDetails) {
         console.error(
-            "docs/reference/format-details.md: error: run node ci/content-format-reference.mjs to refresh the archetype reference",
+            "docs/reference/format-details.md: error: run node ci/content-format-reference.mjs to refresh the archetype and being-look references",
         );
         process.exitCode = 1;
     }

package/content-config.mjs

@@ -776,6 +776,7 @@ const PDF_KEYS = [
     "unprinted",
     "coverage",
     "indexSeeAlso",
+    "indexHeads",
     "copyright",
     "license",
 ];
@@ -1920,6 +1921,17 @@ function normalizePdf(value, rootDir, contentPackage) {
         fail("pdf.copyright", "must be one line — the licence statement is the one that runs on");
     }
 
+    /** @type {string[]} */
+    const indexHeads = [];
+    if (input.indexHeads !== undefined) {
+        if (!Array.isArray(input.indexHeads)) fail("pdf.indexHeads", "must be a list of strings");
+        input.indexHeads.forEach((head, i) => {
+            const field = `pdf.indexHeads[${i}]`;
+            if (typeof head !== "string" || !head.trim()) fail(field, "must be a non-empty string");
+            indexHeads.push(head);
+        });
+    }
+
     return Object.freeze({
         books,
         out: input.out === undefined ? "" : requireNonEmptyString(input.out, "pdf.out"),
@@ -1939,6 +1951,9 @@ function normalizePdf(value, rootDir, contentPackage) {
         // Whether an index names a note another book prints, as
         // `Name: Book title, p. N`.
         indexSeeAlso: optionalBoolean(input.indexSeeAlso, "pdf.indexSeeAlso", false),
+        // Leading words an index inverts: `Kingdom of ` files `Kingdom of
+        // Targud` again as `Targud, Kingdom of`.
+        indexHeads: Object.freeze(indexHeads),
         copyright: copyright.trim(),
         license:
             input.license === undefined ?

package/docs/api.md

@@ -323,29 +323,30 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `dnd5e`, `hm3`, `sohl`. A key outside this list is an error at its own line. The system blocks are one per system the address vocabulary recognizes, sorted by name after the fixed keys, so a further system is a change to `SYSTEM_IDS` alone. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
 
-| Export                    | Signature                                    | Returns                                  | Use it when                                                                                       |
-| ------------------------- | -------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `DRAFT_TAG`               | `const DRAFT_TAG`                            | —                                        | naming the declared tag that marks a note as unfinished                                           |
-| `GM_TAG`                  | `const GM_TAG`                               | —                                        | naming the declared tag that marks a GM-only note                                                 |
-| `BEING_ARCHETYPES`        | `const BEING_ARCHETYPES`                     | `Readonly<Record<string, string>>`       | looking up the case-sensitive being archetypes and their meanings                                 |
-| `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                        | looking up, per content type, its `data:` field list and its closed `subType` values              |
-| `NOTE_TOP_LEVEL_FIELDS`   | `const NOTE_TOP_LEVEL_FIELDS`                | `readonly TopLevelFieldSpec[]`           | reading the top-level keys a note accepts, in formatted order, with what each one means           |
-| `NOTE_TOP_LEVEL_KEYS`     | `const NOTE_TOP_LEVEL_KEYS`                  | `readonly string[]`                      | reading just the key names, in the order the formatter writes them                                |
-| `NOTE_TOP_LEVEL_KEY_SET`  | `const NOTE_TOP_LEVEL_KEY_SET`               | `ReadonlySet<string>`                    | testing whether a top-level key is one the note format declares                                   |
-| `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`               | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere      |
-| `EVENTS_FIELD`            | `const EVENTS_FIELD`                         | `DataFieldSpec`                          | reading the one `events` declaration that `lore`, `place` and `affiliation` share, with its check |
-| `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                              |
-| `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                      | reading the declared tags a note of a type may carry, flattened                                   |
-| `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                         |
-| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading single-valued tag slots declared for a note type                                          |
-| `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in      |
-| `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                          |
-| `isGmNote`                | `isGmNote(fm)`                               | `boolean`                                | checking whether a note is restricted to GM-facing output                                         |
-| `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                                  |
-| `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                     |
-| `assertVocabularyCharset` | `assertVocabularyCharset(vocabulary, where)` | throws                                   | refusing a vocabulary declaration whose type or subType breaks the address charset                |
-| `dataFields`              | `dataFields(type, vocabulary)`               | `readonly DataFieldSpec[] \| undefined`  | looking up the `data:` keys a note type may carry                                                 |
-| `subTypes`                | `subTypes(type, vocabulary)`                 | `readonly string[] \| null \| undefined` | looking up the closed `subType` values a note type declares                                       |
+| Export                    | Signature                                    | Returns                                         | Use it when                                                                                                                   |
+| ------------------------- | -------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `DRAFT_TAG`               | `const DRAFT_TAG`                            | —                                               | naming the declared tag that marks a note as unfinished                                                                       |
+| `GM_TAG`                  | `const GM_TAG`                               | —                                               | naming the declared tag that marks a GM-only note                                                                             |
+| `BEING_ARCHETYPES`        | `const BEING_ARCHETYPES`                     | `Readonly<Record<string, string>>`              | looking up the case-sensitive being archetypes and their meanings                                                             |
+| `BEING_LOOK_VOCABULARY`   | `const BEING_LOOK_VOCABULARY`                | `Readonly<Record<string, readonly LookWord[]>>` | reading the closed words a being's gender, frame and appearance take, each with its label and meaning, keyed by `data:` field |
+| `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                               | looking up, per content type, its `data:` field list and its closed `subType` values                                          |
+| `NOTE_TOP_LEVEL_FIELDS`   | `const NOTE_TOP_LEVEL_FIELDS`                | `readonly TopLevelFieldSpec[]`                  | reading the top-level keys a note accepts, in formatted order, with what each one means                                       |
+| `NOTE_TOP_LEVEL_KEYS`     | `const NOTE_TOP_LEVEL_KEYS`                  | `readonly string[]`                             | reading just the key names, in the order the formatter writes them                                                            |
+| `NOTE_TOP_LEVEL_KEY_SET`  | `const NOTE_TOP_LEVEL_KEY_SET`               | `ReadonlySet<string>`                           | testing whether a top-level key is one the note format declares                                                               |
+| `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`                      | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere                                  |
+| `EVENTS_FIELD`            | `const EVENTS_FIELD`                         | `DataFieldSpec`                                 | reading the one `events` declaration that `lore`, `place` and `affiliation` share, with its check                             |
+| `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                               | looking up the tags a note type may declare, grouped                                                                          |
+| `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                             | reading the declared tags a note of a type may carry, flattened                                                               |
+| `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                                      | reading the declared tag groups that apply to a note type                                                                     |
+| `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                           | reading single-valued tag slots declared for a note type                                                                      |
+| `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                       | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in                                  |
+| `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                       | checking whether a note is tagged as an unfinished draft                                                                      |
+| `isGmNote`                | `isGmNote(fm)`                               | `boolean`                                       | checking whether a note is restricted to GM-facing output                                                                     |
+| `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                        | building the message for a `subType` outside the address charset                                                              |
+| `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                        | building the message for a `type` outside the address charset                                                                 |
+| `assertVocabularyCharset` | `assertVocabularyCharset(vocabulary, where)` | throws                                          | refusing a vocabulary declaration whose type or subType breaks the address charset                                            |
+| `dataFields`              | `dataFields(type, vocabulary)`               | `readonly DataFieldSpec[] \| undefined`         | looking up the `data:` keys a note type may carry                                                                             |
+| `subTypes`                | `subTypes(type, vocabulary)`                 | `readonly string[] \| null \| undefined`        | looking up the closed `subType` values a note type declares                                                                   |
 
 ### `engine.infobox`
 
@@ -507,6 +508,19 @@ What trade a settlement supports (`data.market`): the six-step scale, stated onc
 | `marketClass`    | `marketClass(value)`   | `object\|undefined` | the class a value names, for rendering what a number means                                        |
 | `checkMarket`    | `checkMarket(note)`    | `object[]`          | linting a place's `market` — a value off the scale, located at the value that states it           |
 
+### `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.
+
+| 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                                      |
+
 ### `engine.mapPlaces`
 
 The places a map is drawn from — this package's index records and every fetched dependency's entries, read through one shape — and what their `parents` say: the world, the continents, each place's continent, and everything the containment tree can get wrong, reported as findings located at the entry that states it.

package/docs/authoring/frontmatter.md

@@ -35,6 +35,8 @@ The [note-type reference](../reference/note-types.md) lists every field accepted
 
 A being's `data.archetypes` names the roles it can fill in an adventure. Choose every specific role that fits, such as `entertainer` for a performer or `guildsperson` for someone whose professional training or connections matter. Use `[commoner]` when no specific archetype fits. `commoner` cannot share the list with another value. The [archetype reference](../reference/format-details.md#actors) defines the available roles.
 
+A being's look is stated in a closed vocabulary. `data.gender` and `data.frame` take one word each, as do `data.appearance.eye_color`, `hair_color` and `skin_color`; `data.appearance.complexion` takes one word or a list of them. A value outside a field's list — a variant spelling such as `gray`, a word from another field's list, or an empty string — is an error naming the words the field takes. Leave a field out when the fact is unrecorded. `data.appearance.extra_features` is a free-text list for the marks no word covers. The [look reference](../reference/format-details.md#a-beings-look) gives every word and what it means.
+
 A `sohl:`, `hm3:` or `dnd5e:` block holds values for that Foundry system. Its `system:` child contains values sent to the system's DataModel. The system block can override shared routing and art where the declared field permits it. `data.pack` and `data.packFolder` are shared routes; a system-specific route belongs in that system block. The [detailed mapping reference](../reference/format-details.md#mappings-every-type-shares) and [system-block explanation](../reference/format-details.md#frontmatter-has-three-regions) cover precedence and emitted fields.
 
 One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.

package/docs/configuration.md

@@ -1161,6 +1161,7 @@ The keys of `pdf` itself are shared by every book:
 | `pdf.unprinted`    | string (`WHERE` clause)       | no       | `""`                   |
 | `pdf.coverage`     | `warning` \| `error` \| `off` | no       | `warning`              |
 | `pdf.indexSeeAlso` | boolean                       | no       | `false`                |
+| `pdf.indexHeads`   | string[]                      | no       | `[]` — none inverted   |
 | `pdf.copyright`    | string (one line)             | no       | `""`                   |
 | `pdf.license`      | string (one or more lines)    | no       | `""`                   |
 
@@ -1185,6 +1186,15 @@ The keys of `pdf` itself are shared by every book:
   `Name: _Book title_, p. N` with the page the note's entry starts on in its
   home book. It is `false` by default, and the index then lists only the notes
   the book is home to. See [The index](guides/book.md#the-index).
+- `pdf.indexHeads` lists leading words that open many names, such as
+  `Kingdom of ` or `Ritual:`. Each is matched literally against the start of
+  a note's `name.full`, so a head that ends in a space includes it. A note
+  whose name opens with one is also filed in the index under the rest of its
+  name, followed by the head without its trailing space or colon: `Kingdom of
+Targud` is also listed as `Targud, Kingdom of`, with the same pages as the
+  note's own entry. Where several heads match, the longest applies. A blank
+  entry, or a value that is not a list of strings, is an error at the offending
+  key. See [The index](guides/book.md#the-index).
 - A note several books select prints in each of them. Its **home book** is the
   first book in `pdf.books` that selects it; a note a book selects twice is
   still one book's, and prints at each position. After the books are built the

package/docs/content-format.md

@@ -90,6 +90,10 @@ 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 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. `data.appearance.extra_features` stays free text. See [a being's look](reference/format-details.md#a-beings-look).
+
 Places, affiliations, lore and beings may name their culture in `data.culture`, and a `doc` of `subType: settingguide` must. A place or affiliation that names none inherits the culture of its parents. See [culture in the index](reference/format-details.md#culture-in-the-index).
 
 Blockquote alerts use `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!]`, with optional attributes after the marker. They replace the former info and warn div fences; secret blocks remain supported. See [alerts](authoring/links-and-markup.md#alerts).

package/docs/guides/book.md

@@ -409,9 +409,19 @@ notes the book prints.
 | Term                     | Source                | Shown as                                                                           |
 | ------------------------ | --------------------- | ---------------------------------------------------------------------------------- |
 | A note's name            | `name.full`           | the page of the note's entry in **bold**, then the pages of every authored mention |
+| A name without its head  | `name.full`           | the same pages as the note's entry, filed as `Targud, Kingdom of`                  |
 | An alias                 | `name.aliases`        | _see_ the note's name                                                              |
 | An event's in-world name | `data.events[].names` | _see_ the name of the note that holds the event                                    |
 
+A name that opens with a generic word a reader would not look under, such as
+`Kingdom of Targud` or `Ritual: Blessing`, is also filed under the rest of the
+name when [`pdf.indexHeads`](../configuration.md) lists that opening: with
+`indexHeads: ["Kingdom of ", "Ritual:"]` the index lists `Targud, Kingdom of`
+and `Blessing, Ritual`, each with the pages of the note's entry. No alias is
+needed to find the note under its distinctive word. An inverted entry that would
+print the same as another note's term is told apart by the note's subtype, then
+its parent place, as any two equal terms are.
+
 To get a term into the index, give the note a `name.full`, add an alias or an
 event name, or link to the note from prose with a wikilink. A wikilink to a note
 the book prints adds the page it appears on. A term mentioned several times on

package/docs/guides/e2e.md

@@ -91,7 +91,14 @@ image made for that build. The first run downloads the release, which needs
 `FOUNDRYVTT_CACHE`, or in `container_cache` beneath the data root when that is
 unset. Once the archive is cached and the stage has a licence, later runs
 start without signing in to foundryvtt.com, so its rate limit never stops a
-run. Under rootless Docker, set
+run. A key alone does not sign the licence. The image applies
+`FOUNDRYVTT_TEST_LICENSE_KEY` and nothing more; the signature comes from
+accepting the licence agreement in Foundry's own page, once per data root, and
+then persists in `Config/license.json` there. On a fresh data root, start the
+stage with no world (`package-build container test start`), open it in a
+browser and accept the agreement. A run against an unsigned licence fails at
+once saying so, naming the data root, instead of waiting for a world that never
+activates. Under rootless Docker, set
 `FOUNDRYVTT_CONTAINER_USER=0:0`: container root is then the host user, so every
 file under the data root belongs to them, where the image would otherwise run
 Foundry as user 1000. With the local settings in place, seed the world:

package/docs/reference/format-details.md

@@ -3505,7 +3505,7 @@ See [a being's subtype describes the subject](#a-beings-subtype-describes-the-su
 | `affiliations.<Address>.office`    | `string`                                       | A post that body names in its `governance.offices`, where the being holds one                                                                         |
 | `affiliations.<Address>.societies` | `string[]`                                     | The societies the membership is held in, by name; SoHL carries the first as `system.society`                                                          |
 | `socialTies`                       | `Map<Address, Tie>`                            | Defining support and opposition, directed from this being to others                                                                                   |
-| `gender`                           | `male \| female \| other`                      | Gender of the character                                                                                                                               |
+| `gender`                           | `male \| female \| nonbinary \| none \| other` | Gender of the being — see [a being's look](#a-beings-look)                                                                                            |
 | `species`                          | `Address`                                      | Being's species (lore)                                                                                                                                |
 | `born`                             | `date \| unknown`                              | When the being was born; absent, it was never born                                                                                                    |
 | `calendar`                         | `Address`                                      | Calendar note that prints the being's dates                                                                                                           |
@@ -3514,12 +3514,12 @@ See [a being's subtype describes the subject](#a-beings-subtype-describes-the-su
 | `ageYears`                         | `number`                                       | Written by the compiler beside an `age` estimate — the `~` stripped; a note never authors this                                                        |
 | `height`                           | `1.91m \| 6' 3"`                               | Height in metres or feet and inches                                                                                                                   |
 | `weight`                           | `85kg \| 187 lbs`                              | Body weight in kilograms or pounds                                                                                                                    |
-| `frame`                            | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                                                                                   |
-| `appearance.eye_color`             | `string`                                       | Eye color                                                                                                                                             |
-| `appearance.hair_color`            | `string`                                       | Hair color                                                                                                                                            |
-| `appearance.skin_color`            | `string`                                       | Skin color                                                                                                                                            |
-| `appearance.complexion`            | `string`                                       | Complexion                                                                                                                                            |
-| `appearance.extra_features`        | `string[]`                                     | Extra features                                                                                                                                        |
+| `frame`                            | `scant \| light \| medium \| heavy \| massive` | Relative frame — see [a being's look](#a-beings-look)                                                                                                 |
+| `appearance.eye_color`             | a word                                         | Eye colour — see [a being's look](#a-beings-look)                                                                                                     |
+| `appearance.hair_color`            | a word                                         | Hair colour — see [a being's look](#a-beings-look)                                                                                                    |
+| `appearance.skin_color`            | a word                                         | Skin colour — see [a being's look](#a-beings-look)                                                                                                    |
+| `appearance.complexion`            | `word \| word[]`                               | The skin's condition, one word or several — see [a being's look](#a-beings-look)                                                                      |
+| `appearance.extra_features`        | `string[]`                                     | Anything else a stranger would notice, in free text                                                                                                   |
 
 Author `data.height` as a string of decimal metres (`1.91m` or `1.91 m`) or
 whole feet with optional inches (`6'`, `6'3"`, or `6' 3"`). Inches must be
@@ -3543,6 +3543,142 @@ data:
   lore: [lore-marchlaw]
 ```
 
+#### A being's look
+
+**A being's gender, frame and appearance are stated in words from one closed
+vocabulary**, so every package describes a face in the same terms and a
+misspelt or invented word is caught. `data.gender`, `data.frame`,
+`data.appearance.eye_color`, `data.appearance.hair_color` and
+`data.appearance.skin_color` each take one word from their own list.
+`data.appearance.complexion` takes one word or a list of them, since a face
+carries more than one condition at once; a single word means a list of one.
+Any other value — a word from another field's list, a variant spelling such as
+`gray` for `grey`, or an empty string — is an error at the value, naming the
+words the field takes. Leave a field out when the fact is unrecorded.
+
+`data.appearance.extra_features` is not closed. It is a list of free-text
+marks — a scar and where it came from, a missing finger, a limp — for what no
+word in the vocabulary covers.
+
+```yaml
+data:
+  gender: female
+  frame: light
+  appearance:
+    eye_color: dark_brown
+    hair_color: greying_black
+    skin_color: olive
+    complexion: [weathered, freckled]
+    extra_features:
+      - a burn scar across the back of the left hand
+```
+
+The words, and what each means:
+
+<!-- being-look:start -->
+
+**`data.gender`**
+
+| Word        | Label     | Meaning                                                            |
+| ----------- | --------- | ------------------------------------------------------------------ |
+| `female`    | Female    | Female.                                                            |
+| `male`      | Male      | Male.                                                              |
+| `nonbinary` | Nonbinary | Neither male nor female.                                           |
+| `none`      | None      | The being has no gender, as against one that is simply unrecorded. |
+| `other`     | Other     | A gender none of these words fits.                                 |
+
+**`data.frame`**
+
+| Word      | Label   | Meaning                                       |
+| --------- | ------- | --------------------------------------------- |
+| `scant`   | Scant   | Very thin, with little flesh over the bone.   |
+| `light`   | Light   | Slender, narrow through shoulder and hip.     |
+| `medium`  | Medium  | The ordinary build, neither slight nor heavy. |
+| `heavy`   | Heavy   | Broad and solid, in muscle or in flesh.       |
+| `massive` | Massive | Exceptionally large in frame.                 |
+
+**`data.appearance.eye_color`**
+
+| Word         | Label      | Meaning                                                                            |
+| ------------ | ---------- | ---------------------------------------------------------------------------------- |
+| `amber`      | Amber      | Golden or coppery, with no grey or green in it; the honey-toned eye.               |
+| `black`      | Black      | An iris that cannot be told from the pupil in any light, darker than `dark_brown`. |
+| `blue`       | Blue       | Unmixed blue, from pale ice to deep sea.                                           |
+| `brown`      | Brown      | Mid-brown, the iris pattern still legible in ordinary light.                       |
+| `dark_brown` | Dark Brown | Brown so deep the iris barely separates from the pupil.                            |
+| `grey`       | Grey       | Grey or grey-blue, cool and without green.                                         |
+| `green`      | Green      | Green dominant, with no brown ring worth naming.                                   |
+| `hazel`      | Hazel      | Brown and green together, often shifting with the light; the commonest mixed eye.  |
+| `violet`     | Violet     | The pink-violet of an iris carrying no pigment.                                    |
+
+**`data.appearance.hair_color`**
+
+| Word               | Label            | Meaning                                                                   |
+| ------------------ | ---------------- | ------------------------------------------------------------------------- |
+| `auburn`           | Auburn           | Red-brown with the red dominant.                                          |
+| `black`            | Black            | True black, with no brown cast in sunlight.                               |
+| `blonde`           | Blonde           | Light yellow, from near-white to wheat.                                   |
+| `brown`            | Brown            | Mid-brown, neither dark nor reddish.                                      |
+| `chestnut`         | Chestnut         | Mid-brown with a red cast, the brown dominant — between brown and auburn. |
+| `dark_blonde`      | Dark Blonde      | Blonde darkened towards light brown.                                      |
+| `dark_brown`       | Dark Brown       | Brown approaching black, still brown in sunlight.                         |
+| `grey`             | Grey             | Grey throughout, with nothing of the original colour left to read.        |
+| `greying_black`    | Greying Black    | Black still dominant, grey coming in.                                     |
+| `greying_brown`    | Greying Brown    | Brown still dominant, grey coming in.                                     |
+| `red`              | Red              | Ginger or copper, the red unmixed with brown.                             |
+| `silver`           | Silver           | Grey with a bright metallic sheen rather than a dull cast.                |
+| `strawberry_blond` | Strawberry Blond | Pale red-gold: blonde with a red cast, lighter than red.                  |
+| `white`            | White            | Wholly white, whether from age or from carrying no pigment.               |
+
+**`data.appearance.skin_color`**
+
+| Word         | Label      | Meaning                                                                                     |
+| ------------ | ---------- | ------------------------------------------------------------------------------------------- |
+| `pale`       | Pale       | The lightest skin, which burns rather than browns; also skin carrying no pigment.           |
+| `fair`       | Fair       | Light with a pink cast, burning before it browns.                                           |
+| `light`      | Light      | Light and neutral, browning without burning readily.                                        |
+| `medium`     | Medium     | Neither light nor dark, with no strong cast either way.                                     |
+| `olive`      | Olive      | Medium with a green-grey cast.                                                              |
+| `tawny`      | Tawny      | Light brown, warm rather than olive.                                                        |
+| `golden`     | Golden     | Light to medium with a yellow cast.                                                         |
+| `tanned`     | Tanned     | Medium, darkened by sun rather than by birth.                                               |
+| `swarthy`    | Swarthy    | Dark with an olive or sallow cast, between olive and brown.                                 |
+| `brown`      | Brown      | Mid-brown.                                                                                  |
+| `dark`       | Dark       | Darker than brown with no particular cast; the general word where no finer shade is stated. |
+| `dark_brown` | Dark Brown | Deep brown.                                                                                 |
+| `ebony`      | Ebony      | The darkest skin, near-black.                                                               |
+
+**`data.appearance.complexion`**
+
+| Word          | Label       | Meaning                                                                                                                                             |
+| ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ashen`       | Ashen       | Grey and drained; the skin of serious illness, shock or terror.                                                                                     |
+| `blotchy`     | Blotchy     | Uneven in colour, patched red or pale.                                                                                                              |
+| `chapped`     | Chapped     | Reddened and cracked by cold and wind.                                                                                                              |
+| `clear`       | Clear       | Free of blemish, mark or broken vessel.                                                                                                             |
+| `freckled`    | Freckled    | Freckled, in patches or across the whole face.                                                                                                      |
+| `jaundiced`   | Jaundiced   | Yellowed, the colour a failing liver gives.                                                                                                         |
+| `leathery`    | Leathery    | Thickened and toughened by years of exposure.                                                                                                       |
+| `oily`        | Oily        | Carrying a greasy sheen.                                                                                                                            |
+| `pasty`       | Pasty       | Pale and doughy; the skin of indoor work and poor feeding.                                                                                          |
+| `pimpled`     | Pimpled     | Presently broken out, with pimples at brow, cheek or jaw.                                                                                           |
+| `pockmarked`  | Pockmarked  | Pitted by pox, or by deep pimples long since healed.                                                                                                |
+| `rough`       | Rough       | Coarse in texture, without the wear of outdoor work.                                                                                                |
+| `ruddy`       | Ruddy       | High colour at cheek and nose, from weather, drink or constitution.                                                                                 |
+| `sallow`      | Sallow      | Yellowish and bloodless.                                                                                                                            |
+| `scabrous`    | Scabrous    | Rough and scaling, the skin of a lasting complaint such as eczema.                                                                                  |
+| `scarred`     | Scarred     | Marked by healed wounds. `extra_features` says where and from what.                                                                                 |
+| `smooth`      | Smooth      | Even in texture, whatever marks it carries.                                                                                                         |
+| `sun_kissed`  | Sun-Kissed  | Browned by sun on skin not naturally that dark.                                                                                                     |
+| `sunburnt`    | Sunburnt    | Presently burned, red and peeling.                                                                                                                  |
+| `translucent` | Translucent | So pale the vessels show through.                                                                                                                   |
+| `vitiligo`    | Vitiligo    | Patched with white where the skin has lost its colour, most often at face, hands and mouth. The tone it has lost is still what `skin_color` states. |
+| `wan`         | Wan         | Pale and drained; the skin of exhaustion or convalescence.                                                                                          |
+| `weathered`   | Weathered   | Worn and lined by sun and wind; the skin of outdoor work.                                                                                           |
+| `wrinkled`    | Wrinkled    | Deeply lined by age.                                                                                                                                |
+
+<!-- being-look:end -->
+
 #### The bodies a being belongs to, and its standing in each
 
 **Membership**: `{rank: number, office: string, societies: string[]}` — `rank`
@@ -5294,6 +5430,123 @@ The place's `lore` links cover its peoples, calendar, law and history. Political
 languages belong to a polity's `sohl.system.commonSkills`, while the note's
 `description` provides its page summary.
 
+#### A region's settlements table
+
+A region lists its settlements in a table on its own note: one row for each
+settlement, stating what its market is, how many people it holds and who holds
+it. **A row is the whole record of a settlement that has no note.** Where a
+note exists the row links it, and the two must agree. A package that writes no
+such table is not affected by anything in this section.
+
+The table is a markdown table under a level-two `## Settlements` heading on the
+region's `place` note. Its header is exactly these columns, in this order. `For`
+may be left out; the header carries no other column:
+
+| Name | Market | People | Held by | For |
+| ---- | ------ | ------ | ------- | --- |
+
+- **Name** — the settlement. Where it has a note, a link to it with the pipe
+  escaped for the table, `[[place-ashford\|Ashford]]`; otherwise plain text.
+- **Market** — the market class as its number and its name, lower case:
+  `1 hamlet`, `2 village`, `3 town`, `4 market town`, `5 city`, `6 great city`.
+  The scale is the one [`data.market`](#what-a-settlements-market-supports)
+  states.
+- **People** — the population, a whole number, grouped with commas or not:
+  `60`, `420`, `3,400`.
+- **Held by** — who holds it, written in the region's holding model. Link the
+  holder where it has a note.
+- **For** — a short phrase saying why the place is there: the ford, the mine,
+  the shrine.
+
+At least one sentence of prose follows the table, before the next heading,
+saying what the table leaves out. A section filled by an `sql` fence is
+generated from the notes and is not read as a settlements table.
+
+**The region names its holding model as a tag.** A note carrying a settlements
+table carries at least one of these tags; a region whose countryside is held
+two ways carries both. Tags stay open, so a misspelled model is not reported as
+such: the table's note is reported for naming no model.
+
+| `holdingModel` value | the Held by cell names |
+| -------------------- | ---------------------- |
+| `held`               | a person or a house    |
+| `endowed`            | an institution         |
+| `registered`         | an office              |
+| `kin`                | a kindred              |
+| `polis`              | the city               |
+
+A linked holder is an `affiliation` or a `being`, and a `being` is a person: it
+may hold land only in a region tagged `held`.
+
+**A settlement belongs to one table** — that of the nearest place above it, by
+`parents`, that carries a settlements table. Every `settlement` note that table
+covers has a row there and nowhere else.
+
+A worked example. `Vale.md`:
+
+```markdown
+---
+shortcode: vale
+name: { full: The Vale }
+type: place
+subType: region
+tags: [region, held]
+data:
+  population: 100000
+  government: crown
+---
+
+## Settlements
+
+| Name                       | Market        | People | Held by                                  | For                        |
+| -------------------------- | ------------- | -----: | ---------------------------------------- | -------------------------- |
+| [[place-ashford\|Ashford]] | 4 market town |  3,400 | [[affiliation-crown\|the Crown]]         | the ford on the drove road |
+| Weyshott                   | 2 village     |    420 | [[being-aldwyn\|Sir Aldwyn of Brynwold]] | the manor's mill           |
+| Cold Hatch                 | 1 hamlet      |     60 | Sir Aldwyn of Brynwold                   | the sheepwalk              |
+
+Some four hundred further villages lie in the vale, none of them named here.
+```
+
+`Ashford.md` states `parents: [vale]`, `population: 3400` and `market: 4`, so its
+row agrees with it. Weyshott and Cold Hatch have no notes; their rows are their
+whole record. Change Ashford's row to `3,000` and `package-build lint` reports:
+
+```text
+assets/content/Vale.md:16:49: error: figure disagrees: Ashford is carried at 3,000 here and 3,400 on its own note
+```
+
+`package-build lint` reports each of these as an error, each named by the
+phrase its message begins with:
+
+- **`settlements columns`** — the header is not the declared columns in
+  order. The table's rows are not read until it is.
+- **`no holding model`** — the note carries a settlements table and none of
+  the holding-model tags. Reported at its `tags`.
+- **`market class`** — a Market cell is not a class written as its number and
+  its name.
+- **`people figure`** — a People cell is not a positive whole number.
+- **`no holder`** — a Held by cell is empty.
+- **`not a holder`** — a Held by link names a note that is neither an
+  affiliation nor a being.
+- **`holder out of model`** — a Held by link names a being in a region not
+  tagged `held`.
+- **`not a settlement`** — a Name link names a note that is not a place.
+- **`figure disagrees`** — a linked row's People differs from its note's
+  `data.population`, or the note states none.
+- **`market disagrees`** — a linked row's Market differs from its note's
+  `data.market`, or the note states none.
+- **`unlinked settlement`** — an unlinked Name is the name or an alias of a
+  settlement note the table covers. The finding gives the link to write.
+- **`missing row`** — a settlement note the table covers has no row. Reported
+  at the table's header.
+- **`duplicate settlement`** — a settlement has a second row in one table, or
+  a row in a table other than the one covering it.
+- **`no tail`** — no sentence follows the table before the next heading.
+  Reported at the table's last row.
+
+A cell's finding is located at the cell. A link in a cell that resolves to no
+note is reported by the link check, once, and not again here.
+
 ### type: scenario
 
 Content prepared to be played — a situation with its cast, places, and possible outcomes.