@heroiclands/package-build 17.1.0 → 18.0.0

package/docs/content-format.md

@@ -138,6 +138,18 @@ it _there_, and a system that disagrees is not in error. A weapon weighs what
 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 the key a system block still carries are two
+declarations.** The mapping tables name the shared source — `data.species` — and
+the corpus writes the same fact inside the block it has always written it in —
+`hm3.species`. Those are two positions for one field, and both are read while
+the corpus moves, with the block winning. A field says so by naming each: its
+shared source, and the legacy in-block key it is being swept off. Reading it
+from the legacy position is _reported_, so the sweep has a progress signal, and
+the note compiles to the identical document either way — the same read-both,
+report-one shape every other retirement in this format uses. Until #305 the two
+were one declaration, so a field could name only one of them, and a row this
+table stated was reachable only by a note that had already moved.
+
 **A field whose spelling means something else at the note level has no shared
 source.** The fallback assumes the two vocabularies agree about what a name
 means, and they do not always: a note's top-level `title` is the heading its page
@@ -166,7 +178,7 @@ 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`,
+never inferred from a coincidence of names: `skill`, `weapongear`, `armor`,
 `containergear` and `miscgear` exist in both systems with _different_ data
 models, so name-matching there would not fail, it would succeed wrongly.
 
@@ -174,6 +186,22 @@ 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
@@ -186,8 +214,16 @@ 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 |
-| ------------- | ------ | ----- |
+| shared source           | → sohl                    | → hm3                        |
+| ----------------------- | ------------------------- | ---------------------------- |
+| `name.full`             | `name`                    | `name`                       |
+| `img`                   | `img`                     | `img`                        |
+| `id`                    | `_id`                     | `_id`                        |
+| `packFolder` / `folder` | `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
@@ -197,13 +233,377 @@ that matter.
 
 Actor types (`being`, `vehicle`) add one more:
 
