@heroiclands/package-build 19.0.0 → 20.0.0

package/docs/content-format.md

@@ -161,6 +161,22 @@ document rather than the note. `title` is the one field this applies to; `subTyp
 is the other declared item field spelled like a note-level key, and there the two
 levels mean the same thing by design.
 
+**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 until #330 a note could stamp one, and the compiled pack shipped one
+world's play state to every world that installed it.
+
+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.
+
 **A `WikiLink` becomes a shortcode where the target field expects one.** SoHL
 stores cross-references as shortcode strings, which is what the `Code` suffix
 marks: `data.assocSkill` is a link to a skill note, and `system.assocSkillCode`
@@ -208,6 +224,16 @@ 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 (#345). 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
@@ -219,7 +245,7 @@ type.
 | `name.full`             | `name`                    | `name`                       |
 | `img`                   | `img`                     | `img`                        |
 | `id`                    | `_id`                     | `_id`                        |
-| `packFolder` / `folder` | `folder`                  | `folder`                     |
+| `packFolder`            | `folder`                  | `folder`                     |
 | `shortcode`             | `system.shortcode`        | NA                           |
 | `data.templatePriority` | `system.templatePriority` | `flags.hm3.templatePriority` |
 | `actionDefs`            | `system.actionDefs`       | NA                           |
@@ -231,6 +257,30 @@ 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.
 
+**`img` 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 an
+authored path is simply dropped — the note validates, the tree compiles, and the
+value goes nowhere.
+
+Since a dropped value looks exactly like a value never written, the frontmatter
+lint **reports it**: an `img:` (or `portrait:`) authored on a type whose passes
+emit neither 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. `img: 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.
+
 Actor types (`being`, `vehicle`) add one more:
 
 | shared source   | → sohl            | → hm3             |
@@ -240,7 +290,20 @@ Actor types (`being`, `vehicle`) add one more:
 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.
