@heroiclands/package-build 22.20.0 → 22.22.0

package/docs/reference/format-details.md

@@ -354,6 +354,8 @@ order without changing the Markdown body.
 
 A canonical date is `<year>[.<day>[:HHMMSS]]`. The day is one-based within the world's year. `720` covers the whole year; `720.136` covers that day; `720.136:143005` identifies one second. Negative years are valid. Prefix either form with `~` to express uncertainty beyond its written interval. `unknown` is allowed only in fields that accept an unknown occurrence.
 
+**Quote a canonical date that states a day.** `born: "667.130"` is read as written; unquoted, YAML parses the scalar as a number and a trailing zero on the day is gone before any date reader sees it, so `667.130` and `667.13` arrive as one value. A number-valued date is an error wherever appending a zero to its day would still name a day inside the world's year — the message names the file, the line and both readings — and is read as written where no such day exists, since `675.2810` is no day of a 365-day year. A bare year loses nothing and needs no quotes.
+
 A named date uses `datefrom <calendar> <date>`, where the final text follows the calendar's `data.formats.std` pattern, or its first named pattern when `std` is absent. For example, a calendar with `std: "MM/DD/Y GGG"` reads `datefrom commoncal 01/23/326 VR`, `datefrom commoncal 01/326 VR`, and `datefrom commoncal 326 VR`. Omitting the day or month retains month or year precision in frontmatter. The CLI `datefrom` command requires a day to produce one canonical day. The calendar argument is a shortcode or Address. A time follows the day only when specified in the pattern, or as a trailing `HH:mm:ss` when the pattern has no clock tokens. A named date with an era-relative year names its era.
 
 `data.epoch` on a calendar is a canonical `<year>.<day>`: the day on which **calendar year 1, day 1** occurs. It cannot be year-only, approximate, or expressed through its own calendar. `data.moon.newOn` also locates a particular day. The `data.eras[].start` values are `null` or positive **calendar years**. Exactly one null era covers dates before calendar year 1, and exactly one era starts at year 1. Further era starts are distinct positive integers. Numeric start order determines era boundaries, regardless of array order. The null era numbers its years backwards; later eras begin at their own displayed year 1. An era may have a unique uppercase `marker` for resolving authored dates.
