@heroiclands/package-build 22.19.0 → 22.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @heroiclands/package-build
 
+## 22.20.0
+
+### Minor Changes
+
+- Content checks require characters and NPCs to name an archetype and reject unrecognized archetypes; creatures may omit them.
+- Names with unsupported fields now fail validation, and aliases appear beneath the name in infoboxes across published formats.
+
 ## 22.19.0
 
 ### Minor Changes

package/ci/content-format-reference.mjs

@@ -7,7 +7,11 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { formatGenerated } from "../engine/format-generated.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
-import { NOTE_VOCABULARY, SHARED_DATA_FIELDS } from "../engine/note-vocabulary.mjs";
+import {
+    BEING_ARCHETYPES,
+    NOTE_VOCABULARY,
+    SHARED_DATA_FIELDS,
+} from "../engine/note-vocabulary.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const output = path.join(root, "docs/reference/note-types.md");
@@ -104,3 +108,29 @@ if (process.argv.includes("--check")) {
 } else {
     process.stdout.write(result);
 }
+
+const detailsPath = path.join(root, "docs/reference/format-details.md");
+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");
+}
+const archetypes = Object.entries(BEING_ARCHETYPES)
+    .map(([name, meaning]) => `- ${name}: ${meaning}`)
+    .join("\n");
+const updatedDetails = await formatGenerated(
+    details.replace(
+        /<!-- archetypes:start -->[\s\S]*?<!-- archetypes:end -->/,
+        `<!-- archetypes:start -->\n${archetypes}\n<!-- archetypes: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",
+        );
+        process.exitCode = 1;
+    }
+} else {
+    fs.writeFileSync(detailsPath, updatedDetails);
+}

package/docs/api.md

@@ -353,6 +353,7 @@ An addressed content note accepts exactly these top-level keys, in this order: `
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `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         |
 | `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`               | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere |
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |

package/docs/authoring/frontmatter.md

@@ -21,7 +21,9 @@ data: {}
 ---
 ```
 
-`name.full` is the displayed name; `name.aliases` helps search. `description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
+`name` is a map with a required, nonempty `full` display name. Every note may also use `aliases` for an ordered list of other names. The note infobox lists aliases directly beneath the full name. For a `being` with `subType: character`, `given` and `clan` are optional name components. The first alias of a character or NPC is its nickname. Omit optional keys when they do not apply; `given`, `clan`, and alias entries must be nonempty strings when present. No other keys are accepted under `name`.
+
+`description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
 
 Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Links from untagged notes to GM notes are errors; GM notes may link to one another.
 

package/docs/reference/format-details.md

@@ -117,7 +117,8 @@ Item link.
 order** — the very table each `### type:` section below states. There is no
 second list, so a key added to a type appears in the book, on the website and
 in a compendium journal with no further edit. A `Name` row stands first on
-every note, because every note has one.
+every note, because every note has one. An `Aliases` row follows it when the
+note names any aliases, preserving their authored order.
 
 A few keys carry no row, and the reason in each case is one of exactly two —
 the key is **machinery**, steering a build or an interface rather than
@@ -333,6 +334,13 @@ sohl: {}
 Any other top-level key is an error. To keep an author-only note beside the
 content, comment out its YAML lines with `#`. Comments remain valid YAML text
 and do not become data in the JSONL index, generated pages, or Foundry documents.
+
+`name` is a map with a required nonempty `full` string when present. It may
+also contain `aliases`, an ordered list of nonempty strings. A being with
+`subType: character` may additionally contain nonempty `given` and `clan`
+strings. Other keys under `name` are errors. For a character or NPC, the first
+alias is its nickname. A being's homes belong in `data.homes`.
+
 There is no custom site metadata. `description` supplies the page's short
 description; `tags` carries publication and classification tags.
 
@@ -2432,6 +2440,8 @@ For JournalEntries, the following rules apply:
 
 **Archetypes** describe characters in broad terms and help match them to an adventure. The list is:
 
+<!-- archetypes:start -->
+
 - warrior: Can hold a line and win a fight.
 - skirmisher: Fights light — ambush, missile, mobility.
 - infiltrator: Gets in unseen — locks, stealth, disguise.
@@ -2448,6 +2458,10 @@ For JournalEntries, the following rules apply:
 - entertainer: Performs for an audience through acting, music, comedy, or similar arts.
 - guildsperson: Has professional training, standing, or connections that open doors.
 
+<!-- archetypes:end -->
+
+`character` and `npc` beings require at least one archetype. `creature` beings may omit archetypes or write an empty array. Values use the exact lowercase spellings above.
+
 Note that archetypes are descriptive, not proscriptive, and a character may be described by multiple archetypes at once.
 `commoner` stands alone: a being with another fitting archetype does not also carry `commoner`.
 Guild membership alone does not require `guildsperson`; the being's training, standing, or connections must matter to the role.
@@ -2462,34 +2476,34 @@ An Item can mark its readable description with `# ... {#description}`. That head
 
 Generates a living (or undead, or spirit) being.
 
-| `data` property             | Values                                         | Description                                                                                      |
-| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `tokenIcon`                 | `Address`                                      | What a token on the canvas wears — an `icon` address; defaults to `icon`                         |
-| `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
-| `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
-| `occupation`                | `string`                                       | Name of the character's occupation                                                               |
-| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                       |
-| `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                    |
-| `lore`                      | `Address[]`                                    | Other lore concerning this being, such as social standing or law                                 |
-| `culture`                   | `Address`                                      | Primary culture, naming a lore note with `subType: culture`                                      |
-| `homes`                     | `Address[]`                                    | Place the being calls home                                                                       |
-| `affiliations`              | `Address[]`                                    | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
-| `socialTies`                | `Map<Address, Tie>`                            | Defining support and opposition, directed from this being to others                              |
-| `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
-| `species`                   | `Address`                                      | Being's species (lore)                                                                           |
-| `born`                      | `date \| unknown`                              | When the being was born; absent, it was never born                                               |
-| `calendar`                  | `Address`                                      | Calendar note used to print the being's dates                                                    |
-| `died`                      | `date \| unknown`                              | When the being died; absent, it is alive                                                         |
-| `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                    |
-| `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                                                                                   |
+| `data` property             | Values                                         | Description                                                                                                                                           |
+| --------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tokenIcon`                 | `Address`                                      | What a token on the canvas wears — an `icon` address; defaults to `icon`                                                                              |
+| `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                                                                            |
+| `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — character and npc require at least one; creature may omit it or write `[]`; `null` is an error. |
+| `occupation`                | `string`                                       | Name of the character's occupation                                                                                                                    |
+| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                                                                            |
+| `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                                                                         |
+| `lore`                      | `Address[]`                                    | Other lore concerning this being, such as social standing or law                                                                                      |
+| `culture`                   | `Address`                                      | Primary culture, naming a lore note with `subType: culture`                                                                                           |
+| `homes`                     | `Address[]`                                    | Place the being calls home                                                                                                                            |
+| `affiliations`              | `Address[]`                                    | Affilliations (e.g., arcane/divine traditions, polities, etc)                                                                                         |
+| `socialTies`                | `Map<Address, Tie>`                            | Defining support and opposition, directed from this being to others                                                                                   |
+| `gender`                    | `male \| female \| other`                      | Gender of the character                                                                                                                               |
+| `species`                   | `Address`                                      | Being's species (lore)                                                                                                                                |
+| `born`                      | `date \| unknown`                              | When the being was born; absent, it was never born                                                                                                    |
+| `calendar`                  | `Address`                                      | Calendar note used to print the being's dates                                                                                                         |
+| `died`                      | `date \| unknown`                              | When the being died; absent, it is alive                                                                                                              |
+| `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                                                                         |
+| `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                                                                                                                                        |
 
 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

package/engine/base-compiler.mjs

@@ -1133,8 +1133,8 @@ export class BasePackCompiler {
             // - `aliases:`: it fed the alias index, which the bare
             //   `[[Alias]]` form was looked up in; the form is retired, so the
             //   list has no reader left. The nested `name.aliases` is a
-            //   different field and is **not** refused — it is reserved, and
-            //   deliberately neither read nor validated.
+            //   different field: the infobox displays it, and the note name
+            //   check validates it.
             //
             // Both are reported and counted — never skipped, which is how a
             // tree naming a package nothing answers to used to compile zero

package/engine/frontmatter-lint.mjs

@@ -55,7 +55,12 @@
  */
 
 import { isAddressTuple } from "./address.mjs";
-import { authoredNoteKeys, NOTE_TOP_LEVEL_KEY_SET } from "./note-frontmatter.mjs";
+import {
+    authoredNoteKeys,
+    CHARACTER_NAME_KEYS,
+    NOTE_NAME_KEYS,
+    NOTE_TOP_LEVEL_KEY_SET,
+} from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { addressPositions } from "./note-addresses.mjs";
 import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
@@ -78,6 +83,7 @@ import { isAddressSegment } from "./address-charset.mjs";
 // reads is exactly the disagreement to avoid.
 import { DEFAULT_PARENT } from "./folder-notes.mjs";
 import {
+    BEING_ARCHETYPES,
     dataFields,
     declaredTags,
     subTypeCharsetMessage,
@@ -1173,18 +1179,101 @@ export function lintNote(
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
-    if (
-        type === "being" &&
-        Array.isArray(fm.data?.archetypes) &&
-        fm.data.archetypes.includes("commoner") &&
-        fm.data.archetypes.length > 1
-    ) {
-        findings.push({
-            file: note.file,
-            ...at("archetypes", "commoner"),
-            severity: "error",
-            message: "`data.archetypes` may contain `commoner` only by itself",
-        });
+    if (type === "being") {
+        const archetypes = fm.data?.archetypes;
+        if (
+            ["character", "npc"].includes(fm.subType) &&
+            (archetypes == null || (Array.isArray(archetypes) && archetypes.length === 0))
+        ) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(
+                    raw(),
+                    archetypes == null ? ["subType"] : ["data", "archetypes"],
+                ),
+                severity: "error",
+                message: "A character or npc requires at least one `data.archetypes` value",
+            });
+        }
+        if (Array.isArray(archetypes)) {
+            archetypes.forEach((value, i) => {
+                if (!Object.hasOwn(BEING_ARCHETYPES, value)) {
+                    findings.push({
+                        file: note.file,
+                        ...positionOfFrontmatterPath(raw(), ["data", "archetypes", i]),
+                        severity: "error",
+                        message: `Unknown archetype \`${String(value)}\`; use a case-sensitive archetype from the reference`,
+                    });
+                }
+            });
+            const commoner = archetypes.indexOf("commoner");
+            if (commoner !== -1 && archetypes.length > 1) {
+                findings.push({
+                    file: note.file,
+                    ...positionOfFrontmatterPath(raw(), ["data", "archetypes", commoner]),
+                    severity: "error",
+                    message: "`data.archetypes` may contain `commoner` only by itself",
+                });
+            }
+        }
+    }
+    if (Object.hasOwn(fm, "name")) {
+        const name = fm.name;
+        const nameAt = (path) => positionOfFrontmatterPath(raw(), ["name", ...path], { key: true });
+        if (!name || typeof name !== "object" || Array.isArray(name)) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(raw(), ["name"], { key: true }),
+                severity: "error",
+                message: "`name` must be a map with a nonempty `full` string",
+            });
+        } else {
+            const allowed = new Set(NOTE_NAME_KEYS);
+            if (type === "being" && fm.subType === "character") {
+                for (const key of CHARACTER_NAME_KEYS) allowed.add(key);
+            }
+            for (const key of Object.keys(name)) {
+                if (!allowed.has(key)) {
+                    findings.push({
+                        file: note.file,
+                        ...nameAt([key]),
+                        severity: "error",
+                        message: `\`name.${key}\` is not valid for this note`,
+                    });
+                }
+            }
+            if (typeof name.full !== "string" || !name.full.trim()) {
+                findings.push({
+                    file: note.file,
+                    ...(Object.hasOwn(name, "full") ? nameAt(["full"]) : nameAt([])),
+                    severity: "error",
+                    message: "`name.full` must be a nonempty string",
+                });
+            }
+            if (Object.hasOwn(name, "aliases")) {
+                if (
+                    !Array.isArray(name.aliases) ||
+                    name.aliases.some((alias) => typeof alias !== "string" || !alias.trim())
+                ) {
+                    findings.push({
+                        file: note.file,
+                        ...nameAt(["aliases"]),
+                        severity: "error",
+                        message: "`name.aliases` must be a list of nonempty strings",
+                    });
+                }
+            }
+            for (const key of CHARACTER_NAME_KEYS) {
+                if (!Object.hasOwn(name, key) || !allowed.has(key)) continue;
+                if (typeof name[key] === "string" && name[key].trim()) continue;
+                findings.push({
+                    file: note.file,
+                    ...nameAt([key]),
+                    severity: "error",
+                    message: `\`name.${key}\` must be a nonempty string`,
+                });
+            }
+        }
     }
     /**
      * The in-block keys this note's own type claims for something other than

package/engine/infobox.mjs

@@ -706,6 +706,9 @@ function noteBox(
     const shown = new Set();
     const name = fm?.name?.full ?? fm?.title;
     if (hasValue(name)) rows.push({ label: "Name", kind: "text", value: String(name) });
+    if (Array.isArray(fm?.name?.aliases) && fm.name.aliases.length) {
+        rows.push({ label: "Aliases", kind: "list", value: fm.name.aliases });
+    }
     if (fm?.type === "being" && Object.hasOwn(BEING_SUBTYPE_LABELS, fm.subType)) {
         rows.push({ label: "Type", kind: "text", value: BEING_SUBTYPE_LABELS[fm.subType] });
     }

package/engine/note-frontmatter.mjs

@@ -24,6 +24,12 @@ export const NOTE_TOP_LEVEL_KEYS = Object.freeze([
 /** Membership test for the top-level vocabulary. */
 export const NOTE_TOP_LEVEL_KEY_SET = new Set(NOTE_TOP_LEVEL_KEYS);
 
