@heroiclands/package-build 22.15.0 → 22.16.0

package/docs/content-format.md

@@ -1,4255 +1,76 @@
-## Content format: how a note becomes documents
-
-### Documentation
-
-Markdown generates a JournalEntry: content before the first H1 becomes its "Introduction" page, and each H1 begins another page. The document Address is `<package>-note-<note_type>-<shortcode>`.
-
-An **infobox** is prepended to the entry's first page, before the prose. It is
-not a page of its own: a page is what a Foundry UUID addresses, and a summary a
-reader has to navigate to is a summary they do not see. What the box holds, and
-where it sits in every other medium, is [the infobox](#the-infobox) below.
-
-**There are two kinds of infobox.**
-
-A **note infobox** summarises the subject itself, from `data:` — a scenario's
-length, party size and required archetypes; a place's subtype and its parent; a
-weapon's weight and value. None of that is SoHL or HM3 information, and it
-deserves a summary panel all the same. Any type that declares `data:` fields has
-one.
-
-A **system infobox** summarises what one system makes of the note, drawn from
-that system's block. There is one per system, and they are not alike: the two
-systems describe a weapon with different values for impact, heft, reach and draw,
-so neither box can stand for the other.
-
-**Which boxes appear is decided by the note type; what they say is decided by the
-note.** A type that both systems support always shows both system boxes, and a
-box whose system this particular note produces no document for reads
-**"Not available"**.
-
-| note type                                                             | system boxes shown                                 |
-| --------------------------------------------------------------------- | -------------------------------------------------- |
-| `weapon`, `skill`, `being`, `armorgear`, `containergear`, `miscgear`… | SoHL **and** HM3 — either may read _Not available_ |
-| `affiliation`, `affliction`, `attribute`, `concoctiongear`, `mystery` | SoHL only                                          |
-| `armorlocation`                                                       | HM3 only                                           |
-
-This is stated rather than inferred from an empty block, because an absence is a
-poor signal: noticing that something is missing requires already knowing it
-should have been there, and a reader meeting one page has no way to know. A box
-that says _Not available_ tells them outright.
-
-It also separates two facts that an absence would conflate. `Spear (thrown)` is
-HM3-only while spears plainly exist in SoHL — _that_ note has no SoHL form, and
-its SoHL box says so. HM3, by contrast, has no affiliations, mysteries or
-attributes **at all**; on those pages a box reading "Not available" would suggest
-a gap in the note when the truth is about the system's scope, so no HM3 box is
-drawn.
-
-The set of boxes needs no new declaration: the note-type → document-subtype map
-already records which systems each type reaches. Rendering one box per mapped
-system makes the page checkable — _every page carries exactly the boxes its type
-maps to_ is an assertion the build can make, so a missing infobox is a failure
-rather than something nobody notices.
-
-For web pages, the full Markdown body renders as HTML with its infoboxes.
-
-### The infobox
-
-**The infobox is generated content at a known position — prepended, before the
-prose.** It is not a floating sidebar and it is not defined in a rendering
-template. The toolchain settles what each box holds; each medium lays that out
-its own way.
-
-| medium  | placement                                              | collapsing                |
-| ------- | ------------------------------------------------------ | ------------------------- |
-| book    | flows in the column measure, breaking between sections | none, and none needed     |
-| website | side rail on wide screens, inline on narrow            | `<details>`, default open |
-| Foundry | inlined, the page being narrow                         | `<details>`, default open |
-
-Two columns are print-only. A scrolling page has no fixed viewport, so columns
-make a reader travel down and back up, and a narrow screen collapses to one
-column regardless.
-
-**Six rules hold in every medium.**
-
-1. **It is content in document order**, prepended before the prose. An image
-   authored before it appears before it.
-2. **It contains no image.** A picture is authored in the text with its own
-   directive, and its position governs.
-3. **A section is the unit that flows.** Sections are whole and unbreakable and
-   the panel breaks _between_ them, which is what lets a long box cross a
-   column or page boundary without splitting a stat grid down the middle.
-4. **An absent field is absent, not empty.** A row with no value is not
-   emitted, and neither is a section with no rows: a creature carrying no
-   equipment has no `EQUIPMENT` heading rather than an empty one. A placeholder
-   asserts a fact that is not there, and an empty heading asserts that something
-   was expected here and is missing. A corpus writes an absence three ways and
-   all three count: the key is omitted, it holds the field's own default, or it
-   holds a **sentinel** — `na`, `none`, `not applicable` — which is the same
-   absence written as a word. `Potency: Na` is not a fact about a potion.
-5. **A system box is never an empty panel; it says which silence it is.** Rule
-   4 governs rows, and a box is not a row — a heading over nothing asserts that
-   something should have been there. See
-   [the three states of a system box](#the-three-states-of-a-system-box).
-6. **Order is the toolchain's.** A medium renders boxes, sections and rows in
-   the order given.
-
-**Embedded models link to documentation in an infobox.** The model Address
-continues to identify the native Item used for compilation. Its displayed link
-uses that same package, type and Shortcode under `note`, which names the
-corresponding documentation journal. A model with no published documentation
-keeps its known name as plain text; the infobox does not substitute an Actor or
-Item link.
-
-#### What the note box holds
-
-**The note box's fields are the type's own `data:` vocabulary, in its declared
-order** — the very table each `### type:` section below states. There is no
-second list, so a key added to a type appears in the book, on the website and
-in a compendium journal with no further edit. A `Name` row stands first on
-every note, because every note has one.
-
-A few keys carry no row, and the reason in each case is one of exactly two —
-the key is **machinery**, steering a build or an interface rather than
-describing the subject, or it is an **image**, which rule 2 keeps out of the
-box:
-
-| key                      | why it carries no row                            |
-| ------------------------ | ------------------------------------------------ |
-| `templatePriority`       | template machinery, not a fact about the subject |
-| `color`                  | sidebar machinery, not a fact about the subject  |
-| the art slots, `overlay` | an image, which rule 2 keeps out of the box      |
-
-A field whose value is a **mapping** carries no row either — a governance
-ladder or a wall layout has no summary shape — and neither does one the note
-left empty.
-
-A being's `age`, `height`, `weight` and `appearance.*` compose into a single
-**Appearance** clause rather than taking six rows of their own: _Age 34, 6′ 1″,
-181 lbs, medium frame, brown eyes_.
-
-#### What a system box holds
-
-**A system box's fields are that system's own field declaration**, in its
-order. There is no second list here either, so a field added to a type reaches
-the box with no further edit.
-
-Two things keep a fact off it:
-
-- **A value the declaration would have supplied anyway.** A field answered by
-  its own default is a fact about the compiler, not about the note — and that is
-  true of the value, wherever it was written. A corpus writes its defaults out:
-  `improveFlag: false` and `combatCategory: none` are typed into hundreds of
-  notes that mean nothing by them.
-- **A fact the note box already put on the page.** A gear item's weight is
-  system-agnostic and belongs to the note. What counts is what the note box
-  _shows_, not what its vocabulary declares — the same fact is written under
-  `data:` on one note and at its destination path on another, and a system box
-  that stood down on the declaration alone would leave it on no surface at all.
-
-**A measured quantity carries its unit on its value** — `Price 160d`,
-`Weight 1.1 lbs`. The unit belongs to the quantity rather than to the name of
-the quantity, so it is not folded into the label: `Price (d)` beside `160` makes
-a reader reassemble one fact from two cells, and reads worst in the book, whose
-label column is a narrow small-caps rule. A medium cannot supply it either —
-appending `d` to a price means knowing which row is the price, which is the one
-thing a generic renderer must never know. A row carrying a unit is `text`,
-because a number with a unit is text for presentation.
-
-**What a field is called** is a **presentation overlay** on that same
-declaration, per system. It carries two things a compiler's field list cannot,
-because they are about a page rather than about a document: a reader's word
-where the declaration's key is the compiler's — `assocSkillCode` is exactly
-right in a DataModel and wrong in a panel somebody reads — and the handful of
-keys that belong on no page at all, either because the box shows the same fact
-whole somewhere else or because they steer a character sheet rather than
-describe the subject. It is an overlay and not a list: a field it does not
-mention still gets a row, under its own humanised name.
-
-Four types are read differently, because their box is derived rather than read
-field by field — a **being**, whose attributes, skills, mystical abilities and
-carried gear are one flat `sohl.items` list; **armour**, whose protection is
-shown for all four aspects with an unstated one rendered `0`; a **weapon**,
-whose strike modes are shown one per line with an unstated value rendered `—`;
-and a **projectile**, whose impact is three declared fields composing into the
-one quantity a reader wants. Both of those placeholders are decided by the
-toolchain and travel as data, so no renderer has to know which field it is
-looking at.
-
-A weapon's strike modes are authored either as a **list**, each mode carrying
-its own `shortcode`, or as a **mapping** keyed by the mode's name. Both are
-read, and both yield the same section.
-
-#### The three states of a system box
-
-A system box says something on every page that carries one. Which of the three
-it says is decided here and travels as the box's `statement`, so a medium draws
-one thing and decides none of it.
-
-| state          | when                                                       | what the box says                       |
-| -------------- | ---------------------------------------------------------- | --------------------------------------- |
-| content        | the system holds something the note box has not shown      | its sections, and no `statement`        |
-| not available  | the system maps this note's type but produced no document  | `statement: Not available`              |
-| nothing to add | the system produced a document holding nothing new to show | `statement: Nothing beyond the profile` |
-
-The third state is not the second. _Not available_ is a statement about this
-note — the system has no document for it, and a reader can act on that. A
-system that _does_ compile the note and holds only facts the note box has
-already given says so instead, because a reader told "not available" would go
-looking for a document that exists, and an empty panel tells them nothing at
-all.
-
-A system that does not map the note's type gets **no box**. A box reading
-_Not available_ on every affiliation page would suggest a gap in the note when
-the truth is about the system's scope.
-
-Whether a document was produced is the compile's own answer rather than a
-reading of the frontmatter. Three things must hold: the note must carry that
-system's block, its type must map to the system, and it must route to a pack of
-the document class that map names. The block is the first of them because a
-system block is what makes a game document — see
-[A system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
-A pack declaring **no** system is compiled by the fallback pass, which reads one
-system's block and no other, so the question is the same one whether or not the
-pack answered it.
-
-#### Four section layouts
-
-A section says how it is arranged, and a renderer switches on that and on a
-value's `kind` — never on a field name, which is what keeps a field list from
-leaking back into a template.
-
-| `layout` value | shape                           | what carries it | where it is used           |
-| -------------- | ------------------------------- | --------------- | -------------------------- |
-| `rows`         | label/value pairs, one per line | `rows`          | a profile                  |
-| `grid`         | short label/value cells         | `cells`         | attributes, armour aspects |
-| `runin`        | groups of comma-joined entries  | `groups`        | skills, equipment          |
-| `list`         | one entry per line              | `entries`       | mystical abilities         |
-
-| `kind` value | the value is                    |
-| ------------ | ------------------------------- |
-| `text`       | a string                        |
-| `number`     | a number                        |
-| `link`       | `{text, url?, uuid?, address?}` |
-| `links`      | a list of those                 |
-| `list`       | a list of strings               |
-
-A website renders a link by its `url`, a compendium journal by its `uuid`, and
-the book by the `address`, which is the entry's own label in the volume. A
-reference the index could not reach keeps its words rather than being dropped.
-
-**Emitted shape**, as a page's front matter carries it:
-
-```yaml
-infoboxes:
-  - id: note
-    kind: note
-    title: Profile
-    sections:
-      - id: profile
-        layout: rows
-        rows:
-          - label: Name
-            kind: text
-            value: Brànwâal Dôrgaar
-          - label: Affiliations
-            kind: links
-            value:
-              - text: The Silent Talon Company
-                url: /thalorna/affiliation-slntlncmpny/
-  - id: sohl
-    kind: system
-    system: sohl
-    title: SoHL
-    available: true
-    sections:
-      - id: attributes
-        label: Attributes
-        layout: grid
-        cells:
-          - label: STR
-            value: 14
-      - id: skills
-        label: Skills
-        layout: runin
-        groups:
-          - label: Combat
-            entries:
-              - text: Melee 75
-  - id: hm3
-    kind: system
-    system: hm3
-    title: HM3
-    available: false
-    sections: []
-    statement: Not available
-```
-
-### Frontmatter has three regions
-
-A HeroicLands note has opening YAML frontmatter with nonempty `shortcode` and
-`type` values. Other Markdown files are ordinary Markdown. A note's frontmatter
-has three regions:
-
-| Region               | Describes                                               | Unknown keys |
-| -------------------- | ------------------------------------------------------- | ------------ |
-| **Top level**        | The note's identity, name, description, and publication | An error     |
-| **`data:`**          | The subject itself, shared by systems                   | An error     |
-| **`hm3:` / `sohl:`** | The subject as one system's documents                   | An error     |
-
-The complete top-level allowlist, in its required order, is `shortcode`, `name`,
-`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Omit fields that
-do not apply. The first fields of a typical note look like this:
-
-```yaml
----
-shortcode: example
-name: { full: Example }
-type: lore
-subType: concept
-description: A short page description.
-tags: [draft]
-data: {}
-sohl: {}
----
-```
-
-Any other top-level key is an error. To keep an author-only note beside the
-content, comment out its YAML lines with `#`. Comments remain valid YAML text
-and do not become data in the JSONL index, generated pages, or Foundry documents.
-There is no custom site metadata. `description` supplies the page's short
-description; `tags` carries publication and classification tags.
-
-Arrays and objects use one-line YAML flow form when the complete line is under
-100 characters. At 100 characters or more, they use full block form. A multiline
-flow collection is formatted into one of those forms; folded collections are
-not used. `content-build format --write` applies this rule and the top-level
-order without changing the Markdown body.
-
-#### Dates and reckoning markers
-
-A calendar names and orders the days within a year. An **era** states where its
-year count begins. Several eras may use one calendar; each has its own origin.
-An era may declare a short, uppercase `marker` for authored dates. The marker
-selects that era and the calendar whose months interpret the date inside it:
-
-```yaml
-data:
-  born: VR(676/12/5)
-```
-
-`VR` is a marker declared on an era row of the Common Calendar. `VR(720/5/14)`
-means its year 720, fifth month, fourteenth day. `VR(720/5)` states month
-precision, and `VR(720)` states year precision. The parser retains that
-precision; it does not invent a first day when the author only knows a year.
-`VR(~-480)` keeps an approximate year. A date whose occurrence is known but
-whose value is not recorded is `unknown`, with no marker.
-
-The calendar-neutral spelling is `<year>.<day>[:HHMMSS]`: `720.136` names day
-136 of canonical year 720, and `720.136:143005` adds 14:30:05. The dot means
-**day of year**, not a month. Its day must fit the world's `data.year.days`,
-and its time must fit a 24-hour day. A bare year is also accepted. Unmarked
-slash dates are accepted as calendar-neutral numeric month/day values; their
-month division has no named calendar, so use a marker when the month is part
-of a people's reckoning.
-
-An era's `start` locates its first year on the canonical timeline. The marker's
-own start is written canonically, such as `start: 1`, so its definition has no
-circular reference. Another era may place its start using a marker already
-defined in the corpus. A year-precision start anchors the reckoning at the
-first day of that canonical year for conversion; it does not date the event
-that gave the era its name. A marker must be unique across the corpus and contain
-uppercase letters or digits, beginning with a letter. An optional `end` bounds
-dates in that era; a year-precision end includes the whole named year.
-
-**`data:` is closed.** It holds the type-specific facts about the
-subject — a weapon's weight, an affliction's transmission, a being's species —
-and every note type declares which keys it may carry. A misspelled key is a
-finding in either region.
-
-Every note type may put a pinned document id in `data.id`, a shared compendium
-route in `data.pack`, a shared folder Address in `data.packFolder`, and source
-details in `data.harnworld`. A system block's `pack` or `packFolder` overrides
-the shared value for that system. A `being` may also describe its social profile
-in `data.social`.
-
-**Tags are open, except the ones that classify.** A tag naming a theme or a region — `underworld`,
-`byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
-A tag that classifies the subject is different, because something queries it. A
-settlement tagged `village` appears in the list of villages and an untagged one
-does not, so `vilage` does not merely look wrong: it removes the note from an
-index, silently, and the index still renders. That is the same failure a
-misspelled `data:` key is, and it gets the same answer — the vocabulary
-is declared, so a near miss is a finding that names what you probably meant.
-
-| group               | applies to             | tags                                                                                                                                                                                                                                                                                                                                                    |
-| ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **place kind**      | `place` / `settlement` | `city`, `city-state`, `town`, `village`, `settlement`, `port`, `fortress`, `citadel`, `castle`, `stronghold`, `garrison`, `camp`, `oasis`, `waypoint`, `post`, `precinct`, `district`, `necropolis`, `hall`, `capital`                                                                                                                                  |
-| **place character** | `place`                | `fortified`, `temple`, `market`, `trading`, `merchant`, `mining`, `fishing`, `naval`, `military`, `imperial`, `provincial`, `coastal`, `river`, `lakeside`, `hill`, `mountain`, `valley`, `forest`, `woodland`, `inland`, `island`, `frontier`, `border`, `craft`, `caravan`, `pilgrimage`, `holy`, `sacred`, `free`, `ford`, `portage`, `pass`, `well` |
-| **place scale**     | `place` / `region`     | `continent`                                                                                                                                                                                                                                                                                                                                             |
-| **being station**   | `being`                | `tradesfolk`, `common-folk`, `soldiery`, `administration`, `clergy`, `mages`, `underworld`, `dependents`, `guilded`, `unguilded`                                                                                                                                                                                                                        |
-| **being kind**      | `being`                | `character`, `creature`                                                                                                                                                                                                                                                                                                                                 |
-| **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                                                                 |
-
-**`draft` is the one tag either build reads.** It does two things and nothing
-else: a link _into_ a draft note renders marked, and the note itself states that
-it is unfinished wherever a reader meets it.
-
-A link into it renders as
-`<span class="sohl-draft-link" title="Draft — not yet written">…</span>` in a
-compiled journal and on the website alike, with the appearance supplied by the
-consuming system's stylesheet or the site theme.
-
-The note's own statement is the **draft notice**, and it reads the same on every
-surface:
-
-> **Draft.** This entry is unfinished. What it states may change, and nothing in
-> it is settled.
-
-It leads the entry — above the infobox and above the prose — because a reader
-deciding whether to rely on an entry has to be told before they read it. Where
-it lands:
-
-| Surface      | What carries it                                                      |
-| ------------ | -------------------------------------------------------------------- |
-| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page       |
-| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`    |
-| The book     | a drawn mark and a left rule between the entry's plate and its panel |
-| The website  | the theme's own notice, above the infobox rail and the prose         |
-
-**An Actor carries it once.** A being's prose reaches two fields, and a document
-saying the same thing twice teaches a reader to skip it — a printed sheet draws
-both in turn — so the dossier carries the notice and the appearance is
-untouched. The two systems pair by the authored section each field reads rather
-than by its name, so `dossier` and `biography` carry it while `appearance` and
-`description` do not.
-
-**The mark is a notice, not a hazard** — `fa-circle-exclamation`, which Foundry
-bundles, so a journal page carries it with no module stylesheet loaded. The book
-draws its own, because a consumer declaring no icon family is the ordinary case
-and a glyph a face lacks is silent in Typst. Stripped of mark and rule the
-sentence still states the whole thing, which is the floor every surface is built
-to.
-
-**Nothing else changes**: the note compiles, validates, publishes and resolves
-exactly as any other, and it stays in the packs, in the link manifest and on the
-site. That is what separates the tag from the retired `draft:` field, whose whole
-effect was to move a note from published to unresolvable without saying so — and
-which is refused, by name, if you write it.
-
-**The group's scope is what makes the check work.** A group names the types it
-applies to, and a place's kinds are only ever checked on a place. Without that
-the rule is wrong on every note it touches: `azravan` on a faith, `barter` on an
-economy note and `secret` on three lore notes each sit a typo's distance from
-`caravan`, `border` and `sacred`, and none of them is a mistake. Scoped, the same
-corpus reports nothing — while a settlement tagged `vilage` is still caught, even
-beside a correct `town`.
-
-**Kind and character are separate because one slot could not hold both.** A
-fishing village is a `village` that is `fishing`, and the field this list
-replaced had to spell that `Fishing Village` as a value of its own — which is why
-a query for villages found two of the eleven that existed.
-
-**A station is not a rank.** Which kind of body a person belongs to — the
-clergy, the soldiery, the tradesfolk — is a different axis from where they stand
-inside one, which is what `data.lore` carries by naming the rank. A tag holds the
-first because a person may be several at once and because nothing ranks
-`clergy` against `mages`.
-
-**A continent is a region carrying a tag, not a subtype**, because structurally it
-is a region: the same fields, the same parent chain, everything but scale.
-
-#### A being's kind is the one tag group that is a slot
-
-A person and a beast carry very different amounts of data, and a being note says
-which it is with a tag rather than leaving it to be guessed from how much the
-note holds.
-
-| `beingKind` value | the subject is                                                                                                                                |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `character`       | a person — someone with a name, a station, a history, and the attributes, skills and carried gear that go with living a life                  |
-| `creature`        | a beast, a monster or a made thing — statted for what it does rather than for who it is, and usually carrying no equipment and no affiliation |
-
-**The slot is filled once, or not at all.** The two are alternative answers to
-one question, so a note carrying both has answered it twice and every reader of
-the tag gets to pick; that is refused as an error naming the note. A being
-carrying **neither** is not a finding. The kind is authored deliberately, and
-nothing can tell a being nobody has classified from one whose author means to
-leave it unclassified — a tree part-way through tagging is a tree with untagged
-beings in it, and failing its build would be a rule about the schedule rather
-than about the content.
-
-**Nothing else fills the slot, and nothing else is refused for failing to.** A
-being tagged `undead` or `beast-of-burden` is describing the subject in the
-author's own words, in a region that is open, and this build has no standing to
-take that back. What is refused is a near miss of one of the two — `charcter`
-drops the note out of every query for characters while the list still renders —
-and the two of them together. Those are the only two refusals a closed tag
-vocabulary can make here, and both are errors, so a build carrying one fails.
-
-**The same two words name two other things, and neither is this.** `hm3.type`
-takes `character` or `creature` as the HM3 _document_ a being compiles to, in a
-system block rather than in `tags:`. Both are also **retired note types**, so a
-note writing `type: character` is refused by name and told to write `being`.
-Three namespaces, one pair of words; the tag is the system-agnostic one, and it
-is the only one that describes the subject rather than a document.
-
-**Neither the book nor the website branches on the kind.** One flow serves both
-— the authored image, then the infobox, then the prose — and a creature's box is
-simply shorter, because it has less in it. A section with nothing to put in it is
-not emitted at all, so a creature with no equipment has no `EQUIPMENT` heading
-rather than an empty one, exactly as rule 4 of [the infobox](#the-infobox) drops
-a row with no value. The tag classifies the subject, which is what makes a list
-of the creatures in a setting a thing a query can ask for; it is not an
-instruction to a renderer.
-
-The mapping tables below describe the **document** destinations. A key that
-appears in no table still reaches the web page; it simply reaches no Foundry
-document.
-
-**The shared source is a default; the system block overrides it.** Where a field
-can be reached two ways — `data.weight` through the mapping table, or
-`sohl.system.weightBase` written directly — the value in the system block wins.
-`data:` says what is true of the thing in general; a system says what is true of
-it _there_, and a system that disagrees is not in error. A weapon weighs what
-`data.weight` says unless SoHL says otherwise, and then SoHL is right for SoHL.
-
-This is the same rule as `hm3.type` overriding a derived document type, applied
-to fields: derive from the shared source, and let the system state the exception.
-
-**A shared source and an in-block key are separate declarations.**
-`data.gender` is the shared source for HM3 gender; `hm3.gender` is its
-in-block spelling, and `hm3.system.gender` is the native destination.
-The native destination wins, followed by the in-block value and the shared
-source. Field declarations name both source and destination explicitly.
-
-**A field without a shared source reads its system declaration.** An
-`affiliation` item's `system.title` is the style of address an office carries;
-the note's heading reads `name.full`. The field reads
-`<system>.system.<field>` and the in-block position, which describe the
-document. Native species is independent of the shared lore Address in `data.species`.
-`subType` has the same meaning at both levels.
-
-**Some of a system's fields are runtime state, and a note may not write any of
-them.** A data model declares everything a document stores, and part of that is
-what _play_ writes: an affliction's `onsetDate` is the world time its onset
-fired at. Writing `<system>.system.<field>` reaches such a field as directly as
-any other — the block is a verbatim passthrough, and the field really is in the
-schema — so a note left free to stamp one ships that world's play state to
-every world that installs the compiled pack.
-
-So a field the document writes for itself is **declared as such**, and the
-declaration says both halves of the fact: authoring it is an error naming the
-note, the key and what the field holds, and the compiled document leaves the key
-out entirely so the data model's own initial value stands. This is a property of
-the field rather than a list of names, so it covers every such field a system
-adds later. The per-type tables below never list one — they are the vocabulary
-an author writes — and each type that has any names them under its table.
-
-**An `Address` becomes a `Shortcode` where the target field expects one.** SoHL
-resolves a stored cross-reference among the items one actor holds, and packages do
-not exist there, so the field holds a `Shortcode`. Four `affiliation` fields are
-authored as Addresses and stored that way: `data.seat` becomes `system.seat`,
-`data.parents` becomes `system.parents`, `data.domains` becomes `system.domain`,
-and each authored key of `data.relations` becomes a key of `system.relations`. The
-reduction happens at build time, and two things are errors naming the note: an
-Address whose type the field does not accept, and two Addresses that reduce to one
-shortcode, which the field cannot hold both of.
-
-**A SoHL skill Address becomes a native Item UUID.** An affiliation's
-`sohl.system.commonSkills` names skills in its own package or a declared
-dependency. Its `system.commonSkills` contains the exact published Item UUIDs,
-including each foreign module's own pack name. Native skill lookup uses those
-UUIDs; the journal, website and book use documentation links for presentation.
-
-**A `Code` suffix marks a different thing.** `system.assocSkillCode`,
-`system.assocAffiliationCode` and `system.parentSkillCode` hold a `Shortcode` at
-both ends — each is authored as one, under `<system>.system`, and emitted verbatim
-— so no Address is reduced into them and none of them has a shared source. A value
-carrying a separator is refused there by the shortcode charset rather than read as
-an Address. `data.assocSkill`, `data.assocAffiliation` and `data.parentSkill` are
-properties of the **page**: each is an Address naming the note an infobox row
-links to, and none reaches a compiled document.
-
-### The note vocabulary, and how it maps
-
-A note has its own `type` and `subType`. **This is a third vocabulary** — not
-SoHL's and not HM3's. It says what the note _is_ and the scope it covers,
-irrespective of whether it becomes an Actor, an Item, a JournalEntry or nothing
-at all in any particular system.
-
-Each system then declares a map from the note's `(type, subType)` onto its own
-document type — and, for SoHL, its own `system.subType`. The map is **declared**,
-never inferred from a coincidence of names: `skill`, `weapongear`, `armorgear`,
-`containergear` and `miscgear` exist in both systems with _different_ data
-models, so name-matching there would not fail, it would succeed wrongly.
-
-Because the map derives the document type, `hm3.type` and `sohl.system.subType`
-are **overrides**, not required declarations. A note states them only when the
-map cannot decide, or decides wrongly.
-
-**Four rows cannot decide, and there `hm3.type` is required.** HM3 splits four
-of the note vocabulary's types across several documents — `mysticalability` into
-a `psionic`, a `spell` or an `invocation`; `trauma` into an `injury` or a
-`trait`; `weapongear` into a `weapongear` or a `missilegear`; `being` into a
-`character` or a `creature`. Nothing in the note's own vocabulary partitions
-cleanly onto any of those splits, so the note says which, in its own block, and
-a note that says nothing is **an error naming the note and listing the permitted
-values**. It is never defaulted: a default would pick one and be right about
-half the time.
-
-A consequence worth knowing before you author a being's embedded items: a
-`(type, shortcode)` reference has no block of its own to read a discriminator
-from, so it **cannot address a one-to-many type**. `[[weapongear-spear]]` names
-no single HM3 document, and the reference is refused rather than resolved to
-whichever came first.
-
-A note whose `(type, subType)` has no mapping for a system it carries a block
-for is an **error naming the note**, never a silent skip and never a guess at the
-first matching value. Where a mapping is missing for a whole class of note, that
-is a gap in the vocabulary rather than something to write into every note: an
-override that thousands of notes need is a missing subType value.
-
-**A type's `subType` values are stated in one shape**, so that they can be read
-and compared to the vocabulary that enforces them. Under the type's
-heading, write `**subType**:` on a line of its own, then one bullet per value —
-`- <value>` or `- <value>: <definition>` — and nothing else between the marker
-and the list. A type that has no `subType`, or whose values are not enumerated
-yet, writes no marker at all. Any other spelling is a build error naming the
-line: five were in use, and a reader that accepted them all would keep accepting
-the sixth by reading a section as declaring nothing, which is exactly the drift
-the comparison exists to catch.
-
-### Mappings every type shares
-
-Eight rows were identical in all sixteen tables below, so they are stated once
-here and omitted there. Each per-type table shows only what is particular to that
-type.
-
-| shared source           | → sohl                    | → hm3                        |
-| ----------------------- | ------------------------- | ---------------------------- |
-| `name.full`             | `name`                    | `name`                       |
-| `data.icon`             | `img`                     | `img`                        |
-| `data.id`               | `_id`                     | `_id`                        |
-| `data.packFolder`       | `folder`                  | `folder`                     |
-| `shortcode`             | `system.shortcode`        | NA                           |
-| `data.templatePriority` | `system.templatePriority` | `flags.hm3.templatePriority` |
-| `actionDefs`            | `system.actionDefs`       | NA                           |
-| `notes`                 | `system.notes`            | `system.notes`               |
-
-**A column reads NA wherever the type produces no document in that system.** An
-`affiliation` has no HM3 form, so its whole HM3 column is NA; `armorlocation` has
-no SoHL form, so its SoHL column is. Nothing else varies — which is why these
-rows are worth stating once: repeated sixteen times they buried the differences
-that matter.
-
-**`data.icon` maps onto a document that has one, and not every type's does.**
-The row is shared because the key is legal on every note whatever its type, not
-because every document carries artwork: `doc`, `place`, `lore` and `scenario`
-compile into a JournalEntry, which has no image of any kind, and a `folder`
-compiles into a Foundry `Folder`, which has none either. A `homepage` compiles
-into no compendium document at all. On any of those the mapping has no
-destination, so the resolved value is simply dropped — the note validates, the
-tree compiles, and the value goes nowhere.
-
-**What a note writes is an address; what a document carries is a path.**
-`data.icon` is an `Address` defaulting to type `icon`, so a being writes
-`icon: anvil` and never a file name. The compiler resolves that address to the
-file the owning package ships and writes the resulting path into `img`. The two
-sides of this row are therefore in two different currencies, which is why the
-row reads `data.icon → img` rather than naming one thing twice.
-
-Since a dropped value looks exactly like a value never written, the frontmatter
-lint **reports it**: an art key authored on a type whose passes emit none is a
-warning naming the note and the key. A warning rather than an error, because the
-note still compiles correctly and the key is not certainly unwanted — a note's
-top level is the generated page's front matter as well, so a site template may
-read there what no document carries. `null` is never reported: that is the
-blessed way to say "this note names no art", and on a type with no art it is a
-true and harmless thing to say.
-
-Which types those are is **not a list**. It is asked of the passes: a type routes
-to a document, a document to the pass that compiles it, and each pass declares
-the art it writes (`emitsArt`). A second table of iconless types would be a table
-free to drift from what is actually emitted, which is the defect rather than the
-check.
-
-#### The four art slots
-
-A note declares the art its document needs, and every other image in it is
-inline. All four slots are ordinary `Address` fields declaring a default type,
-exactly as `seat` declares `place` — a bare shortcode takes its type from the
-declaration, and qualification climbs the same short-form ladder every other
-link uses.
-
-| field       | default type | accepts         | resolves into                | on                                        |
-| ----------- | ------------ | --------------- | ---------------------------- | ----------------------------------------- |
-| `icon`      | `icon`       | `icon`, `image` | `document.img`               | every Actor/Item type, and embedded items |
-| `tokenIcon` | `icon`       | `icon`, `image` | `prototypeToken.texture.src` | Actor types                               |
-| `bgImage`   | `image`      | `icon`, `image` | `background.src`             | map types                                 |
-| `banner`    | `image`      | `icon`, `image` | the site hero image          | any note; not a Foundry field             |
-
-All four are authored under `data:`:
-
-```yaml
-data:
-  icon: anvil
-  banner: packagebuild-none-image-skillbnr
-```
-
-**Every slot accepts a second type beyond the one it defaults to**, and the two
-defaults pair with the same accepted set: `icon` and `tokenIcon` default to
-`icon`, `bgImage` and `banner` default to `image`, and all four accept `icon`
-**and** `image` regardless of which one they default to. A bare shortcode still
-takes the slot's default — `icon: anvil` above names an `icon`, not an `image`
-— and it is a **qualified** value, one that states its own type, that the
-accepted set governs. `sohl-kethira-basic` writes an `icon` slot this way
-twenty times, once per faith tradition, because a deity's profile art is a full
-illustration rather than a game icon:
-
-```yaml
-data:
-  icon: image-kpagrik
-```
-
-That value is accepted because `image` is in the slot's accepted set, not
-because it matches the default — `icon` still defaults to `icon`. `audio` is
-refused at all four slots: a sound is not art, and a value naming one — `icon:
-audio-thunder`, say — is an error naming the set the slot accepts, never a
-silent fall back to the note's default art.
-
-**These properties are legal on _every_ note**, whatever its type. `data:` is a
-closed container and the per-type vocabularies below are the only lists there
-are, so a key legal everywhere is stated once here rather than repeated in
-twenty-five tables where the one that was mistyped would be the one nobody
-noticed:
-
-| shared `data` property | Values                 | Description                                                          |
-| ---------------------- | ---------------------- | -------------------------------------------------------------------- |
-| `id`                   | `string`               | A pinned document identity.                                          |
-| `pack`                 | `string`               | The shared compendium route.                                         |
-| `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
-| `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
-| `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
-
-`icon` is legal everywhere because most types compile into a document that
-carries one; where a type's passes emit none, the lint says so and the value is
-left alone, because a page template may still read it. `banner` reaches no
-compiled document at all, and a page is what every note publishes.
-
-The other two are narrower, and each type's own table names them: `tokenIcon`
-on the Actor types, `bgImage` on a map.
-
-**A portrait is not one of them.** A picture of the subject is a picture, so it
-is authored in the prose that describes the subject, as an ordinary embedded
-image — see [the lead image](#the-lead-image). A slot exists for art a
-_document field_ needs; nothing else earns one.
-
-**A reference carries no slashes and no extension.** That is what keeps it from
-being read as a file name, and it is checked: a value shaped like a pathname is
-an error naming the note and the key.
-
-`tokenIcon` unset defaults to `icon`. A token has to read at grid scale and when
-a map is zoomed out, so it is an `icon` rather than an `image`, and its fallback
-has to be `icon`-typed too.
-
-Actor types (`being`, `vehicle`) therefore add one row:
-
-| shared source    | → sohl                       | → hm3                        |
-| ---------------- | ---------------------------- | ---------------------------- |
-| `data.tokenIcon` | `prototypeToken.texture.src` | `prototypeToken.texture.src` |
-
-An actor's two pieces of art are two different questions. `data.icon` is the
-profile art — what a directory listing shows beside the name and what the sheet
-header carries. `data.tokenIcon` is what a token on the canvas wears. Both are
-addresses and both resolve the same way; only the destination differs. An Item
-has one piece of art, so this row applies to actor types alone.
-
-**A `data:` source is still read at the top level, for now.** `data:` did
-not invent the facts it holds — it gathered them out of the top level — so every
-key it collected has a **pre-`data:` spelling** that is read after the declared
-one and reported as retiring. This is the shared level's counterpart to the
-in-block `<system>.<key>` retirement, and the two are separate: a note may have
-moved one and not the other.
-
-**No image key is one of those.** A top-level `img:` is not authored at all:
-`data.icon` is a different key holding a different kind of value, and a note
-writing `img:` is naming a file where an address belongs. `portrait:` is not authorable at any level; a portrait is an embed in the body.
-
-**Two of the eight are Item-only in SoHL.** `actionDefs` and `notes` are declared
-on every SoHL Item subtype and on no SoHL Actor, so on a `being` or a `vehicle`
-the SoHL column of both reads NA.
-
-`notes` is also the one row that is emitted rather than mapped: SoHL writes
-`system.notes` empty on every Item, and no note-level key fills it yet. The row
-states where such a key would land, which is what makes `armorlocation`'s
-exception below sayable at all.
-
-**A third SoHL Item mapping has no shared source, so it is not a row.** SoHL
-writes `system.docHtml` on every Item from the note's own prose — the UUID of the
-JournalEntry that prose compiled into, which is derived rather than authored.
-HM3's data model has nowhere to put such a pointer, so the same prose reaches an
-HM3 item only as its own journal.
-
-**One exception.** HM3's `armorlocation` declares no `notes` — it is the one
-subtype that extends the Foundry base directly with no templates — so `notes` is
-NA on both sides for that type, and its table says so.
-
-**And one divergence, tracked rather than specified away.** HM3 records a
-template priority on an Actor and not on an Item: `hm3/actors.mjs` writes
-`flags.hm3.templatePriority`, and HM3's Item pass writes no equivalent, so an HM3
-item compiled from a template note loses the fact that it is one
-The row states the mapping the format makes;
-the gap is in the pass, not in the table.
-
-#### A pathname names the package that owns the file
-
-A note names a file once, and four surfaces have to serve it: a Foundry
-install, this repository's own working tree, the website, and the book. Each
-addresses the same file differently, so an authored pathname is a **statement
-of ownership** and every surface derives its own address from it.
-
-**The first segment names the package, when an `assets/` follows it.**
-Everything after that `assets/` is the _suffix_ — the path inside the package's
-shipped tree, and the one piece every derived form is built from. A pathname
-that does not open `<package>/assets/` belongs to the package being compiled,
-and the whole of it is the suffix.
-
-```markdown
-![A map of the Vale](images/maps/valeofthorns.webp) <!-- this package's -->
-![A shield](sohl/assets/icons/noun/shield.svg) <!-- the sohl package's -->
-```
-
-The four forms, for a `thalorna` note (the `thalorna` package ships as the
-Foundry module `sohl-thalorna`) writing `images/map.webp`:
-
-| Surface     | Address                                                  |
-| ----------- | -------------------------------------------------------- |
-| **Foundry** | `modules/sohl-thalorna/assets/images/map.webp`           |
-| **Local**   | `assets/images/map.webp`                                 |
-| **Web**     | `https://cdn.heroiclands.org/thalorna/images/map.webp`   |
-| **Book**    | `assets/images/map.webp`, staged beside the Typst source |
-
-And for the same note writing `sohl/assets/icons/noun/shield.svg`, a file the
-system ships and this repository does not hold:
-
-| Surface     | Address                                                   |
-| ----------- | --------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`               |
-| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository  |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`  |
-| **Book**    | not carried — a build stages only what this package ships |
-
-**The package's name is not its Foundry id.** `thalorna` is what the content is
-called, what a note writes, and what the website serves it under.
-`sohl-thalorna` is what Foundry installs the module as, and it appears in the
-Foundry form alone. The two words are the same for `sohl` and for `hm3`, which
-is exactly why they are kept apart here.
-
-Which packages a build can resolve is derived from its configuration: its own
-`contentPackage`, every game system it compiles content for (`systems:`,
-`packs[].system`, `requiresSystem`, `relationships.systems`), and every package
-it declares under `relationships`, whose `contentPackage` names the content
-where that differs from the Foundry id. A pathname naming a package the build
-does not know still resolves on the website and in the book — those need only
-the name and the suffix — and has no Foundry address, which is refused rather
-than guessed.
-
-An art package that replaces another package's images can declare
-`packageBuild.assets[].bindsTo` on the relevant asset copy. Each file's basename
-then acts as a shortcode for the declared package and type. The related
-`relationships.requires[].contentIndex` supplies the address index; with that
-index enabled, an asset with no matching note is a located build error. See
-[asset bindings](configuration.md#packagebuildstagedir-and-packagebuildassets)
-for the configuration and cache requirements.
-
-**The host is configuration.** `site.assets` in `package-build.config.yaml` is
-the root the web form is joined onto, and a package-owned image on a page with
-none set is an error naming that key.
-
-**A pathname naming no package at all passes through on every surface** — an
-absolute URL, a `data:` URI, a protocol-relative `//host/…`, or a `/`-rooted
-path, which Foundry serves from its data root. That is how a note addresses
-core Foundry art (`/icons/svg/mystery-man.svg`) or a package this build knows
-nothing of (`/systems/dnd5e/icons/spell.webp`).
-
-**A `systems/…` or `modules/…` pathname is refused**, with a finding naming the
-replacement. It is a Foundry address written where an ownership statement
-belongs: it resolves for Foundry and for nothing else, because neither the
-website nor the book has any such directory. `systems/sohl/assets/ui/logo.webp`
-is written `sohl/assets/ui/logo.webp`, and `systems/hm3/images/svg/sword.svg` —
-where the package serves its pictures from its own root — is written
-`hm3/assets/images/svg/sword.svg`, because `assets/` is where a package's files
-sit in every derived form.
-
-`worlds/` is not a Foundry root for this purpose. A package may not ship files
-out of a world, so a note writing one has made a different mistake and gets the
-ordinary "this package owns it" reading — a plainly broken path rather than a
-plausible one that 404s with nothing reporting it.
-
-**The rule is about ownership, not a list of directories.** A package owns its
-whole `assets/` tree and the directory names inside it are its own business:
-`sohl-kethira-basic` keeps art under `assets/artwork/`, and `artwork/deity.webp`
-is that package's by the same rule that claims `icons/…` and `images/…`.
-
-**Where a pathname is still authored, it follows this rule.** That is the
-address of an image in a note's body, and a map note's `overlay`. The art
-fields do not: `icon`, `tokenIcon`, `bgImage` and `banner` name
-addresses, and the path comes from the record the resolved address points at —
-which already carries the owning package, so there is nothing for a first
-segment to state.
-
-#### `banner:` reaches no compiled document
-
-`data.banner` is the page's hero image, and it is the one art slot with no
-Foundry destination: searching a built `packs-json` tree for it turns up
-nothing. It reaches the generated page and the book's section plates, and
-nothing else.
-
-It is an `Address` all the same, defaulting to type `image`, so a section note
-writes `banner: skillbnr` and a note borrowing another package's plate writes
-`banner: packagebuild-none-image-skillbnr`. The resolved record carries the
-owning package, and each surface joins the suffix onto its own root — the site
-onto `site.assets`, the book onto the directory it stages banners into.
-
-**`banner: null` is how a note says it wants no plate.** It is a true statement
-on any type, and the frontmatter lint never reports it.
-
-#### The pack a note compiles into
-
-`data.pack` names which configured compendium receives the note's document.
-
-```yaml
-data:
-  pack: items-hm3
-```
-
-It is deliberately close to the retired `package:` and deliberately not the same
-word: `package:` said which _distribution_ owned a note — now the repository's
-`contentPackage`, and not authorable — while `pack:` says which
-_compendium_ receives its document.
-
-**It names the pack for the note's _own_ document.** A document derived from it
-— an item's prose compiling into a `JournalEntry` of its own — is not what the
-author was addressing, and is routed by the pass that produces it.
-
-**`<system>.pack` names the pack for one system's document.** Routing is per
-system: each block the note carries sends its own document where that block
-says, and a note carrying two blocks may place them in two packs.
-
-```yaml
-data:
-  pack: items-sohl
-hm3:
-  pack: items-hm3
-```
-
-**Unstated, a system's document goes to that system's default pack of its
-class** — the pack of the class declaring that `system:`, or, where none does,
-the pack of the class marked `default: true`. Where nothing answers, the build
-refuses rather than guessing, and names the candidates.
-
-**`pack` and `packFolder` are different questions.** `pack` names _which
-compendium_ receives a document; `packFolder` names the folder note whose
-address the document is filed under _within_ whichever compendium that is. They
-compose, and both are read per system, so a note may place its two systems'
-documents in different packs and different folders:
-
-```yaml
-sohl:
-  pack: characteristics
-  packFolder: none-folder-miscgear
-```
-
-**`pack: none` compiles the note into no document.** The note is walked,
-published as a page, present in the content index with an address and no
-Foundry UUID, and addressable by wikilink like any other; every pack compiler
-passes over it without a finding, and the check that reports a note nothing
-compiles says nothing about it. Write it on a page that belongs on the website
-and in no compendium — a page of developer documentation, a page about the
-package itself:
-
-```yaml
-shortcode: architecture
-type: doc
-subType: concept
-data:
-  pack: none
-```
-
-A link to such a note resolves everywhere the note is addressable. On the web
-it is an ordinary link to the page. In a compiled journal there is no document
-to open, so the reader gets the link's text as prose and no `@UUID` — the
-mirror of a link into a package that publishes documents and no pages.
-
-It is accepted only on a type whose **sole document is the JournalEntry its
-prose becomes** — `doc`, `place`, `lore` and `scenario`. On a type that
-compiles an Item, an Actor, a Macro, a Scene or an Adventure it is refused by
-name, because there it would drop the document the type exists to produce;
-the message names that document. It is read per system like any other
-`pack:`, so `<system>.pack: none` withholds one system's document while the
-shared declaration names a pack for the rest, and a configured pack may not
-be called `none`.
-
-Four declarations are refused, each with the reason:
-
-| written                                     | why it is refused                                                                            |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| a **companion** pack                        | A companion is written by another pack's pass, so no note may be routed into one.            |
-| a pack **nothing answers to**               | The message lists the configured packs of that document type.                                |
-| a pack of **another document type**         | A note's `pack:` names a pack of its own document type.                                      |
-| **`none`** on a type with a second document | The Item, Actor, Macro, Scene or Adventure the type compiles into would be dropped, by name. |
-
-#### Template priority: which template wins
-
-A note can mark its document as a **starting template** the Create dialog offers
-to clone from, so a new being or item is born populated rather than blank. The
-value is a **priority**, and the priority is the whole mechanism — it decides
-which of several competing templates a player is actually offered.
-
-The shared mapping table above names it `data.templatePriority`, targeting
-`system.templatePriority` in SoHL and `flags.hm3.templatePriority` in HM3.
-
-> **`archetype` is the retiring spelling.** It is still read, in the `sohl:`
-> block and at the top level, so a tree sweeps on its own schedule
-> — but the frontmatter linter refuses it, and
-> what is compiled and emitted is `templatePriority` on all three sides.
->
-> It is more than a rename, and the collision is **already live** rather than
-> pending: `archetypes` is specified above as the _sort_ a character is, and a
-> being's row declares it. So a number deciding which template wins and a list of
-> what sort of character this is would otherwise be distinguished **only by a
-> plural `s`**.
->
-> A note carrying both spellings with **different** values is refused rather than
-> resolved quietly — `templatePriority: null` and `archetype: 0` say opposite
-> things, and picking either silently would decide it on the author's behalf.
-
-```yaml
-data:
-  templatePriority: 0 # a template, at the priority SoHL's own ship at
-```
-
-```yaml
-data:
-  templatePriority: null # not a template
-```
-
-**Every note SoHL compiles into an Item or an Actor must state it.** Absent, the
-build refuses: "not a template" has to be _said_, not left out, or an omission
-and a decision look identical. The value is a number or `null`, and **`0` is a
-real priority** — the one SoHL's own templates ship at — not an absence.
-
-**Where it lands differs by system, because HM3's data model has no field for
-it.** SoHL records it in `system`; HM3 keeps it under its own flag scope,
-`flags.hm3`, and a note that is not a template writes nothing there rather than a
-`null` nothing reads. Both HM3 Item and Actor passes write their own flag when
-the note declares a priority.
-
-**How a winner is chosen.** Opening a Create dialog gathers every candidate
-across the world and every matching compendium, _including other modules'_. Those
-are filtered to the `(type, subType)` being created, deduped by **`shortcode`** —
-a template's stable identity, where the name is only presentation — and one
-winner is taken per shortcode:
-
-1. the highest priority;
-2. then the nearest source — **world**, then **system**, then **module** — so a
-   GM's own copy shadows a shipped one at equal priority;
-3. then a stable UUID, so the answer never depends on load order.
-
-**The reserved ranges make a collision predictable.** Two packages can easily
-ship a template under one shortcode, and the number says which yields:
-
-| priority   | reserved for               |
-| ---------- | -------------------------- |
-| `0`–`98`   | SoHL and HM3 themselves    |
-| `99`–`999` | other HeroicLands packages |
-| `1000`+    | everyone else              |
-
-HeroicLands reserves everything below `1000`. Since the highest priority wins,
-**anyone else's template always beats content shipped from here** — which is the
-point: a module author can override a standard template without coordinating with
-anybody, and be certain it takes effect.
-
-#### The document id
-
-A note's Foundry `_id` is **derived from its canonical address**, and no note
-needs to write one:
-
-```yaml
-type: miscgear
-shortcode: bowlcer
-# no `id:` — the document is filed under makeId("document", "sohl-none-miscgear-bowlcer")
-```
-
-The derivation is exactly:
-
-```
-_id = makeId("document", "<package>-<system>-<type>-<shortcode>")
-```
-
-— the note's canonical address, hashed with SHA-1 and truncated to the 16 hex
-characters a Foundry id is. Nothing else feeds it.
-
-**One type hashes under a different namespace, and a consumer must not assume
-otherwise.** A `Folder` is a document of its own class, and its id is
-`makeId("folder", <address>)` — a separate namespace so that a folder and an
-item sharing a shortcode cannot derive one id, which Foundry would not report
-because it keys folders and documents in separate collections. See
-[`type: folder`](#type-folder).
-
-**So the id is transported, not recomputed.** The content index publishes an
-`id` on every entry it gives an identity to, beside the `uuid` that identity
-ends in, and both are computed by whatever owns that entry's derivation — the
-folder pass for a folder, the journals pass for a documentation journal, this
-rule for everything else. Re-deriving one from the `canonical` key alone reads
-correctly and is wrong for a folder, and wrong in a way nothing outside the
-build can detect: the result is a plausible 16-character id that resolves to
-nothing.
-
-**The Address determines the default id.** `content-lint` refuses a duplicate
-Address across the packs of a document type, so the derived id shares that
-uniqueness scope. An author pins a document's identity with `data.id` when it
-must remain stable across an Address change.
-
-**An authored `data.id` wins**, and that is how a document's identity is
-**pinned**:
-
-```yaml
-shortcode: bowlcer
-type: miscgear
-data:
-  id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
-```
-
-A blank `data.id:` is not a pin — it is a deleted value with the key left behind, and
-is treated as absent.
-
-**A rename moves the id, and that is the trade.** The address carries the
-shortcode, so renaming a shortcode gives the document a new `_id`. Two things
-make that acceptable: a shortcode rename already breaks every wikilink to the
-note, so it is a breaking change either way; and a note that must keep its
-identity across one pins its `id`, which is what the pin is for. One diagnostic
-narrows — `content-build` tells a **rename** from a **withdrawal** by matching
-document ids across releases, and for an unpinned note both sides now move
-together. It never reports a _wrong_ successor, and it stays exact for a pinned
-note; for the rest, the diff reports the vacated address.
-
-**A note with no address gets no id, and no document.** `type` and `shortcode`
-are what a note is addressed by, so a note missing either cannot be filed and
-the build refuses it by that name rather than by a missing `id:`.
-
-#### Address changes
-
-`(type, shortcode)` is a published interface. Other packages can link to it or
-use it as an Item model, so changing either part requires those references to
-change too. `content-build addresses diff` compares the package with a released
-baseline and reports addresses whose published documents are absent. A pinned
-`data.id` preserves document identity across a shortcode change; it does not
-keep the old address available for links.
-
-#### The compendium folder
-
-A note says which folder of its pack it lands in:
-
-```yaml
-data:
-  packFolder: poisonsandtoxins # a folder note's address
-```
-
-**`packFolder` is a folder note's address** — an ordinary address, resolved the
-way every other reference is, and written in any form [the grammar
-admits](#shorter-forms). The field supplies the type, so a bare shortcode is a
-complete address here; `folder-poisonsandtoxins` and the fully qualified
-`sohl-none-folder-poisonsandtoxins` name the same folder. An address no folder
-note answers to is a build error naming the folders the package does declare.
-
-Note this is the _pack_ folder, not the note's directory. The directory is
-`file.path` / `file.folder`, which a content table reads separately.
-
-**Where a folder materialises is derived from what references it.** Every pack
-holding a document that names a folder gets that folder, and its ancestors with
-it — so a documentation journal is filed beside the item it describes without
-the journals pack having to declare anything. A folder nothing references
-materialises nowhere.
-
-One folder note and one Address supply every pack that references it.
-`data.packFolder` names a folder by Address. A top-level `folder:` key is
-refused with a finding that names `data.packFolder` and the authored line.
-
-#### The knowledgebase category
-
-`kbcat` names the group a note is listed under on the knowledgebase and the
-website. It is written in the system block:
-
-```yaml
-sohl:
-  kbcat: poisontoxin
-```
-
-**It compiles into no document.** No pack compiler reads it and no `system`
-field receives it. It reaches a published page because a note's frontmatter is
-copied onto that page, where a list layout groups by `sohl.kbcat` — so `kbcat`
-is the one key in this section that answers _where does this appear_ for the
-web rather than for Foundry. `pack` and `packFolder` place a document in a
-compendium; `kbcat` places a page in a list.
-
-That is also why it is specified here rather than in a type's table. A type's
-fields say what the **builder** compiles, and `kbcat` is never compiled — but
-what a note **may write** is broader than what any one consumer reads, and a
-check that equated the two reported thousands of correctly authored properties
-as unknown.
-
-**It is editorial, and deliberately independent of `subType`.** The two are not
-alternative spellings of one classification and neither is derived from the
-other. `kbcat` both _subdivides_ a subtype — `trauma`/`physcond` is listed as
-`physdisability`, `physfeature` or `physprivations` — and _renames_ one for
-display, as `trauma`/`fear` listed under `phobias`. Most notes that carry a
-`kbcat` declare no `subType` at all. So the two are stated separately where both
-apply, and a reviewer should not read a disagreement between them as an error.
-
-**The value is free-form, and nothing validates it.** There is no configured
-list of categories. The frontmatter check knows `kbcat` is a key every type may
-write and says nothing whatever about its value. A layout supplies display
-titles and an explicit order for the values it knows about, and appends any
-other value as its own group, titled by humanizing it.
-
-The consequence is worth stating plainly, because it is the failure mode this
-key has: **a misspelled category is not a build error and is not dropped — it
-silently becomes a group of one**, sorted in after the known ones.
-
-**A note that writes none is dropped from the list entirely.** Grouping is by
-the key, so a page carrying no value falls in no group and is absent from the
-list page — not listed last, not listed under a fallback heading, absent, with
-nothing reported at either build. Every note of a listed type in SoHL's tree
-carries one today, and nothing in this package enforces that; the content index
-is where the question _which notes carry no `kbcat`?_ is answered.
-
-**It is also what a content table sections on.** `sohl.kbcat AS _section` in a
-`sql` fence is the ordinary case of _Content tables_ below, and the same
-free-form value decides the headings there.
-
-### Addresses
-
-Three types name one thing from another in a content tree, and they are not
-lengths of one another:
-
-| type        | written                                      | where it is met                                             |
-| ----------- | -------------------------------------------- | ----------------------------------------------------------- |
-| `Address`   | `<package>-<system>-<note_type>-<shortcode>` | a frontmatter field, a `model:`, an art slot, a link target |
-| `Shortcode` | `<shortcode>`                                | a note's own identity, and a key a runtime resolves by      |
-| `Wikilink`  | `[[<Address>[#<anchor>]\|<text>]]`           | body prose                                                  |
-
-An **`Address`** is the tuple below, and it is what every field typed `Address`
-in the tables that follow holds. It is equally what a `model:` names, what an art
-slot points at and what a wikilink resolves through — so an address is the thing
-being named, and the brackets around one in prose are a separate matter. Three
-rules govern it, and the first three subsections below state them in turn: the
-tuple is read by position, any suffix of it may be written, and each omitted
-segment is supplied by a default the position declares.
-
-A **`Shortcode`** is one segment, and nothing expands it — see _A shortcode is
-one segment, and nothing expands it_ below.
-
-A **`Wikilink`** is the prose form, which contains an Address — see _Wikilinks_
-below.
-
-#### The canonical address
-
-```text
-<package>-<system>-<note_type>-<shortcode>
-```
-
-The final segment is the shortcode, preceded by the note type, the system and
-the package. Each segment has one position. The system says which kind of target
-is named:
-
-| system        | target                                                                      |
-| ------------- | --------------------------------------------------------------------------- |
-| `note`        | Readable note content: a web page, a book entry, or a Foundry JournalEntry. |
-| `none`        | A systemless target such as an asset, Folder, Macro or Scene.               |
-| `sohl`, `hm3` | A game system's Actor or Item document.                                     |
-
-A note can publish more than one Address. A `being` note, for example, publishes
-`thalorna-note-being-bctrncml` for its readable content and
-`thalorna-sohl-being-bctrncml` for its SoHL Actor. An item note follows the same
-pattern for its page and Item. The type segment remains the authored note type
-in each Address.
-
-#### Shorter forms
-
-Authors may omit segments from the left. The complete Address states all four:
-
-| form                            | expands to                                               |
-| ------------------------------- | -------------------------------------------------------- |
-| `package-system-type-shortcode` | itself                                                   |
-| `system-type-shortcode`         | `<this package>-system-type-shortcode`                   |
-| `type-shortcode`                | `<this package>-<this position's system>-type-shortcode` |
-| `shortcode`                     | as above, with the type from the field's declaration     |
-
-There is no `package-type-shortcode` form. A reference to another package states
-its system as well as its package.
-
-#### Authored references and generated references
-
-Authored notes may use any permitted suffix. Builds leave source bytes unchanged.
-Generated content indexes, SQL records, site frontmatter and generated
-Wikilinks contain complete Addresses. For example, `data.parents: [north]` in
-`thalorna` emits `data.parents: [thalorna-note-place-north]`.
-
-SQL queries compare Address-valued fields to complete Addresses. A note's
-`shortcode` is a distinct identity component, so it is not equal to an Address
-stored in `data.parents`, `data.domains` or a governance rank's `lore`. Use the
-target's complete identity for that comparison. A stub has no published page
-address; its note identity still contains the package, system, type and shortcode.
-
-The toolchain holds parsed Addresses as complete tuples internally. Address-keyed
-relation maps hold typed targets and standing values. Only generated output
-serializes these properties to Address strings. Runtime Shortcodes, Foundry
-UUIDs, file paths and URLs keep their own representations.
-
-An Address-valued `data:` field must name a target in this package or a declared
-dependency index. `content-build lint` reports a missing target at the value or
-map key that names it. A stub counts as a target for data even though it
-publishes no page. Art slots use their own missing-art warning and document
-fallback.
-
-#### An omitted segment defaults from where the link is written
-
-An omitted segment is a default, not a wildcard. Every short form expands to one
-complete Address before lookup.
-
-- **Package:** the current package. A short address never falls through to a
-  dependency.
-- **System in `[[link|text]]`:** `note`, for every note type. Use an explicit
-  game system to name its Actor or Item, or `none` to name a systemless target.
-- **System in `![[link|text]]`:** `none`. An embed names an image or icon asset;
-  it also supplies `image` as the type of a bare shortcode.
-- **System in frontmatter:** a system block such as `sohl:` or `hm3:` supplies
-  its game system. Other Address fields default to `note`, except fields
-  declared for images, icons or folders, which default to `none`.
-
-For example, `[[macro-autoattack|Automated Attack]]` names the readable macro
-note, while `[[none-macro-autoattack|Automated Attack]]` names the Foundry Macro.
-`![[icon-anvil|Anvil]]` names the systemless icon asset.
-
-**A complete Address is lowercase throughout.** Every segment — package,
-system, type and shortcode alike — contains only lowercase ASCII letters and
-digits (`^[a-z0-9]+$`). Declared Address fields reject uppercase segments.
-A model reference accepts mixed-case Shortcodes and resolves their lowercase
-Address identity; this does not change a native embedded item's Shortcode.
-
-**Parsing is positional counting from the right, and nothing else.** Every
-segment is lowercase alphanumeric — shortcodes, **types** and **subTypes** are
-all `^[a-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
-`^[a-z0-9]+$` too — so the hyphen is purely a separator. There is no longest-match
-against a roster and no vocabulary check before splitting.
-
-**`type` and `subType` are held to that charset, not merely expected to meet
-it**. A type is the first segment of every address, so a hyphen in one is
-read back as a segment boundary that was never meant as one. A `subType` reaches
-no address, sections being retired, but it is held to the same rule all the
-same: it is a vocabulary term the whole toolchain keys on, one closed set away
-from being an address again, and a charset that holds for two of the three
-segments and half of a fourth is a rule nobody can state. Both are checked
-against the same constant a shortcode is checked against, and a note carrying a
-hyphenated value is reported where it wrote it:
-
-```text
-Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not a well-formed subType — a subType is lowercase letters and digits only (^[a-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. It is a vocabulary term the whole toolchain keys on, and one closed set away from being an address segment again, so a charset that held for every term but this one would be a rule nobody could state in a sentence
-```
-
-The `doc` subType is **`userguide`**. A hyphenated `user-guide` is refused by
-the shared charset check. Shortcodes likewise contain only lowercase letters
-and digits, preserving one unambiguous Address grammar.
-
-`type/shortcode` with a slash is accepted. A slash is _unconditionally_ an
-address separator — pipe or no pipe — so an unknown type before one is an error
-rather than something to guess at.
-
-#### A shortcode is one segment, and nothing expands it
-
-A **`Shortcode`** is a single segment of the same charset an address segment is
-held to, and it is a type of its own rather than the shortest `Address`. It
-names a thing's identity, or it is the key something resolves by where the other
-three segments have nothing to say:
-
-| where a `Shortcode` is written               | what it names                                                                       |
-| -------------------------------------------- | ----------------------------------------------------------------------------------- |
-| a note's own `shortcode:`                    | the note's identity — the name every address of it is built from                    |
-| a custom embedded entry's `system.shortcode` | that entry's identity within the actor that holds it                                |
-| an emitted `system.relations` key            | the other body this one has a standing towards                                      |
-| a mystery's `skillAptitudes` keys            | the skill an aptitude weighs, where the key is not a `subType:` selector            |
-| a `Code`-suffixed system field               | what the resolved address is stored as — see _The note vocabulary, and how it maps_ |
-
-**The test is whether the position can take the full four-tuple.** An `Address`
-accepts it by definition, and the positions above cannot: a `system.relations`
-key is read at runtime as `relations[shortcode]`, among the items one actor
-carries, where packages do not exist. So nothing defaults a `Shortcode` out to
-four segments, and a value persisted there as an address names no standing at
-all.
-
-**The two halves of `relations` are two types.** The key an author writes is an
-`Address` — a body in another package is named in full, and one in this package
-by its shortcode alone — and the key the compiled Item carries is the
-`Shortcode` that address names. The builder performs the reduction, exactly as
-it does for a `Code`-suffixed field, and two authored keys reducing to one
-emitted key is an error naming both addresses: a shortcode is unique within one
-package's address space, so two packages may each declare one, and the compiled
-field holds one of the two.
-
-**A bare shortcode in an `Address` field is not a `Shortcode`.** It is an
-Address written at its shortest, with the package, the system and the type all
-supplied by the position — the same value as the full tuple, spelled shorter.
-Which of the two a field holds is the field's own declaration, stated in the
-`Values` column of the tables below and nowhere else.
-
-#### Every address resolves, and every build says so the same way
-
-An address that names no note **fails the build** — in the link checker,
-in the pack compilers and in the site build alike.
-
-A `draft` note exists, resolves, compiles and publishes; a link to it renders
-visibly marked. An Address landing nowhere is a typo or an omission and earns
-an error.
-
-There are six ways a link can fail, and each is one **error** with one message
-wherever it is met:
-
-| finding          | what it means                                 | the fix                                                |
-| ---------------- | --------------------------------------------- | ------------------------------------------------------ |
-| `unlabelled`     | no `\|`, so the link addresses nothing        | write `[[type-shortcode\|Text]]`                       |
-| `not-an-address` | labelled, but the target is not an address    | write the address, not the name                        |
-| `not-lowercase`  | any segment of the address is capitalised     | lowercase it — every segment is lowercase              |
-| `unknown-type`   | qualified, but names no type this build knows | correct the type segment                               |
-| `unresolved`     | parses as an address; nothing publishes it    | fix the shortcode, or qualify to reach another package |
-| `ambiguous`      | _unreachable; kept for the manifest_          | —                                                      |
-| `unknown-anchor` | the address resolves; the `#section` does not | correct the anchor                                     |
-
-`ambiguous` is a reserved reason in the result vocabulary. An omitted segment
-defaults rather than wildcarding, so each written target expands to one
-canonical Address and a lookup returns one entry or none.
-
-The vocabulary and the messages live in one module (`engine/wikilink-syntax.mjs`)
-precisely because an author meets whichever build ran first. Three resolvers read
-one authored link; they must not describe the same mistake in three ways, and
-they must never disagree about whether it is a mistake at all.
-
-#### In frontmatter, the address is written bare
-
-An **`Address` field** takes the address with no brackets:
-
-```yaml
-data:
-  parents:
-    - hexhodai
-  seat: tashal
-```
-
-not `[[hexhodai]]`. The field is declared as an `Address`, so the schema knows
-what the value is and reads it as one; brackets are a wikilink's punctuation,
-which the reader would have to strip before it could do anything.
-
-A frontmatter value is parsed by the address grammar above, so a single-segment
-value such as `hexhodai` names the target by its shortcode alone, with every
-other segment supplied by the position. Frontmatter is structure rather than
-prose: a field value is a reference something else will compile against, and it
-should say exactly what it points at.
-
-**A field can supply the type.** A field naming one kind of note declares its
-default — `seat` a `place`, `parents` an `affiliation`, `stations` a `lore` — so
-the type segment defaults from the declaration and a bare shortcode is the
-ordinary case, not an abbreviation of one. That is why the examples above read
-`tashal` rather than `place-tashal`: the shorter form carries the same
-information, because the field already said what kind of thing it points at.
-
-The frontmatter lint checks scalar Addresses, entries in Address lists, and
-Address map keys at the entry's own location. Segments contain lowercase ASCII
-letters and digits; wikilink brackets, labels, anchors, and spaces do not belong
-in these fields. Optional null values and empty lists or maps express no
-reference. Grammar and accepted types are checked independently of whether a
-target exists.
-
-An affiliation's `economy` accepts only `affiliation` and `lore` Addresses.
-Each entry states its type: `affiliation-merchants` or `lore-tanvrcrncy`.
-There is no default type; a bare shortcode is an error.
-Bundle `contents` likewise requires a type for each document.
-
-**The declaration constrains the type; it does not shorten the address.** A field
-value may be written at any length, and every length is equally correct so long
-as the type it names is the one the field declares. All four of these are valid
-in a `seat` field:
-
-```yaml
-seat: tashal
-seat: place-tashal
-seat: none-place-tashal
-seat: kethira-none-place-tashal
-```
-
-Each is a **suffix** of the canonical address, which is why the third one names
-the system and the fourth cannot omit it — see [Shorter forms](#shorter-forms).
-
-An `affiliation-` prefix there is an **error naming the field and both types** —
-never a silent widening of what the field accepts. Where a field permits more
-than one type with no default among them, a bare shortcode is refused
-outright — an error naming the field and the types it accepts, never a
-resolution across them.
-
-**A position's default and its accepted set are two different declarations,
-and most positions are not ambiguous at all.** The paragraph above is about a
-position that permits more than one type with no default among them; `seat` is
-the plainer case, permitting exactly one. Between those sits a third shape,
-and it is the common one: a position that nominates one of its accepted types
-as the default while accepting others besides. There a bare shortcode is never
-a candidate to weigh — it takes the default outright, every time — and the
-accepted set is what a value that states its own type is checked against
-instead: naming any member of the set is as valid as naming the default
-itself, and naming a type outside it is an error against the set, never
-against the default alone. [The four art slots](#the-four-art-slots) are
-declared exactly this way — each one accepts a second type beyond the one a
-bare shortcode takes.
-
-**Only the type segment defaults.** Package and system are not the field's to
-supply — it has no opinion about which package holds the target — so reaching
-another package's note means qualifying, and because parsing is positional
-counting from the right, qualifying at all means naming the type too.
-`kethira-tashal` is not "the `tashal` place in `kethira`"; it is two segments, so
-it reads as type `kethira`, shortcode `tashal`, and fails.
-
-So the ladder has one rung where the field helps and three where it only checks:
-a bare shortcode takes its type from the declaration, and every longer form
-states the type itself and is verified against it.
-
-This is enforced rather than merely preferred: the build walks every frontmatter
-value, reports each bracketed link it finds, and reports each value whose
-qualification contradicts its field. A successful run says so — _no wikilink in
-frontmatter_ is part of what `content-build links` reports when it passes.
-
-Brackets belong in prose, where a link sits inside a sentence and needs marking
-off from the words around it. A frontmatter value has nothing to be marked off
-from.
-
-### Wikilinks
-
-A **`Wikilink`** is how body prose names something:
-
-```text
-[[<Address>[#<anchor>]|<text>]]
-```
-
-The brackets, the `#<anchor>` and the `|<text>` label are the Wikilink's own.
-What sits inside them is an `Address` like any other — read by the same grammar,
-written at any of its lengths, and taking each omitted segment from where the
-link is written, which for body prose is this package and system `note`. So
-nothing about resolution belongs to the bracketed form: a wikilink and a
-frontmatter field ask the same question of the same value, and the findings above
-are the answers either of them gets.
-
-The anchor is the Wikilink's, not the Address's. It names a section of the target
-by the slug that section's heading declares — `[[place-tashal#market|the
-market]]` — and one naming no section there is the `unknown-anchor` finding.
-Written alone, `[[#slug|Text]]` addresses a section of the page the link sits on,
-which is the one form carrying no address at all.
-
-#### Every wikilink carries a label
-
-There is one namespace, and the pipe is required:
-
-| written             | resolved as | displays                   |
-| ------------------- | ----------- | -------------------------- |
-| `[[Address\|]]`     | an address  | the target note's own name |
-| `[[Address\|Text]]` | an address  | `Text`                     |
-| `[[Name]]`          | nothing     | a finding                  |
-
-**A link written without a label addresses nothing**, and the correction
-is always the same: write `[[type-shortcode|Text]]`.
-
-The bare form does not resolve by display name or alias. `name.aliases` is
-indexed for search and completion, while an authored link names an Address.
-A top-level `aliases:` key is refused.
-
-Requiring the label is also what makes positional parsing safe. Note names
-contain hyphens — `Grukar-ahk` is a name, not a `Grukar` of type `ahk` — so a
-target that does not parse as an address is reported as one that does not, rather
-than split at an arbitrary place or quietly looked up somewhere else.
-
-The **empty** label is not a way of writing no label. It says _address this
-target, and show whatever it calls itself_ — so a note renamed later takes its new
-name at every citation with no link edited. `[[x|]]` is labelled; `[[x]]` is not.
-
-It is the label that is required, not a target: the anchor-only form above
-carries its pipe like every other link.
-
-### Assets are types
-
-`icon`, `image` and `audio` are types in the type vocabulary, and an address
-reaches one exactly as it reaches a being or a skill. Their trees are
-the one thing about them that differs: they sit beside `content/` rather than
-inside it, because the thing a note is addressing is a file rather than a note.
-
-**Three roots, one per type.** The directory is named for what it holds and the
-type is named for what an address reaches, so the two differ by a letter and the
-mapping is declared rather than derived from the name:
-
-| root            | type    |
-| --------------- | ------- |
-| `assets/icons`  | `icon`  |
-| `assets/images` | `image` |
-| `assets/audio`  | `audio` |
-
-**A file's extension decides whether it is an asset at all**, and its root
-decides which type. Every image-extensioned file anywhere under `assets/icons`
-is an icon, and every audio-extensioned file under `assets/audio` is an audio
-asset, however deep it sits.
-
-That filter is load-bearing rather than tidy-minded: `provenance.yaml` files
-live **inside** these roots, at any level, and a walk that took every file would
-read attribution records as assets. A directory under `assets/` that is not one
-of the four holds no addressable asset — `assets/ui` is a package's own
-furniture, and nothing addresses it.
-
-**An asset type carries no system.** Its addresses keep the fourth segment, and
-it is always `none` — `sohl-none-icon-anvil`, never `sohl-icon-anvil` — so key
-parsing stays uniform across every type. The path shape is a property of the
-type rather than a test on a value.
-
-#### The filename is the shortcode
-
-```text
-assets/icons/game-icons/lorc/anvil.svg   →   <package>-none-icon-anvil
-assets/images/beings/creatures/drake.webp →  <package>-none-image-drake
-```
-
-**The extension is not part of the address**, and neither are the directories
-above the file. A root's shortcodes are one flat namespace however deeply the
-tree nests, so two files under one root sharing a basename are two claims on one
-address and a build error naming both. Across roots they are no such thing:
-`icon-anvil` and `image-anvil` are different addresses.
-
-Leaving the extension out is what makes a format change free. Changing an icon
-from SVG to WebP is dropping a different file in place, and no note changes;
-`abysdrksvg` and `abysdrkwebp` would be two addresses for one drake.
-
-**Beneath the root the structure is arbitrary, exactly as it is under
-`assets/content`.** A note's address does not depend on where its `.md` sits,
-and an asset's address does not depend on where its file sits within its root.
-Both trees are arranged for the people who maintain them —
-`icons/game-icons/<contributor>/`, `images/beings/creatures/` — and either can be
-rearranged wholesale without a single reference changing.
-
-**That freedom is the point.** Whoever maintains a tree organises it however
-makes sense to them — by contributor, by subject, by the source a set came from,
-by whatever the next thousand files want — and the build has no opinion. A
-layout that carried meaning would spend that freedom to buy nothing: moving a
-file would become a breaking change, and the arrangement would answer to the
-walk rather than to the person reading it.
-
-**The root itself is the exception, and only because an asset root is
-homogeneous.** `assets/content` is mixed: it holds beings, places, skills and
-the rest side by side, and each note declares its own `type:`, so no directory
-needs to. An asset root holds one type and nothing else — everything under
-`assets/icons` is an icon — which is what lets the root supply the type. It has
-to: a `.webp` carries no frontmatter and has nowhere to say what it is.
-
-So the two trees follow one rule about layout and differ on exactly one point:
-a note's type comes from the note, an asset's type comes from its root. That is
-also why the three roots are a closed list rather than a convention — a fourth
-directory under `assets/` declares nothing, so nothing in it is addressable.
-`assets/ui` and `assets/fonts` fall out of that rule rather than needing an
-exemption.
-
-**A shortcode is lowercase alphanumerics.** A filename that is not — a version
-string, a hyphen, a date stamp — cannot be addressed, and the build says so
-rather than inventing a shortcode for it.
-
-#### The asset record
-
-An asset reaches the content index as a record of its own — one line per
-addressable file, in the same JSON Lines index the notes publish into. It
-carries no frontmatter, no anchors and no `foundry` block: a file declares
-nothing about itself, compiles into no document, and publishes no page, so the
-`address` holds the canonical key and no page slug.
-
-| `asset` field | Source     | What it says                                                       |
-| ------------- | ---------- | ------------------------------------------------------------------ |
-| `path`        | the walk   | Where the file sits inside the emitting package's asset directory. |
-| `attribution` | provenance | The person holding the rights, to whom attribution is legally due. |
-| `source`      | provenance | Where it came from — a URL, or a sentence.                         |
-| `ai`          | provenance | Whether the file is machine-generated — `true` or `false`.         |
-| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.       |
-| `notes`       | provenance | Anything else a person reading the attribution needs.              |
-
-Every field is present on every record, blank where nothing states one. A fixed
-shape is what lets a consumer read `asset.license` without first asking whether
-the package happened to record one.
-
-**`path` is what makes resolution one step.** The record is emitted by the
-package holding the bytes, so the path is that package's path and each consumer
-joins its own root onto it:
-
-| Consumer | `thalorna-none-image-thorn` resolves to                            |
-| -------- | ------------------------------------------------------------------ |
-| Web      | `<cdn base>/thalorna/images/beings/characters/thorn.webp`          |
-| Book     | `<asset base>/thalorna/images/beings/characters/thorn.webp`        |
-| Foundry  | `modules/sohl-thalorna/assets/images/beings/characters/thorn.webp` |
-
-Foundry names a **Foundry package id** rather than a content package, because
-the two are distinct — they are equal in the system only by coincidence, and in
-`sohl-thalorna` they differ.
-
-##### Where provenance comes from
-
-A `provenance.yaml` states the provenance fields in the table above, and nothing
-else: an unknown key is a finding rather than a silent drop, because `licence`
-beside `license` is otherwise an attribution record that looks complete and
-carries nothing.
-
-One address resolves its record in this order:
-
-1. A sibling `<filename.ext>.yaml`, which **replaces** an inherited record
-   wholesale rather than merging over it. A sidecar exists precisely because the
-   inherited answer is wrong for this one file, so carrying half of it forward
-   would make the record's meaning depend on a directory two levels up.
-2. Otherwise the nearest `provenance.yaml`, searching the file's own directory
-   and then its ancestors, **stopping at the type root**. A record above the root
-   would speak for trees it says nothing about.
-3. Otherwise nothing, and the provenance fields are blank. A package that
-   records no attribution is a fact to state, not a walk to fail.
-
-**The nearest record is the whole answer.** It is never merged with the one
-above it, so a record states every key it means to claim — which is what lets a
-reader open one file and know what the tree beneath it carries, instead of
-resolving a chain by hand.
-
-That is also why `attribution` and `license` are **required in any record that
-exists**: a key left out is not inherited from above, it is simply absent, so a
-record stating neither leaves every file it covers with no rights holder and no
-terms. Omitting one is a finding. `source`, `ai` and `notes` stay optional,
-because a blank is a truthful answer for each of them.
-
-#### A font is not an asset
-
-`assets/fonts` is not a root, and a font has no address.
-
-**An asset type exists so a note can name a file and a package can substitute
-it.** Nothing about a font answers to either half. No note names a typeface —
-the art slots are `icon`, `tokenIcon`, `bgImage` and `banner` — and substituting
-one package's font for another's is not something anyone wants.
-
-**Neither consumer of a font can use an address.** A stylesheet names a file
-with `url()`, resolved relative to the stylesheet and never through the content
-index. The book names a _family_ — `#set text(font: "Libertinus Serif")` — and
-the typesetter matches that against a directory it is pointed at. One wants a
-relative path, the other a family name; an address serves neither.
-
-**And the model fits badly.** An address holds one file whose format is free to
-change, which suits a picture. A font family is a matrix of family, weight and
-style, and a filename already says which cell a file is — a shortcode would have
-to re-encode that, worse.
-
-So fonts stay ordinary files a package ships and points a tool at, and their
-licences are recorded where a person reads them rather than in an index.
-
-#### `icon` and `image` are two types, not one
-
-An icon has to stay coherent drawn into a 32×32 slot, which is why icons are
-SVG. An image is unbounded, expected to be large, and unreadable at that size.
-That is a fitness property of the asset itself, and one merged type would leave
-every consumer inferring the handling from the extension; two types let a guard
-assert it instead.
-
-So the two have **separate shortcode namespaces**. `icon-anvil` and
-`image-anvil` are different addresses for different purposes, and a rewrite rule
-reaches one without touching the other.
-
-**An asset address is its own name.** `image-thorn` is an image called `thorn`;
-any resemblance to `being-thorn` is coincidence, and nothing derives one from
-the other.
-
-#### `packagebuild` is a reserved package name
-
-package-build is an npm package rather than a system or a module, and it ships
-a set of images — section banners chiefly — that many packages draw on.
-Addressing them as `packagebuild-none-image-<shortcode>` lets a note reach one
-without declaring a dependency on some parent system or module it otherwise has
-no relationship with.
-
-**Its files reach the website and the book and no Foundry document.** Foundry
-installs no package of that name and no relationship can be declared with one,
-so `banner:` — the one art slot with no Foundry destination — is where a
-`packagebuild` address belongs. A body image naming one, written either way, is
-refused with the line and column it sits on.
-
-`packagebuild` is therefore **reserved** in the package registry: nothing may
-create a real package that collides with it, and its resolution is special-cased,
-because no installed directory sits behind the name.
-
-#### An embedded image is a wikilink
-
-```text
-![[address|label]]
-```
-
-There is no image grammar. An embed is the wikilink above, with `!` meaning
-_render it here_ rather than _link to it_, and the syntax supplying the default
-type the way a field declaration does — `image`. The short-form ladder, the
-package and system defaults, the lowercase rule, the ambiguity reporting and the
-findings vocabulary all apply unchanged.
-
-| written                             | means                                    |
-| ----------------------------------- | ---------------------------------------- |
-| `![[anvil\|]]`                      | decorative — the common case             |
-| `![[anvil\|An anvil]]`              | alt text where it carries meaning        |
-| `![[anvil]]`                        | unlabelled, and a finding like any other |
-| `![[sohl-none-image-anvil\|Anvil]]` | qualified, reaching another package      |
-
-The parser distinguishes a missing label from an empty one, so _deliberately
-decorative_ and _not written_ differ without an exemption.
-
-**The label is the alt text, and it stays with the referrer.** One image serves
-many documents, and only the referrer knows what it means where it sits.
-
-**An embed reaches asset types only.** The syntax invites the broader reading —
-transclusion of an arbitrary note — so the restriction is a guard rather than a
-convention.
-
-**An embed takes the same directive an image does**, in the same place —
-immediately after the closing `]]`, with no space:
-
-```markdown
-![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
-![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
-![[thalornamap|Map of Thalorna]]{.full-width}
-![[thalornamap|Map of Thalorna]]{.full-width, float: top-left}
-![[thalornamap|Map of Thalorna]]{float: top-left, .full-width}
-```
-
-**The same parser reads both**, so an embed takes a width class, a `size:`, a
-`float:`, or a combination in any order, comma-separated — everything
-[an image's directive](#width-is-a-class-and-the-ordinary-width-carries-no-marker)
-takes and nothing beyond it. The width, size, and position vocabularies are the ones
-above, and they are closed here for the same reason: a directive that is quietly
-ignored looks exactly like one that worked, and a directive holding a problem is
-not honoured in part either.
-
-**A being's portrait is one of these**, opening its `{#appearance}` section by
-convention rather than declared in a field — see
-[the lead image](#the-lead-image).
-
-### Three states of a note
-
-A note has three states, and two of them are nothing but conventions the format
-already carried.
-
-| State     | Body    | Marker          | Page         | Document                          | Link target |
-| --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
-| **stub**  | empty   | none            | no           | yes, where one would not be empty | no          |
-| **draft** | written | `tags: [draft]` | yes, noticed | yes, noticed                      | yes         |
-| **full**  | written | none            | yes          | yes                               | yes         |
-
-"Document" here is the document a note's frontmatter earns. A system's Actor or
-Item is earned by that system's block, in every state —
-[a system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
-
-**Full is the absence of everything.** It is the default and carries no marker,
-which is right: the overwhelming majority of a finished corpus should say
-nothing about its own finishedness.
-
-There is no new frontmatter key, no new filetype and no second parser. A stub is
-a `.md` file the walk already finds, and the moment somebody writes a body it
-becomes an ordinary note — nothing moves, nothing is deleted, and every inbound
-link starts resolving.
-
-#### A stub is a note with an empty body
-
-> **The body is empty when everything after the closing frontmatter fence is
-> whitespace.** Nothing else is empty.
-
-The rule is that severe because the test has to be one you can apply by looking
-at the file. Every softer rule makes two files that look different behave the
-same.
-
-| After the fence         | Empty? | What happens                                                    |
-| ----------------------- | ------ | --------------------------------------------------------------- |
-| Nothing, or blank lines | yes    | A stub                                                          |
-| An HTML comment         | no     | A note with a body that renders to nothing. The lint reports it |
-| A horizontal rule       | no     | The same                                                        |
-| A lone heading          | no     | The same                                                        |
-| `_To be written._`      | no     | The same                                                        |
-
-An HTML comment is deliberately not empty. An invisible marker deciding whether
-a page exists is exactly the failure the retired `draft:` field was removed for.
-
-#### What a stub emits
-
-A stub's index record is its frontmatter plus the derived keys, **minus
-`address` and `anchors`**. The absent address is the whole signal, and it is the
-column a table renderer already reads.
-
-It keeps everything else:
-
-- **`file`**, which is what you edit and what every diagnostic names.
-- **`id`**, which is the identity every diagnostic and every table reads.
-- **`foundry`**, naming each document that was made.
-
-#### A document that would be empty is not created
-
-> **If the resulting document would be empty, it is not created** — and the
-> index then names no artefact: `uuid`, `path` and `address` are `null`, which
-> is how a record says one was not made.
-
-The test is about the **output**, which is what lets one rule cover every case:
-
-| The note                           | The document                           | Made? |
-| ---------------------------------- | -------------------------------------- | ----- |
-| `place`, `lore`, `doc`, `scenario` | its JournalEntry, which _is_ the prose | no    |
-| any item type, `macro`             | the Item or Macro, from `data:`        | yes   |
-| the same note's documentation      | a JournalEntry of the same prose       | no    |
-| `map`                              | the Scene, from `data:`                | yes   |
-
-An unwritten arcane talent still compiles into its Item, because an Item is its
-`data:` and that is not empty. What it has no documentation journal for is the
-same thing an unwritten `place` has no journal for: there is nothing to put in
-one.
-
-**An infobox does not count as content.** The panel is a rendering of `data:`
-that the index already publishes, so an entry holding nothing else would tell a
-reader exactly what the record told them.
-
-Nothing anywhere names a document that was not made: a compendium UUID for one
-would send every consumer that resolves it to a document the pack does not hold.
-
-What is suppressed with the page is the web address and the link target: a
-wikilink into a stub is refused, and a table cell listing one prints its name as
-plain text rather than as a link.
-
-#### Two types are structural and exempt
-
-`folder` and `homepage` have no body by design — a folder note's page is a
-generated section index, and the homepage's is the site's front door. An empty
-body on either keeps its address and resolves as **full**, because such a note is
-complete.
-
-Every type in the vocabulary declares whether an empty body suppresses its page,
-so adding a type means answering the question rather than inheriting a default.
-
-#### A stub is still referenceable as data
-
-`borders.to` and `routes.to` name a place by `Address`, and those are **index
-relations rather than page links**: a border with a stub on the far side is a
-valid statement about the world and resolves. So does `parents` for the
-containment tree and `domains` for tenure — a stub appears in its region's
-`contains` and on its holder's `holdings`, rendered as plain text. What a stub
-cannot be is the target of a wikilink, because a wikilink points at a page.
-
-### What a note produces
-
-Note types fall into two groups, and only the first has a mapping table.
-
-**Types that _may_ produce a system document** — a SoHL or HM3 Actor or Item,
-one per system, described by the tables further down.
-
-**Types producing only a core document** — `lore`, `place`, `scenario`, `doc`,
-`map`, `macro` and `homepage`. A core document is one Foundry defines rather than
-a system: a JournalEntry, a Scene, a Macro. These are system-agnostic, so such a
-note carries no `sohl:` or `hm3:` block, has no mapping table, and shows no
-**system** infoboxes.
-
-It may still show a **note** infobox, and several should: a scenario's length,
-party size and required archetypes, or a place's subtype and parent, are exactly
-what a reader wants at a glance. Being outside both systems is not the same as
-having nothing worth summarising.
-
-Every note in **both** groups still produces its JournalEntry and its web page.
-The difference is only whether a system Actor or Item is created as well.
-
-#### A system block is what makes a game document
-
-> **A note produces a system's Actor or Item only where it carries that
-> system's block.** A note carrying no block for any system produces no Actor
-> and no Item anywhere, whatever its packs declare.
-
-The block is not a place to put optional detail — it is the statement that this
-person or thing is meant to be played. Its absence is a statement too, and it is
-made silently: the note is passed over by the Actor and Item passes exactly as
-any note they do not own, with no finding.
-
-**Prose is untouched by this.** A body with content still compiles into one
-JournalEntry, one web page and one PDF page, however many blocks the note
-carries and whether or not it carries any; an empty body still compiles none of
-the three. So a note has three states, and each reaches the next by one edit in
-one file, with its address, its id, its index record and every link into it
-unchanged:
-
-| The note carries           | Produces                                       |
-| -------------------------- | ---------------------------------------------- |
-| no block, empty body       | an index record — a name that can be queried   |
-| no block, a written body   | a page, a PDF page and a JournalEntry          |
-| a block, a written body    | all of those, plus that system's Actor or Item |
-| two blocks, a written body | one document per system, and one of each other |
-
-Write the person; add a system block when someone will need a token. A setting's
-cast is mostly people nobody rolls dice against, and a note about one of them
-carries no block and occupies no slot in a compendium a referee browses.
-
-**A note carrying no document publishes no UUID for one.** Its address, its
-page and its documentation journal are published as they are for any other note,
-and the `foundry` entry that would name an Actor or an Item is absent — the same
-statement [`pack: none`](#the-pack-a-note-compiles-into) makes about a pack,
-made about a system.
-
-**A block for a system this package ships no pack for is an error.** The
-authored data would be discarded either way, so the build says so, once per note
-per system, naming the system and the document class:
-
-```
-assets/content/People/Aelric.md:7:1: error: carries a `hm3:` block, and no Actor pack in this package compiles hm3 documents, so the block is discarded — declare `system: hm3` on one of the `packs:`, or remove the block.
-```
-
-A pack declaring no `system:` is compiled by the fallback pass, which reads one
-system's block — so a systemless Actor pack serves that system and not every
-system a note might write. A package shipping for a second system declares
-`system:` on a pack of each class it compiles.
-
-That includes actors. A being producing its Actor and nothing else would be
-a system-bearing note with readable content, giving a prose link
-naming it nowhere to land. It carries a documentation journal like every other
-such note, addressed
-`<package>-note-being-<shortcode>` beside the Actor's
-`<package>-<system>-being-<shortcode>`.
-
-**A being keeps its prose inline as well.** `system.appearance` and
-`system.dossier` are still the rendered text, where an item's description is an
-`@UUID` pointer into its journal. The difference is deliberate and is about
-size: one item is embedded across hundreds of beings, so baking its description
-into every copy bloats the compendium by the length of the prose times the
-number of carriers, and the pointer buys that back. An actor is singular, so the
-same indirection would cost a reader a click and save nothing.
-
-### One note is at most one document per system
-
-A note produces **at most one document in each system**. That constraint is worth
-stating because the obvious counter-example is real, and the way it is resolved
-shapes how weapons are authored.
-
-SoHL gives a weapon **strike modes**: `system.strikeModes` on a single
-`weapongear`, each mode melee or missile. A shorkana has four — the edge, the
-blunt of the swung blade, the haft or pommel, and the throw. HM3 has no such
-field: it assumes one usage per item, so those four modes are three
-`weapongear` documents and one `missilegear`.
-
-**The mechanical values cannot be shared, so the modes cannot be lifted into
-`data:`.** Impact, heft, reach and draw all differ between the two systems even
-where the concept matches. `data:` holds what the _thing_ is; how it performs is
-each system's own, and belongs in that system's block.
-
-**So the second document becomes a second note.** A `Spear` note carries a
-`sohl:` block describing four strike modes and an `hm3:` block describing its
-usual melee profile; a separate `Spear (thrown)` note carries **only** an `hm3:`
-block, describing the missilegear. That yields two shortcodes, which is what HM3
-needs, and the companion never appears in SoHL, which is what SoHL needs.
-
-The population is small. Of HM3's eleven `missilegear` items, seven are distinct
-objects with a SoHL counterpart — `Arrow (Longbow)`, `Bolt (Crossbow)`,
-`Dart (Blowgun)`, `Stone (Sling)` and so on, which are ordinary notes carrying
-both blocks. Only four are companions: `Javelin (thrown)`, `Shorkana (thrown)`,
-`Spear (thrown)`, `Taburi (thrown)`.
-
-**Every note carrying an `hm3:` block states its type.** Nothing can derive
-whether `Spear (thrown)` is a `weapongear` or a `missilegear` — there is no other
-system to infer from and no subType to read — and the same is true of the note
-carrying both blocks, whose SoHL strike modes describe every usage at once. So
-`hm3.type` is _required_ on both, not only on the companion.
-
-The following special markdown sequences are recognized:
-
-```
-# Heading {#id .class1 .class2 attr="value"}
-```
-
-Any header can include curly braces. Inside the curly braces:
-
-- `#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)
-
-#### Images
-
-An image is authored in the body, in the place it belongs, and every surface
-renders it there — the book, the website and a Foundry Journal Page alike. One
-authored statement, three renderers, which is the single-sourcing every other
-part of this format follows.
-
-```markdown
-![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
-![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
-
-![Map of Thalorna](images/maps/thalorna.webp){.full-width}
-```
-
-**An image is a block.** It stands alone in its paragraph, with a blank line
-either side of it, and every surface renders it as a figure. An image sharing a
-paragraph with prose is refused, because a width and a position mean nothing
-applied to a word in the middle of a sentence.
-
-**The alt text is the caption.** Print has no `alt` attribute and has to put
-those words somewhere a reader can see them, so every surface draws them under
-the picture; the two HTML surfaces carry them as `alt` as well. A title —
-`![alt](src "title")` — is refused rather than dropped in silence: there is one
-place for those words and this is it.
-
-##### Width is a class, and the ordinary width carries no marker
-
-| `class` value | book                          | website            | Foundry journal |
-| ------------- | ----------------------------- | ------------------ | --------------- |
-| _(none)_      | natural width within a column | natural width      | natural width   |
-| `.full-width` | page measure                  | full content width | full page width |
-
-The simple case needs no spelling, which is why the ordinary width has no name.
-
-**No pixel values, ever.** A number means something in a browser and nothing
-coherent in print, and a directive carrying a class and a dimension at once
-gives one question two answers with no rule for which wins. `{width=800}` is
-refused.
-
-##### Named size is `size:`
-
-| `size` value | website and Foundry | book         |
-| ------------ | ------------------- | ------------ |
-| `auto`       | natural size        | natural size |
-| `small`      | 64 CSS pixels       | 1.6 cm       |
-| `medium`     | 128 CSS pixels      | 3.2 cm       |
-| `large`      | 256 CSS pixels      | 5.6 cm       |
-| `xlarge`     | 512 CSS pixels      | 8 cm         |
-| `full-width` | content measure     | page measure |
-
-These are maximum display widths for Markdown images and embedded assets;
-height follows the file's aspect ratio. The available column, page, or browser
-measure caps every size, and print also caps image height within the page.
-Omitting `size:` means `auto`, which uses the file's natural dimensions within
-those bounds. `full-width` spans the book's page rather than one column. The
-`.full-width` class also grants page scope in print; when it accompanies a
-bounded `size:`, the image keeps that bounded width inside the page figure.
-A `size:` may sit before or after `float:` in the same directive, and neither
-changes the other's behavior.
-
-##### Position is `float:`
-
-| `float` value  | book                 | website and Foundry journal     |
-| -------------- | -------------------- | ------------------------------- |
-| `top-left`     | top of the column    | floated left, text wraps        |
-| `bottom-left`  | bottom of the column | floated left, text wraps        |
-| `top-right`    | top of the column    | floated right, text wraps       |
-| `bottom-right` | bottom of the column | floated right, text wraps       |
-| `center`       | top of the column    | centred, with no text beside it |
-
-**Print cannot wrap text around an arbitrary shape.** A Typst float occupies
-the column measure, so in the book only the vertical half of a position has an
-effect — top of the column or bottom of it — while the horizontal half does
-not. The website and a Foundry journal get true CSS wrap from the same
-directive. Expect the same statement, not the same page.
-
-An image with no `float:` is an ordinary block in the flow, where it was
-written. A `.full-width` image is set at the **top of a new page**: the book is
-set in two columns, only a float spans them both, and a float is placed where
-the page has room rather than where it was written — so the page breaks before
-the picture, and the prose that follows it runs below it on the same page. The
-picture can therefore never print above the prose that introduces it or after
-the prose that follows it, at the cost of the page before it ending short. A
-picture taller than the page takes a page of its own.
-
-A `.full-width` image that **also states a `float:`** is asking for a float and
-gets one, with no break before it. A float is placed where it fits, which may be
-the next page.
-
-##### All three vocabularies are closed
-
-`{.fullwidth}`, `{.full_width}`, `{width=800}` and `{float: middle}` are
-refused, located by file, line and column, and the build fails. An unrecognised
-value rendering as the ordinary width is the failure worth preventing, because
-it looks exactly like a directive that worked.
-
-A directive holding anything this section does not name is not honoured at all,
-even in the part that parsed: a half-honoured directive is the same silent
-failure in a smaller costume. The image keeps its braces and renders them as
-literal text, so the mistake is visible on the page as well as in the log.
-
-**Nothing else reaches emitted markup.** The width and position classes and the
-address are all that leave a note; there is no `style`, no `id` and no arbitrary
-attribute, because data is never compiled into markup here. An address carries
-a scheme of `http:` or `https:`, or none at all.
-
-##### Where an address resolves
-
-An image's address follows [the pathname rule](#a-pathname-names-the-package-that-owns-the-file)
-— its first segment says which package owns the file — and each surface
-resolves it to what that surface serves:
-
-- **Foundry** is handed the path inside the install, so `images/map.webp`
-  reaches a journal page as `modules/<package>/assets/images/map.webp`. An
-  address with no such path — a package this build declares no relationship
-  with, or `packagebuild`, which Foundry installs nothing of — is **refused,
-  located by file, line and column**, and the build fails. Foundry is the one
-  surface a correctly written pathname can be dead on while the other two
-  resolve it, and a `src` that resolves against nothing looks exactly like an
-  address that worked.
-- **The book** is handed a copy of the file, staged out of this package's own
-  asset tree into the build directory before the compiler runs. An address
-  naming a file this package does not ship — another package's, or a URL —
-  cannot be staged, and the book prints the caption alone and says so.
-- **The website** passes the address through exactly as authored, because a
-  site serves its imagery from its own asset host and this package is not told
-  what that host is. An address that has to resolve there is written as a full
-  URL.
-
-#### Content tables
-
-A fenced `dataview` block is replaced by the table its query selects:
-
-````markdown
-```dataview
-TABLE WITHOUT ID name.full AS "Name", shortcode AS "Code"
-WHERE type = "armorgear"
-```
-````
-
-**A query that selects nothing is a build error.** A zero-row table publishes as
-a bare header and a rule, and a stale query — a renamed type, a retired
-category, a typo'd path — is then indistinguishable from a category that is
-legitimately empty. Eight tables in one note published that way for months after
-a type rename, and no build said a word.
-
-Where a table is _meant_ to be empty, say so on the fence:
-
-````markdown
-```dataview allow-empty
-TABLE WITHOUT ID name.full AS "Name"
-WHERE type = "affliction" AND sohl.kbcat = "not-written-yet"
-```
-````
-
-The opt-in is on the fence rather than in the query because it is a statement
-about this directive, not part of the query language. Either way the table is
-still rendered — the finding is the point, not withholding the output.
-
-##### In SQL, over the content index
-
-`dataview` is being replaced by **SQL**, queried over the content index, and both
-fences work while the corpus is converted. The query is real SQL, run by
-DuckDB — not a dialect maintained by this package.
-
-````markdown
-```sql
-SELECT address.slug AS _ref,
-       sohl.kbcat   AS _section,
-       name.full    AS "Name",
-       sohl.weight  AS "Weight"
-FROM notes
-WHERE type = 'miscgear'
-ORDER BY sohl.kbcat, name.full
-```
-````
-
-**`FROM notes`** is the content index: one row per note, plus one per
-documentation entry, so `type = 'miscgear'` selects the items and never their
-journals. A nested field is addressed exactly as a note authors it —
-`sohl.weight`, `name.full`, `file.path` — because the index is read as JSON and
-every nested object is inferred as a struct. A field a note type does not carry
-reads `NULL` rather than failing.
-
-**`notes` leaves out stubs; `entries` does not.** Both carry a derived `state`
-column — `stub`, `draft` or `full` — and `notes` is exactly
-`SELECT * FROM entries WHERE state <> 'stub'`. So every table already written
-selects what it always selected, and gains `state` for free; a table that should
-list the unwritten beside the written changes one word:
-
-````markdown
-```sql
-SELECT address.slug    AS _ref,
-       name.full       AS "Name",
-       state           AS "State",
-       m.name          AS "Market",
-       data.population AS "People"
-FROM entries
-LEFT JOIN market m ON m.value = data.market
-WHERE type = 'place' AND subType = 'settlement'
-  AND list_contains(data.parents, 'place-aelwyth')
-ORDER BY data.population DESC NULLS LAST, name.full COLLATE NOCASE
-```
-````
-
-A written settlement renders as a link and a stub renders as plain text, from
-one query with no branch in it: `_ref` is the stub's absent address, and the
-renderer already prints a bare cell where it is null.
-
-A fence selecting `FROM notes` that **would** gain rows from `FROM entries` is
-warned about at the fence, with the count — so adopting stubs in a given table
-stays a decision somebody makes rather than one they forget.
-
-The ladder is what makes "how finished is this?" a query:
-
-```sql
-SELECT state, count(*) AS n FROM entries GROUP BY state ORDER BY state
-```
-
-**`market`** is the six-step market scale as a relation — `value`, `name`,
-`trade` — so a table prints `village` beside the number a note wrote without a
-second copy of the scale living in authored content.
-
-**The state is derived, never stored.** No index record carries it, no note can
-author it, and nothing in `data:` may claim it: the only authored signal is the
-`draft` tag, which marks the one thing reading the body cannot reveal.
-
-**Two aliases are read by the renderer rather than printed**, because which
-column links and where a section breaks are decisions about output, not
-relational operations:
-
-| Alias      | What it does                                                           |
-| ---------- | ---------------------------------------------------------------------- |
-| `_ref`     | Makes the row's **first** rendered column a wikilink to that address.  |
-| `_section` | Emits a headed table per distinct value, in the order the rows arrive. |
-
-`_section` is why one query replaces the forty near-identical blocks a grouped
-table would otherwise need: the authored `ORDER BY` decides the section order too.
-
-**Beware `packFolder`.** It is a note's _pack_ folder, not its directory — the
-directory is `file.folder`. (The `folder` field it replaced is retired; a query
-naming it matches nothing.)
-
-###### Reading another package's notes
-
-Each package this one **depends on** is attached as a schema named after it, so
-a satellite can tabulate what it builds on:
-
-````markdown
-```sql
-SELECT name.full AS "Name", sohl.skillBase AS "Base"
-FROM sohl.notes
-WHERE type = 'skill'
-ORDER BY name.full
-```
-````
-
-This package's own notes stay at the unqualified `notes`, and a query may read
-both at once — joining your beings against the skills they cite is one `FROM`
-clause. It needs no fetch and no configuration: a dependency's published index
-is already cached when a compile starts, because resolving addresses across
-packages needs it.
-
-Which dataset a query reads is `FROM`'s job rather than a fence property. A
-fence naming a file would write a build artifact's path into the corpus, so
-renaming the artifact would mean sweeping every note that cited it.
-
-###### Header arguments
-
-Statements _about the directive_ — as opposed to the query — are written after
-the language as **org-babel header arguments**:
-
-````markdown
-```sql :section-level 3 :allow-empty
-SELECT name.full AS "Name", sohl.kbcat AS _section
-FROM notes WHERE type = 'affliction'
-```
-````
-
-The language word stays first and stays plain, so GitHub, Prettier and every
-other markdown reader still highlight the block as SQL and simply ignore what
-follows.
-
-| Argument               | What it does                                                                             |
-| ---------------------- | ---------------------------------------------------------------------------------------- |
-| `:allow-empty`         | A table selecting nothing is intended, not a stale query. Without it, empty is an error. |
-| `:section-level <1-6>` | The heading level `_section` emits. Default `2`.                                         |
-
-The grammar is org's, so it extends without inventing a spelling per property:
-
-- a key is `:name` **starting a word**, so a colon inside or ending one is text
-  — `:caption Gear: the tables` is a single argument;
-- a value runs to the next key or the end of the line, spaces included;
-- a key with no value means `true`, which is what `:allow-empty` is;
-- a value may be `"quoted"` to hold a word that would otherwise read as a key;
-- a repeated key takes its last value.
-
-`dataview` keeps its own bare `allow-empty`; it is the retiring language and its
-grammar is frozen.
-
-```
-:::secret
-This is secret text
-:::
-```
-
-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.
-
-In FoundryVTT, the passage is a secret section visible to the GM and owners of the journal:
-
-```html
-<section class="secret" id="secret-example">
-  <p>This is secret text</p>
-</section>
-```
-
-On webpages, the passage appears as a collapsed spoiler that any reader can open:
-
-```html
-<details>
-  <summary>Spoiler</summary>
-  <p>This is secret text</p>
-</details>
-```
-
-In books, the passage is visible under a **GM note** label. A printed page has no reader permissions or interactive disclosure control.
-
-#### Actors
-
-All actor types, including being and vehicle, have their entire markdown section processed as normal.
-
-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:
-
-- warrior: Can hold a line and win a fight.
-- skirmisher: Fights light — ambush, missile, mobility.
-- infiltrator: Gets in unseen — locks, stealth, disguise.
-- mage: Commands arcane practice.
-- cleric: Commands religious practice and standing.
-- healer: Treats wounds and illness.
-- scholar: Reads, researches, and knows things.
-- courtier: Navigates rank, negotiation, and intrigue.
-- woodsman: Travels and survives wild country.
-- mariner: Handles boats and blue water.
-- artisan: Builds, repairs, and appraises craft work.
-- trader: Moves goods, values them, and knows markets.
-
-Note that archetypes are descriptive, not proscriptive, and a character may be described by multiple archetypes at once.
-
-#### Items
-
-All item types, including affiliation, affliction, armor, armorlocation, attribute, concoction, containergear, miscgear, mystery, mysticalability, projectile, skill, trauma, weapon, and lore, have their entire markdown section processed as normal.
-
-The following H1 headers are treated specially:
-
-- `# ... {#appearance}`: The contents of this header become the `doc.description` property in hm3. **SoHL has no Item `appearance` field** — none of its thirteen Item subtypes declares one (only Actors do), so this section is not written to a SoHL item.
-
-### type: being
-
-Generates a living (or undead, or spirit) being.
-
-| `data` property             | Values                                         | Description                                                                                      |
-| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `tokenIcon`                 | `Address`                                      | What a token on the canvas wears — an `icon` address; defaults to `icon`                         |
-| `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                       |
-| `archetypes`                | `Archetype[]`                                  | What sort of character this is. **Always an array** — `[]` where none apply; `null` is an error. |
-| `occupation`                | `string`                                       | Name of the character's occupation                                                               |
-| `social`                    | `Map<string, unknown>`                         | The being's social profile                                                                       |
-| `stations`                  | `Address[]`                                    | Name of the stations the character belongs to                                                    |
-| `lore`                      | `Address[]`                                    | Lore concerning this being — the people it is of, the standing it holds, the law it lives under  |
-| `homes`                     | `Address[]`                                    | Place the being calls home                                                                       |
-| `affiliations`              | `Address[]`                                    | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
-| `socialTies`                | `Map<Address, Tie>`                            | Defining support and opposition, directed from this being to others                              |
-| `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
-| `species`                   | `Address`                                      | Being's species (lore)                                                                           |
-| `born`                      | `date \| unknown`                              | When the being was born; absent, it was never born                                               |
-| `died`                      | `date \| unknown`                              | When the being died; absent, it is alive                                                         |
-| `age`                       | `34 \| ~34`                                    | Age in years, stated only to override what `born` says; `~` marks an estimate                    |
-| `ageYears`                  | `number`                                       | Written by the compiler beside an `age` estimate — the `~` stripped; a note never authors this   |
-| `height`                    | `number`                                       | Height in meters                                                                                 |
-| `weight`                    | `number`                                       | Weight in kilograms                                                                              |
-| `frame`                     | `scant \| light \| medium \| large \| massive` | Relative frame size                                                                              |
-| `appearance.eye_color`      | `string`                                       | Eye color                                                                                        |
-| `appearance.hair_color`     | `string`                                       | Hair color                                                                                       |
-| `appearance.skin_color`     | `string`                                       | Skin color                                                                                       |
-| `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
-| `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
-
-#### The people who matter to a being
-
-`data.socialTies` records relationships that define the subject's dossier, not
-everyone the subject knows. An absent entry says nothing about that relationship.
-An acquaintance belongs here when, for example, a guard will recognize the
-subject at a gate. A father and an independent adult son can have no tie in
-either note; a daughter who relies on her father may be his `dependent`.
-
-The keys are bare Addresses with an explicit `being` or `affiliation` type.
-Values are `patron`, `friend`, `dependent`, `acquaintance`, `rival`, or
-`nemesis`. A patron supports the subject from greater power or status; a
-friend supports them from goodwill; a dependent relies on their protection;
-an acquaintance knows them without a strong disposition; a rival opposes them
-without implacable hostility; a nemesis opposes them personally and
-implacably. The infobox groups targets by term and links to their notes.
-
-```yaml
-data:
-  socialTies:
-    being-kaldor: patron
-    being-alys: dependent
-    affiliation-silverguild: nemesis
-    kethira-note-being-kaldas: rival
-```
-
-The full Address names a target in another package. Each target has one tie:
-writing its short and full Address in the same map still names one target and is
-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
-mechanical modifier.
-
-#### When a being was born, when it died, and how old it is
-
-**Absence asserts a fact rather than recording a gap**, and that is what these
-three fields are built around.
-
-- **`born` absent** says the being was **never born** — a construct, a spirit,
-  an elemental, a thing that was made. **`born: unknown`** says it was born and
-  the date is unrecorded, which is the commonest shape in a tree.
-- **`died` absent** says the being is **alive**, which is the common case and so
-  takes the cheapest form. **`died: unknown`** says it is dead and the date is
-  unrecorded. Both spellings of `died` mean dead.
-- **`age` is optional and is an override.** Written, it wins over anything the
-  dates say. Unwritten beside a dated `born`, it is the age that follows from
-  the date and the package's declared present — see below. Unwritten beside
-  `born: unknown` or an absent `born`, the age is unknown.
-
-Most people in a setting do not know their own birth date, so an age beside
-`born: unknown` is an ordinary complete record and not a note working around the
-schema. Where the number is somebody's estimate rather than a fact, write it
-`~34` — the same `~` a date carries. The estimate string is kept exactly as
-written; the compiler adds `ageYears` beside it, the plain number with the `~`
-stripped, for anything that needs to sort or filter on the age rather than
-read it.
-
-#### The age a dated `born` computes to
-
-A package states the day its setting stops on `data.present`, on its own
-`world` or `celestial` `place` note — see _What a body states about itself_
-under `type: place`. Against that date, a being with a dated `born` and no
-authored `age` compiles the age it implies: the two dates compared, not the
-two years subtracted, so a birthday that falls later in the year than the
-present counts one less than the years alone would say. A package that
-declares no present computes no age and says nothing about it — the same
-silence a package with no calendar mechanism meets.
-
-**An authored `age` beside a dated `born` is expected to agree with what the
-date computes.** Where it does not, `content-build lint` raises a warning
-naming both values, so a stale age left behind after a `born` was corrected
-does not go unnoticed. The warning is silent beside `born: unknown` or an
-absent `born` — there is nothing there to disagree with — and silent wherever
-the package declares no present, for the same reason no age is computed at
-all.
-
-`birthday:` is the retired spelling of `born:`. Both are read and `born` wins,
-so a note compiles identically either way; the old spelling is reported until
-every tree has moved.
-
-#### The lead image
-
-**A being's portrait is the first thing inside its `{#appearance}` section,
-always.**
-
-```markdown
-# Appearance {#appearance}
-
-![[<address>|<the being's full name>]]{float: top-left}
-```
-
-**Nothing about that embed is special.** It is an ordinary embedded image with
-an ordinary directive, and no pass treats it differently for sitting where it
-sits. What is strict is the convention: the portrait opens the appearance
-section, so a reader opening any being note finds the picture in the same place,
-and an author writing one never has to decide where it goes.
-
-**The section is the part that is not a convention.** `{#appearance}` is what
-becomes an actor's `system.appearance`, so a picture written above that heading
-is outside the section and reaches no document. The heading carries the anchor
-at **H1** — a deeper heading is not matched, and its whole section is extracted
-as empty rather than reported.
-
-The label is the being's full name. That is what a reader needs when the picture
-does not load, and what a screen reader announces in its place.
-
-**There is no `portrait` field**, at any level. A portrait is a picture of the
-subject, and a picture of the subject belongs in the prose that describes it —
-where an author can see it, move it, caption it or remove it, as with any other
-image. A field puts it somewhere only a template can reach, and every template
-then has to agree about where that is.
-
-Later images are ordinary images too — a second picture of the being, a coat of
-arms, a map of its holding — and they sit wherever the prose wants them,
-including in `{#dossier}`.
-
-**A being with no portrait writes no lead image.** There is no empty form and no
-placeholder.
-
-#### A being's embedded items
-
-`<system>.items` is a list, and each entry compiles into one embedded Item. An
-entry takes one of two shapes.
-
-**A copy of a catalogue item** names it with `model:` — an address, read by the
-same grammar every wikilink is. The entry's remaining keys are merged over the
-model, so it carries the model's values except where it says otherwise.
-
-```yaml
-sohl:
-  items:
-    - { model: skill-wpnc, system: { masteryLevelBase: 52 } }
-    - { model: sohl-sohl-weapongear-whmr }
-    - { model: sohl-sohl-weapongear-dgr, system: { shortcode: dgr2, name: Offhand dagger } }
-```
-
-| key      | required | meaning                                                       |
-| -------- | -------- | ------------------------------------------------------------- |
-| `model`  | yes      | The address of the item this entry is a copy of               |
-| `system` | no       | Values that override the model's                              |
-| `name`   | no       | A name of this entry's own, where it differs from the model's |
-| `data`   | no       | Art this entry names — see _An entry's art_ below             |
-
-**`type:` is not written beside a `model`.** The address already names the type,
-so a second statement of it is a place to be wrong, and it is refused.
-
-**The address is written at whatever length says what it means.** Within this
-package `type-shortcode` is enough; reaching another package means the full
-`package-system-type-shortcode`, since the forms are suffixes of the canonical
-address. The system segment defaults from the block the entry sits in — an entry
-under `sohl.items` defaults to `sohl` — which is why the short form names an
-**Item** here while the same string in body prose names a page.
-
-**A custom item** — one that copies nothing — states `name`, `type` **and**
-`system.shortcode`, all three required, plus whatever else its data model needs.
-It is written in **block form**, never inline, so the two kinds of entry are
-distinguishable at a glance:
-
-```yaml
-sohl:
-  items:
-    - name: Whetstone
-      type: miscgear
-      system:
-        shortcode: whetstone
-        weight: 1
-        value: 5
-        durability: 0
-```
-
-**A top-level `shortcode:` is retired**. It selected a template, while the
-`system.shortcode` beside it was the compiled item's identity — one word for two
-things — and it could not say which package a template came from, so an address
-resolved into a dependency only because no local pack claimed it and would have
-retargeted silently the day one did.
-
-#### An entry's art
-
-An entry is an item in every respect but where it is written, so it carries art
-by the two rules [an item note](#the-four-art-slots) does. It names an `icon`
-address under its own `data:`, and that resolves into the embedded document's
-`img`:
-
-```yaml
-sohl:
-  items:
-    - name: Quiver (leather)
-      type: miscgear
-      data:
-        icon: quiver
-      system:
-        shortcode: quiver
-```
-
-`icon` is the only slot an entry has. The other three belong to a note: two
-describe an Actor or a map, and `banner` is a page's hero image, which an
-embedded document has no page for.
-
-**Naming none is the common case, and it takes a default.** An entry copying a
-`model:` carries the catalogue item's art, and an entry copying nothing takes
-the default its type pairs in `itemBuilders` — the same default an item note of
-that type compiles with. An entry naming an address of its own overrides either.
-Writing `icon: ""` ships the document blank on purpose, and no default replaces
-it.
-
-**`data:` reaches no compiled document.** It is where a note names art, and a
-compiled Item has `img` instead; the container is read and goes no further.
-
-#### Identifying a being's embedded items
-
-Each entry in `sohl.items` compiles into one embedded Item, and its `_id` is
-derived from **what the entry is**, never from where it sits in the list:
-
-```
-_id = makeId(<the actor's id>, "<subType>:<system.shortcode>")
-```
-
-An entry's identity is its **own `system.shortcode`**. The `model:` is not it —
-a model names the item this entry is a _copy of_, and is never written to the
-document — so two entries may share one model and are then two embodiments, each
-stating its own identity:
-
-```yaml
-sohl:
-  items:
-    - model: weapongear-dgr # the catalogue's dagger
-      name: Dagger 1
-      system:
-        shortcode: dgr1 # this dagger's own identity
-    - model: weapongear-dgr
-      name: Dagger 2
-      system:
-        shortcode: dgr2
-```
-
-**Two entries resolving to one identity are a build error naming both.** Without
-their own `system.shortcode`, both daggers above carry the model's `dgr`,
-which makes them the same entity to everything that resolves by `(type,
-shortcode)` — compendium/world reconciliation, template shadowing, cohort
-membership, effect and expression references. A `name` cannot stand in: it is
-presentation, free to be localized or to diverge.
-
-**Reordering the list moves no id.** A key carrying the entry's position
-so inserting an item renumbered every id after it and a re-import created new
-documents beside the old ones — while nothing about those documents had changed,
-only their neighbours. The same is now true of a note's journal pages: an
-unanchored page is keyed on its heading, so inserting a heading leaves every
-other page's id where it was. Two sibling pages sharing a heading is likewise a
-build error, matching the `MD024` lint rule that already refuses it.
-
-A `sohl` block produces a SoHL actor of type `being`. An `hm3` block produces an HM3 actor. Its document type is **not** derived: `hm3.type` states it, and must be `character` or `creature`. A note that omits it is an error naming the note — see _The note vocabulary, and how it maps_.
-
-A SoHL "being" document is created, as will an "HM3" document.
-
-| shared source     | → sohl | → hm3               |
-| ----------------- | ------ | ------------------- |
-| `data.species`    | NA     | NA                  |
-| `data.gender`     | NA     | `system.gender`     |
-| `data.occupation` | NA     | `system.occupation` |
-
-`data.species` is a lore Address describing the being's species. HM3's
-`hm3.system.species` is independent native text; it does not inherit from
-`data.species`. The in-block `hm3.species` spelling is also accepted, with
-`hm3.system.species` taking precedence.
-
-### type: homepage
-
-The package's front page, published at `https://www.heroiclands.org/<package>/`.
-Exactly one note in a content tree declares this type, and it compiles into
-no Foundry document: it is a page and nothing else.
-
-It declares a `shortcode` — conventionally `root` — because that is what a
-link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
-resolves to `/<package>/`. The shortcode names the page in links; its address
-is the package root. The page heading reads `name.full` and defaults to
-`packageBuild.manifest.title`. `description` supplies the page's short
-description.
-
-The page is its body, published verbatim: no wikilink is resolved on it and
-no table expanded, so its links are markdown links, package-relative
-(`kb/rules/`) or external. An index of what the package publishes is not
-written here and is not generated anywhere — it is a `doc` note carrying a
-content table, linked from this page like any other.
-
-The homepage uses the same top-level allowlist as every addressed note. It has
-no Foundry document id; a pinned `data.id` has no role on this type.
-
-### type: vehicle
-
-Represents a conveyance able to hold goods and people moving from one place to another.
-
-| `data` property    | Values    | Description                                                              |
-| ------------------ | --------- | ------------------------------------------------------------------------ |
-| `tokenIcon`        | `Address` | What a token on the canvas wears — an `icon` address; defaults to `icon` |
-| `templatePriority` | `number`  | Template priority, _null_ = not a template                               |
-
-If `sohl` is present, this becomes a `vehicle` actor.
-
-It maps nothing beyond the shared rows above, actor row included: a vehicle
-carries a template priority and no field of its own.
-
-### type: affiliation
-
-Represents a related group of beings.
-
-Note that affiliations may have multiple parent affiliations.
-
-**A pantheon is not a subType.** It is a `faithtradition` carrying subordinate
-faith traditions — the individual religions of that pantheon name it in
-`parents`. There is no `pantheon` value, because every other subType answers
-_what kind of body is this_ while a pantheon answers _where does it sit_, and an
-enum that mixes the two makes a note choose between a kind and a level. The
-hierarchy already carries the answer, so nothing is lost by deriving it: a faith
-tradition with faith traditions beneath it is a pantheon.
-
-The same reasoning is why the three traditions are siblings. `faithtradition`,
-`arcanetradition` and `spirittradition` partition by _what a practice concerns_ —
-the divine, magic, the spirit world — and that partition is load-bearing rather
-than descriptive: a system filtering which mystical practices may associate with
-an affiliation can only be as precise as the distinction it filters on.
-
-**subType**:
-
-- guild: A sworn association of craftsmen holding monopoly over a trade within a locality.
-- order: A body of members bound by vows or a rule of life to a shared purpose.
-- polity: A sovereign body ordering the persons within a territory — states, city-states, tribal confederations. Its ranks apply to all who fall under its authority.
-- faithtradition: A tradition of belief and practice concerning the divine, whether organized or not.
-- arcanetradition: A tradition of belief and practice concerning magic and its practice, whether organized or not.
-- spirittradition: A tradition of belief and practice concerning spirits — ancestors, totems, and the numinous world — whether organized or not.
-- lineage: A body claiming common descent from a known ancestor, whose standing and obligations pass by birth — clans, houses, dynasties, septs.
-- venture: A band bound by contract or shared undertaking rather than by vow or public authority — free companies, ships' crews, trading expeditions, adventuring parties.
-- criminal: An association organized to profit from activity its host polity forbids, sustained by its own enforcement rather than by law.
-- governmental: An organ constituted by a polity to exercise some portion of its authority — ministries, chanceries, courts, exchequers. Its ranks apply only to those who serve in it.
-- fellowship: A voluntary association without vow, trade monopoly, or public authority — formed for mutual company, aid, or shared practice.
-
-**GovernanceModel**
-
-- Autocracy: a single person holds unchecked authority, however acquired
-- Monarchy: one ruler legitimated by descent, election, or sacred office
-- Oligarchy: a small closed group rules, whether by birth, wealth, or rank — membership is not
-  conferred by election and its authority is not held for a term
-- Republic: sovereignty rests in the citizen body and is exercised through offices held for a fixed
-  term by election, which a ruling class supplies the holders of in practice
-- Council: a deliberating body governs collectively with no single head
-- Democracy: the general membership decides, directly or through representatives, and any member may
-  hold office
-- Theocracy: authority derives from divine mandate and rests with its clergy
-- Meritocracy: position is earned by demonstrated skill, achievement, or expertise
-- Stratocracy: the armed force is itself the government
-- Feudal: authority flows through nested personal oaths rather than a central office
-- Confederation: autonomous members retain sovereignty under a weak common center
-- Anarchic: no formal governing authority — custom or force fills the gap
-
-**Republic, Oligarchy and Democracy are three answers to one question**, and the
-boundaries are testable rather than a matter of taste. Ask who fills the offices
-and on what terms. If a closed group holds authority outright, with no election
-and no term, it is an **Oligarchy**. If offices are elective and time-limited but
-a propertied or senatorial order supplies nearly everyone who holds them, it is a
-**Republic**. If any member may hold office and the general body decides, it is a
-**Democracy**.
-
-The distinction is not academic: it is the difference between a ladder whose top
-rungs are a class one is born or bought into, and one whose top rungs are an
-office one is voted into and then vacates. A republic's ladder therefore carries
-**both** — the civic status (Citizen) and the standing in the governing body above
-it (Senator) — because a citizen is not a member of the Senate, and conflating the
-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               |
-
-**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:
-owned outright, with no standing at law except through an owner. The title is
-what this body calls it and the description is how this body puts it, but the
-obligations and rights belong to the standing itself, so they are written once
-and cited by every ladder that confers it.
-
-That is also what makes a rank answerable across bodies. Without it, asking what
-a `Naukrátissa` may do means reading the Bethûan fleet's ladder; with it, the
-rank names the standing, and the standing says.
-
-**Standing**: aligned, unaligned, rival, nemesis
-
-| `data` property      | Values                   | Description                                                                                    |
-| -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
-| `templatePriority`   | `number`                 | Template priority, _null_ = not a template                                                     |
-| `demonym`            | `string`                 | What a member of this affiliation is called (a Vylarian)                                       |
-| `epithet`            | `string`                 | The by-name it is known by — a god's, an order's, a company's                                  |
-| `symbol`             | `string`                 | Its emblem in words: a feather atop a golden scale, a chisel carving a star                    |
-| `governance.model`   | `GovernanceModel`        | Type of government structure, if applicable                                                    |
-| `governance.summary` | `string`                 | summary of the governance situation                                                            |
-| `governance.ranks`   | `Rank[]`                 | The ranks available to members of the affiliation                                              |
-| `governance.offices` | `Map<name, description>` | Official offices in the affiliation                                                            |
-| `seat`               | `Address`                | Where the affiliation's authority sits                                                         |
-| `domains`            | `Address[]`              | Places over which this affiliation holds sway                                                  |
-| `population`         | `number`                 | Number of people in the affiliation (precision 2 significant digits).                          |
-| `economy`            | `Address[]`              | Economic life: `affiliation` or `lore` Addresses, with an explicit type and no default         |
-| `lore`               | `Address[]`              | Lore concerning it — the peoples it draws on, the god a faith venerates, its law, its calendar |
-| `parents`            | `Address[]`              | Affiliations that this affiliation is subordinate to                                           |
-| `relations`          | `Map<Address, Standing>` | Standing with other affiliations, keyed by the other body's Address                            |
-
-**A faith tradition is not its god.** An `affiliation` of subType
-`faithtradition` is a _religion_ — a practice, with an ordained priesthood, a
-calendar and a body of observance — and it can outlive belief in the god
-entirely, while one god may be venerated by several religions that agree on
-nothing else. So the god is `lore` of subType `deity`, cited from the faith
-through `lore`, and never a property of it.
-
-`epithet` and `symbol` stay with the religion for the same reason, and they are
-not a faith's alone: they are what the members call the thing and what they
-carve, so a guild has them as much as a cult does. What a god _is_ — its nature,
-its domains, its aspects — belongs on the deity note, where every religion that
-venerates it can point at one account.
-
-**Every one of those describes the organisation.** A membership — which office a
-being holds, what title it bears, where it stands on the ladder — is recorded on
-the affiliation _as embedded on that being_, and nothing about it belongs in the
-catalogue entry. That is the split `governance` draws: the organisation publishes
-the ranks and offices that exist, and a membership names which of them it holds.
-
-**Rank is the organisation's, not the member's.** A bare `level: 4` on a
-membership says nothing on its own; it means _Knight_ only because the polity
-declared that rung. So the ladder is authored once, on the body that confers it,
-and a member's rank is an index into it. Level 0 is reserved for the excluded —
-outlawed, expelled, excommunicated — which is a standing the organisation still
-recognises, and so still has to define.
-
-**Offices are named, not ranked.** A Chancellor and a Marshal are both great
-officers and neither is above the other, so an office is a key with a
-description rather than a rung — and a being may hold an office at any rank, or a
-rank with no office at all.
-
-**`domains` is territorial, and only territorial.** Seventy-seven divine
-affiliations currently spell `domain:` the other way, holding a deity's sphere of
-influence as prose — _Love, Beauty, and Prosperity_; _Fertility, Agriculture,
-Peace, and Healing_. That sense **folds into `description`**, which those notes
-leave empty in all but one case, and it does not become a field of its own.
-
-A sphere is a characterisation, not a reference. Nothing compiles against it, no
-other note points at it, and rendering it as a list would imply a vocabulary that
-does not exist — whereas `description` is exactly the field for a one-line
-statement of what a thing is. The fuller treatment already has a home: `lore` of
-subType `deity` covers a god's nature, domains, epithets and aspects in prose.
-
-That frees the name for the territorial sense, which earns it: every affiliation
-subType holds sway somewhere, while the divine sense applies to one.
-
-**`domains` names what the affiliation holds directly**, and nothing beneath
-it. A polity whose `domains` names a region holds the region; the settlements
-within it are the region's, reached through its `contains`, and are not
-repeated here. A house holds its manors and names each; the crown holds the
-realm and names the realm. What lies below a holder is answered by the two
-hierarchies together — `place.parents` for where a place sits, and
-`affiliation.parents` for whom a holder answers to — so a subinfeudated manor
-sits in one region by the first and under a lord of another polity by the
-second, and both pages say so.
-
-The website reads `domains` across the package and every fetched index and
-writes the affiliation's page a `holdings` list — every place its `domains`
-names, each entry `{ title, url, type, subType }`, sorted by `subType` then
-`title`, and absent when `domains` names nothing. Every place it names carries
-the affiliation back in `held_by`. Both are derived; a note that writes one has
-it replaced.
-
-If `sohl` is present, this becomes an `affiliation` item.
-
-| shared source    | → sohl             | → hm3 |
-| ---------------- | ------------------ | ----- |
-| `subType`        | `system.subType`   | NA    |
-| `data.seat`      | `system.seat`      | NA    |
-| `data.domains`   | `system.domain`    | NA    |
-| `data.parents`   | `system.parents`   | NA    |
-| `data.relations` | `system.relations` | NA    |
-
-An affiliation writes SoHL common skills under `sohl.system.commonSkills` as a
-list of skill Addresses. An abbreviated value names a skill in the authoring
-package; a skill in the SoHL system package uses its complete Address:
-
-```yaml
-sohl:
-  system:
-    commonSkills:
-      - herb
-      - sohl-sohl-skill-law
-```
-
-The compiled SoHL Item stores the exact published Item UUIDs in
-`system.commonSkills`. An empty or absent list emits `[]`. A foreign target must
-come from a declared `relationships.systems` or `relationships.requires` content
-index. Each UUID uses the module and pack named by that target's published index;
-a missing skill Item or Item UUID is an error at the authored Address. The
-content index retains complete Addresses. Journal, web and book infoboxes link
-to a skill's published documentation journal when one exists and otherwise show
-its name as plain text.
-
-`governance` reaches no system field. Ranks and offices are the note's and the
-web page's — SoHL's affiliation item has nowhere to put them, and inventing a
-mapping for a field no schema declares is the drift these tables exist to catch.
-`system.society`, `system.office`, `system.title` and `system.level` are
-likewise absent here: they are filled on an embedded membership, never from a
-catalogue note's `data:`.
-
-**`system.title` is the style of address the office carries**, Ajaw or Warden,
-which a being holds by virtue of its rank. The note's page heading reads
-`name.full`. Author the style of address on the membership — the `system.title`
-of the entry in a being's `sohl.items` — or, on a catalogue note that carries
-one, at `sohl.system.title`.
-
-### type: affliction
-
-Represents an affliction.
-
-**subType**:
-
-- disease: A biological affliction: an illness or parasite that infects the body or mind (e.g. typhoid, tuberculosis, river blindness)
-- poisontoxin: A chemical affliction: a toxic substance or venom that impairs or kills the host (e.g. hemotoxin, mandrake, wasp venom)
-- maladiction: A supernatural affliction: a curse, hex, or divine/spiritual blight that assails the body, mind, or aura by arcane, divine, or spirit means. The affliction is a metaphysical agent with a course and outcome
-
-**TransmissionTypes**
-
-- none: no transmission mode
-- airborne: Transmission through the air, such as via droplets or aerosols
-- contact: Transmission through direct physical (skin) contact
-- bodyfluid: Transmission through bodily fluids: blood, saliva, etc.
-- injested: Transmission through ingestion of contaminated substances
-- proximity: Transmission through close proximity to an infected individual, but separate from airborne or direct contact modes.
-- vector: Transmission through a vector, such as an insect or animal bite
-- perception: Transmission through sensory perception, such as sight or sound
-- arcane: Transmission through arcane means
-- divine: Transmission through divine means
-- spirit: Transmission through spirit means
-
-| `data` property               | Values              | Description                                                                               |
-| ----------------------------- | ------------------- | ----------------------------------------------------------------------------------------- |
-| `templatePriority`            | `number`            | Template priority, _null_ = not a template                                                |
-| `transmission`                | `TransmissionTypes` | Method of transmission                                                                    |
-| `outcome`                     | `death \| cured`    | Result after affliction has run its course                                                |
-| `healingRate`                 | `number`            | Likelihood of positive outcome of healing test                                            |
-| `contagionIndex`              | `number`            | how contagious the disease is                                                             |
-| `outcomeTraumas`              | `SafeExpression`    | Expression returning traumas that result from affliction recovery                         |
-| `onsetDurationFormula`        | `RollFormula`       | Formula to calculate duration until onset after contracting affliction                    |
-| `onsetDurationBase`           | `number`            | That duration in seconds, stated outright instead of rolled                               |
-| `healingCheckDurationFormula` | `RollFormula`       | Formula to calculate duration until next healing check (measured from last healing check) |
-| `healingCheckDurationBase`    | `number`            | That duration in seconds, stated outright instead of rolled                               |
-| `resolutionDurationFormula`   | `RollFormula`       | Formula to calculate duration after onset to resolution                                   |
-| `resolutionDurationBase`      | `number`            | That duration in seconds, stated outright instead of rolled                               |
-
-If `sohl` is present, this becomes an `affliction` item.
-
-| shared source                      | → sohl                               | → hm3 |
-| ---------------------------------- | ------------------------------------ | ----- |
-| `subType`                          | `system.subType`                     | NA    |
-| `data.transmission`                | `system.transmission`                | NA    |
-| `data.outcome`                     | `system.outcome`                     | NA    |
-| `data.contagionIndex`              | `system.contagionIndexBase`          | NA    |
-| `data.onsetDurationFormula`        | `system.onsetDurationFormula`        | NA    |
-| `data.onsetDurationBase`           | `system.onsetDurationBase`           | NA    |
-| `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
-| `data.healingCheckDurationBase`    | `system.healingCheckDurationBase`    | NA    |
-| `data.resolutionDurationFormula`   | `system.resolutionDurationFormula`   | NA    |
-| `data.resolutionDurationBase`      | `system.resolutionDurationBase`      | NA    |
-
-**A timed phase is a triplet, and a note writes two thirds of it.** SoHL stores
-each phase as `{…DurationFormula, …DurationBase, …Date}`, and the three are
-authored differently:
-
-| third              | who writes it | what it says                                             |
-| ------------------ | ------------- | -------------------------------------------------------- |
-| `…DurationFormula` | the note      | what is **rolled** to get the interval                   |
-| `…DurationBase`    | the note      | the interval **outright**, in seconds, instead of a roll |
-| `…Date`            | play          | _when the phase actually fired_                          |
-
-Write the **formula** for a phase whose length varies — `"2d6*86400"` for an
-incubation of two-to-twelve days — and the **base** for one that does not. Both
-are intervals in **seconds**, and a bare number is a valid formula, so
-`onsetDurationFormula: 86400` and `onsetDurationBase: 86400` differ only in
-whether a roll is attempted.
-
-**Omitting either omits the key**, rather than writing a default over it. That
-matters because the data model's own `null` is what several phases fall back on:
-a trauma that sets no `healingCheckDuration*` takes the world's configured
-healing-check interval, and one that sets no `bloodLossAdvanceDurationBase` does
-not bleed at all. A compile-time `null` is still a value, and would answer those
-questions for every note in every world.
-
-**The `…Date` third is never authored.** It records when the phase fired, which
-only play can know, so `system.contractDate`, `system.onsetDate`,
-`system.treatmentDate` and `system.resolutionDate` are runtime state and a note
-that writes one fails the build. They are world times, and `0` is a valid one,
-so there is no blank a note could write either; leave them out and the data
-model's `null` stands.
-
-`data.healingRate` and `data.outcomeTraumas` are page data. SoHL reads an
-affliction’s base healing rate from `sohl.healingRateBase`. Its item declaration
-does not read `data.outcomeTraumas`.
-
-### type: armorgear
-
-Note: `data.quantity` may not be specified. Quantity is always 1.
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-| `weight`           | `number` | Gear weight                                |
-| `value`            | `number` | Gear value                                 |
-| `quality`          | `number` | Gear quality                               |
-| `durability`       | `number` | Gear durability                            |
-
-If a `sohl` property is present, a SoHL item of type "armorgear" is created.
-
-The note type is `armorgear` in both systems.
-
-| shared source     | → sohl                  | → hm3           |
-| ----------------- | ----------------------- | --------------- |
-| `data.weight`     | `system.weightBase`     | `system.weight` |
-| `data.value`      | `system.valueBase`      | `system.value`  |
-| `data.quality`    | `system.qualityBase`    | NA              |
-| `data.durability` | `system.durabilityBase` | NA              |
-
-### type: armorlocation
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-
-if a `hm3` property is present, an HM3 item of type "armorlocation" is created.
-
-| shared source | → sohl | → hm3 |
-| ------------- | ------ | ----- |
-| `notes`       | NA     | NA    |
-
-### type: attribute
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-
-if a `sohl` property is present, a SoHL item of type "attribute" is created.
-
-| shared source | → sohl | → hm3 |
-| ------------- | ------ | ----- |
-
-### type: concoctiongear
-
-**subType**:
-
-- mundane: ordinary and common in everyday use, generally simple in composition (often a single dried or otherwise prepared ingredient)
-- exotic: A complex and valuable concoction, often a mixture of different herbs and/or chemicals, with medicinal or other unique properties or effects, but not magical in nature.
-- elixir: An arcane alchemical concoction of great power.
-
-| `data` property    | Values                          | Description                                       |
-| ------------------ | ------------------------------- | ------------------------------------------------- |
-| `templatePriority` | `number`                        | Template priority, _null_ = not a template        |
-| `weight`           | `number`                        | Gear weight                                       |
-| `value`            | `number`                        | Gear value                                        |
-| `quality`          | `number`                        | Gear quality                                      |
-| `durability`       | `number`                        | Gear durability                                   |
-| `quantity`         | `number`                        | Gear quantity (default: 1)                        |
-| `potency`          | `na \| mild \| strong \| great` | Concoction Potency (mundane/exotic concoctions)   |
-| `strength`         | `number`                        | Strength: higher the number, greater the strength |
-
-if a `sohl` property is present, a SoHL item of type "concoctiongear" is created.
-
-| shared source     | → sohl                  | → hm3 |
-| ----------------- | ----------------------- | ----- |
-| `subType`         | `system.subType`        | NA    |
-| `data.weight`     | `system.weightBase`     | NA    |
-| `data.value`      | `system.valueBase`      | NA    |
-| `data.quality`    | `system.qualityBase`    | NA    |
-| `data.durability` | `system.durabilityBase` | NA    |
-
-`data.quantity` is page data for a concoction. SoHL sets `system.quantity` to
-`1` for each compendium item.
-
-### type: containergear
-
-Note: `data.quantity` may not be specified; quantity is always set to 1.
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-| `weight`           | `number` | Gear weight                                |
-| `value`            | `number` | Gear value                                 |
-| `quality`          | `number` | Gear quality                               |
-| `durability`       | `number` | Gear durability                            |
-| `capacity`         | `number` | HM3 container capacity (in lbs)            |
-
-if a `sohl` property is present, a SoHL item of type "containergear" is created.
-
-if a `hm3` property is present, an HM3 item of type "containergear" is created.
-
-| shared source     | → sohl                  | → hm3                 |
-| ----------------- | ----------------------- | --------------------- |
-| `data.weight`     | `system.weightBase`     | `system.weight`       |
-| `data.value`      | `system.valueBase`      | `system.value`        |
-| `data.quality`    | `system.qualityBase`    | NA                    |
-| `data.durability` | `system.durabilityBase` | NA                    |
-| `data.capacity`   | NA                      | `system.capacity.max` |
-
-SoHL reads a container’s capacity in pounds from `sohl.maxCapacity`.
-
-### type: miscgear
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-| `weight`           | `number` | Gear weight                                |
-| `value`            | `number` | Gear value                                 |
-| `quality`          | `number` | Gear quality                               |
-| `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
-
-if a `sohl` property is present, a SoHL item of type "miscgear" is created.
-
-if a `hm3` property is present, an HM3 item of type "miscgear" is created.
-
-| shared source     | → sohl                  | → hm3             |
-| ----------------- | ----------------------- | ----------------- |
-| `data.weight`     | `system.weightBase`     | `system.weight`   |
-| `data.value`      | `system.valueBase`      | `system.value`    |
-| `data.quality`    | `system.qualityBase`    | NA                |
-| `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | NA                      | `system.quantity` |
-
-SoHL sets `system.quantity` to `1` for each compendium item.
-
-### type: mystery
-
-**subType**:
-
-- boon: A flat ±N modifier to an associated skill's mastery level, from any source.
-- boost: One or more temporary mastery boosts to an associated skill (Mastery Boost table).
-- fate: A mystery that quantifies the ability to alter destiny or fate.
-- grace: A mystery that quantifies ability to call effectually on divine favor.
-- birthsign: A mystery that describes the arcane sign under which the being was born.
-- other: A mystery that does not fit into the other predefined categories.
-- piety: A mystery that quantifies devotion to a religion.
-
-**SkillAptitude**: either a single skill
-
-| `data` property    | Values                                                                             | Description                                                    |
-| ------------------ | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `templatePriority` | `number`                                                                           | Template priority, _null_ = not a template                     |
-| `assocSkill`       | `Address`                                                                          | Associated skill                                               |
-| `assocAffiliation` | `Address`                                                                          | Associated affiliation                                         |
-| `skillAptitudes`   | `Map<Shortcode, number>`, the key a skill's shortcode or `subType:<skill-subtype>` | Bonuses and penalties, per skill or per kind of skill          |
-| `level`            | `number`                                                                           | Magnitude of the mystery                                       |
-| `charges.value`    | `number`                                                                           | Current number of charges available, _null_ = charges not used |
-| `charges.max`      | `number`                                                                           | Maximum number of charges, _null_ = no maximum                 |
-
-if a `sohl` property is present, a SoHL item of type "mystery" is created.
-
-`system.assocSkillCode` and `system.assocAffiliationCode` are authored under
-`sohl.system` as shortcodes and have no shared source; `data.assocSkill` and
-`data.assocAffiliation` name the same two notes as Addresses, for the page.
-
-| shared source         | → sohl                  | → hm3 |
-| --------------------- | ----------------------- | ----- |
-| `subType`             | `system.subType`        | NA    |
-| `data.skillAptitudes` | `system.skillAptitudes` | NA    |
-| `data.charges.value`  | `system.charges.value`  | NA    |
-| `data.charges.max`    | `system.charges.max`    | NA    |
-
-`data.level` is page data for a mystery. SoHL reads the item’s level from
-`sohl.levelBase`.
-
-### type: mysticalability
-
-**subType**:
-
-- spiritrite: A prepared ceremony by which a practitioner petitions the spirit world.
-- spiritaction: A discrete supernatural act performed through an allied or bound spirit.
-- spiritpower: A standing power conferred on its bearer by a spirit.
-- ritualaction: A prescribed ritual act performed to earn the favour of a deity.
-- divineincantation: A spoken invocation channelling the power of a deity.
-- arcaneincantation: A formally learned spell, invoked by word and gesture.
-- arcanetalent: An innate arcane knack, possessed without formal training.
-- spirittalent: An innate affinity for the spirit world, possessed without training.
-- alchemy: The preparation of substances imbued with mystical potency.
-- divination: The practice of obtaining hidden knowledge or foreknowledge by mystical means.
-
-| `data` property    | Values    | Description                                                    |
-| ------------------ | --------- | -------------------------------------------------------------- |
-| `templatePriority` | `number`  | Template priority, _null_ = not a template                     |
-| `assocSkill`       | `Address` | Associated skill                                               |
-| `assocAffiliation` | `Address` | Associated affiliation                                         |
-| `masteryLevel`     | `number`  | Mastery Level                                                  |
-| `level`            | `number`  | Magnitude of the mystery                                       |
-| `charges.value`    | `number`  | Current number of charges available, _null_ = charges not used |
-| `charges.max`      | `number`  | Maximum number of charges, _null_ = no maximum                 |
-
-if a `sohl` property is present, a SoHL item of type "mysticalability" is created.
-
-If an `hm3` property is present, an HM3 item is created, and `hm3.type` states which — `psionic`, `spell` or `invocation`. It is **authored, not derived from `subType`**: the ten mystical-ability subtypes do not partition onto HM3's three documents (a `spiritrite`, an `alchemy` and a `divination` each answer to none of them), so a derivation would be a guess with a plausible shape. A note that omits it is an error naming the note.
-
-`system.assocSkillCode` and `system.assocAffiliationCode` are authored under
-`sohl.system` as shortcodes and have no shared source; `data.assocSkill` and
-`data.assocAffiliation` name the same two notes as Addresses, for the page.
-
-| shared source        | → sohl                 | → hm3         |
-| -------------------- | ---------------------- | ------------- |
-| `subType`            | `system.subType`       | **see above** |
-| `data.charges.value` | `system.charges.value` | NA            |
-| `data.charges.max`   | `system.charges.max`   | NA            |
-
-`data.masteryLevel` and `data.level` are page data for an ability. SoHL reads
-the item’s base mastery and level from `sohl.masteryLevelBase` and
-`sohl.levelBase`.
-
-### type: projectilegear
-
-**subType**:
-
-- none
-- arrow
-- bolt
-- bullet
-- dart
-- other
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-| `weight`           | `number` | Gear weight                                |
-| `value`            | `number` | Gear value                                 |
-| `quality`          | `number` | Gear quality                               |
-| `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
-
-if a `sohl` property is present, a SoHL item of type "projectilegear" is created.
-
-If an `hm3` property is present, an HM3 item of type "missilegear" is created.
-
-Note that `weapon` can also produce an HM3 `missilegear`. Since `(type, shortcode)` is a
-flat namespace, a `projectilegear` and a `weapon` sharing a shortcode would collide on the
-HM3 side while remaining distinct on the SoHL side.
-
-| shared source     | → sohl                  | → hm3             |
-| ----------------- | ----------------------- | ----------------- |
-| `subType`         | `system.subType`        | NA                |
-| `data.weight`     | `system.weightBase`     | `system.weight`   |
-| `data.value`      | `system.valueBase`      | `system.value`    |
-| `data.quality`    | `system.qualityBase`    | NA                |
-| `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | NA                      | `system.quantity` |
-
-SoHL sets `system.quantity` to `1` for each compendium item.
-
-### type: skill
-
-**subType**:
-
-- social
-- nature
-- craft
-- lore
-- language
-- script
-- mystical
-- physical
-- combat
-- combattechnique
-
-| `data` property    | Values    | Description                                |
-| ------------------ | --------- | ------------------------------------------ |
-| `templatePriority` | `number`  | Template priority, _null_ = not a template |
-| `masteryLevel`     | `number`  | HM3 mastery level                          |
-| `parentSkill`      | `Address` | Parent skill this skill specializes        |
-
-if a `sohl` property is present, a SoHL item of type "skill" is created.
-
-If an `hm3` property is present, an HM3 item of type "skill" is created.
-
-Note: `hm3.system.type` (skill types) use the values "Craft", "Physical", "Communication", "Combat", "Magic", and "Ritual". These do not cleanly map to the `subType` values. Because of this, the `hm3.system.type` value must be specified with the appropriate value when defining HM3 skills.
-
-`system.parentSkillCode` is authored under `sohl.system` as the shortcode of the
-skill this one specializes, and has no shared source; `data.parentSkill` names that
-skill as an Address, for the page.
-
-| shared source       | → sohl           | → hm3                 |
-| ------------------- | ---------------- | --------------------- |
-| `subType`           | `system.subType` | See notes above       |
-| `data.masteryLevel` | NA               | `system.masteryLevel` |
-
-SoHL reads a skill’s base mastery from `sohl.masteryLevelBase`.
-
-### type: trauma
-
-**subType**:
-
-- injury: Physical harm caused by an external force.
-- fear: Emotional response to a perceived threat or danger.
-- morale: Emotional state affecting group cohesion and individual morale.
-- pall: Influence of existential chaos, death, or life-draining forces.
-- psycond: Mental and emotional disorder.
-- physcond: A persistent physical condition of the body (descriptive; e.g. albinism, a limp, poor eyesight)
-- auralshock: Severe shock to the aura, resulting in temporary loss of aura-related abilities.
-- fatigue: Physical or mental exhaustion resulting from prolonged activity or stress.
-- infection: Swelling or inflammation exacerbating an existing condition or injury, often fatal.
-- shock: A prolonged physiological state of shock lasting hours or days, following severe trauma or blood loss — distinct from the transient combat-shock states.
-- coma: A prolonged state of unconsciousness.
-
-| `data` property                   | Values        | Description                                                            |
-| --------------------------------- | ------------- | ---------------------------------------------------------------------- |
-| `templatePriority`                | `number`      | Template priority, _null_ = not a template                             |
-| `healingCheckDurationFormula`     | `RollFormula` | Formula for the interval between healing checks                        |
-| `healingCheckDurationBase`        | `number`      | That interval in seconds, stated outright instead of rolled            |
-| `bloodLossAdvanceDurationFormula` | `RollFormula` | Formula for the interval between blood-loss advances                   |
-| `bloodLossAdvanceDurationBase`    | `number`      | That interval in seconds. Setting it is what makes the wound bleed     |
-| `courseDurationFormula`           | `RollFormula` | Formula for the interval between course tests — shock, coma, infection |
-| `courseDurationBase`              | `number`      | That interval in seconds, stated outright instead of rolled            |
-
-if a `sohl` property is present, a SoHL item of type "trauma" is created.
-
-If an `hm3` property is present, an HM3 item is created. `hm3.type` must be specified as either `injury` or `trait`.
-
-| shared source                          | → sohl                                   | → hm3 |
-| -------------------------------------- | ---------------------------------------- | ----- |
-| `subType`                              | `system.subType`                         | NA    |
-| `data.healingCheckDurationFormula`     | `system.healingCheckDurationFormula`     | NA    |
-| `data.healingCheckDurationBase`        | `system.healingCheckDurationBase`        | NA    |
-| `data.bloodLossAdvanceDurationFormula` | `system.bloodLossAdvanceDurationFormula` | NA    |
-| `data.bloodLossAdvanceDurationBase`    | `system.bloodLossAdvanceDurationBase`    | NA    |
-| `data.courseDurationFormula`           | `system.courseDurationFormula`           | NA    |
-| `data.courseDurationBase`              | `system.courseDurationBase`              | NA    |
-
-**A trauma's three timed phases follow the triplet rule** stated under
-`affliction`: write the formula or the base, both in seconds, and omitting each
-leaves the key out so the data model answers. Two of them fall back to a **world
-setting** when the trauma sets neither half — the healing check and the course —
-which is why a default written here would be wrong rather than merely
-redundant. `bloodLossAdvanceDurationBase` is the switch that makes a wound
-bleed: a trauma that sets it bleeds, one that leaves it unset does not.
-
-**`system.contractDate` and `system.treatmentDate` are never authored.** They
-are the world times the injury was taken and last treated — runtime state, for
-the reason `affliction`'s four dates are — so a note that writes one fails the
-build.
-
-### type: weapongear
-
-Note: `data.quantity` may not be specified. Quantity is always 1.
-
-| `data` property    | Values   | Description                                |
-| ------------------ | -------- | ------------------------------------------ |
-| `templatePriority` | `number` | Template priority, _null_ = not a template |
-| `weight`           | `number` | Gear weight                                |
-| `value`            | `number` | Gear value                                 |
-| `quality`          | `number` | Gear quality                               |
-| `durability`       | `number` | Gear durability                            |
-
-if a `sohl` property is present, a SoHL item of type "weapongear" is created,
-carrying every strike mode the weapon has — melee and missile alike — on
-`system.strikeModes`.
-
-If an `hm3` property is present, an HM3 item is created, and `hm3.type` states whether it is a `weapongear` or a `missilegear`. **`weapon` has no `subType`**: SoHL distinguishes a weapon's uses with strike modes rather than by kind, and HM3 has one document per usage, so nothing but the note can say which usage it describes. Every note carrying an `hm3:` block states it — the one carrying both blocks as well as the companion carrying only `hm3:`, which is usually a `missilegear` — see _One note is at most one document per system_.
-
-| shared source     | → sohl                  | → hm3           |
-| ----------------- | ----------------------- | --------------- |
-| `data.weight`     | `system.weightBase`     | `system.weight` |
-| `data.value`      | `system.valueBase`      | `system.value`  |
-| `data.quality`    | `system.qualityBase`    | NA              |
-| `data.durability` | `system.durabilityBase` | NA              |
-
-### type: lore
-
-In-world information about people, places, or concepts.
-
-**subType**:
-
-- cosmology: The structure of reality — planes, realms, creation, and the ordering of what exists.
-- deity: Individual gods and their attributed natures, domains, epithets, and aspects.
-- theology: How the divine is held to operate — worship, sacrifice, afterlife, sin and grace.
-- arcana: How magic is held to operate — mechanism, traditions, and philosophies of practice.
-- spirit: The non-divine numinous — spirits, celestials, fae, and their natures.
-- economy: How wealth moves — barter, coinage, trade networks, credit, and measure.
-- law: How obligation is ordered and enforced — citizenship, custom, courts, and tenure.
-- calendar: How time is reckoned and marked — dating, seasons, festivals, and astrology.
-- history: What has happened — eras, events, chronicles, and genealogies of rule.
-- material: Substances and their properties — minerals, reagents, herbs, and preparations.
-- folk: Related sapient beings of a single or tightly related species: kindreds, ancestries.
-- culture: A social grouping of individuals with common beliefs, mores, and values.
-- bestiary: A kind of creature that is not a people — beasts, monsters, and the made things
-  that were never born. What `folk` covers for the sapient, this covers for everything else.
-- gathering: A scheduled public occasion people travel to — a tournament or martial games, a
-  great market or fair, a religious festival, a ceremony or rite. What these share is assembly
-  on a cycle: a place, a time, and something contested or observed. Held apart from `calendar`,
-  which covers the _reckoning_ — a festival's date is calendar and the festival is not, and a
-  tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
-  of people rather than an occasion they attend.
-
-| `data` property | Values                                                                      | Description                                                                        |
-| --------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `epoch`         | `date`                                                                      | Which in-world day the world's clock reads zero on                                 |
-| `months`        | `{ name, abbreviation?, days }[]`                                           | The months this calendar keeps, in order — the list sums to the world's year       |
-| `weekdays`      | `{ name, abbreviation? }[]`                                                 | The days of the week it names, in order; a calendar with no week writes none       |
-| `seasons`       | `{ name, abbreviation?, monthStart?, monthEnd?, dayStart?, dayEnd? }[]`     | The seasons it marks, bounded by month or by day of year                           |
-| `eras`          | `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, end? }[]` | The year-counts kept in it; a marker names one era and uses this calendar's months |
-| `dateFormats`   | `Map<slot, format>`                                                         | Calendaria display formats for this calendar                                       |
-| `event`         | `Map<field, value>`                                                         | A dated occurrence, with its sources, locations, reach, and relationships          |
-
-`data.event` is available on every `lore` subType. It holds structured
-chronology metadata, including the event's kind, date, sources, and the places
-it affects. The shared format checks that it is a map; a content package may
-check the details and relationships within that map. It is metadata for
-chronology tools and does not appear as an infobox row.
-
-#### What a calendar note declares
-
-**The calendar keys belong to `subType: calendar` and to no other genre of
-`lore`.** A note carrying one under any other subType is refused, and a calendar
-note that states no `months` and no `epoch` is refused too: a calendar divides
-the year and says where the count begins, and one that does neither is prose
-about time rather than a calendar.
-
-```yaml
-shortcode: commoncal
-name:
-  full: The Common Calendar
-type: lore
-subType: calendar
-data:
-  epoch: VR(720/1/1)
-  months:
-    - { name: Floralis, abbreviation: Flor, days: 30 }
-    - { name: Lusenar, abbreviation: Luse, days: 31 }
-    # … ten more, summing to the world's year
-  seasons:
-    - { name: Spring, monthStart: 1, monthEnd: 3 }
-  eras:
-    - shortcode: founding
-      name: After the Founding
-      marker: VR
-      abbreviation: AF
-      proclaimedBy: vylarinmpr
-      start: 1
-  dateFormats: { full: "D MMMM, YYYY", yearLabel: "[Year] YYYY" }
-```
-
-`dateFormats` accepts `short`, `long`, `full`, `time`, `weekHeader`,
-`yearHeader`, `yearLabel`, and `crossCalendar`. Each value is a Calendaria
-format string. Its date tokens may appear bare; ordinary words belong in
-`[brackets]` or `{braces}` so they print literally. A bare letter run that is
-not a Calendaria token is an error. The `time12` slot is outside this
-vocabulary.
-
-**Position in the list is position in the year.** Days that belong to no month
-are a short month like any other: a five-day festival is one entry, and where it
-sits in the list is where it falls in the year. There is no intercalary
-mechanism, because there is nothing for one to do.
-
-**How long the year is, how the day divides and how the moon moves are facts
-about the world, not about a calendar**, so no calendar note states any of them
-— they are written once on the world's own `place` note and on its moon's, and
-every calendar is compiled against them. The one arithmetic check follows from
-that: `months` must sum to `year.days`, and a list that does not describes a
-different world rather than a different calendar.
-
-**An era is a way of counting years within a calendar**, so its rows sit beside
-the months. Each states its own `shortcode`, unique within the note. A date
-names an era with its marker, such as `VR(720/5/14)`. A calendar may contain
-several era rows, each with its own marker and year origin. The marker is an
-authoring identifier; the `abbreviation` is its printed label.
-`proclaimedBy` is optional: a reckoning whose proclaiming body is unknown, or
-whose body has no note, says so by leaving it out.
-
-**A calendar with no week writes no `weekdays`.** An empty list and an absent
-one say the same thing, and nothing downstream shows a weekday for a calendar
-that names none.
-
-### type: map
-
-A map note has its own prose and a Foundry Scene. A map can depict a place or an encounter. Several maps can depict the same place; the map names that place with `sohl.place`, while the place note does not list its maps.
-
-**subType**:
-
-- `battlemap`: A tactical Scene built in Foundry.
-- `localmap`: A settlement or local-area Scene built in Foundry.
-- `regionalmap`: A large-scale chart with an authored image and scale.
-- `totm`: A gridless image Scene for theatre-of-the-mind play.
-
-| `data` property   | Values       | Description                                                |
-| ----------------- | ------------ | ---------------------------------------------------------- |
-| `scene`           | object       | Exported Foundry Scene for battle and local maps           |
-| `fixup`           | object[]     | Asset address replacements in an exported Scene            |
-| `bgImage`         | Address      | Background image for regional and theatre-of-the-mind maps |
-| `scale`           | object       | Regional distance and unit per grid unit                   |
-| `dimensions`      | `[int, int]` | Optional shared dimensions metadata                        |
-| `pxPerGrid`       | number       | Optional shared grid size metadata                         |
-| `navName`         | string       | Short Scene navigation name                                |
-| `levelName`       | string       | Embedded Level name                                        |
-| `backgroundColor` | string       | Colour outside the art                                     |
-| `overlay`         | string       | Foreground art path                                        |
-| `walls`           | object       | Regional wall geometry                                     |
-| `doors`           | object       | Regional door geometry                                     |
-| `lights`          | object       | Regional light geometry                                    |
-| `tiles`           | object       | Regional tile geometry                                     |
-| `sounds`          | object       | Regional sound geometry                                    |
-| `regions`         | object       | Regional region geometry                                   |
-| `notes`           | object       | Regional pin geometry                                      |
-| `place`           | Address      | Depicted place, when one exists                            |
-
-#### Battle and local maps
-
-Author the Scene in Foundry, export it, convert the export to YAML, and put the resulting object at `data.scene`. Preserve its walls, lights, tiles, regions, levels, environment, flags, and canvas settings. The export can name art from another Foundry package; that path is used as authored in Foundry. The Scene needs positive whole-number `width` and `height`, at least one Level, a valid `initialLevel` when present, and a unique 16-character `_id` on each embedded document. The build derives the top-level Scene `_id` from the map note, adds compendium keys and build metadata, and otherwise preserves the exported fields.
-
-A pin's `text` can contain `#anchor`, where the map note has a heading such as `# Big Bad Wolf {#myanchor1}`. With `text: '#myanchor1'`, the compiled pin opens the JournalEntry and page generated from this map note and displays **Big Bad Wolf**. Its position, icon, other settings, and embedded `_id` remain as exported. A missing anchor is a build error. Pins whose text does not use `#anchor` retain their exported text and references.
-
-`data.fixup` replaces exported asset paths without editing the Scene object by
-hand. Each entry has `path`, `type: address`, and `value`, an asset Address in
-the local or a fetched content index. Paths start at `data.scene` and use a
-property path with array indices or stable embedded `_id` selectors. A path
-must name one existing string or null field, and the address must resolve; any
-mistake fails the build. An `_id` selector remains stable when Foundry reorders
-an array on export.
-
-```yaml
-data:
-  fixup:
-    - { path: ".notes[NNNNNNNNNNNNNNNN].texture.src", type: address, value: sohl-none-icon-book }
-    - { path: ".sounds[0].path", type: address, value: sohl-none-audio-forest }
-```
-
-Fixups change the compiled copy only. The exported Scene in the note stays
-intact, and pin anchor binding runs after fixups. A package name such as
-`fvtt` is an ordinary address package name: it needs published asset records
-before its addresses can resolve.
-
-```yaml
-shortcode: wolfden
-name: { full: The Wolf's Den }
-type: map
-subType: battlemap
-data:
-  scene:
-    name: Wolf Den Scene
-    width: 1900
-    height: 2600
-    grid: { type: 1, size: 100, distance: 5, units: ft }
-    initialLevel: defaultLevel0000
-    levels:
-      - { _id: defaultLevel0000, background: { src: modules/maps/den.webp } }
-    notes:
-      - { _id: NNNNNNNNNNNNNNNN, text: "#myanchor1", x: 950, y: 2350 }
----
-# Big Bad Wolf {#myanchor1}
-```
-
-When the Scene has pins, its Adventure bundle carries the Scene and the JournalEntry generated from its Markdown. Importing that bundle preserves the IDs the pins address.
-
-#### Regional maps
-
-A `regionalmap` uses `data.bgImage`, an image Address, and `sohl.dimensions: [width, height]` plus `sohl.pxPerGrid` to build a gridless Scene. `data.scale: {distance: positive number, unit: nonempty string}` sets the distance per grid unit. Its shared `data` fields can also name `overlay`, `backgroundColor`, `levelName`, `navName`, `walls`, `doors`, `lights`, `tiles`, `sounds`, `regions`, and `notes`; the latter geometry uses the map-note conventions described in the SoHL map authoring guide. `data.scene` is not used for a regional map.
-
-An SVG `data.bgImage` remains vector art on the site and in the book. The Foundry build stages a PNG at the note's stated dimensions with the installed SVG renderer; the source SVG is unchanged. Its aspect ratio must match the stated dimensions. A selected regional SVG map takes a full page in the PDF.
-
-#### Theatre-of-the-mind maps
-
-A `totm` map names its background with `data.bgImage` and its canvas size with
-`sohl.dimensions: [width, height]`. It builds a gridless Scene with token vision
-off. It needs no `sohl.pxPerGrid` or `data.scale`. The Markdown body remains the
-map's prose.
-
-### type: place
-
-**subType**:
-
-- world: A self-contained whole in which places exist — a planet, plane, or realm.
-- region: A bounded division of a world or larger region — continents, marches, uplands, provinces.
-- settlement: A place where folk dwell together — cities, towns, villages, holdings, camps.
-- site: A place significant by what was made or done there — ruins, monoliths, henges, works, battlefields.
-- structure: A single building or habitation — halls, keeps, temples, inns, towers.
-- feature: A place significant by its terrain — forests, rivers, falls, passes, fords.
-- celestial: A body observed from a world rather than located on one — a sun, a planet, a comet.
-
-| `data` property                   | Values                                              | Description                                                                  |
-| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `demonym`                         | `string`                                            | What a person from this place is called — a Vylarian                         |
-| `purpose`                         | `placeCharacter` tag                                | The reason a settlement, site, or structure exists                           |
-| `lore`                            | `Address[]`                                         | Lore concerning this place — its peoples, its law, its calendar, its history |
-| `parents`                         | `Address[]`                                         | Enclosing places within which this place is located                          |
-| `population`                      | `number`                                            | Approximate population (precision 2 significant digits)                      |
-| `market`                          | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
-| `borders`                         | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
-| `routes`                          | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
-| `world.equatorialCircumferenceKm` | `number`                                            | The distance round the body at its equator, in kilometres                    |
-| `world.surfaceGravityG`           | `number`                                            | Surface gravity, as a multiple of Earth's                                    |
-| `world.axialTiltDegrees`          | `number`                                            | The tilt of the axis, in degrees                                             |
-| `year.days`                       | `number`                                            | How many days the body's year holds                                          |
-| `year.hoursPerDay`                | `number`                                            | How many hours the day divides into                                          |
-| `year.minutesPerHour`             | `number`                                            | How many minutes the hour divides into                                       |
-| `year.secondsPerMinute`           | `number`                                            | How many seconds the minute divides into                                     |
-| `present`                         | `date`                                              | The day the setting stops and play begins                                    |
-| `body.diameterKm`                 | `number`                                            | The body's diameter, in kilometres                                           |
-| `body.orbitalRadiusKm`            | `number`                                            | How far it orbits from the body it circles, in kilometres                    |
-| `body.orbit`                      | `string`                                            | The orbit's shape — `circular` means the cycle never varies                  |
-| `body.inclined`                   | `boolean`                                           | Whether the orbit is inclined to the plane the world orbits in               |
-| `moon.cycle`                      | `number`                                            | How many days it takes to return to the same phase                           |
-| `moon.newOn`                      | `date`                                              | A day it was new, written in the reference calendar                          |
-| `moon.eclipses`                   | `string`                                            | `never`, `rare`, `occasional` or `frequent`                                  |
-
-#### Why a place exists
-
-`data.purpose` selects one of the place's own `placeCharacter` tags. It is
-optional on settlements, sites, and structures. A mining settlement on a coast
-can carry `tags: [mining, coastal]` and `data.purpose: mining`: the coast locates
-it; the mine explains its existence. The value must belong to the declared
-`placeCharacter` vocabulary and also appear among that note's tags. The tags
-include `ford`, `portage`, `pass`, and `well` for places founded around a crossing,
-a break in navigation, a mountain route, or scarce water. The body explains the
-specific history; the selected tag gives tables a consistent grouping value.
-
-#### What a body states about itself
-
-**The four groups above are the world's own facts, and they are legal on a
-`world` or a `celestial` note and nowhere else.** A region, a settlement, a
-site, a structure or a feature is somewhere _within_ a world and says nothing
-about the world's year.
-
-```yaml
-# the world — type: place, subType: world
-data:
-  world: { equatorialCircumferenceKm: 40000, surfaceGravityG: 1.0, axialTiltDegrees: 23.5 }
-  year: { days: 365, hoursPerDay: 24, minutesPerHour: 60, secondsPerMinute: 60 }
-  present: 720
-
-# 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/1, eclipses: rare }
-```
-
-**`year.days` is where the year's length lives, and every calendar in the
-package is compiled against it.** A package whose notes state no `year` has no
-calendar mechanism at all: no sum is checked, and nothing is emitted. That is
-the right answer for a package building a setting whose world facts somebody
-else wrote down.
-
-**One year and one moon to a package.** Two years is two settings and nothing
-can say which one a calendar divides; a `moon` with no `year` anywhere is
-refused, because a cycle counted in days has no year to be measured against.
-
-**`present` is the day an age is computed against**, written in the grammar a
-note's dates are written in, so a setting whose present is best said in an era
-says it that way.
-
-**`world.axialTiltDegrees`, the circumference, the gravity, the moon's diameter
-and its orbital radius are read by nobody.** They are there so a reader knows
-what kind of world this is. What the build consumes is the year, the day's
-divisions, the present, the moon's cycle and epoch, and whether its orbit is
-circular and inclined.
-
-#### What a settlement's market supports
-
-`population` states how many people a settlement holds; `market` states what a
-traveller can buy there. Those are different questions — two settlements of
-eight hundred are a different proposition when one holds a weekly market and
-the other a chartered fair with a moneylender — so a note states both, either,
-or neither.
-
-The value is a **class**, not a measurement. The numbers order six steps and do
-nothing else: a `5` is not a market two fifths larger than a `3`, it is a city
-rather than a town. `content-build lint` refuses a value off the scale instead
-of rounding it onto one, so a reader can trust that a number means the same
-thing on every page.
-
-| `market` value | the settlement is | what can be had there                                                                             |
-| -------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
-| `1`            | a hamlet          | no market — what neighbours trade among themselves                                                |
-| `2`            | a village         | a weekly market: staples, a smith, what a household cannot make                                   |
-| `3`            | a town            | a regular market, most common goods, several trades working full time                             |
-| `4`            | a market town     | a chartered fair, goods carried from a week away, a moneylender                                   |
-| `5`            | a city            | anything ordinary, in quantity; foreign goods; a guild structure                                  |
-| `6`            | a great city      | the rare and the imported as a matter of course; banking; the market from which other markets buy |
-
-The key is meaningful on a settlement, and the lint checks no `subType`
-condition — as it checks none for `population`. Which places a fact says
-something about is the author's judgement, and the `data:` container is closed
-per type rather than per subType.
-
-#### Where a place is, in relation to other places
-
-`parents` states what a place is **within**. Two more properties state what
-it is **next to** and what it is **reachable from**, as data rather than as
-prose, so that two notes describing one frontier cannot quietly disagree about
-which side of it each is on:
-
-```yaml
-data:
-  borders: # places sharing a frontier
-    - { to: dunharargn, bearing: NE } # both required
-    - { to: bethuargn, bearing: W }
-  routes: # journeys from this place's centre
-    - { to: steinmark, bearing: SW, mode: land, days: 3, terrain: [road, mountains] }
-    - { to: denizara, bearing: W, mode: ship, days: 5 }
-    - { to: kethramir, bearing: E, mode: land, days: 30, terrain: [dunes], leagues: 90 }
-```
-
-- `to` — required; an `Address` naming the other place. Its type segment defaults
-  to `place` and `place` is the whole of its accepted set, so `vylar`,
-  `place-vylar` and `thalorna-none-place-vylar` name one place and a `to` naming
-  anything else is an error. **A bare shortcode names a place in this package**,
-  which is what the fully qualified form is for: naming a place in a declared
-  dependency's index, so two packages using one shortcode never answer for each
-  other.
-- `bearing` — required; where the neighbour or the destination lies from here.
-- `mode` — required on a route; how the journey is travelled.
-- `days` — required on a route; a marker meaning "about this, under normal
-  conditions", from the scale below. Any other value is an error.
-- `terrain` — optional on a route; the terrains crossed, in travel order, from
-  the registry below. Each terrain names the modes that cross it, so open sea
-  on a land route — or a road on a ship route — is an error.
-- `leagues` — optional on a route; a distance, only where the note states one.
-
-**A border is a shared frontier between areas.** Regions commonly state one;
-a settlement does so only when it actually shares a frontier with another
-place. Most settlements use `parents` for where they sit and `routes` for
-journeys between them. A pair appears in `routes` once per `mode` — a port and its
-neighbour may be three days by land and one by ship — and in `borders` once.
-**A place never borders its own parent or child**: containment is `parents`,
-and restating it as adjacency makes the two contradict each other.
-
-**Both ends state the relation, and `content-build lint` checks that they
-agree.** A border at `NE` from one side is a border at `SW` from the other; a
-route stated by land in three days from one side is stated by land in three
-days from the other, at the opposite bearing. A neighbour that states nothing
-back is a warning naming both notes — the pair is half-written, not wrong. A
-neighbour that states a different bearing, a different `days` or a different
-`mode` is an error, because one of the two notes is wrong and a reader cannot
-tell which. Every `to` must resolve to a place, every value must come from its
-closed set, and each finding is located at the entry that states it.
-
-The terrain names form one shared registry in package-build. A route crossing
-a package boundary uses the same terrain and mode rules at both ends.
-
-For every place that participates in a border or route, the map builder draws
-an itinerary from that place. A site page carries it as a linked SVG. A PDF
-book that includes the place gives its map a separate full page after the
-entry. A configured Foundry Scene pack carries a gridless map backed by a
-generated PNG, with Notes linked to importable place journals. Places with no
-relations create no itinerary output.
-
-**A relation that crosses a package boundary is written in full at both ends.**
-An omitted `<package>` segment is the package being built, in whatever note the
-value is read from — a note of this package's own, or a record a consumer fetched
-out of a dependency's index — so a short `to` names a different place in a
-different build. Only the fully qualified form names one place everywhere, which
-is why the long form is not optional for a border or a route between packages,
-and why a short `to` in a fetched record names the package being built rather
-than the package that wrote it.
-
-| `bearing` value | where the other place lies |
-| --------------- | -------------------------- |
-| `N`             | north                      |
-| `NE`            | north-east                 |
-| `E`             | east                       |
-| `SE`            | south-east                 |
-| `S`             | south                      |
-| `SW`            | south-west                 |
-| `W`             | west                       |
-| `NW`            | north-west                 |
-
-| `mode` value | travelled                    |
-| ------------ | ---------------------------- |
-| `land`       | on foot, mounted, or by cart |
-| `boat`       | on a river or a lake         |
-| `ship`       | on open sea                  |
-
-| `days` value | meaning                                      |
-| ------------ | -------------------------------------------- |
-| `1`          | a day                                        |
-| `2`          | two days                                     |
-| `3`          | three days                                   |
-| `5`          | about five days                              |
-| `10`         | a ten-day week                               |
-| `20`         | two ten-day weeks                            |
-| `30`         | three ten-day weeks                          |
-| `45`         | a month and a half                           |
-| `60`         | two months                                   |
-| `90`         | a season                                     |
-| `180`        | many months                                  |
-| `360`        | who knows — a journey nobody reckons in days |
-
-| `terrain` value | crossed by         |
-| --------------- | ------------------ |
-| `road`          | land               |
-| `track`         | land               |
-| `plain`         | land               |
-| `steppe`        | land               |
-| `hills`         | land               |
-| `mountains`     | land               |
-| `forest`        | land               |
-| `jungle`        | land               |
-| `marsh`         | land               |
-| `dunes`         | land               |
-| `desert`        | land               |
-| `ice`           | land               |
-| `coast`         | land, boat or ship |
-| `open-sea`      | ship               |
-| `river`         | boat               |
-| `lake`          | boat               |
-
-#### What lies within a place, and who holds it
-
-`parents` states what a place is within; an affiliation's `domains` states
-what it holds. The website reads both across the package and every fetched
-index and writes each place's page two lists, each entry
-`{ title, url, type, subType }` and each absent when empty:
-
-- `contains` — every place whose `parents` names this one, sorted by
-  `subType` then `title`. A region lists its settlements, sites, structures
-  and features; a settlement lists the structures within it.
-- `held_by` — every affiliation whose `domains` names this one, sorted by
-  `title`.
-
-Both are derived; a note that writes one has it replaced. **`domains` is
-never expanded**: a region held by a polity lists the polity in `held_by`, and
-a settlement within that region lists only the house or order whose `domains`
-names it — its lord's lord is reached through `affiliation.parents`.
-
-**A settlement, a site or a structure is held by someone.** One of those that
-no affiliation's `domains` names — in this package or in a fetched index — is
-a warning from `content-build lint`, `unheld land`, located at the note's
-`type:` line, so a gap in tenure shows while a note is written. A `world`, a
-`region` and a `feature` are exempt: a region is held through its polity's
-`domains`, and a river by nobody.
-
-#### Population figures
-
-`population` is an approximate count, written to two significant digits. A
-place states one, and so does an affiliation — how many people it counts,
-wherever they are. `content-build lint` reads those figures against each other
-and reports four warnings, each named by the phrase its message begins with.
-
-- **`over-held land`** — the polities whose `domains` name a place count more
-  people than the place states. A polity subordinate to another polity holding
-  the same place is already inside that polity's figure and is not counted
-  twice. A **settlement is exempt**: the polity of a city-state holds the city
-  and counts the hinterland around it, so its figure is properly the larger.
-- **`over-full region`** — the regions whose `parents` name a place count more
-  people than the place states. A region naming both its parent and its
-  grandparent counts under the nearer of the two, so a place written into two
-  levels of the hierarchy is not counted at both.
-- **`oversized settlement`** — a settlement states more people than a place
-  containing it does, whether its own region or any place above that.
-- **`disputed figure`** — a `doc` note carries a figure beside a wikilink to
-  the place or affiliation it belongs to, and the two disagree. The finding is
-  located at the number the page wrote, and a figure written twice is located
-  twice.
-
-The first three are reported on the note's own `data.population`; the fourth
-on the citation.
-
-**A figure is read as a population only where it carries `~`.** That marker is
-what separates a population from the other numbers a table puts beside a place
-— a distance, a stage count, a tally of days — so `| [[place-rgn\|X]] | ~2,000 |`
-is a claim about people and `| [[place-rgn\|X]] | 3 |` is not.
-
-**Rounding is admitted.** Two significant digits carry a half-unit of error,
-widest at the bottom of a decade, so a place whose figure falls up to five per
-cent below what it contains is not a finding.
-
-**An unstated figure is silent.** A place or affiliation with no `population`
-contributes nothing to a sum and is never the subject of a finding, so a
-half-written region is quiet rather than noisy. A fetched index carries
-`parents` and `domains` but no figure, so a dependency's places sit in the
-geography and its people are counted nowhere.
-
-**There is deliberately no urban-share rule.** The share of a region's people
-living in its named settlements cannot be measured from the notes: the
-settlement layer names the notable places and is complete nowhere, so the ratio
-reports how much of a region has been written rather than how much of it is
-urban.
-
-**A place declares what is true of its ground.** Its governing affiliations
-carry their own `domains`; maps name the place they depict through `data.place`.
-The place's `lore` links cover its peoples, calendar, law and history. Political
-languages belong to a polity's `sohl.system.commonSkills`, while the note's
-`description` provides its page summary.
-
-### type: scenario
-
-Content prepared to be played — a situation with its cast, places, and possible outcomes.
-
-**subType**:
-
-- campaign: A long arc toward a goal, spanning many adventures — carries standing cast, factions, and its own timeline.
-- adventure: A self-contained undertaking with a specific objective, playable in a few sessions.
-- encounter: A single scene or challenge, reusable within an adventure or on its own.
-
-| `data` property    | Values                                       | Description                                                                    |
-| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------ |
-| `parents`          | `Address[]`                                  | List of parent scenarios of this scenario (campaigns, etc.)                    |
-| `locations`        | `Address[]`                                  | List of locations associated with this scenario                                |
-| `cast`             | `Address[]`                                  | individuals associated with this scenario                                      |
-| `factions`         | `Address[]`                                  | Affiliations associated with this scenario                                     |
-| `follows`          | `Address[]`                                  | Prerequisite scenarios that should be completed before beginning this scenario |
-| `status`           | `draft \| playtested \| published`           | Playability status of this scenario                                            |
-| `party.size`       | `solo \| small \| standard \| large \| host` | Suggested party size (solo=1, small=2-3, standard=4-6, large=6-7, host=7+)     |
-| `party.archetypes` | `Archetype[]`                                | Archetypes of characters suitable for completion                               |
-
-### type: doc
-
-**subType**:
-
-- rules: The rules of the game, independent of medium — valid at a table with paper and dice.
-- userguide: How to operate the Foundry implementation to play by the rules.
-- reference: Out-of-world lookup material about the setting or system — correspondences, conversions, glossaries.
-- howto: A task with an outcome, written as the steps that reach it.
-- concept: An explanation of how something works and why it is shaped that way, read to understand rather than to follow.
-- settingguide: An orientation to a setting or region, bringing its places, peoples, institutions, and daily life into one usable frame with links to detailed notes.
-
-A `doc` declares no properties of its own.
-
-Choose `settingguide` for an entry point that stands on its own while guiding
-players and GMs into a setting. A `concept` explains one subject, a `reference`
-supports lookup, and a `userguide` explains how to operate the Foundry
-implementation. The setting guide can use ordinary SQL content tables and
-`:::secret` passages; its genre does not change its Address, journal, or page
-rendering.
-
-```markdown
 ---
-shortcode: reedflatsguide
-name: { full: The Reed Flats Guide }
+shortcode: contentformat
+name: { full: "Authoring HeroicLands content" }
 type: doc
-subType: settingguide
-description: A starting point for adventures in the Reed Flats.
+subType: userguide
 ---
 
-The Reed Flats are a network of marsh settlements linked by river trade.
-Their routes, customs, and rival groups shape everyday journeys.
-
-:::secret
-The old ferry route is known to the local guides.
-:::
-```
-
-The field is a genre and only a genre: it says what kind of page this is, never
-who reads it. A page written for a developer is a `howto` or a `concept` like
-any other, and the audience is the section it sits in.
-
-**A page that introduces a type is an ordinary note, named by convention.**
-Write `type: doc`, `subType: reference`, `shortcode: <type>` — so the
-affiliations introduction is `doc-affiliation`, addressed and linked like
-anything else, and typically carrying a generated table of what it introduces.
-It has no build path of its own, and it is the only kind of index there is: a
-site is its homepage and its pages, and nothing is generated between them.
-
-There is no landing page and no section. A section appears in **no address**: a
-page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
-section is what Hugo calls a content directory, and the note format does not
-carry one.
-
-So a `doc`'s `subType` is a **genre** and nothing else, closed to the values
-above.
-
-### type: macro
-
-A script offered on the macro bar, plus the prose explaining what it does and
-when to reach for it. Produces a Foundry **Macro** and, from the same note, the
-JournalEntry every note produces — so a macro's documentation is a document a
-player can open, not a comment nobody reads.
-
-**The script is a page of the note, addressed by an anchor.** The macro's
-`command` is the first **language-tagged** JavaScript fence on the page whose
-heading carries `{#script}`:
-
-````markdown
-# Script {#script}
-
-```js
-await CONFIG.SOHL.class.Utility.currentCombatantAttack();
-```
-````
-
-Three rules follow, and each is deliberate. The anchor names the **page**, not
-the heading text, so the heading may be worded freely and
-`[[macro-autoattack#script]]` still opens exactly this page. The fence must
-be **tagged** — an untagged fence is a code sample whose language nobody stated,
-and treating it as executable would make an illustrative snippet the macro. And
-only the **first** tagged fence counts, so a note may document its macro
-with examples that are plainly not the macro. A note with no `{#script}` page,
-or no tagged fence on it, is a **build error**: a macro with no command is a
-macro-bar button that does nothing.
-
-**The executable copy is read from the raw markdown.** The journal's copy of the
-same fence has been through table expansion and wikilink conversion first, so
-the two diverge on purpose — the journal renders prose _about_ the script, while
-the macro runs exactly what the author typed.
-
-**This is not compiling data into code.** A Macro's `command` is authored source
-shipped as content and run by Foundry's own macro runner under the permission
-model that governs every macro in a world. Nothing evaluates, compiles, or
-revives anything; the compiler copies text from a fence into a JSON field.
-
-**Both settings are `sohl` properties, not `data` ones.** The compiler reads
-them with the same accessor every `sohl` field uses — the `sohl:` block first,
-then the note's top level — so `data.macroType` is not read, and a macro is not
-a journal-only note the way `place`, `lore` and `scenario` are: it produces a
-Foundry **Macro**, and these two describe that document.
-
-| `sohl` property | Values                      | Description                                                          |
-| --------------- | --------------------------- | -------------------------------------------------------------------- |
-| `macroType`     | `script`                    | The Foundry macro type. Defaults to `script`, and `chat` is an error |
-| `macroScope`    | `global \| actors \| actor` | How far the macro reaches. Defaults to `global`                      |
-
-**`macroType: chat` is an error, not an unimplemented feature.** A chat macro's
-`command` is chat text rather than source, so none of the `{#script}` fence
-rules describe it, and compiling one through this path would ship a macro whose
-body was a code block posted verbatim into chat. Chat macros as content would
-need an authoring convention of their own.
+# Authoring HeroicLands content
 
-The note's `data.icon` resolves the way every other note's does; a note that
-authors none takes Foundry's own `icons/svg/dice-target.svg`.
+A content package begins with Markdown notes under `assets/content/`. Each note has YAML frontmatter describing its identity and data, followed by prose. Folder names beneath `assets/content/` are for authors; `type`, `subType`, and Addresses determine what the build creates.
 
-### type: bundle
+Start with [your first note](authoring/first-note.md). It explains the smallest valid note and shows the JournalEntry, web page, book entry, and content-index record made from it. Then use the chapters below in the order your note needs them.
 
-A bundle of notes to be taken as a single unit — an `Adventure` in Foundry VTT.
+| Need                                                      | Read                                                        |
+| --------------------------------------------------------- | ----------------------------------------------------------- |
+| Frontmatter, `data`, system blocks, and infoboxes         | [Frontmatter](authoring/frontmatter.md)                     |
+| Addresses, links, anchors, fences, and inline expressions | [Links and markup](authoring/links-and-markup.md)           |
+| Images, icons, audio, provenance, and sidecars            | [Assets](authoring/assets.md)                               |
+| Canonical dates, calendars, eras, and conversions         | [Dates and calendars](authoring/dates-and-calendars.md)     |
+| All accepted note types, subtypes, and fields             | [Note type reference](reference/note-types.md)              |
+| Exact format details and system mappings                  | [Detailed reference](reference/format-details.md)           |
+| Optional readability and wording suggestions              | [Prose analysis](commands.md#package-build-prose-lint-path) |
 
-| `data` property | Values      | Description                                            |
-| --------------- | ----------- | ------------------------------------------------------ |
-| `contents`      | `Address[]` | The documents the Adventure holds; `[]` when unstated. |
+## The shared note
 
-```yaml
----
-type: bundle
-shortcode: hegovynvale
-name:
-  full: The Hegóvyn Vale
-data:
-  contents:
-    - map-hegovynvale
-    - miscgear-bowlcer
-    - being-aurochs
----
-Prose describing what the bundle is for.
-```
-
-An `Adventure` carries **copies** of what it holds, not references: importing one
-creates or updates each document in the world, after which they live
-independently. So a bundle is not a folder — a folder is a live grouping that
-persists in the pack.
+A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
-**Each address names the note's own document.** That is the same rule `pack:`
-follows, so there is one answer and not two. A note that compiles into _two_
-documents — an item and the JournalEntry its prose became — puts the second in a
-bundle when the bundle names its `note` Address:
-`sohl-miscgear-bowlcer` is the Item, `miscgear-bowlcer` its description page.
+A `:::caption {#anchor}` fence labels the next prose, code, table, or image block. Its anchor makes the block addressable; `[[#anchor|]]` displays the generated kind and number, such as **Figure 12**. Foundry gives the captioned block a JournalEntryPage. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references) for the syntax.
 
-**An address that resolves to nothing fails the build.** A `folder` address is
-refused with a message of its own: a folder materialises in every pack holding
-something filed in it, so it belongs to no one pack and there is no single copy
-to take.
+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
+[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
+more `: definition` lines. See [footnotes and definition lists](authoring/links-and-markup.md#footnotes-and-definition-lists)
+for examples and placement in journals, web pages, and books.
 
-**The note's prose becomes the Adventure's `description`**, which is what
-Foundry renders on the import card. A bundle is something you hand someone, so
-its prose belongs on the document itself — which is why, unlike an item, a
-bundle earns no separate documentation journal.
+An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
-Each Adventure is written to the pack the note's `pack` names — the shared
-routing field every type uses, not one of the bundle's own — defaulting to the
-configured `Adventure` pack, conventionally `adventures`. `<system>.pack`
-overrides it for that system, as it does everywhere else.
+Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
+Foundry compiles it only into private compendiums. An untagged note cannot link
+to it. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
+explains routing for documents and their prose journals.
 
-**It cannot be the `adventures` companion**, though, where a repository also
-compiles map notes: that pack is written by the scenes pass, and a companion is
-written by its parent pass rather than routed to. A repository that authors
-bundles declares an Adventure pack of its own, and one that declares none is
-told so by name.
+A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
 
-**A pack's `system:` constrains what its Adventures may hold.** An `Adventure`
-has no `system` field, so a bundle spanning two systems cannot be one document
-that knows it spans them: it is one Adventure per system, and the pack each is
-written to is what carries the system. A pack declaring `system: hm3` sees the
-HM3 packs and the system-neutral ones, so a member that publishes no HM3
-document is **left out rather than failing** — and named, because an installer
-that quietly ships half its contents is worse than one that fails. A pack
-declaring no system scopes nothing away, and a member it cannot find is a dead
-address.
+| Authored section | SoHL Actor          | HM3 Actor            |
+| ---------------- | ------------------- | -------------------- |
+| `{#appearance}`  | `system.appearance` | `system.description` |
+| `{#dossier}`     | `system.dossier`    | `system.biography`   |
 
-**The bundles pass runs last**, after every pass producing what a bundle can
-hold — Item, Actor, JournalEntry, Macro and Scene. That ordering is derived from
-what the pass declares it reads, not from the order `packs:` happens to list, so
-an Adventure pack declared first still compiles last.
+An Item's `{#description}` page is its readable description. The note Address `<package>-note-<type>-<shortcode>#description` resolves to a JournalEntryPage UUID. The build writes the same `@UUID[...]` pointer to SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item note without that anchor uses its first page as the description. Other pages and anchors remain available for links.
 
-### type: folder
+## A complete minimal note
 
-Foundry's `Folder` — the grouping documents are filed in, and the last document
-this package compiled from bespoke configuration (`*-folders.yaml`, five files
-per tree) rather than from a note. Those files are retired; a pack that
-still names one is refused.
+Place this at `assets/content/Places/Harbor.md`:
 
-```yaml
+```markdown
 ---
-type: folder
-shortcode: possessionscooking
-name:
-  full: Cooking
-data:
-  parent: possessionsmiscgear
-  color: "#7a4b2a"
+shortcode: harbor
+name: { full: Harbor }
+type: lore
+subType: concept
 ---
-```
 
-| `data` property | Values                                    | Description                                                                    |
-| --------------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
-| `parent`        | `Address`, or a map of them keyed by pack | The folder this one sits in — one address, or one per pack. Unset at the root. |
-| `color`         | `"#RRGGBB"`, a string                     | The folder's colour. Unset for Foundry's default.                              |
+# Harbor
 
-A folder is addressed `<package>-none-folder-<shortcode>` — **`none`**, because a
-`Folder` is a core Foundry document like a `JournalEntry` or a `Scene`, not a
-system's. Its shortcode is [an address segment](#the-canonical-address) like
-every other, so it is strictly lowercase alphanumeric: `possessionscooking`,
-never `possessions-cooking`, which would read as two segments and resolve to
-nothing.
-
-**`color` must be quoted**, and YAML gives no third option: `color: #7a4b2a`
-parses as `null` (a `#` after a space opens a comment) and `color: 000000` parses
-as the number `0`. Write `"#RRGGBB"` to retain the string.
-
-`parent` is an address, so a dangling one is an ordinary dead-address finding
-rather than a special-cased `Unknown folder id`, and a cycle is refused. Both are
-reported when the tree is read, not when something happens to reference the
-folder that carries them.
-
-**`parent` may be a map keyed by pack**, because a folder's _identity_ is one
-thing and its _hierarchy_ is another. The same folder is deliberately filed
-under different parents in different packs: an item compendium is browsed by
-kind, a journal compendium is read by subject.
-
-```yaml
-data:
-  parent:
-    default: ~ # at the root of the items pack
-    journals: descriptions # under Rules/Descriptions in the journals pack
+A sheltered place where ships load and unload.
 ```
 
-`default` is every pack that is not named; an explicit `~` under a pack key means
-_at the root there_, which is a different statement from saying nothing. A plain
-scalar — the everyday spelling, and the right one wherever the hierarchies agree
-— is exactly `{ default: <value> }`. The folder keeps **one id** across every
-pack it materialises in, which is what files a documentation journal beside the
-item it describes; only its parent differs.
-
-Every key but `default` names a **pack the package declares**, and one that names
-none is a finding of its own. It cannot be a harmless surplus: the compile asks
-the map for the pack it is writing and falls back to `default` when there is no
-such key, so a mistyped `journal:` files the folder wherever the default puts it
-— exactly the hierarchy the key was written to override, and silently.
-
-**A folder note carries no prose.** It is structure, not content, so it produces
-no documentation journal and takes no part in `docEntryTypes`.
-
-**It declares no pack.** Which packs a folder materialises in is derived from
-[what references it](#the-compendium-folder), and its ancestors materialise with
-it; a folder nothing references materialises nowhere.
-
-**Its Foundry `_id` is derived from its address**, stable across runs, so a new
-folder needs no invented id. An authored `id` is kept where one is present —
-which is what lets a tree sweep its folder YAML into notes without a world that
-already holds those folders losing them. Two folders claiming one id is a build
-error.
+The note's readable Address is `<package>-note-lore-harbor`. In prose, link to it with `[[lore-harbor|Harbor]]`. The package segment comes from `package-build.config.yaml`; a regular wikilink defaults to the readable `note` system. An image embed such as `![[icon-harbor|Harbor]]` defaults to `none` instead.
 
-The derivation is `makeId("folder", "<package>-none-folder-<shortcode>")`, and
-the namespace is **`folder`**, not the `document` one [every other note hashes
-under](#the-document-id): a folder and an item sharing a shortcode would
-otherwise derive the same id, and Foundry keys the two in separate collections
-so neither would complain. The content index publishes this value, so a consumer
-reads a folder's id rather than recomputing one.
+The [first-note guide](authoring/first-note.md) shows the build commands and how to add a system document. Use the [command reference](commands.md) for exact flags and the [diagnostics guide](diagnostics.md) for located errors.