@@ -2086,11 +2088,69 @@ See the [authoring examples](../authoring/links-and-markup.md#footnotes-and-defi
 # Heading {#id .class1 .class2 attr="value"}
 ```
 
-Any header can include curly braces. Inside the curly braces:
+Any header can end with a braced attribute block, in the same grammar a
+`:::caption` and a named block take. Inside the braces:
+
+- `#id` names the anchor a link resolves to (only one allowed)
+- `.class1` names a CSS class (any number of classes allowed)
+- `attr="value"` names an HTML attribute whose value is `value` (any number of
+  key/value pairs allowed)
+
+The id is what every surface publishes; a class and an attribute reach only the
+surfaces that have somewhere to put them.
+
+|                 | an `#id`                                                    | a `.class`            | an `attr="value"`      |
+| --------------- | ----------------------------------------------------------- | --------------------- | ---------------------- |
+| Website         | the heading's `id`, and the target of `[[note#id\|…]]`      | the heading's `class` | written on the heading |
+| Foundry journal | the anchor the page is addressed by, and the heading's `id` | the heading's `class` | written on the heading |
+| Book            | the Typst label the heading is linked to                    | dropped               | dropped                |
+
+**The book drops both**, because Typst has no stylesheet for a class to name
+and no element for an attribute to sit on. A heading whose appearance matters in
+print is set by the book's own template, not by a class an author writes.
+
+An id contains letters, digits, `_` or `-`. A class and an attribute key begin
+with a letter. Braces holding nothing the grammar recognises — a set, a die
+expression, a measurement — are one finding at the heading's line, and the
+heading is set as it was written so nothing is lost while the author reads the
+message.
+
+`id=` and `class=` are refused in favour of `#id` and `.class`, and an attribute
+beginning `on` is refused as an event handler, exactly as on a named block: a
+heading's attributes are written onto the element, so nothing authored in a note
+becomes code on a published page.
+
+#### A section withheld from players
+
+The class `secret` on the heading that opens a section withholds that section.
+The heading keeps its id, so the section stays linkable: secrecy is a property
+of the section, not of the name a link resolves to.
+
+```markdown
+# The Cellar {#cellar .secret}
+
+The contraband is behind the false wall.
+```
+
+The section runs from the heading to the next heading that opens a page, which
+is the span Foundry makes one page of.
 
-- `#id` represents an id anchor named `id` (only one allowed)
-- `.class1` represents a CSS class named `class1` (any number of classes allowed)
-- `attr="value"` represents an HTML attribute named `attr` whose value is `value` (any number of attr/value pairs allowed)
+| Surface | What a reader meets                                                                                               |
+| ------- | ----------------------------------------------------------------------------------------------------------------- |
+| Foundry | The journal page is visible to the GM alone — `ownership: { default: 0 }`, `CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE` |
+| Website | The heading and everything under it sit inside the expandable `<details>` a `:::secret` block renders as          |
+| Book    | The heading and everything under it are set in the labelled block a `:::secret` is set in                         |
+
+**On the website this is a spoiler and not access control.** The withheld
+section is in the published page, so a reader who opens the element or reads the
+source reads it — exactly as a `:::secret` block is. Foundry is the only surface
+that withholds anything from anybody. Write nothing in a `.secret` section that
+would matter if a player read it on the web.
+
+A `:::secret` block inside a withheld section is legal and renders as it does
+anywhere else. `.secret` on a heading that opens **no** page covers no page, so
+no surface can honour it: that is a finding at the heading's own line, answered
+by giving the heading an anchor or raising it to the top level.
 
 #### Images
 
@@ -2352,6 +2412,59 @@ errors. Duplicate and unknown attributes are errors.
 | `allow-empty=true`                          | Permits a query selecting no rows. Default `false`. |
 | `section-level=1` through `section-level=6` | Sets the heading level for `_section`. Default `2`. |
 
+##### Page lists
+
+A fenced `pagelist` block renders a list of the pages carrying a tag. It is the
+companion of a content table and answers the other question: a table says what
+a set of notes contains, a page list says which pages belong to a group.
+
+````markdown
+```pagelist {tag="key-concept" type=lore sort=type descriptions=true}
+
+```
+````
+
+**The group is the tag, not an enumeration.** A hand-written list of links is
+a second place the membership is recorded, and the two drift the moment a page
+is written and nobody edits the landing that should name it. A page list reads
+`tags:` instead, so tagging a page files it and untagging it removes it.
+
+**The fence takes no body.** Every statement about the directive is an
+attribute in the shared braced grammar, so there is one grammar to learn; text
+written inside the fence is reported rather than printed, and a fence nobody
+closed is reported rather than swallowing the rest of the note.
+
+| Attribute           | What it does                                                              |
+| ------------------- | ------------------------------------------------------------------------- |
+| `tag=`              | Required. The tag a page carries to join the list.                        |
+| `type=`             | Restricts the list to one note type. Every type by default.               |
+| `sort=name`         | Alphabetical, case and accents folded, tiebroken on address. The default. |
+| `sort=type`         | Groups the note types and orders by name within each.                     |
+| `descriptions=true` | Follows each link with the page's `description`. Default `false`.         |
+| `allow-empty=true`  | Permits a tag no page carries. Default `false`.                           |
+
+The tag is matched the way `tags:` is read everywhere else — a leading `#`,
+surrounding space and letter case are all insignificant, while the spelling of
+the tag itself is exact. Nothing guesses at a near miss.
+
+**What a list holds.** Every note of this package that carries the tag and
+publishes a page. A **stub** publishes no page, so it holds no address and joins
+no list. A documentation journal is not listed beside the note it documents,
+because they are one page. A note tagged `gm` is listed in Foundry and left out
+of the website and the book, which is the same audience rule a content table's
+relations follow.
+
+**Each entry is a link, resolved by the surface that is building.** The
+directive is answered before the body is walked and spliced in where the fence
+sat, so the list reaches a reader as compendium journal links in Foundry and
+page links on the website and in the book — the same resolution an authored
+`[[…]]` gets, including the cue on a link into a `draft` note.
+
+**A tag no page carries is an error at the fence's line and column**, naming
+the tag and, where the directive restricts one, the type. An empty list under
+an authored heading is how a misspelled tag survives a build, so the
+directive's silence is what is refused rather than its output.
+
 ##### Captioned blocks
 
 `:::caption {#anchor}` labels the next Markdown block, whether it is prose,
@@ -2381,48 +2494,74 @@ block is prose. The website and Foundry number each category within a note;
 the PDF numbers each category through the book. Foundry gives a captioned block
 its own JournalEntryPage, so its anchor has a page UUID.
 
-`:::info` and `:::warn` mark explanatory and cautionary boxes inline. Their
-content is Markdown, and the boxes carry a label and icon on the web, in
-Foundry, and in the book. An optional `{#id}` gives a box an HTML anchor.
-Close each with a whole-line `:::`. Empty, nested, and unclosed boxes are
-errors at the opening line.
+##### Named blocks
+
+`:::secret`, `:::info` and `:::warn` set a passage apart from the prose around
+it. The opener and the closing `:::` each take a whole line, the content is
+Markdown and renders normally, and the fences stay outside code blocks. An
+empty, nested or unclosed block is an error at its opening line, as is a name
+that is not one of the three.
+
+A braced attribute block may follow the name. It takes an id as `#id`, classes
+as `.class`, and any other attribute as `key="value"`. `title` is reserved and
+supplies the heading; without it a block heads itself **Secret**, **Info** or
+**Warn**. A title carries its own emphasis and nothing else — a tag written
+there is escaped. `id=` and `class=` are refused in favour of `#id` and
+`.class`, and an attribute beginning `on` is refused as an event handler.
 
 ```markdown
 :::info
 The harbor remains open through winter.
 :::
 
-:::warn {#flood-warning}
+:::warn {#flood-warning title="Seasonal closure"}
 Spring floods close the eastern road.
 :::
-```
 
-```
-:::secret
-This is secret text
+:::secret {#harbor .wide}
+The harbor master is working for the smugglers.
 :::
 ```
 
-Use a whole-line `:::secret` opener and a whole-line `:::` closer to mark a GM passage. Markdown inside the block, including links and emphasis, renders normally. Keep the fences outside code blocks and close each one before starting another. An unclosed or nested block is a build error at the source line.
+The block's name is the first class on the emitted element and the author's
+classes follow it. **No block carries an inline `style`**, so the appearance is
+a stylesheet's. The base stylesheet styles `section.info` and `section.warn`;
+`section.secret` is left to Foundry, which styles it and owns the reveal control
+on it.
 
-In FoundryVTT, the passage is a secret section visible to the GM and owners of the journal:
+In FoundryVTT a block is a section whose first line is its heading, and a
+`secret` is the section Foundry shows to the GM and to owners of the journal:
 
 ```html
-<section class="secret" id="secret-example">
-  <p>This is secret text</p>
+<section class="secret wide" id="harbor">
+  <strong>Secret</strong><br />
+  <p>The harbor master is working for the smugglers.</p>
 </section>
 ```
 
-On webpages, the passage appears as a collapsed spoiler that any reader can open:
+A `secret` that states no id of its own is given one derived from its body, so
+that Foundry can remember the section once a reader reveals it.
+
+On webpages a block is a disclosure any reader can open, titled in its summary:
 
 ```html
-<details>
-  <summary>Spoiler</summary>
-  <p>This is secret text</p>
+<details class="secret wide" id="harbor">
+  <summary class="secret">Secret</summary>
+  <p>The harbor master is working for the smugglers.</p>
 </details>
 ```
 
-In books, the passage is visible under a **GM note** label. A printed page has no reader permissions or interactive disclosure control.
+In a book each block is a coloured box headed by its title. A printed page has
+no reader permissions and no interactive disclosure control, so a `secret` is
+visible there.
+
+**A secret is a presentation distinction and not access control.** It is in the
+same authored note as the prose around it, and a reader who inspects source or
+generated output may see it.
+
+**A malformed block does not silence the blocks around it.** It is reported at
+its own line and left as the author wrote it, and every well-formed block in the
+note still renders.
 
 #### Actors
 
@@ -2432,11 +2571,6 @@ The following H1 headers are treated specially:
 
 - `# ... {#appearance}`: The contents of this header become the `doc.appearance` property in sohl and `doc.description` in hm3.
 - `# ... {#dossier}`: The contents of this header become the `doc.dossier` property in sohl and `doc.biography` in hm3.
-- `# ... {#spoilers}`: The contents of this header are not written to the actor at all.
-
-For JournalEntries, the following rules apply:
-
-- `# ... {#spoilers}`: The contents of this header go into a page which is viewable only by the GM (`CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE`).
 
 **Archetypes** describe characters in broad terms and help match them to an adventure. The list is:
 
@@ -2487,7 +2621,7 @@ Generates a living (or undead, or spirit) being.
 | `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)                                                                                         |
+| `affiliations`              | `Map<Address, Membership>`                     | Bodies the being belongs to, keyed by Address, each entry the standing it holds there                                                                 |
 | `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)                                                                                                                                |