+/** The name properties every note accepts, in display order. */
+export const NOTE_NAME_KEYS = Object.freeze(["full", "aliases"]);
+
+/** Additional name components accepted by an individual character. */
+export const CHARACTER_NAME_KEYS = Object.freeze(["given", "clan"]);
+
 /** Return authored keys from an opening YAML frontmatter map. */
 export function authoredNoteKeys(markdown) {
     const source = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];

package/engine/note-vocabulary.mjs

@@ -666,6 +666,25 @@ export function isGmNote(fm) {
     return hasTag(fm, GM_TAG);
 }
 
+/** The case-sensitive archetypes and their author-facing meanings. */
+export const BEING_ARCHETYPES = Object.freeze({
+    warrior: "Can hold a line and win a fight.",
+    skirmisher: "Fights light — ambush, missile, mobility.",
+    infiltrator: "Gets in unseen — locks, stealth, disguise.",
+    mage: "Commands arcane practice.",
+    cleric: "Commands religious practice and standing.",
+    healer: "Treats wounds and illness.",
+    scholar: "Reads, researches, and knows things.",
+    courtier: "Navigates rank, negotiation, and intrigue.",
+    woodsman: "Travels and survives wild country.",
+    mariner: "Handles boats and blue water.",
+    artisan: "Builds, repairs, and appraises craft work.",
+    trader: "Moves goods, values them, and knows markets.",
+    commoner: "Fits no more specific archetype; handles ordinary work and daily life.",
+    entertainer: "Performs for an audience through acting, music, comedy, or similar arts.",
+    guildsperson: "Has professional training, standing, or connections that open doors.",
+});
+
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.

