@heroiclands/package-build 22.18.0 → 22.20.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @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
+
+**Beings**
+
+- Beings can be described as Commoners, Entertainers, or Guildspeople, and Commoner stands alone when no other archetype fits.
+
+### Patch Changes
+
+- Books place infoboxes after each entry’s authored content, and Foundry journals place each infobox on its own page after the authored pages.
+
 ## 22.18.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,7 @@ The generated project includes a homepage, website and book targets, npm scripts
 
 ## Documentation
 
-The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md).
+The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md). This toolchain does not build its own site or book. A Hugo theme dependency would form a cycle because the theme uses package-build for releases.
 
 | Topic                                             | Guide                                                        |
 | ------------------------------------------------- | ------------------------------------------------------------ |

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                                         |
@@ -417,7 +418,7 @@ The infobox declarations this toolchain ships, one per system, and the single ca
 
 ### `engine.infoboxRender`
 
-Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
+Drawing a declared infobox: HTML for separate Foundry pages appended after authored pages, Typst panels after each note’s authored body in the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
 
 | Export                 | Signature                             | Returns   | Use it when                                                              |
 | ---------------------- | ------------------------------------- | --------- | ------------------------------------------------------------------------ |

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.
 
@@ -31,10 +33,12 @@ The formatter keeps a collection on one line when the full line is under 100 cha
 
 The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, `icon`, and `banner` fields. A type such as `being` also has its own fields, including `culture`, `homes`, and `affiliations`. A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
 
+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 `sohl:` or `hm3:` 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.
 
 ## Publication and summaries
 
-A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; presentation adapts to each medium. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.
+A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; the book places boxes after the authored body, Foundry appends one page per box, and the website places boxes in its responsive side rail. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.

package/docs/reference/format-details.md

@@ -11,10 +11,12 @@ subType: reference
 
 Markdown generates a JournalEntry: content before the first H1 becomes its "Introduction" page, and each H1 begins another page. The document Address is `<package>-note-<note_type>-<shortcode>`.
 