+actor types alone. Note the asymmetry in where the two are authored: `img` stays
+at the note's top level and `portrait` moved under `data:`, because a note's
+token art is a fact about the _note as a published artefact_ while the portrait
+is a fact about the _subject_.
+
+**A `data:` source is still read at the top level, for now.** `data:` (#128) did
+not invent the facts it holds — it gathered them out of the top level, where
+`portrait:` sat beside `img:` — so every key it collected has a **pre-`data:`
+spelling** that is read after the declared one and reported as retiring. Write
+`data.portrait`; a tree still on `portrait:` compiles to the identical document
+and gets a warning naming the line, until a later release removes the position.
+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.
 
 **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`
@@ -268,6 +331,74 @@ 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.
 
+#### An asset path's first segment says which package owns it
+
+`img` and `portrait` are paths, and a path has to say **which package holds the
+file** — because a module's content routinely cites the system's art, while the
+system's content never cites the module's. The first segment answers that, and
+there are exactly three answers:
+
+| Authored path starts with | Owner                 | Emitted              |
+| ------------------------- | --------------------- | -------------------- |
+| `systems/`                | a separate **system** | unchanged            |
+| `modules/`                | a separate **module** | unchanged            |
+| anything else             | **this package**      | `<assetRoot>/<path>` |
+
+`<assetRoot>` is `<packageKind>/<foundryPackage>/assets`, derived from the
+configuration — `systems/sohl/assets` for the system,
+`modules/sohl-thalorna/assets` for that module. So one authored
+`icons/relic.svg` means "my own `assets/icons/relic.svg`" in whichever package
+writes it, while an authored `systems/sohl/assets/icons/noun/shield.svg` names
+the system's file and is left exactly as written wherever it appears. That
+second case is not hypothetical: every default this toolchain pairs with an item
+type is a `systems/sohl/…` path, so a module's compiled documents carry it
+verbatim.
+
+**The third row is "anything else", not a list of directories.** It is a rule
+about ownership: a package owns its whole `assets/` tree, and the directory
+names inside it are that package's business. `sohl-kethira-basic` keeps art
+under `assets/artwork/`, and `artwork/deity.webp` is rooted under its assets by
+the same rule that roots `icons/…` and `images/…` there.
+
+An address naming **no** package passes through untouched, which is that same
+rule rather than an exception — an absolute URL, a `data:` URI and a `/`-rooted
+path each already address something no package owns, so prefixing any of them
+would break an address that was already correct.
+
+`worlds/` is deliberately **not** exempt. A package may not ship art out of a
+world, so a note writing one has made a mistake; prefixing it yields a plainly
+broken path rather than a plausible one that 404s in Foundry with nothing
+reporting it.
+
+#### `banner:` addresses the CDN, not the Foundry install
+
+**`banner:` is a path, and it does not follow the rule above.** It is worth
+stating plainly, because the two fields look alike and a value written for one
+resolves somewhere else entirely under the other.
+
+`banner:` never reaches a compiled document — searching a built `packs-json`
+tree for it turns up nothing. It is a top-level key, so it passes through to the
+generated page, and its only consumer is the Hugo theme, whose
+`partials/banner-url.html` applies its own rule: an absolute URL passes through,
+and **anything else is prefixed with `images/`** and joined onto
+`params.cdnBaseURL`. A `banner:` written to the package rule therefore resolves
+to a doubled path:
+
+```text
+banner: systems/sohl/assets/images/banners/lore.webp
+      → <cdnBaseURL>/images/systems/sohl/assets/images/banners/lore.webp
+```
+
+That can be made to work by mirroring the path on the CDN, and one consumer
+does exactly that — but it is not what the author meant.
+
+**The two are not reconciled, because they are not two spellings of one thing.**
+`img:` addresses a file inside a Foundry install, where the package that holds
+it is the question worth asking. `banner:` addresses a file on a CDN, where
+there are no packages at all. Write a `banner:` relative to the CDN's `images/`
+root — `banners/lore.webp`, not `images/banners/lore.webp` and not a
+package-rooted path.
+
 #### The pack a note compiles into
 
 `pack` names which configured compendium receives the note's document.
@@ -396,10 +527,23 @@ _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.
+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 (#310).
 
 **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
@@ -409,7 +553,7 @@ 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
+`packFolder: <address>` 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
@@ -629,22 +773,58 @@ The full address is the unambiguous form, and almost nothing uses it — 92 of
 12,056 links in the current trees. The rest rely on shorter forms, each dropping
 segments from the left:
 
-| form                            | resolves by                                  |
-| ------------------------------- | -------------------------------------------- |
-| `package-system-type-shortcode` | exactly, always                              |
-| `package-type-shortcode`        | `(type, shortcode)` within the named package |
-| `type-shortcode`                | `(type, shortcode)` within this package      |
-| `shortcode`                     | `shortcode` within this package — see below  |
-
-The last row is the everyday case, and it means two different things by
-context. In a **frontmatter field** the type segment is supplied by the field's
-own declaration, so `tashal` is a complete address. In **body prose** there is no
-field to supply it, so a bare shortcode is resolved across types and must match
-exactly one; an ambiguity is an error naming the candidates.
+| form                            | expands to                                               |
+| ------------------------------- | -------------------------------------------------------- |
+| `package-system-type-shortcode` | itself                                                   |
+| `system-type-shortcode`         | `<this package>-system-type-shortcode`                   |
+| `type-shortcode`                | `<this package>-<this block's system>-type-shortcode`    |
+| `shortcode`                     | as above, with the type from the field's own declaration |
+
+There is no `package-type-shortcode`: the forms are exactly the **suffixes** of
+the canonical address, so naming another package means naming its system too.
+`kethira-place-tashal` is three segments, which reads as system `kethira`, and
+fails.
+
+#### An omitted segment defaults from where the link is written
+
+It is **not** a wildcard and resolution is not a search. Every short form expands
+to exactly one canonical address before anything is looked up, so a lookup either
+finds one entry or none — there is no candidate set, and a cross-package
+ambiguity is impossible by construction.
+
+- **package** omitted → the current package. A short address therefore names
+  _this_ package and never falls through to a dependency; reaching another one is
+  the fully qualified form's job.
+- **system** omitted → **the system block the link is written under**. Anywhere
+  under `sohl:` is `sohl`; anywhere under `hm3:` is `hm3`; **anywhere else** —
+  top-level frontmatter, `data:`, and body prose — is `none`. The enclosing block
+  decides at any depth, so `sohl.items[3].model` and `sohl.system.body.structure`
+  default alike; the field has no say.
+
+**Under `none`, a system-bearing type addresses its documentation.** A note's
+`none` address _is_ its `doc<type>` journal — the Item is the one with a system —
+so a prose `[[affiliation-sirvadar|Sirvadar]]` names the page, which is what
+prose almost always means. A prose link that means the **Item** states the
+system: `[[sohl-affiliation-sirvadar|…]]`.
+
+Only a type whose own document carries a system is redirected this way. A
+`macro` and the map types have documentation journals too, but their own
+documents are core ones already at `none`, so `macro-autoattack` names the Macro
+and `docmacro-autoattack` its journal — two live addresses.
+
+**An address is lowercase throughout** (#340). Every segment — package,
+system, type and shortcode alike — is `^[a-z0-9]+$`, so a capital anywhere in an
+address is an error naming the lowercase form.
+
+The shortcode was the exception until #340: it was case-sensitive and routinely
+mixed (`Clb`, `LtShoe`, `HsTunic`) while the address built from it was lowercased
+wholesale, so the authored name and its address disagreed. Two names differing
+only in case are two names nobody can tell apart, and they collapsed onto one
+address, one `_id` and one URL with nothing to report it.
 
 **Parsing is positional counting from the right, and nothing else.** Every
 segment is alphanumeric — shortcodes, **types** and **subTypes** are all
-`^[A-Za-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
+`^[a-z0-9]+$`, systems come from a closed registry, and `contentPackage` is
 alphanumeric — so the hyphen is purely a separator. There is no longest-match
 against a roster and no vocabulary check before splitting.
 
@@ -659,7 +839,7 @@ 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 letters and digits only (^[A-Za-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
+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
 ```
 
 One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
@@ -672,7 +852,7 @@ No retirement-specific code outlived the sweep.
 
 That is a guarantee rather than an observation, and it holds: of **4,456 distinct
 shortcodes** across the four content trees, not one contains a character outside
-`[A-Za-z0-9]`. It is load-bearing, so relaxing the charset later would break
+`[a-z0-9]`. It is load-bearing, so relaxing the charset later would break
 resolution with nothing to say so.
 
 `type/shortcode` with a slash is the legacy form, still resolved so links written
@@ -735,14 +915,21 @@ nowhere is a typo or an omission, and both want fixing.
 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           |
-| `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 vendor the manifest |
-| `ambiguous`      | more than one package publishes the short form | write `[[package-type-shortcode\|Text]]`  |
-| `unknown-anchor` | the address resolves; the `#section` does not  | correct the anchor                        |
+| 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 since #336; kept for the manifest_ | —                                                      |
+| `unknown-anchor` | the address resolves; the `#section` does not   | correct the anchor                                     |
+
+`ambiguous` no longer fires. An omitted segment defaults rather than wildcarding,
+so a written target expands to one canonical address and a lookup returns one
+entry or none — two claimants is a state the grammar can no longer reach. The
+reason is retained so a consumer switching on it does not break, and because a
+vendored manifest built by an older toolchain may still carry the finding.
 
 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
@@ -813,19 +1000,6 @@ 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.
 
-#### Not yet implemented
-
-One rule in this section is settled but unbuilt, and describes the target rather
-than current behaviour:
-
-- **The `<system>` segment.** `readQualifier` reads package, type and shortcode;
-  there is no system segment. A four-segment target today parses as
-  `package-type-shortcode` with a hyphenated shortcode, or fails.
-  The corpus is close to the rule already. Of 12,056 links, 10,413 are
-  `[[type-shortcode|Label]]`, which is correct as written. Two authored links use
-  an unpiped multi-segment target, and 69 use a pipe with a note name where an
-  address belongs; those are the migration.
-
 ### What a note produces
 
 Note types fall into two groups, and only the first has a mapping table.
@@ -847,6 +1021,21 @@ 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.
 
+That has been true of actors only since #337. A being used to produce its Actor
+and nothing else, which left it the one system-bearing note with no address at
+`none` — so a prose link naming it had nowhere to land. It now carries a
+documentation journal like every other such note, addressed
+`<package>-none-docbeing-<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
@@ -1112,6 +1301,62 @@ Generates a living (or undead, or spirit) being.
 | `appearance.complexion`     | `string`                                       | Complexion                                                                                       |
 | `appearance.extra_features` | `string[]`                                     | Extra features                                                                                   |
 
+#### 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 |
+
+**`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** (#334). 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.
+
 #### Identifying a being's embedded items
 
 Each entry in `sohl.items` compiles into one embedded Item, and its `_id` is
@@ -1121,28 +1366,26 @@ 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:
+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:
-    - shortcode: dgr # selects the catalogue's dagger
-      type: weapongear
+    - model: weapongear-dgr # the catalogue's dagger
       name: Dagger 1
       system:
         shortcode: dgr1 # this dagger's own identity
-    - shortcode: dgr
-      type: weapongear
+    - 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 catalogue's `dgr`,
+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
@@ -1210,7 +1453,7 @@ the divine, magic, the spirit world — and that partition is load-bearing rathe
 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
+**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.
@@ -1377,7 +1620,7 @@ one, at `sohl.system.title`.
 
 Represents an affliction.
 
-**subType**
+**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)
@@ -1406,8 +1649,11 @@ Represents an affliction.
 | `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.
 
@@ -1420,8 +1666,41 @@ If `sohl` is present, this becomes an `affliction` item.
 | `data.contagionIndex`              | `system.contagionIndexBase`          | NA    |
 | `data.outcomeTraumas`              | `system.outcomeTraumas`              | 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.
 
 ### type: armorgear
 
@@ -1624,7 +1903,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 
 ### type: projectilegear
 
-**subTypes**:
+**subType**:
 
 - none
 - arrow
@@ -1661,7 +1940,7 @@ HM3 side while remaining distinct on the SoHL side.
 
 ### type: skill
 
-**subTypes**:
+**subType**:
 
 - social
 - nature
@@ -1708,17 +1987,42 @@ Note: `hm3.system.type` (skill types) use the values "Craft", "Physical", "Commu
 - 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 |
+| `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" will be 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    |
+| 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
 
@@ -1749,7 +2053,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 
 In-world information about people, places, or concepts.
 
-subType:
+**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.
@@ -1765,6 +2069,12 @@ subType:
 - 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 |
 | --------------- | ------ | ----------- |
@@ -1792,7 +2102,7 @@ the place from the map is the end that cannot, because a map is written once and
 depicts what it depicts. A place's maps are therefore derived — every map whose
 `place` is this one — and the relation exists in exactly one place.
 
-subType:
+**subType**:
 
 - battlemap: Tactical scale, for a scene played out square by square.
 - localmap: Roughly a kilometre across — a settlement, a holding, a small valley.
@@ -1851,11 +2161,16 @@ single Level is synthesised from `img`, `overlay`, `levelName` and
 > system would want the identical art — so the field sits beside every other
 > note's `img` rather than inside a system block.
 >
-> `image` is **retired in favour of it**, in the three steps `package:` took
-> (#56), and this is the first: both spellings are read, `img` wins where a note
-> carries both, and a note still writing `image` gets a located **warning**
-> rather than a refusal. It compiles to the byte-identical document, so failing
-> a build over it would red a tree that has done nothing wrong.
+> `image` was **retired in favour of it**, in the three steps `package:` took
+> (#56), and all three have now run
+> ([package-build#149](https://github.com/HeroicLands/package-build/issues/149)).
+> Through the window both spellings were read, `img` won where a note carried
+> both, and a note still writing `image` got a located **warning** rather than a
+> refusal — it compiled to the byte-identical document, so failing a build over
+> it would have redded a tree that had done nothing wrong. The trees were then
+> swept, and the alias dropped. `image` is now simply not a key a map has: in a
+> `sohl:` block it is reported as unknown, and either way the note is refused
+> for the `img` it never declared.
 
 **Two unit conventions, deliberately.** Geometry — walls, doors, lights, tiles,
 sounds, region shapes — is authored in **pixels**, Foundry's native storage,
@@ -1895,7 +2210,7 @@ three maps, and none of those maps needs to know it is a keep.
 
 ### type: place
 
-subType:
+**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.
@@ -1938,7 +2253,7 @@ place it depicts — see `type: map` below.
 
 Content prepared to be played — a situation with its cast, places, and possible outcomes.
 
-subType:
+**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.
@@ -1957,7 +2272,7 @@ subType:
 
 ### type: doc
 
-subType:
+**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.
@@ -2198,3 +2513,10 @@ 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 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 (#310).