package/engine/retired-fields.mjs

@@ -48,13 +48,8 @@
  * nothing checks unrecognized top-level keys, so left in place it would be
  * silently ignored rather than reported.
  *
- * **`name.aliases` fed the same index and is nonetheless kept.** It is
- * **reserved** — held for a use that does not exist yet — so it is the one
- * field here that is neither retired nor read. Nothing consults it: no index,
- * no resolver, no lint rule, no emitter. A note carrying one compiles,
- * resolves and emits exactly as if it were absent, and `tests/name-aliases-
- * reserved.test.ts` pins that equivalence so a future reader cannot be added
- * by accident.
+ * **`name.aliases` lists alternate names.** The note infobox shows them in
+ * authored order. They do not create addresses or change link resolution.
  *
  * **What `traits:` did.** It held a being's own description — gender,
  * species, age, birth date, height, weight, frame and `appearance.*` — at the
@@ -199,10 +194,8 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * unambiguous folded in every note's `name.full` and so dictated what a note
  * could be named. The form is retired, so the list has no reader.
  *
- * **`name.aliases` is a different field and is not retired.** It fed the same
- * index, but unlike the top-level list it is being kept — reserved, unread,
- * and deliberately unmentioned by this message, which would otherwise tell an
- * author to delete a field they are allowed to write. See
+ * **`name.aliases` is a different field.** It lists alternate names in the
+ * infobox and is deliberately unmentioned by this message. See
  * {@link assertNoAliasesField}.
  *
  * @param {string} [file] - The note's path, named in the message. Omit it where
