@heroiclands/package-build 23.2.2 → 23.3.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @heroiclands/package-build
 
+## 23.3.1
+
+### Patch Changes
+
+**New npcs**
+
+- `package-build npc new` writes a complete npc note from a culture and a gender, filling every other field, an Appearance paragraph and a name; the same spec always gives the same person, and `--seed` draws another.
+- Give any field yourself, inline or from a JSON or YAML file, including the name and the Appearance and Dossier text, and it is written exactly as you gave it.
+- A culture describes its people in `data.appearanceProfile`, with weighted eye, hair and skin colours, complexions, frames and height ranges, and names the tongue they speak in `data.language`.
+- A language skill note lists its speakers' names in `data.names`: one or several patterns such as `{given} {clan}` or `{given} {given.male}sen`, by gender where forms differ, and the lists they draw on; a name you give must fit one.
+- `package-build lint` checks a profile's words, weights and ranges, and a language's pattern and lists.
+
+## 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

package/bin/content-commands.mjs

@@ -31,6 +31,7 @@
  *   npx package-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
  *   npx package-build reachability <dir> [file] [--index <shortcode>]
  *   npx package-build addresses diff --from <zip|dir> [--strict]
+ *   npx package-build npc new (--spec <json> | --specfile <path>) [--seed <text>] [--out <path>]
  *
  * In a consuming repository, wrapped as npm scripts — SoHL spells them:
  *   npm run build:compiledb                // → … package compile (all packs)
@@ -112,7 +113,12 @@ import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-
 import { prepareTreeSqlTables } from "../engine/sql-tables.mjs";
 // The one place a link finding is worded, shared with both builds.
 import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
-import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
+import {
+    emitDiagnostic,
+    positionOfFrontmatterPath,
+    positionOfLiteral,
+    positionOfYamlPath,
+} from "../engine/diagnostics.mjs";
 import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
@@ -127,6 +133,14 @@ import { CHART_HORIZON_DAYS } from "../engine/map-layout.mjs";
 import { GRAPHVIZ_ENGINES } from "../engine/map-graphviz.mjs";
 import { loadMapWorld } from "../engine/map-places.mjs";
 import { encodeAddresses } from "../engine/address-values.mjs";
+import YAML from "yaml";
+import { worldInvariants } from "../engine/calendar-notes.mjs";
+import { reckoningContext } from "../engine/reckoning-markers.mjs";
+import { BEING_LOOK_VOCABULARY } from "../engine/note-vocabulary.mjs";
+import { profileFindings } from "../engine/appearance-profile.mjs";
+import { namesFindings } from "../engine/language-names.mjs";
+import { parseAddress, renderAddress } from "../engine/address.mjs";
+import { cultureKey, generateNpc, npcDefaults, npcSpecProblems } from "../engine/npc-generate.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -241,7 +255,8 @@ export function registerContentCommands(cli) {
         )
         .command(withIndexPreflight(mapCommand()))
         .command(withIndexPreflight(reachabilityCommand()))
-        .command(addressesCommand());
+        .command(addressesCommand())
+        .command(withIndexPreflight(npcCommand()));
 }
 
 /** Optional sentence findings and note-level readability reports. */