@@ -2517,15 +2651,70 @@ describe a being's body. Item gear weight remains a numeric `data.weight`.
 `data.culture` names the culture in which a character belongs. It is one
 Address to a `type: lore`, `subType: culture` note. A named character with a
 known culture states it here; generic beings and templates can omit it.
-`data.lore` holds other lore concerning the being, such as social standing or
-law. Record the primary culture in `data.culture` only.
+`data.lore` holds the law the being lives under, the customs it is subject to
+and the traditions it was raised in. Record the primary culture in
+`data.culture` only, and a standing in `data.affiliations`.
 
 ```yaml
 data:
   culture: lore-vedyariclt
-  lore: [lore-commonerrnk]
+  lore: [lore-marchlaw]
 ```
 
+#### The bodies a being belongs to, and its standing in each
+
+**Membership**: `{rank: number, office: string}` — `rank` required, `office` not.
+
+`data.affiliations` is a **map keyed by the body's Address**, and each entry is
+the standing the being holds in that body. The key is what makes the pair
+expressible: a being in two bodies holds a standing in each, and two bodies may
+call a rung the same word.
+
+An entry carries two keys and nothing else:
+
+- **`rank`** — **required**, a **number**, the level on that body's own
+  `governance.ranks` ladder. The body declares `{level, title, description}` for
+  every rung, so a number indexes into it and the body stays the single source
+  for what its level 5 is called.
+- **`office`** — optional, a **string**, matched against the keys of that body's
+  `governance.offices` map.
+
+**Every entry states a `rank`**, because belonging to a body is holding some
+standing in it. Where nothing more is known the rung is `1`, the ordinary
+member; `0` is the rung for someone cast out, which is a real answer rather than
+a default — the ladders carry `0 Níding`, `0 Outlaw` and `0 Struck from the
+Roll`. Between them the two ends cover every standing a member can hold, so an
+entry that states no rank is an **error** at the entry's own line, and the
+message names both numbers rather than only the gap.
+
+An entry carrying an **office and no rank** is that same error and not a second
+one, reported once: an office distinguishes a person within a standing rather
+than standing in for one, so such an entry puts a person in a post in nothing.
+An entry carrying a rank and no office is complete.
+
+```yaml
+data:
+  affiliations:
+    affiliation-vrystwldtrbs: { rank: 5, office: War Chief }
+    affiliation-greenwardens: { rank: 1 }
+    affiliation-silverguild: { rank: 0 }
+```
+
+Both values are checked against the body the entry is keyed by. A `rank` that
+is not a level the body confers and an `office` that is not one of its keys are
+each an error naming the file, line and column — so a renamed rung or a renamed
+post fails on every being pointing at it. Naming one body twice, by its short
+and full Address, still names one body and is an error.
+
+The infobox prints the standing closing on its body — `War Chief, Hárár, of
+Vrystwald Tribes` — and links an office to the description the body itself
+declares, so recording the post needs no note about the post.
+
+For SoHL, a being embeds one affiliation item per entry: `rank` **is** that
+item's `system.level` and `office` its `system.office`. A standing is a fact
+about the setting rather than about one system, so the `sohl:` block states
+none of it.
+
 #### The people who matter to a being
 
 `data.socialTies` records relationships that define the subject's dossier, not
