@heroiclands/package-build 22.21.0 → 22.22.0

package/docs/configuration.md

@@ -1462,6 +1462,7 @@ packageBuild:
 | [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
 | [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
 | [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.baseStyles`](#packagebuildbasestyles)                                       | boolean                                     | no       | `true`                                                     |
 | [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
 | [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
 | [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                                       |
@@ -1475,7 +1476,7 @@ packageBuild:
 | [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
 | [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
 
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
@@ -1561,6 +1562,31 @@ repository has to compute. Neither declares anything, both default to
 
 > ``package-build config: `packageBuild.manifestFlags` must be a non-empty string.``
 
+### `packageBuild.baseStyles`
+
+Whether the package takes the shared base stylesheet. It defaults to `true`,
+is staged to `styles/package-build-base.css` under the stage root, and is
+named first in the generated manifest's `styles`.
+
+The sheet carries only what every package's compiled content relies on to be
+legible — the definition-list style an infobox and the markdown `Term` /
+`: definition` syntax both emit — and is scoped to the journal, enriched-field
+and editor containers so it cannot reach Foundry's own interface.
+
+It loads into the cascade layer Foundry reserves for the package kind,
+`system` or `modules`, which is the weakest layer a package can occupy. A
+package overrides any rule in it from its own stylesheet, whether that sheet
+names a layer or none at all, with no specificity contest and no
+`!important`. The term column, the gutter and the width at which the list
+stacks are custom properties — `--pb-deflist-term-width`,
+`--pb-deflist-gutter` and `--pb-deflist-row-gap` — so a package adjusts them
+without copying the rule.
+
+Declare `false` to decline it; nothing is staged and nothing is added to
+`styles`:
+
+> ``package-build config: `packageBuild.baseStyles` must be true or false.``
+
 ### `packageBuild.manifest`
 
 `packageBuild.manifest.title` is a required, non-empty string for a Foundry

package/docs/content-format.md

@@ -31,7 +31,9 @@ Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
 `{allow-empty=true}` are examples. Inline font glyphs use the package's icon
 registry, as in `:icon warning:{size=lg}`; image icons use asset Addresses.
-`:::info` and `:::warn` add labelled boxes within the prose. The
+`:::info` and `:::warn` add labelled boxes within the prose. A
+`pagelist` fence renders the pages carrying a tag as a list of links, so a
+landing page states a group by intent rather than enumerating it. The
 [links and markup guide](authoring/links-and-markup.md) gives the complete syntax.
 Footnotes use `[^id]` references and `[^id]:` definitions, with numeric output
 markers scoped to each note. Definition lists use a term followed by one or

package/docs/guides/reference-pages.md

@@ -45,6 +45,21 @@ WHERE type = 'affiliation'
 ```
 ````
 
+Where the page introduces a _group_ rather than a type, a `pagelist` fence
+states the group by its tag and lists the pages carrying it:
+
+````markdown
+```pagelist {tag="key-concept" descriptions=true}
+
+```
+````
+
+That keeps the entry page true as notes are written: a page joins the list by
+carrying the tag, so nobody has to remember to add it here. A tag no page
+carries is a build error naming the tag. See
+[page lists](../authoring/links-and-markup.md#page-lists) for the attributes it
+takes.
+
 `data.pack: none` is appropriate when the page belongs on the site and in the
 index but does not need a Foundry compendium entry. A documentation package
 has no packs at all. A page with an empty body is a stub: it remains in the

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` 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)
+`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.
+
+| 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:
 
@@ -2529,31 +2663,41 @@ data:
 
 #### The bodies a being belongs to, and its standing in each
 
-**Membership**: `{rank: number, office: string}`, both optional.
+**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 optional keys and nothing else:
+An entry carries two keys and nothing else:
 
-- **`rank`** — 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`** — a **string**, matched against the keys of that body's
+- **`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.
 
-An entry with neither is valid and is the ordinary shape: it says the being
-belongs to the body and nothing more.
+**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: {}
+    affiliation-silverguild: { rank: 0 }
 ```
 
 Both values are checked against the body the entry is keyed by. A `rank` that
@@ -2942,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:
@@ -3620,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 }
@@ -3869,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.
@@ -41,9 +58,9 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `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`, a level on that body's own ladder, and `office`, a post that body names.                                                                                                                                                                                                                                                    |
+| `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                                                  | `male`, `female` or `other`.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -52,11 +69,11 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `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.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                                                  | Complexion.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `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.

package/engine/anchored-sections.mjs

@@ -15,8 +15,8 @@
  * **Anchored body sections** — the `# Heading {#anchor}` convention, and how a
  * compiler pulls one section out of a note's prose.
  *
- * The content format gives three anchors a document meaning: `{#appearance}`,
- * `{#dossier}` and `{#spoilers}`. *Which field* each lands in is a system's
+ * The content format gives two anchors a document meaning: `{#appearance}` and
+ * `{#dossier}`. *Which field* each lands in is a system's
  * business — SoHL writes the first to an actor's `appearance`, HM3 to an
  * actor's and an item's `description` — but *finding* it is not, so the
  * extraction lives here where every compiler reaches it.
@@ -30,6 +30,8 @@
  */
 
 import { renderFoundryMarkdown } from "./helpers.mjs";
+import { collectAnchors } from "./anchors.mjs";
+import { splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
  * Extract the body of an H1 section whose heading carries the explicit
@@ -39,6 +41,11 @@ import { renderFoundryMarkdown } from "./helpers.mjs";
  * heading exists. Fenced code blocks are respected so `# foo` inside
  * ``` blocks does not trigger a match.
  *
+ * An anchor declared on a lower heading is found by {@link collectAnchors}
+ * but not by the `#\s+` match below, so it extracts as absent rather than as
+ * wrong — {@link misplacedAnchorSection} is the check a caller runs first to
+ * tell the two apart.
+ *
  * @param {string} body - The note body.
  * @param {string} anchorId - The anchor to find.
  * @returns {string} The section's markdown, or "".
@@ -57,8 +64,7 @@ export function extractAnchorSection(body, anchorId) {
         }
         const h1Match = !inCodeBlock ? line.match(/^\s*#\s+(.+?)\s*#*\s*$/) : null;
         if (h1Match) {
-            const anchor = h1Match[1].match(/\{#([^}]+)\}\s*$/);
-            const id = anchor?.[1]?.trim().toLowerCase() || null;
+            const id = splitHeadingAttributes(h1Match[1]).id.toLowerCase() || null;
             if (capturing) break;
             if (id === wanted) {
                 capturing = true;
@@ -81,3 +87,28 @@ export function renderSection(body, anchorId) {
     const slice = extractAnchorSection(body, anchorId);
     return slice ? renderFoundryMarkdown(slice) : "";
 }
+
+/**
+ * Where an `{#appearance}` or `{#dossier}` anchor sits on a heading below the
+ * top level, which {@link extractAnchorSection} cannot read.
+ *
+ * {@link module:engine/anchors.collectAnchors} finds the anchor at any
+ * level, because a lower heading legitimately starts a journal page. It does
+ * not feed an actor field: an H1-only extractor reads nothing from one, and a
+ * caller that trusts the empty result as "no such section" rather than
+ * "found, but unreadable" compiles a blank field with nothing to say why.
+ *
+ * @param {string} body - The note body.
+ * @param {string} anchorId - The anchor to check, case-insensitively.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{line: number}|null} The misplaced anchor's line, or `null` when
+ *   it is absent or already on an H1.
+ */
+export function misplacedAnchorSection(body, anchorId, bodyLine = 1) {
+    const wanted = String(anchorId).toLowerCase();
+    const found = collectAnchors(body, bodyLine).find(
+        (anchor) => anchor.slug.toLowerCase() === wanted,
+    );
+    if (!found || found.level === 1) return null;
+    return { line: found.line };
+}