-| shared source | → sohl | → hm3 |
-| ------------- | ------ | ----- |
+| shared source   | → sohl            | → hm3             |
+| --------------- | ----------------- | ----------------- |
+| `data.portrait` | `system.portrait` | `system.bioImage` |
+
+An actor carries `img` (its token art) and `portrait` (its sheet portrait)
+independently, which is why this is a row of its own rather than a second
+spelling of the one above. An Item has no second image, so the row applies to
+actor types alone.
+
+**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
+(`HeroicLands/package-build#283`). The row states the mapping the format makes;
+the gap is in the pass, not in the table.
+
+#### The pack a note compiles into
+
+`pack` names which configured compendium receives the note's document.
+
+```yaml
+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 no longer 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` overrides it for one system.** A note that compiles into two
+systems can send each document to its own pack:
+
+```yaml
+pack: items-sohl
+hm3:
+  pack: items-hm3
+```
+
+**Unstated, the document goes to the pack of its type marked `default: true`.**
+Where no pack of that type is the default, the build refuses rather than
+guessing, and names the candidates.
+
+Three 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.                           |
+
+#### 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
+> (`HeroicLands/package-build#266`) — 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 of HM3's passes write it — an Item's flag was missing
+until `HeroicLands/package-build#283`, which made an item note's priority reach
+SoHL and stop at HM3, with nothing said on either side.
+
+**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. A consumer holding a
+content-index entry can therefore recompute a document's id, and so its
+compendium UUID, from the `canonical` key alone; it is not a value the index has
+to transport.
+
+**Why the address and not an authored string.** A note used to declare an
+opaque 16-character `id` — 6,343 of them across the four content trees — which
+said nothing its address did not, could not be read or reviewed, and was
+guaranteed by nothing: `content-lint` refuses a **duplicate address** across
+every pack of a document type, which is exactly the scope a primary document's
+id must be unique within, and it said nothing at all about a duplicate `id`. So
+the derived id inherits a guard that already exists, where the authored one had
+none. It is the same principle that turned `folder: ONXsqZAIZr2qzxTb` into
+`packFolder: <path>` above: an opaque derived identity does not belong in
+authored content.
+
+**An authored `id` still wins**, and that is how a document's identity is
+**pinned**:
+
+```yaml
+type: miscgear
+shortcode: bowlcer
+id: plaiQQm2T5zVK5mO # pinned: this document keeps this id
+```
+
+A blank `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 note **declares** the rename (below).
+
+**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:`.
+
+#### Declaring a rename
+
+A note names the shortcode it used to be published under:
+
+```yaml
+type: weapongear
+shortcode: Taburi
+renamedFrom: Tabri
+```
+
+`(type, shortcode)` is a **published interface** — every satellite that declares
+`itemCatalog: true` assembles its beings out of those addresses — so renaming a
+shortcode breaks other repositories, and `content-build addresses diff` exists to
+say so before a release does. To be useful it has to name where the address
+_went_, and since ids are derived it can no longer work that out for an unpinned
+note: both sides of the match move together, and the rename reads as a
+withdrawal.
+
+**Pinning an `id` needs foresight; a declaration needs only hindsight.** A pin
+has to be written _before_ the rename, by an author who does not yet know they
+will make one. An author who has just renamed a shortcode knows exactly what the
+old one was, and that is the only moment anyone does — so this is the key to
+reach for, and `id:` stays what it is for: keeping a document's identity across
+the rename, which is a different question from explaining it.
+
+**It takes one shortcode or a list**, because renames chain: the diff runs
+against a released baseline, and a shortcode may have been renamed more than once
+since. List every name the baseline might still know it by.
+
+```yaml
+shortcode: Taburin
+renamedFrom:
+  - Tabri
+  - Taburi
+```
+
+**It is transient.** Once every baseline a build is compared against post-dates
+the rename, the declaration has nothing left to say and should be deleted. That
+is what separates it from an `id:` pin, which is permanent.
+
+**One key per note, at the top level**, however many systems the note compiles
+into: a shortcode is the note's rather than a system block's, so a note carrying
+`sohl:` and `hm3:` blocks compiles two documents that share one shortcode, and
+one declaration covers both.
+
+**What a declaration changes is what the diagnostic can say, not what it says
+about you.** A finding reports which of the two joins it had, because they are
+not equally checkable — a matched id is a fact a reader can verify in both
+artefacts, while a declaration is the author's word:
+
+```text
+since sohl@0.8.2, weapongear:Tabri is no longer published; the note now
+published as weapongear:Taburi declares it was renamed from Tabri. Every
+package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
+```
+
+A rename that is neither pinned nor declared is still reported as a
+**withdrawal**. Nothing infers a successor from a similar-looking string: a wrong
+one sends the reader to the wrong fix, which is worse than saying nothing.
+
+`content-lint` holds a declaration to the same rules a current address is held
+to. An entry must be a well-formed shortcode, must not be the note's own, and
+must name an address the package actually **vacated** — an entry naming an
+address some note still publishes is refused, as are two notes claiming one
+predecessor, since an address had one holder and so has one successor. A repeat
+of the same entry is a warning; the declaration still works.
+
+#### The compendium folder
+
+A note says which folder of its pack it lands in. Two spellings are read, and
+`packFolder` wins where both are present:
+
+```yaml
+packFolder: poisonsandtoxins # a folder note's address
+folder: ONXsqZAIZr2qzxTb # a Foundry id
+```
+
+**`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.
+
+**`folder` is a Foundry id**, and is unchanged: a note that names one is read,
+resolved and emitted exactly as before.
+
+**Which one a value is comes from the field it was written in, never from the
+string.** Both are alphanumeric, so there is nothing in the value to tell them
+apart.
+
+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.
+
+That derivation is what makes a whole class of defect unrepresentable. The
+folder used to be declared twice, once per pack, in two files free to disagree:
+`sohl-thalorna` was missing 57 of its item folders from its journal folder file
+and `sohl-kethira-basic` had no journal folder file at all, so both emitted
+documentation journals into folders their own pack never declared — silently.
+With one folder note and one address there is no second file to disagree with
+the first.
+
+> **`packFolder` was a path** for one release (`Possessions/Misc_Gear/Cooking`).
+> A path encoded the hierarchy in the value, so reparenting a folder made every
+> note naming it wrong — a structural edit became a corpus-wide rewrite. The
+> path form is **removed**, not deprecated: nothing authored it yet, which is
+> the whole reason the change was cheap enough to make.
+
+#### 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.
+
 ### WikiLinks
 
 Twenty-seven fields in the tables below take a `WikiLink`, and a link is written
@@ -477,11 +877,11 @@ objects with a SoHL counterpart — `Arrow (Longbow)`, `Bolt (Crossbow)`,
 both blocks. Only four are companions: `Javelin (thrown)`, `Shorkana (thrown)`,
 `Spear (thrown)`, `Taburi (thrown)`.
 
-**A companion note requires its system's type.** With one block and no
-counterpart, 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. So
-`hm3.type` is _required_ on a single-block note, and is an override only on notes
-that carry both.
+**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:
 
@@ -495,6 +895,133 @@ Any header can include curly braces. Inside the curly braces:
 - `.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)
 