@@ -2558,8 +2747,8 @@ an error.
 Each tie is one-sided. The target need not name the subject back, even when
 `patron` and `dependent` would describe opposite ends of the same support.
 Kinship, household membership, organizational membership, rank, and office are
-distinct facts. Their relevant effects may appear as ties, while their details
-belong in prose, `data.affiliations`, or governance fields. A tie has no
+distinct facts. Their relevant effects may appear as ties, while a membership
+and the standing held in it belong in `data.affiliations`. A tie has no
 mechanical modifier.
 
 #### When a being was born, when it died, and how old it is
@@ -2897,12 +3086,46 @@ two is the commonest way to get a non-monarchy wrong.
 **Rank**
 Definition of a level within the organization (e.g., Priest, Layperson, Member, Gang Leader, Master, etc.)
 
-| Property      | Values    | Description                                                                                                                          |
-| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `level`       | number    | The ranking within the affiliation, increasing values starting with 1, 0 indicates intentional exclusion (expulsion/excommunication) |
-| `title`       | string    | Title associated with the Rank                                                                                                       |
-| `description` | string    | Description of the Rank                                                                                                              |
-| `lore`        | `Address` | The standing this rank _is_ — a `lore` note of subType `law`, shared with every other body that confers the same thing               |
+| Property      | Required | Values    | Description                                                                                                                          |
+| ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `level`       | yes      | integer   | The ranking within the affiliation, increasing values starting with 1, 0 indicates intentional exclusion (expulsion/excommunication) |
+| `title`       | yes      | string    | Title associated with the Rank                                                                                                       |
+| `description` | yes      | string    | Description of the Rank                                                                                                              |
+| `lore`        | no       | `Address` | The standing this rank _is_ — a `lore` note of subType `law`, shared with every other body that confers the same thing               |
+
+**`level`, `title` and `description` together are a complete statement of a
+rung**, and nothing further is required for a ladder to be correct. Each is an
+**error** when it is missing or empty, and a `level` that is not a whole number
+is an error too: the ladder is what a member's `rank` indexes into, so a rung
+with no title makes a standing that resolves to nothing, and one with no
+description ships a rung that says nothing on a sheet or a page. A rung accepts
+only these four keys, and each problem on a rung is reported separately, so a
+ladder with three is fixed in one pass rather than three builds.
+
+**A level belongs to one rung.** Two rungs claiming one level is an **error** on
+the second, naming the first, because the ladder is read by level: a member whose
+`rank` is that level answers to whichever rung is written higher in the file, and
+moving two lines renames the standing. A body that confers two titles at one
+standing writes them as one rung — `title: Knight or Dame` — or gives each its
+own level.
+
+```yaml
+data:
+  governance:
+    ranks:
+      - { level: 0, title: Vrystrith, description: Kinless and owed nothing. }
+      - { level: 4, title: Fródrád, description: A householder whose word carries. }
+      - level: 5
+        title: Hárár
+        description: First among them, by the assent of the householders.
+        lore: lore-harar-standing
+```
+
+**Reach for `lore` only where the standing needs more said about it than a
+description can hold** — obligations, rights, what it takes to enter it, what
+ends it. Most rungs do not: a description that states what the standing is has
+already said the whole of it, and a note that restates the rung it hangs off
+costs a reader a click and tells them nothing.
 
 **A rank's `lore` is shared; its `title` is not.** A Normen kingdom calls it
 `Thrall` and a Vylarian province calls it `Slave`, and they mean one standing:
@@ -3575,7 +3798,7 @@ name: { full: The Common Calendar }
 type: lore
 subType: calendar
 data:
-  epoch: 1.1
+  epoch: "1.1"
   months:
     - { name: Floralis, abbreviation: Flor, days: 30 }
     - { name: Lusenar, abbreviation: Luse, days: 31 }
@@ -3824,7 +4047,7 @@ data:
 # its moon — a note of its own, because a moon is a body and not a property
 data:
   body: { diameterKm: 3800, orbitalRadiusKm: 388600, orbit: circular, inclined: true }
-  moon: { cycle: 30, newOn: 720.1, eclipses: rare }
+  moon: { cycle: 30, newOn: "720.1", eclipses: rare }
 ```
 
 **`year.days` is where the year's length lives, and every calendar in the

package/docs/reference/note-types.md

@@ -11,6 +11,23 @@ Choose a note's `type` for the subject it describes. Use `subType` when its type
 
 The [first-note guide](../authoring/first-note.md) teaches the shape of a note. [Frontmatter](../authoring/frontmatter.md) explains shared and system-specific values. The [detailed reference](format-details.md) gives the full behavior and examples.
 
+## Top-level keys
+
+These are the only keys a note writes at its top level, in the order the formatter puts them. A key absent from this table is a lint error at its own line: the region is closed, so the key reaches no document and no page. Facts about the subject belong under `data`, and values for one game system belong inside that system's block.
+
+| Key           | Meaning                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `shortcode`   | The note's own address segment, unique within its type.                                   |
+| `name`        | The display names — a required `full`, and any `aliases`.                                 |
+| `type`        | What the note is about, which decides its vocabulary and its document.                    |
+| `subType`     | The type's own genre, where it declares one.                                              |
+| `description` | The short page summary.                                                                   |
+| `tags`        | Draft state, GM routing, and the descriptive labels a page list reads.                    |
+| `data`        | The facts about the subject itself, shared by every system.                               |
+| `dnd5e`       | What the `dnd5e` system makes of the subject — its document's mechanics, routing and art. |
+| `hm3`         | What the `hm3` system makes of the subject — its document's mechanics, routing and art.   |
+| `sohl`        | What the `sohl` system makes of the subject — its document's mechanics, routing and art.  |
+
 ## Shared `data` fields
 
 These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.
@@ -30,34 +47,34 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 **Subtypes:** `npc`, `character`, `creature`.
 
-| Field                            | Shape                     | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| -------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data.social`                    | map                       | The being's social profile.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `data.tokenIcon`                 | an Address                | What a token on the canvas wears — an `icon` address; unset, it follows `icon`.                                                                                                                                                                                                                                                                                                                                                     |
-| `data.templatePriority`          | number                    | Template priority; unset means the note is not a template.                                                                                                                                                                                                                                                                                                                                                                          |
-| `data.archetypes`                | list                      | Archetypal behaviours the being fits.                                                                                                                                                                                                                                                                                                                                                                                               |
-| `data.occupation`                | string                    | What the being does for a living.                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `data.stations`                  | list of Addresses         | Stations the being holds.                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `data.lore`                      | list of Addresses         | Lore concerning this being, such as the standing it holds or the law it lives under.                                                                                                                                                                                                                                                                                                                                                |
-| `data.culture`                   | an Address                | The being's primary culture, as a culture lore note.                                                                                                                                                                                                                                                                                                                                                                                |
-| `data.homes`                     | list of Addresses         | Places the being calls home.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.affiliations`              | list of Addresses         | Affiliations the being belongs to — traditions, polities, and the rest.                                                                                                                                                                                                                                                                                                                                                             |
-| `data.socialTies`                | a map keyed by Address    | Defining ties directed from this being to others: `patron` (Supports the subject from greater power, wealth, or status.); `friend` (Supports the subject out of goodwill.); `dependent` (Relies on the subject's support or protection.); `acquaintance` (Knows the subject without a strong disposition.); `rival` (Opposes the subject without implacable hostility.); `nemesis` (Opposes the subject personally and implacably.) |
-| `data.gender`                    | string                    | `male`, `female` or `other`.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.species`                   | an Address                | The being's species, as a lore note.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `data.born`                      | string                    | When the being was born — a date, or `unknown` where the birth is unrecorded. Absent, the being was never born.                                                                                                                                                                                                                                                                                                                     |
-| `data.calendar`                  | an Address                | Calendar used to display this being's dates.                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.died`                      | string                    | When the being died — a date, or `unknown` where the death is unrecorded. Absent, the being is alive.                                                                                                                                                                                                                                                                                                                               |
-| `data.age`                       | string                    | Age in years, stated only to override what `born` says — `34`, or `~34` for an estimate. Unstated beside a dated `born` it is computed; unstated beside an unknown or absent `born` the age is unknown.                                                                                                                                                                                                                             |
-| `data.ageYears`                  | number                    | Written by the compiler beside an `age` estimate — the `~` stripped, the magnitude alone. A note never authors this.                                                                                                                                                                                                                                                                                                                |
-| `data.height`                    | metres or feet and inches | Height in metres or feet and inches.                                                                                                                                                                                                                                                                                                                                                                                                |
-| `data.weight`                    | kilograms or pounds       | Body weight in kilograms or pounds.                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `data.frame`                     | string                    | Relative frame — `scant`, `light`, `medium`, `large` or `massive`.                                                                                                                                                                                                                                                                                                                                                                  |
-| `data.appearance.eye_color`      | string                    | Eye colour.                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `data.appearance.hair_color`     | string                    | Hair colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.appearance.skin_color`     | string                    | Skin colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `data.appearance.complexion`     | string                    | Complexion.                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `data.appearance.extra_features` | list                      | Anything else a stranger would notice.                                                                                                                                                                                                                                                                                                                                                                                              |
+| Field                            | Shape                                                   | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| -------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.social`                    | map                                                     | The being's social profile.                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `data.tokenIcon`                 | an Address                                              | What a token on the canvas wears — an `icon` address; unset, it follows `icon`.                                                                                                                                                                                                                                                                                                                                                     |
+| `data.templatePriority`          | number                                                  | Template priority; unset means the note is not a template.                                                                                                                                                                                                                                                                                                                                                                          |
+| `data.archetypes`                | list                                                    | Archetypal behaviours the being fits.                                                                                                                                                                                                                                                                                                                                                                                               |
+| `data.occupation`                | string                                                  | What the being does for a living.                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `data.stations`                  | list of Addresses                                       | Stations the being holds.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `data.lore`                      | list of Addresses                                       | Lore concerning this being — the law it lives under, the customs it is subject to, the traditions it was raised in.                                                                                                                                                                                                                                                                                                                 |
+| `data.culture`                   | an Address                                              | The being's primary culture, as a culture lore note.                                                                                                                                                                                                                                                                                                                                                                                |
+| `data.homes`                     | list of Addresses                                       | Places the being calls home.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `data.affiliations`              | a standing map keyed by Address, or a list of Addresses | Bodies the being belongs to, keyed by Address, each entry holding the standing it holds there — `rank`, required, a level on that body's own ladder, and `office`, optional, a post that body names.                                                                                                                                                                                                                                |
+| `data.socialTies`                | a map keyed by Address                                  | Defining ties directed from this being to others: `patron` (Supports the subject from greater power, wealth, or status.); `friend` (Supports the subject out of goodwill.); `dependent` (Relies on the subject's support or protection.); `acquaintance` (Knows the subject without a strong disposition.); `rival` (Opposes the subject without implacable hostility.); `nemesis` (Opposes the subject personally and implacably.) |
+| `data.gender`                    | string                                                  | One of `male`, `female`, `nonbinary`, `none` or `other`. `none` says the being has no gender; an absent field says its gender is unrecorded.                                                                                                                                                                                                                                                                                        |
+| `data.species`                   | an Address                                              | The being's species, as a lore note.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `data.born`                      | string                                                  | When the being was born — a date, or `unknown` where the birth is unrecorded. Absent, the being was never born.                                                                                                                                                                                                                                                                                                                     |
+| `data.calendar`                  | an Address                                              | Calendar used to display this being's dates.                                                                                                                                                                                                                                                                                                                                                                                        |
+| `data.died`                      | string                                                  | When the being died — a date, or `unknown` where the death is unrecorded. Absent, the being is alive.                                                                                                                                                                                                                                                                                                                               |
+| `data.age`                       | string                                                  | Age in years, stated only to override what `born` says — `34`, or `~34` for an estimate. Unstated beside a dated `born` it is computed; unstated beside an unknown or absent `born` the age is unknown.                                                                                                                                                                                                                             |
+| `data.ageYears`                  | number                                                  | Written by the compiler beside an `age` estimate — the `~` stripped, the magnitude alone. A note never authors this.                                                                                                                                                                                                                                                                                                                |
+| `data.height`                    | metres or feet and inches                               | Height in metres or feet and inches.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `data.weight`                    | kilograms or pounds                                     | Body weight in kilograms or pounds.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `data.frame`                     | string                                                  | Relative frame — one of `scant`, `light`, `medium`, `heavy` or `massive`.                                                                                                                                                                                                                                                                                                                                                           |
+| `data.appearance.eye_color`      | string                                                  | Eye colour.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `data.appearance.hair_color`     | string                                                  | Hair colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `data.appearance.skin_color`     | string                                                  | Skin colour.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `data.appearance.complexion`     | string or list                                          | The skin's condition — one value, or several, because a face carries more than one at once. A single value means a list of one.                                                                                                                                                                                                                                                                                                     |
+| `data.appearance.extra_features` | list                                                    | Anything else a stranger would notice.                                                                                                                                                                                                                                                                                                                                                                                              |
 
 **System mappings**
 

package/engine/actor-compiler.mjs

@@ -56,6 +56,7 @@ import { emitDiagnostic } from "./diagnostics.mjs";
 // The `{#appearance}` / `{#dossier}` convention is the note format's, so the
 // extraction is shared; which field a section lands in stays the system's.
 export { extractAnchorSection, renderSection } from "./anchored-sections.mjs";
+import { misplacedAnchorSection } from "./anchored-sections.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { beingDefaultArt } from "./art-fields.mjs";
 import { contentPackage } from "./content-package.mjs";
@@ -472,6 +473,28 @@ export class SystemActorCompiler extends BasePackCompiler {
         return { img, token: this.artPath(fm, "tokenIcon") ?? img };
     }
 
+    /**
+     * Report an `{#appearance}` or `{#dossier}` anchor on a heading
+     * {@link extractAnchorSection} cannot read, rather than letting the field
+     * it feeds compile blank with nothing to say why.
+     *
+     * @param {string} body - The note body.
+     * @param {string} anchorId - `"appearance"` or `"dossier"`.
+     * @param {string} ctx - The actor's label, for the message.
+     * @returns {void}
+     */
+    checkAnchoredSection(body, anchorId, ctx) {
+        const misplaced = misplacedAnchorSection(body, anchorId, this.currentNote?.bodyLine);
+        if (!misplaced) return;
+        this.noteError(
+            `${ctx}: {#${anchorId}} sits on a heading below the top level, and only ` +
+                `an H1 feeds the ${anchorId} field — move the heading to the top level ` +
+                "or drop the anchor",
+            { line: misplaced.line },
+        );
+        this.errorCount++;
+    }
+
     /**
      * Which `(actor, subType:identity)` each resolved entry claimed, and the
      * entry that claimed it first.