@@ -227,13 +220,9 @@ export function aliasesRetiredMessage(file) {
  * it reads as "this note claims no other names", a statement about a namespace
  * that no longer exists.
  *
- * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
- * the retired alias index, and both lost their reader with it, but only the
- * top-level one is retired: `name.aliases` is **reserved**, held for a use that
- * does not exist yet. So it is neither refused nor read — no index consults it,
- * no rule validates its contents, nothing derives from it, and nothing emits
- * it. It rides in the note as inert data, and a note carrying one compiles,
- * resolves and emits exactly as if it were absent.
+ * **The nested `name.aliases` is deliberately not refused.** It is the note's
+ * ordered alternate names and appears in the note infobox. It does not create
+ * addresses or change how authored links resolve.
  *
  * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
  * rather than resolving a dotted key: the top-level field is the whole subject,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.19.0",
+    "version": "22.20.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/note-frontmatter.d.mts

@@ -4,3 +4,7 @@ export function authoredNoteKeys(markdown: any): string[];
 export const NOTE_TOP_LEVEL_KEYS: readonly string[];
 /** Membership test for the top-level vocabulary. */
 export const NOTE_TOP_LEVEL_KEY_SET: Set<string>;
+/** The name properties every note accepts, in display order. */
+export const NOTE_NAME_KEYS: readonly string[];
+/** Additional name components accepted by an individual character. */
+export const CHARACTER_NAME_KEYS: readonly string[];

package/types/engine/note-vocabulary.d.mts

@@ -244,6 +244,24 @@ export const DECLARED_TAGS: Readonly<{
         tags: readonly string[];
     }>;
 }>;