+#### 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 = "armor"
+```
+````
+
+**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 (#246). 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.
+
+**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 used to need: the authored `ORDER BY` decides the section order too.
+
+**Beware `folder`.** It is a note's _pack_ folder, not its directory — the
+directory is `file.folder`.
+
+###### 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
@@ -562,42 +1089,84 @@ The following H1 headers are treated specially:
 
 Generates a living (or undead, or spirit) being.
 
-| `data` property             | Values                                         | Description                                                                                     |
-| --------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `portrait`                  | `string`                                       | File path to the portrait image                                                                 |
-| `templatePriority`          | `number`                                       | Template priority, _null_ = not a template                                                      |
-| `archetypes`                | `Archetype[]`                                  | List of archtypical behaviors                                                                   |
-| `occupation`                | `string`                                       | Name of the character's occupation                                                              |
-| `stations`                  | `WikiLink[]`                                   | Name of the stations the character belongs to                                                   |
-| `lore`                      | `WikiLink[]`                                   | Lore concerning this being — the people it is of, the standing it holds, the law it lives under |
-| `homes`                     | `WikiLink[]`                                   | Place the being calls home                                                                      |
-| `affiliations`              | `WikiLink[]`                                   | Affilliations (e.g., arcane/divine traditions, polities, etc)                                   |
-| `gender`                    | `male \| female \| other`                      | Gender of the character                                                                         |
-| `species`                   | `WikiLink`                                     | Being's species (lore)                                                                          |
-| `age`                       | `number`                                       | Age of the character                                                                            |
-| `birthday`                  | `YYYY/MM/DD`                                   | Date of birth of the character                                                                  |
-| `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                                                                                  |
+| `data` property             | Values                                         | Description                                                                                      |
+| --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `portrait`                  | `string`                                       | File path to the portrait image                                                                  |
+| `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                                                               |
+| `stations`                  | `WikiLink[]`                                   | Name of the stations the character belongs to                                                    |
+| `lore`                      | `WikiLink[]`                                   | Lore concerning this being — the people it is of, the standing it holds, the law it lives under  |
+| `homes`                     | `WikiLink[]`                                   | Place the being calls home                                                                       |
+| `affiliations`              | `WikiLink[]`                                   | Affilliations (e.g., arcane/divine traditions, polities, etc)                                    |
+| `gender`                    | `male \| female \| other`                      | Gender of the character                                                                          |
+| `species`                   | `WikiLink`                                     | Being's species (lore)                                                                           |
+| `age`                       | `number`                                       | Age of the character                                                                             |
+| `birthday`                  | `YYYY/MM/DD`                                   | Date of birth of the character                                                                   |
+| `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                                                                                   |
+
+#### 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 entry's _top-level_
+`shortcode` is a **selector** — it names the catalogue template the entry is
+written from and is never written to the document — so two entries may share
+one:
+
+```yaml
+sohl:
+  items:
+    - shortcode: dgr # selects the catalogue's dagger
+      type: weapongear
+      name: Dagger 1
+      system:
+        shortcode: dgr1 # this dagger's own identity
+    - shortcode: dgr
+      type: weapongear
+      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 catalogue'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.** The key used to carry 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.
 
 If a `sohl` property is present, a SoHL actor of type "being" will be created.
 
-If an `hm3` property is present, an HM3 actor is created. Its document type is derived from the note's `subType`; `hm3.type` overrides that, and must be `character` or `creature`.
+If an `hm3` property is present, an HM3 actor is created. 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 will be created, as will an "HM3" document.
 
-| shared source           | → sohl            | → hm3                        |
-| ----------------------- | ----------------- | ---------------------------- |
-| `data.portrait`         | `system.portrait` | `system.bioImage`            |
-| `data.templatePriority` | `system.template` | `flags.hm3.templatePriority` |
-| `data.species`          | NA                | `system.species`             |
-| `data.gender`           | NA                | `system.gender`              |
-| `data.occupation`       | NA                | `system.occupation`          |
+| shared source     | → sohl | → hm3               |
+| ----------------- | ------ | ------------------- |
+| `data.species`    | NA     | `system.species`    |
+| `data.gender`     | NA     | `system.gender`     |
+| `data.occupation` | NA     | `system.occupation` |
 
 ### type: homepage
 
@@ -618,10 +1187,8 @@ Represents a conveyance able to hold goods and people moving from one place to a
 
 If `sohl` is present, this becomes a `vehicle` actor.
 
-| shared source           | → sohl            | → hm3 |
-| ----------------------- | ----------------- | ----- |
-| `data.portrait`         | `system.portrait` | NA    |
-| `data.templatePriority` | `system.template` | NA    |
+It maps nothing beyond the shared rows above, actor row included: a vehicle
+carries a portrait and a template priority and no field of its own.
 
 ### type: affiliation
 
@@ -856,7 +1423,7 @@ If `sohl` is present, this becomes an `affliction` item.
 | `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
 | `data.resolutionDurationFormula`   | `system.resolutionDurationFormula`   | NA    |
 