-An **infobox** is prepended to the entry's first page, before the prose. It is
-not a page of its own: a page is what a Foundry UUID addresses, and a summary a
-reader has to navigate to is a summary they do not see. What the box holds, and
-where it sits in every other medium, is [the infobox](#the-infobox) below.
+Each emitted infobox becomes a separate page at the end of the JournalEntry,
+after every authored page. The page names are **Properties Infobox**,
+**SoHL Infobox**, and **HM3 Infobox**, in that order where emitted. Generated
+page ids derive from the entry and box identity, separately from authored
+heading names and anchors. An authored heading may share an infobox page name.
+What the boxes hold is [the infobox](#the-infobox) below.
 
 **There are two kinds of infobox.**
 
@@ -62,16 +64,13 @@ For web pages, the full Markdown body renders as HTML with its infoboxes.
 
 ### The infobox
 
-**The infobox is generated content at a known position — prepended, before the
-prose.** It is not a floating sidebar and it is not defined in a rendering
-template. The toolchain settles what each box holds; each medium lays that out
-its own way.
+**The toolchain settles what each box holds; each medium places it.**
 
-| medium  | placement                                              | collapsing                |
-| ------- | ------------------------------------------------------ | ------------------------- |
-| book    | flows in the column measure, breaking between sections | none, and none needed     |
-| website | side rail on wide screens, inline on narrow            | `<details>`, default open |
-| Foundry | inlined, the page being narrow                         | `<details>`, default open |
+| medium  | placement                                                                                                     | collapsing                |
+| ------- | ------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| book    | after the note's authored body, before the next entry; flows in the column measure, breaking between sections | none                      |
+| website | side rail on wide screens, inline on narrow screens                                                           | `<details>`, default open |
+| Foundry | one page per emitted box, after all authored pages                                                            | `<details>`, default open |
 
 Two columns are print-only. A scrolling page has no fixed viewport, so columns
 make a reader travel down and back up, and a narrow screen collapses to one
@@ -79,8 +78,8 @@ column regardless.
 
 **Six rules hold in every medium.**
 
-1. **It is content in document order**, prepended before the prose. An image
-   authored before it appears before it.
+1. **Placement belongs to the medium**, as described above. Authored images
+   remain in the body in their authored order.
 2. **It contains no image.** A picture is authored in the text with its own
    directive, and its position governs.
 3. **A section is the unit that flows.** Sections are whole and unbreakable and
@@ -118,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
@@ -334,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.
 
@@ -442,16 +449,16 @@ surface:
 > **Draft.** This entry is unfinished. What it states may change, and nothing in
 > it is settled.
 
-It leads the entry — above the infobox and above the prose — because a reader
+It leads the entry, before the authored content, because a reader
 deciding whether to rely on an entry has to be told before they read it. Where
 it lands:
 
-| Surface      | What carries it                                                      |
-| ------------ | -------------------------------------------------------------------- |
-| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page       |
-| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`    |
-| The book     | a drawn mark and a left rule between the entry's plate and its panel |
-| The website  | the theme's own notice, above the infobox rail and the prose         |
+| Surface      | What carries it                                                              |
+| ------------ | ---------------------------------------------------------------------------- |
+| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page               |
+| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`            |
+| The book     | a drawn mark and a left rule between the entry's plate and its authored body |
+| The website  | the theme's own notice, above the infobox rail and the prose                 |
 
 **An Actor carries it once.** A being's prose reaches two fields, and a document
 saying the same thing twice teaches a reader to skip it — a printed sheet draws
@@ -2433,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.
@@ -2445,8 +2454,17 @@ For JournalEntries, the following rules apply:
 - 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.
+
+<!-- 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.
 
 #### Items
 
@@ -2458,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,6 +1179,102 @@ export function lintNote(
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+    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
      * the note-level field of that name, which every note-level check below

package/engine/infobox.mjs

@@ -51,9 +51,9 @@
  *
  * ## Six rules that hold in every medium
  *
- * 1. **The infobox is generated content in document order** — prepended,
- *    before the prose. Not a floating sidebar. An image authored before it
- *    appears before it.
+ * 1. **Placement belongs to the medium.** The book puts boxes after the
+ *    authored body, Foundry appends one page per box, and the website uses
+ *    a side rail on wide screens and inline boxes on narrow screens.
  * 2. **It contains no image.** A picture is authored in the text with its own
  *    directive, and its position governs. {@link NOTE_FIELD_PRESENTATION}
  *    withholds the art slots and `overlay` for that reason and no other.
@@ -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/journals.mjs

@@ -335,16 +335,13 @@ export function buildPages(rawPages, entryId, noteName, captions) {
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
- * @param {string} [params.infobox] - The note's infobox, already rendered to
- *   HTML. Prepended to the entry's first page, which is where the format puts
- *   it: the box is generated content in document order, before the prose, and
- *   a Foundry page is narrow enough that inlining it is the only arrangement
- *   that reads. It is **not** a page of its own — a page is what a UUID
- *   addresses, and a summary a reader has to navigate to is a summary they do
- *   not see.
+ * @param {Array<{id: string, name: string, html: string}>} [params.infoboxes] -
+ *   Emitted boxes, each rendered to HTML. Each becomes a separate page after
+ *   the authored pages. Its identity uses the box id in a generated-page
+ *   namespace, independent of authored headings and anchors.
  * @param {string} [params.notice] - A statement about the entry rather than
  *   about its subject, already rendered to HTML — see {@link
- *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
@@ -357,13 +354,21 @@ export function buildJournalEntry({
     folder = null,
     flags,
     stats = defaultStats(),
-    infobox = "",
+    infoboxes = [],
     notice = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name, scanCaptions(markdown).captions);
-    if (infobox.trim() && pages.length) {
-        pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
+    for (const box of infoboxes) {
+        const pageId = makeId("journal-infobox-page", `${id}:${box.id}`);
+        pages.push({
+            _id: pageId,
+            name: box.name,
+            type: "text",
+            title: { show: true, level: 1 },
+            text: { format: 1, content: box.html },
+            _key: `!journal.pages!${id}.${pageId}`,
+        });
     }
     if (notice.trim() && pages.length) {
         pages[0].text.content = `${notice}\n${pages[0].text.content}`;
@@ -522,7 +527,15 @@ export class Journals extends BasePackCompiler {
             id,
             name,
             markdown,
-            infobox: infoboxesToHtml(boxes, { link: linkToUuid }),
+            infoboxes: boxes.map((box) => ({
+                id: box.id,
+                name: `${
+                    box.id === "note" ? "Properties"
+                    : box.id === "sohl" ? "SoHL"
+                    : "HM3"
+                } Infobox`,
+                html: infoboxesToHtml([box], { link: linkToUuid }),
+            })),
             // Whether the entry is settled, asked of the tag through the one
             // reader of it. This sits here rather than in `buildJournalEntry`
             // for the reason `skipNote` runs first: a note with no prose

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/pdf-build.mjs

@@ -639,9 +639,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             anchorPrefix,
             captions: numberedCaptions,
         });
-        // The infobox is generated content in document order — prepended,
-        // before the prose. An image the note authored ahead of it still comes
-        // first, because the image lives in the body and the body follows.
+        // Infoboxes follow the authored body within this note's entry.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
             router: routerFor(resolved),
@@ -651,10 +649,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             link: (value) => linkToTypst(value, plan.links, labelFor),
         });
         // Whether the entry is settled comes before anything it says: the
-        // notice leads the leaf, ahead of the panel, which is the position it
-        // holds on every other surface.
+        // notice leads the leaf, before the authored body.
         const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
-        const parts = [notice, panel, prose].filter((part) => part);
+        const parts = [notice, prose, panel].filter((part) => part);
         return parts.join("\n\n");
     };
 

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/engine/site-build.mjs

@@ -984,7 +984,6 @@ export function renderPages(pages, options) {
  */
 const SITE_PASSES = Object.freeze({
     sohlKb: () => require("../sohl/kb-passes.mjs").sohlKbPass,
-    packageDocs: () => require("./documentation-links.mjs").documentationLinksPass,
 });
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.18.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",
@@ -174,7 +174,6 @@
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
-        "@heroiclands/hugo-theme": "^0.9.0",
         "@types/node": "^26.2.0",
         "npm-run-all": "^4.1.5",
         "vitest": "^5.0.0"
@@ -198,16 +197,7 @@
         "changeset": "changeset",
         "changeset:version": "changeset version && node bin/package-build.mjs changelog group && npm install --package-lock-only",
         "prepare": "git config core.hooksPath .githooks || true",
-        "build:deps": "node bin/package-build.mjs deps fetch",
-        "build:content-index": "node bin/package-build.mjs content-index",
-        "build:site-content": "node bin/package-build.mjs site",
-        "build:site-html": "hugo --source build/hugo --minify --gc --cleanDestinationDir",
-        "build:site-root": "node bin/package-build.mjs site-root",
-        "build:site": "run-s build:deps build:content-index build:site-content build:site-html build:site-root",
-        "build:book": "run-s build:deps build:content-index build:book-content",
-        "build:book-content": "node bin/package-build.mjs pdf",
-        "serve:site": "run-s build:deps build:content-index build:site-content serve:site-html",
-        "serve:site-html": "hugo server --source build/hugo"
+        "build:deps": "node bin/package-build.mjs deps fetch"
     },
     "engines": {
         "node": ">=24.0.0"

package/types/engine/journals.d.mts

@@ -139,21 +139,18 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
- * @param {string} [params.infobox] - The note's infobox, already rendered to
- *   HTML. Prepended to the entry's first page, which is where the format puts
- *   it: the box is generated content in document order, before the prose, and
- *   a Foundry page is narrow enough that inlining it is the only arrangement
- *   that reads. It is **not** a page of its own — a page is what a UUID
- *   addresses, and a summary a reader has to navigate to is a summary they do
- *   not see.
+ * @param {Array<{id: string, name: string, html: string}>} [params.infoboxes] -
+ *   Emitted boxes, each rendered to HTML. Each becomes a separate page after
+ *   the authored pages. Its identity uses the box id in a generated-page
+ *   namespace, independent of authored headings and anchors.
  * @param {string} [params.notice] - A statement about the entry rather than
  *   about its subject, already rendered to HTML — see {@link
- *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infobox, notice, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infoboxes, notice, }: {
     id: string;
     name: string;
     markdown: string;
@@ -161,7 +158,11 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
     folder?: string | null | undefined;
     flags?: object | undefined;
     stats?: object | undefined;
-    infobox?: string | undefined;
+    infoboxes?: {
+        id: string;
+        name: string;
+        html: string;
+    }[] | undefined;
     notice?: string | undefined;
 }): object;
 /**

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,

package/engine/documentation-links.mjs

@@ -1,31 +0,0 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
-
-import fs from "node:fs";
-import path from "node:path";
-
-import { parseMarkdownFile } from "./helpers.mjs";
-
-const LOCAL_MARKDOWN_LINK = /\[([^\]\n]+)\]\(([^\s)]+\.md(?:#[^\s)]*)?)\)/g;
-
-/** Keep repository-relative documentation links usable on addressed pages. */
-export function documentationLinksPass({ config, book = false }) {
-    const root = config.paths.content;
-    const cache = new Map();
-    return {
-        beforeLinks(text, page) {
-            return text.replace(LOCAL_MARKDOWN_LINK, (whole, label, target) => {
-                const [fileName, fragment] = target.split("#", 2);
-                const file = path.resolve(path.dirname(page.file), fileName);
-                if (!file.startsWith(`${root}${path.sep}`) || !fs.existsSync(file)) return whole;
-                let address = cache.get(file);
-                if (!address) {
-                    const { frontmatter } = parseMarkdownFile(file);
-                    if (!frontmatter?.type || !frontmatter?.shortcode) return whole;
-                    address = `/${config.contentPackage}/${frontmatter.type}-${frontmatter.shortcode}/`;
-                    cache.set(file, address);
-                }
-                return `[${label}](${address}${fragment && !book ? `#${fragment}` : ""})`;
-            });
-        },
-    };
-}

package/types/engine/documentation-links.d.mts

@@ -1,7 +0,0 @@
-/** Keep repository-relative documentation links usable on addressed pages. */
-export function documentationLinksPass({ config, book }: {
-    config: any;
-    book?: boolean | undefined;
-}): {
-    beforeLinks(text: any, page: any): any;
-};