+/** The case-sensitive archetypes and their author-facing meanings. */
+export const BEING_ARCHETYPES: Readonly<{
+    warrior: "Can hold a line and win a fight.";
+    skirmisher: "Fights light — ambush, missile, mobility.";
+    infiltrator: "Gets in unseen — locks, stealth, disguise.";
+    mage: "Commands arcane practice.";
+    cleric: "Commands religious practice and standing.";
+    healer: "Treats wounds and illness.";
+    scholar: "Reads, researches, and knows things.";
+    courtier: "Navigates rank, negotiation, and intrigue.";
+    woodsman: "Travels and survives wild country.";
+    mariner: "Handles boats and blue water.";
+    artisan: "Builds, repairs, and appraises craft work.";
+    trader: "Moves goods, values them, and knows markets.";
+    commoner: "Fits no more specific archetype; handles ordinary work and daily life.";
+    entertainer: "Performs for an audience through acting, music, comedy, or similar arts.";
+    guildsperson: "Has professional training, standing, or connections that open doors.";
+}>;
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.

package/types/engine/retired-fields.d.mts

@@ -49,10 +49,8 @@ export function assertNoDraftField(fm: object | null | undefined, { file, absPat
  * unambiguous folded in every note's `name.full` and so dictated what a note
  * could be named. The form is retired, so the list has no reader.
  *
- * **`name.aliases` is a different field and is not retired.** It fed the same
- * index, but unlike the top-level list it is being kept — reserved, unread,
- * and deliberately unmentioned by this message, which would otherwise tell an
- * author to delete a field they are allowed to write. See
+ * **`name.aliases` is a different field.** It lists alternate names in the
+ * infobox and is deliberately unmentioned by this message. See
  * {@link assertNoAliasesField}.
  *
  * @param {string} [file] - The note's path, named in the message. Omit it where
@@ -68,13 +66,9 @@ export function aliasesRetiredMessage(file?: string): string;
  * it reads as "this note claims no other names", a statement about a namespace
  * that no longer exists.
  *
- * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
- * the retired alias index, and both lost their reader with it, but only the
- * top-level one is retired: `name.aliases` is **reserved**, held for a use that
- * does not exist yet. So it is neither refused nor read — no index consults it,
- * no rule validates its contents, nothing derives from it, and nothing emits
- * it. It rides in the note as inert data, and a note carrying one compiles,
- * resolves and emits exactly as if it were absent.
+ * **The nested `name.aliases` is deliberately not refused.** It is the note's
+ * ordered alternate names and appears in the note infobox. It does not create
+ * addresses or change how authored links resolve.
  *
  * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
  * rather than resolving a dotted key: the top-level field is the whole subject,