-### type: armorgear
+### type: armor
 
 Note: `data.quantity` may not be specified. Quantity is always 1.
 
@@ -870,7 +1437,9 @@ Note: `data.quantity` may not be specified. Quantity is always 1.
 
 If a `sohl` property is present, a SoHL item of type "armorgear" will be created.
 
-if a `hm3` property is present, an HM3 item of type "armorgear" will be created.
+if a `hm3` property is present, an HM3 item of type "armorgear" will be created. The
+note type is `armor` in both cases: the `gear` suffix named a document subtype rather
+than the thing the note is about.
 
 | shared source     | → sohl                  | → hm3           |
 | ----------------- | ----------------------- | --------------- |
@@ -902,7 +1471,7 @@ if a `sohl` property is present, a SoHL item of type "attribute" will be created
 | shared source | → sohl | → hm3 |
 | ------------- | ------ | ----- |
 
-### type: concoctiongear
+### type: concoction
 
 **subType**:
 
@@ -1043,13 +1612,7 @@ if a `sohl` property is present, a SoHL item of type "mystery" will be created.
 
 if a `sohl` property is present, a SoHL item of type "mysticalability" will be created.
 
-If an `hm3` property is present, an HM3 item is created. The following mappings are performed:
-
-- if `subType` === `arcaneinvocation`, `hm3.type` = `spell`
-- if `subType` === `divineinvocation`, `hm3.type` = `invocation`
-- if `subType` === `arcanetalent`, `hm3.type` = `psionic`
-
-If `hm3.type` is specified, it must be `psionic`, `spell` or `invocation`.
+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.
 
 | shared source           | → sohl                        | → hm3         |
 | ----------------------- | ----------------------------- | ------------- |
@@ -1061,7 +1624,7 @@ If `hm3.type` is specified, it must be `psionic`, `spell` or `invocation`.
 | `data.charges.value`    | `system.charges.value`        | NA            |
 | `data.charges.max`      | `system.charges.max`          | NA            |
 
-### type: projectilegear
+### type: projectile
 
 **subTypes**:
 
@@ -1175,7 +1738,7 @@ if a `sohl` property is present, a SoHL item of type "weapongear" will be create
 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. **`weapon` has no `subType`**: SoHL distinguishes a weapon's uses with strike modes rather than by kind, and HM3's document type follows from which of those the note describes. A note carrying both blocks is a `weapongear` in each; a companion note carrying only `hm3:` states `hm3.type` itself, and is usually a `missilegear` — see _One note is at most one document per system_.
+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           |
 | ----------------- | ----------------------- | --------------- |
@@ -1310,8 +1873,8 @@ Foundry, so the build refuses rather than resolving.
 > system-specific, and HM3 would want the identical Scene. Authoring it under
 > `sohl:` means a map produces nothing for a system-agnostic build and carries a
 > SoHL infobox implying a specificity it does not have. It is the same class of
-> mistake as storing `archetype` in flags: the data went where the only available
-> container was, rather than where it belongs. Three notes carry it today.
+> mistake as storing the template priority in flags: the data went where the only
+> available container was, rather than where it belongs. Three notes carry it today.
 
 **A map is always a leaf.** Its frontmatter references nothing outside itself.
 `notes:` is a list of `[anchor, GridLocation]`, and each anchor names a heading in
@@ -1489,3 +2052,150 @@ need an authoring convention of their own.
 
 The note's `img` is a content-relative path resolved the way every other note's
 is; a note that authors none takes Foundry's own `icons/svg/dice-target.svg`.
+
+### type: bundle
+
+A bundle of notes to be taken as a single unit — an `Adventure` in Foundry VTT.
+
+| `data` property | Values       | Description                                            |
+| --------------- | ------------ | ------------------------------------------------------ |
+| `contents`      | `WikiLink[]` | The documents the Adventure holds; `[]` when unstated. |
+
+```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.
+
+**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 only when the bundle names it by its own `doc…` address:
+`miscgear-bowlcer` is the item, `docmiscgear-bowlcer` its description page.
+
+**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.
+
+**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.
+
+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.
+
+**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 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.
+
+**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.
+
+### type: folder
+
+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.
+
+```yaml
+---
+type: folder
+shortcode: possessionscooking
+name:
+  full: Cooking
+data:
+  parent: possessionsmiscgear
+  color: "#7a4b2a"
+---
+```
+
+| `data` property | Values                                     | Description                                                                    |
+| --------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
+| `parent`        | `WikiLink`, 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.                              |
+
+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 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`. All 639 colour values across the five trees are already
+written `"#RRGGBB"`.
+
+`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
+```
+
+`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.