@@ -490,6 +505,12 @@ function docsCommand() {
                 type: "string",
                 default: "docs",
             });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
             yargs.option("out", {
                 describe: "Write to this file instead of the configured location.",
                 type: "string",
@@ -1555,6 +1576,12 @@ function contentIndexCommand() {
                 describe: "Content tree to read. Defaults to the configured contentBase.",
                 type: "string",
             });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
             yargs.option("out", {
                 describe:
                     "Directory to write into. Defaults to the configured " +
@@ -2515,3 +2542,267 @@ function packageCommand() {
         },
     };
 }
+
+/**
+ * Read an `npc new` spec from `--spec` or `--specfile`.
+ *
+ * @param {{spec?: string, specfile?: string}} argv
+ * @returns {{spec: unknown, file?: string, text?: string}} The spec as parsed,
+ *   and the file and text it was read from where it came from a file.
+ */
+function readNpcSpec(argv) {
+    if (argv.spec !== undefined) {
+        try {
+            return { spec: JSON.parse(argv.spec) };
+        } catch (err) {
+            throw new Error(`\`--spec\` is not JSON: ${err.message}`);
+        }
+    }
+    const file = argv.specfile;
+    const ext = path.extname(file).toLowerCase();
+    if (![".json", ".yaml", ".yml"].includes(ext))
+        throw new Error(`\`--specfile\` ${file} must be a .json, .yaml or .yml file`);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    } catch (err) {
+        throw new Error(`\`--specfile\` ${file} cannot be read: ${err.message}`);
+    }
+    try {
+        return { spec: ext === ".json" ? JSON.parse(text) : YAML.parse(text), file, text };
+    } catch (err) {
+        throw Object.assign(new Error(`${file}: error: ${err.message.split("\n")[0]}`), {
+            located: true,
+        });
+    }
+}
+
+/**
+ * An error located at a note, or at one key of its frontmatter where the note
+ * states it.
+ *
+ * @param {{file?: string, raw?: string}} note - Where the note is.
+ * @param {Array<string|number>} keyPath - The frontmatter key at fault, or the
+ *   map a missing key belongs in.
+ * @param {string} message - What is wrong.
+ * @returns {Error} The error, for `reportFailure` to print as a diagnostic.
+ */
+function noteError(note, keyPath, message) {
+    if (!note.file) return new Error(message);
+    return Object.assign(new Error(message), {
+        file: note.file,
+        keyPath,
+        position: positionOfFrontmatterPath(note.raw ?? "", keyPath, { key: true }),
+    });
+}
+
+/**
+ * `npc new`: resolve the spec's culture through the content tree, then the
+ * culture's appearance profile, its language and the language's name lists,
+ * and write the note. A missing link at any step is an error naming the note
+ * to fix.
+ *
+ * @param {object} config - The resolved pack configuration.
+ * @param {{spec?: string, specfile?: string, seed?: string, out?: string}} argv
+ */
+function newNpc(config, argv) {
+    const { spec, file: specFile, text: specText } = readNpcSpec(argv);
+    const problems = npcSpecProblems(spec);
+    if (problems.length) throw new Error(`npc new: ${problems.join("; ")}`);
+    if (argv.out && fs.existsSync(argv.out))
+        throw new Error(`${argv.out} already exists, and \`npc new\` never overwrites a note`);
+
+    const root = config.paths.content;
+    const records = indexRecordsFor({
+        contentBase: root,
+        config,
+        skipDirectories: config.skipDirectories,
+        problems: [],
+    });
+    const index = buildLinkIndex(root, {
+        config,
+        records,
+        skipDirectories: config.skipDirectories,
+    });
+    const located = (hit) => ({
+        file: hit.file ? path.relative(process.cwd(), hit.file) : undefined,
+        raw: hit.raw,
+    });
+
+    const written = spec.data.culture;
+    const key = cultureKey(written, index);
+    const hit = key ? index.addressHit(key) : undefined;
+    if (!hit)
+        throw new Error(
+            `\`data.culture\` ${JSON.stringify(written)} names no note in this package or ` +
+                "its dependencies",
+        );
+    const culture = hit.fm ?? hit;
+    if (String(culture.type ?? hit.type) !== "lore" || culture.subType !== "culture")
+        throw new Error(
+            `\`data.culture\` ${JSON.stringify(written)} is not a culture: it names a ` +
+                `${culture.type ?? hit.type ?? "note"} of subType ${culture.subType ?? "none"}`,
+        );
+    const cultureNote = located(hit);
+    const profile = culture.data?.appearanceProfile;
+    if (profile === undefined || profile === null)
+        throw noteError(
+            cultureNote,
+            ["data"],
+            `${key} states no \`data.appearanceProfile\`, so \`npc new\` cannot draw its ` +
+                "people's look",
+        );
+    const profileErrors = profileFindings(
+        { file: cultureNote.file, raw: hit.raw, fm: culture },
+        BEING_LOOK_VOCABULARY,
+    );
+    if (profileErrors.length) {
+        for (const finding of profileErrors) emitDiagnostic(finding);
+        throw new Error(`${key}'s appearance profile has ${profileErrors.length} problem(s)`);
+    }
+
+    const tongue = culture.data?.language;
+    if (tongue === undefined || tongue === null)
+        throw noteError(
+            cultureNote,
+            ["data"],
+            `${key} states no \`data.language\`, so \`npc new\` has no name lists to draw ` +
+                "from; name the language skill note its people speak",
+        );
+    const tuple = parseAddress(tongue, {
+        package: index.contentPackage,
+        system: "note",
+        type: "skill",
+        types: index.types,
+        packages: index.packages,
+    });
+    const languageKey = tuple.reason ? undefined : renderAddress(tuple);
+    const languageHit = languageKey ? index.addressHit(languageKey) : undefined;
+    if (!languageHit)
+        throw noteError(
+            cultureNote,
+            ["data", "language"],
+            `${key}'s \`data.language\` names no note in this package or its dependencies`,
+        );
+    const language = languageHit.fm ?? languageHit;
+    if (String(language.type ?? languageHit.type) !== "skill" || language.subType !== "language")
+        throw noteError(
+            cultureNote,
+            ["data", "language"],
+            `${key}'s \`data.language\` ${languageKey} is not a language: it names a ` +
+                `${language.type ?? languageHit.type ?? "note"} of subType ` +
+                `${language.subType ?? "none"}`,
+        );
+    const languageNote = located(languageHit);
+    const names = language.data?.names;
+    if (names === undefined || names === null)
+        throw noteError(
+            languageNote,
+            ["data"],
+            `${languageKey} states no \`data.names\`, so \`npc new\` has no name lists to ` +
+                `draw ${key}'s names from`,
+        );
+    const namesErrors = namesFindings(
+        { file: languageNote.file, raw: languageHit.raw, fm: language },
+        BEING_LOOK_VOCABULARY,
+    );
+    if (namesErrors.length) {
+        for (const finding of namesErrors) emitDiagnostic(finding);
+        throw new Error(`${languageKey}'s name lists have ${namesErrors.length} problem(s)`);
+    }
+
+    const { taken, ...defaults } = npcDefaults(index, key);
+    if (typeof spec.shortcode === "string" && taken.has(spec.shortcode))
+        throw new Error(`\`shortcode: ${spec.shortcode}\` already names a being in this package`);
+    let text;
+    try {
+        ({ text } = generateNpc(spec, {
+            profile,
+            names,
+            language: languageKey,
+            seed: argv.seed,
+            present: worldInvariants(index).present,
+            dateContext: reckoningContext(index),
+            defaults,
+            taken,
+        }));
+    } catch (err) {
+        // A name that does not fit is the spec's fault, so a spec file
+        // locates it at the name it states.
+        if (specFile && Array.isArray(err?.keyPath))
+            Object.assign(err, {
+                file: specFile,
+                position: positionOfYamlPath(specText ?? "", err.keyPath),
+            });
+        throw err;
+    }
+    if (!argv.out) {
+        process.stdout.write(text);
+        return;
+    }
+    fs.mkdirSync(path.dirname(argv.out), { recursive: true });
+    try {
+        fs.writeFileSync(argv.out, text, { flag: "wx" });
+    } catch (err) {
+        if (err?.code === "EEXIST")
+            throw new Error(`${argv.out} already exists, and \`npc new\` never overwrites a note`);
+        throw err;
+    }
+}
+
+/**
+ * `package-build npc new` — a complete NPC being note from a spec, its
+ * appearance drawn from its culture's profile.
+ *
+ * @returns {object} The yargs command module.
+ */
+function npcCommand() {
+    return {
+        command: "npc <action>",
+        describe:
+            "Write a new NPC being note from a spec, its culture's appearance profile and " +
+            "its language's name lists",
+        builder: (yargs) => {
+            yargs.positional("action", {
+                describe: "The action to perform.",
+                type: "string",
+                choices: ["new"],
+            });
+            yargs.option("spec", {
+                describe:
+                    "The spec as a JSON string: frontmatter fields, with `data.culture` and " +
+                    "`data.gender` required.",
+                type: "string",
+            });
+            yargs.option("specfile", {
+                describe: "The spec as a .json, .yaml or .yml file.",
+                type: "string",
+            });
+            yargs.option("seed", {
+                describe:
+                    "Text that seeds generation beside the spec, to draw a different person " +
+                    "from the same spec.",
+                type: "string",
+            });
+            yargs.option("out", {
+                describe:
+                    "Write the note to this new file instead of standard output. An " +
+                    "existing file is never overwritten.",
+                type: "string",
+            });
+            yargs.check((parsed) => {
+                if ((parsed.spec === undefined) === (parsed.specfile === undefined))
+                    throw new Error("`npc new` takes exactly one of `--spec` and `--specfile`");
+                return true;
+            });
+        },
+        handler: async (argv) => {
+            try {
+                newNpc(loadPackConfig(), argv);
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}

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/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.