@heroiclands/package-build 22.21.0 → 22.23.0

package/docs/reference/format-details.md

@@ -352,7 +352,9 @@ order without changing the Markdown body.
 
 #### Dates and calendars
 
-A canonical date is `<year>[.<day>[:HHMMSS]]`. The day is one-based within the world's year. `720` covers the whole year; `720.136` covers that day; `720.136:143005` identifies one second. Negative years are valid. Prefix either form with `~` to express uncertainty beyond its written interval. `unknown` is allowed only in fields that accept an unknown occurrence.
+A canonical date is `<year>[.<day>[:HHMMSS]]`. The day is one-based within the world's year, bound against `data.year.days` on the world's `place` note. A tree whose notes declare no world year bounds no day: the value is read as written, however large. `720` covers the whole year; `720.136` covers that day; `720.136:143005` identifies one second. Negative years are valid. Prefix either form with `~` to express uncertainty beyond its written interval. `unknown` is allowed only in fields that accept an unknown occurrence.
+
+**Quote a canonical date that states a day.** `born: "667.130"` is read as written; unquoted, YAML parses the scalar as a number and a trailing zero on the day is gone before any date reader sees it, so `667.130` and `667.13` arrive as one value. A number-valued date is an error wherever appending a zero to its day would still name a day inside the world's year — the message names the file, the line and both readings — and is read as written where no such day exists, since `675.2810` is no day of a 365-day year. A bare year loses nothing and needs no quotes.
 
 A named date uses `datefrom <calendar> <date>`, where the final text follows the calendar's `data.formats.std` pattern, or its first named pattern when `std` is absent. For example, a calendar with `std: "MM/DD/Y GGG"` reads `datefrom commoncal 01/23/326 VR`, `datefrom commoncal 01/326 VR`, and `datefrom commoncal 326 VR`. Omitting the day or month retains month or year precision in frontmatter. The CLI `datefrom` command requires a day to produce one canonical day. The calendar argument is a shortcode or Address. A time follows the day only when specified in the pattern, or as a trailing `HH:mm:ss` when the pattern has no clock tokens. A named date with an era-relative year names its era.
 
@@ -699,12 +701,12 @@ exactly as `seat` declares `place` — a bare shortcode takes its type from the
 declaration, and qualification climbs the same short-form ladder every other
 link uses.
 
-| field       | default type | accepts         | resolves into                | on                                        |
-| ----------- | ------------ | --------------- | ---------------------------- | ----------------------------------------- |
-| `icon`      | `icon`       | `icon`, `image` | `document.img`               | every Actor/Item type, and embedded items |
-| `tokenIcon` | `icon`       | `icon`, `image` | `prototypeToken.texture.src` | Actor types                               |
-| `bgImage`   | `image`      | `icon`, `image` | `background.src`             | map types                                 |
-| `banner`    | `image`      | `icon`, `image` | the site hero image          | any note; not a Foundry field             |
+| field       | default type | accepts         | resolves into                 | on                                        |
+| ----------- | ------------ | --------------- | ----------------------------- | ----------------------------------------- |
+| `icon`      | `icon`       | `icon`, `image` | `document.img`                | every Actor/Item type, and embedded items |
+| `tokenIcon` | `icon`       | `icon`, `image` | `prototypeToken.texture.src`  | Actor types                               |
+| `bgImage`   | `image`      | `icon`, `image` | `background.src`              | map types                                 |
+| `banner`    | `image`      | `icon`, `image` | the site hero image, 1792×768 | any note; not a Foundry field             |
 
 All four are authored under `data:`:
 
@@ -748,7 +750,7 @@ noticed:
 | `packFolder`           | `Address` or pack map  | The shared compendium folder Address.                                |
 | `harnworld`            | `Map<string, unknown>` | HârnWorld source details.                                            |
 | `icon`                 | `Address`              | The document's profile art — an `icon` address, resolved into `img`. |
-| `banner`               | `Address`              | The page's hero image — an `image` address.                          |
+| `banner`               | `Address`              | The page's hero image — an `image` address, cut to 1792×768.         |
 
 `icon` is legal everywhere because most types compile into a document that
 carries one; where a type's passes emit none, the lint says so and the value is
@@ -851,12 +853,12 @@ ships as the Foundry module `harn-ensemble`) writing `images/map.webp`:
 And for the same note writing `sohl/assets/icons/noun/shield.svg`, a file the
 system ships and this repository does not hold:
 
-| Surface     | Address                                                   |
-| ----------- | --------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`               |
-| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository  |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`  |
-| **Book**    | not carried — a build stages only what this package ships |
+| Surface     | Address                                                       |
+| ----------- | ------------------------------------------------------------- |
+| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`                   |
+| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository      |
+| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`      |
+| **Book**    | not carried, unless a declared replacement carries it instead |
 
 **The content package name and Foundry id are separate values.**
 `harnensemble` is what the content is called, what a note writes, and what the
@@ -882,6 +884,29 @@ index enabled, an asset with no matching note is a located build error. See
 [asset bindings](../configuration.md#packagebuildstagedir-and-packagebuildassets)
 for the configuration and cache requirements.
 
+**A package declared as a replacement is carried into the book, from its
+fetched archive, when it answers the address; every other foreign package
+stays not carried.** A relationship declaring `assetReplacement: true` names a
+dependency whose asset tree answers this package's own addresses first — see
+[`relationships`](../configuration.md#relationships) — and the book is the one
+surface that otherwise refuses a foreign file outright, so it is the one
+surface this changes. A `thalorna` note embedding
+`![[thalornaaltart-none-icon-anvil|An anvil]]` names `thalornaaltart`'s own
+address, exactly as a note citing `sohl`'s shared bestiary art would; when
+`thalornaaltart` is declared with `assetReplacement: true` and its fetched
+archive carries `icon-anvil` under its own package, the book stages that file
+from the archive instead of printing the caption with no picture. A note
+citing a different package's own address this way — `sohl`'s bestiary art,
+say — stays refused exactly as the row above states, because `sohl` was never
+declared as a replacement: a package answers in place of another only when it
+opted in, never because its archive happens to carry a file at the same type
+and shortcode.
+
+A relationship declaring `assetReplacement: true` whose archive was never
+fetched is a configuration mistake, not an ordinary unresolved address: the
+book reports a located error naming the relationship and instructing
+`package-build deps fetch`, rather than printing a caption with no picture.
+
 **The host is configuration.** `site.assets` in `package-build.config.yaml` is
 the root the web form is joined onto, and a package-owned image on a page with
 none set is an error naming that key.
@@ -925,6 +950,18 @@ Foundry destination: searching a built `packs-json` tree for it turns up
 nothing. It reaches the generated page and the book's section plates, and
 nothing else.
 
+**A hero image is 1792×768.** It fills one fixed strip wherever it is drawn, so
+every banner is cut to that size and a picture of any other size is a finding
+naming both sizes — resize the picture to match. The size is stated once, by the
+slot itself, which is what gives an artist a figure to work to before any file
+exists.
+
+No other art slot states a size, and none of them asks anything of a picture's
+dimensions. An `icon` is drawn at a nominal size per medium whatever its file
+holds; a map's `bgImage` sets its own scene's dimensions, so it is whatever size
+the map is; and a picture written in prose is fitted to the room it has. Those
+three accept whatever they are given.
+
 It is an `Address` all the same, defaulting to type `image`, so a section note
 writes `banner: skillbnr` and a note borrowing another package's plate writes
 `banner: packagebuild-none-image-skillbnr`. The resolved record carries the
@@ -1683,14 +1720,17 @@ carries no frontmatter, no anchors and no `foundry` block: a file declares
 nothing about itself, compiles into no document, and publishes no page, so the
 `address` holds the canonical key and no page slug.
 
-| `asset` field | Source     | What it says                                                       |
-| ------------- | ---------- | ------------------------------------------------------------------ |
-| `path`        | the walk   | Where the file sits inside the emitting package's asset directory. |
-| `attribution` | provenance | The person holding the rights, to whom attribution is legally due. |
-| `source`      | provenance | Where it came from — a URL, or a sentence.                         |
-| `ai`          | provenance | Whether the file is machine-generated — `true` or `false`.         |
-| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.       |
-| `notes`       | provenance | Anything else a person reading the attribution needs.              |
+| `asset` field | Source     | What it says                                                                                                                                                                                                                         |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `path`        | the walk   | Where the file sits inside the emitting package's asset directory.                                                                                                                                                                   |
+| `attribution` | provenance | The person holding the rights, to whom attribution is legally due.                                                                                                                                                                   |
+| `source`      | provenance | Where it came from — a URL, or a sentence.                                                                                                                                                                                           |
+| `ai`          | provenance | Whether the file is machine-generated — strictly the YAML boolean `true` or `false`; any other value is a finding, never a stringified record. Unstated resolves to `false`.                                                         |
+| `license`     | provenance | The licence it is used under — an SPDX identifier, or terms.                                                                                                                                                                         |
+| `notes`       | provenance | Anything else a person reading the attribution needs.                                                                                                                                                                                |
+| `role`        | provenance | What the picture is for — `portrait`, `emblem`, `banner`, `plate` or `map`. Absent for an ordinary picture; a value outside that set is a finding. The `image` type only — a value on an `icon` address is a finding and is dropped. |
+| `width`       | the walk   | The file's pixel width, read from its own header. Blank for an SVG, which has no pixel dimensions.                                                                                                                                   |
+| `height`      | the walk   | The file's pixel height, read from its own header. Blank for an SVG, which has no pixel dimensions.                                                                                                                                  |
 
 Every field is present on every record, blank where nothing states one. A fixed
 shape is what lets a consumer read `asset.license` without first asking whether
@@ -1709,6 +1749,90 @@ joins its own root onto it:
 Foundry paths use the **Foundry package id**. The two values are both `thalorna`
 for this image; `harnensemble` content uses `harn-ensemble` in its Foundry paths.
 
+##### What a role declares
+
+`role` names what the picture is for, from a closed set:
+
+| Role       | What it names                                            |
+| ---------- | -------------------------------------------------------- |
+| `portrait` | A picture of a subject — a being, a building, an object. |
+| `emblem`   | A device, arms, a sigil — a mark rather than a scene.    |
+| `banner`   | A wide strip across the head of a page or a book plate.  |
+| `plate`    | A full-measure illustration meant to be looked at.       |
+| `map`      | A plan or chart, read by examining its detail.           |
+
+An asset declaring no role is an ordinary picture: there is no default role
+name, only the absence of one. A value outside this set is refused with a
+finding naming the file, the key and the accepted values, and the record
+carries no role rather than the one it was given. `role` belongs to the
+`image` type only — an `icon` address carries one nominal size per medium
+whatever the file holds, so a `role` declared there is a finding and is
+dropped rather than carried through.
+
+A declared role makes two checks possible. **Shape**, an error, flags an
+asset whose aspect ratio departs from the median of every other asset
+sharing its role — the expectation is derived from the role-sharing group
+itself at build time, never from a second, hand-kept table. **Resolution**,
+a warning, flags an asset whose pixel width falls short of what its role's
+largest print slot needs. Both exempt a vector asset, which carries no pixel
+dimensions and no aspect that survives being drawn at a nominal size.
+
+`role: map` also selects a `:::figure` fence's counter — see
+[figures and numbered references](../authoring/links-and-markup.md#figures-and-numbered-references).
+A fence whose picture draws an address with that role counts as `Map` rather
+than `Figure`, on every surface that numbers it, because the role is the one
+fact the fence's own markup cannot state.
+
+##### What a role draws at
+
+A role names what a picture is for; it says nothing about how large one
+draws. Deciding that is a medium's own job — the book owns a table mapping
+each role to a maximum, and a website's or a Foundry system's stylesheet owns
+the equivalent table for its own surface, keyed off the role class and the
+`width`/`height` attributes the emitted markup carries (blank for a vector).
+Changing a role's slot is one line in that table, not an edit to every note
+drawing one.
+
+**Every size is a maximum, never a target.** The drawn width is the smaller of
+the role's slot and what the file's own pixels support at the medium's print
+floor:
+
+> drawn width = min(the role's slot, natural pixels ÷ the print floor)
+
+A picture is never drawn larger than it was made: a 512px portrait stretched
+across the slot a `plate` fills is a soft rectangle that reads as broken. A
+vector carries no pixel count, so nothing narrows its role's slot; it always
+draws at the slot. An `icon` address takes the medium's nominal icon size
+whatever role it might otherwise have had — `role` never reaches one, since
+the asset record refuses it there.
+
+The book's table, and the print floor it reads from the same constant its page
+geometry is set against (300 dpi):
+
+| Role                        | The book's slot                   |
+| --------------------------- | --------------------------------- |
+| `portrait`, `emblem`        | half the page's text measure      |
+| `banner`, `plate`, `map`    | the full page's text measure      |
+| an `icon` address, any role | one inch, whatever the file holds |
+
+On this book's US Letter page the text measure is about 7.00in, so a
+`portrait` or an `emblem` draws at up to about 3.50in and a `banner`, a
+`plate` or a `map` draws at up to about 7.00in — still the smaller of that
+and what the file's pixels support.
+
+**A worked example.** A `portrait`-role file measuring 900×1350px, drawn with
+no named `size=`: at 300 dpi its pixels support 900 ÷ 300 = 3.00in, which is
+narrower than the role's 3.50in slot, so the book draws it at 3.00in. The same
+picture at 1200×1800px supports 4.00in, wider than the slot, so the book draws
+it at its 3.50in slot instead — the slot bounds it, exactly as a maximum
+should. Either way the emitted markup for the website and for a Foundry
+journal carries `note-image-role-portrait` as a class and `900`/`1350` (or
+`1200`/`1800`) as its `width`/`height` attributes, which is what a stylesheet
+on either surface sizes a `portrait` from.
+
+A named `size=` written beside the embed overrides a role's slot outright, the
+same as it always has — a role decides the size nothing else states.
+
 ##### Where provenance comes from
 
 A `provenance.yaml` states the provenance fields in the table above, and nothing
@@ -1736,9 +1860,40 @@ resolving a chain by hand.
 That is also why `attribution` and `license` are **required in any record that
 exists**: a key left out is not inherited from above, it is simply absent, so a
 record stating neither leaves every file it covers with no rights holder and no
-terms. Omitting one is a finding. `source`, `ai` and `notes` stay optional,
+terms. Omitting one is a finding. `source`, `ai`, `notes` and `role` stay optional,
 because a blank is a truthful answer for each of them.
 
+##### A declared replacement resolves first
+
+A package may declare, on a `relationships.<kind>[]` entry, that a
+dependency's asset tree answers this package's own asset addresses ahead of
+its local record — `assetReplacement: true` in `package-build.config.yaml`.
+Once declared, an asset address resolves in this order:
+
+1. **Every declared replacement, in declaration order.** The package segment
+   of each relationship declaring `assetReplacement: true` is tried in the
+   order those relationships are written, and the first one carrying the
+   address wins.
+2. **Falling through to the package's own record** when no declared
+   replacement carries the address — the resolution this package already
+   performs with no `assetReplacement` declared at all.
+
+**This reaches asset types only.** A being, an item or a lore note is never
+replaced this way, whatever a relationship declares: the rule tests the
+address's type, not the relationship. A replacement answers only `icon`,
+`image` and `audio` addresses whose package segment is this package's own; an
+address naming any other type, or naming a different package, is untouched.
+
+**A replacement's own output address is never itself looked up against
+another replacement.** Resolving `thalornaaltart-none-image-thorn` never asks
+whether something replaces `thalornaaltart` — resolution is a single pass over
+the declared list, not a chain, which forecloses a cycle by construction.
+
+This is distinct from a `foreign` lookup, which serves a declared dependency's
+own content for an address this package's local index does not carry. A
+replacement is consulted **before** the local address; a foreign lookup only
+**after** it misses locally.
+
 #### A font is not an asset
 
 `assets/fonts` is not a root, and a font has no address.
@@ -2086,11 +2241,69 @@ See the [authoring examples](../authoring/links-and-markup.md#footnotes-and-defi
 # Heading {#id .class1 .class2 attr="value"}
 ```
 
-Any header can include curly braces. Inside the curly braces:
+Any header can end with a braced attribute block, in the same grammar a
+`:::figure` fence and a named block take. Inside the braces:
+
+- `#id` names the anchor a link resolves to (only one allowed)
+- `.class1` names a CSS class (any number of classes allowed)
+- `attr="value"` names an HTML attribute whose value is `value` (any number of
+  key/value pairs allowed)
+
+The id is what every surface publishes; a class and an attribute reach only the
+surfaces that have somewhere to put them.
+
+|                 | an `#id`                                                    | a `.class`            | an `attr="value"`      |
+| --------------- | ----------------------------------------------------------- | --------------------- | ---------------------- |
+| Website         | the heading's `id`, and the target of `[[note#id\|…]]`      | the heading's `class` | written on the heading |
+| Foundry journal | the anchor the page is addressed by, and the heading's `id` | the heading's `class` | written on the heading |
+| Book            | the Typst label the heading is linked to                    | dropped               | dropped                |
+
+**The book drops both**, because Typst has no stylesheet for a class to name
+and no element for an attribute to sit on. A heading whose appearance matters in
+print is set by the book's own template, not by a class an author writes.
+
+An id contains letters, digits, `_` or `-`. A class and an attribute key begin
+with a letter. Braces holding nothing the grammar recognises — a set, a die
+expression, a measurement — are one finding at the heading's line, and the
+heading is set as it was written so nothing is lost while the author reads the
+message.
+
+`id=` and `class=` are refused in favour of `#id` and `.class`, and an attribute
+beginning `on` is refused as an event handler, exactly as on a named block: a
+heading's attributes are written onto the element, so nothing authored in a note
+becomes code on a published page.
+
+#### A section withheld from players
+
+The class `secret` on the heading that opens a section withholds that section.
+The heading keeps its id, so the section stays linkable: secrecy is a property
+of the section, not of the name a link resolves to.
+
+```markdown
+# The Cellar {#cellar .secret}
+
+The contraband is behind the false wall.
+```
+
+The section runs from the heading to the next heading that opens a page, which
+is the span Foundry makes one page of.
 
-- `#id` represents an id anchor named `id` (only one allowed)
-- `.class1` represents a CSS class named `class1` (any number of classes allowed)
-- `attr="value"` represents an HTML attribute named `attr` whose value is `value` (any number of attr/value pairs allowed)
+| Surface | What a reader meets                                                                                               |
+| ------- | ----------------------------------------------------------------------------------------------------------------- |
+| Foundry | The journal page is visible to the GM alone — `ownership: { default: 0 }`, `CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE` |
+| Website | The heading and everything under it sit inside the expandable `<details>` a `:::secret` block renders as          |
+| Book    | The heading and everything under it are set in the labelled block a `:::secret` is set in                         |
+
+**On the website this is a spoiler and not access control.** The withheld
+section is in the published page, so a reader who opens the element or reads the
+source reads it — exactly as a `:::secret` block is. Foundry is the only surface
+that withholds anything from anybody. Write nothing in a `.secret` section that
+would matter if a player read it on the web.
+
+A `:::secret` block inside a withheld section is legal and renders as it does
+anywhere else. `.secret` on a heading that opens **no** page covers no page, so
+no surface can honour it: that is a finding at the heading's own line, answered
+by giving the heading an anchor or raising it to the top level.
 
 #### Images
 
@@ -2111,11 +2324,14 @@ either side of it, and every surface renders it as a figure. An image sharing a
 paragraph with prose is refused, because a width and a position mean nothing
 applied to a word in the middle of a sentence.
 
-**The alt text is the caption.** Print has no `alt` attribute and has to put
-those words somewhere a reader can see them, so every surface draws them under
-the picture; the two HTML surfaces carry them as `alt` as well. A title —
-`![alt](src "title")` — is refused rather than dropped in silence: there is one
-place for those words and this is it.
+**Alt text renders as a caption on no surface.** On the website and in a
+Foundry journal it stays on the `img` element's `alt` attribute alone, and the
+book prints nothing beneath a picture that carries none. A visible label and
+caption are drawn only for a picture wrapped in [a `:::figure`
+fence](#the-figure-fence), and the text drawn is always the fence's own
+caption. A title — `![alt](src "title")` — is refused rather than dropped in
+silence: there is one place for those words, the alt text, and a title is not
+it.
 
 ##### Width is a class, and the ordinary width carries no marker
 
@@ -2352,77 +2568,232 @@ errors. Duplicate and unknown attributes are errors.
 | `allow-empty=true`                          | Permits a query selecting no rows. Default `false`. |
 | `section-level=1` through `section-level=6` | Sets the heading level for `_section`. Default `2`. |
 
-##### Captioned blocks
+##### Page lists
 
-`:::caption {#anchor}` labels the next Markdown block, whether it is prose,
-code, a table, or an image. The closing `:::` ends the caption text; blank lines
-between the fence and its block are allowed. The ID is unique within the note
-and contains letters, digits, `_`, or `-`, beginning with a letter. An empty
-caption, missing ID, missing closer, or missing following block is an error at
-the opening line.
+A fenced `pagelist` block renders a list of the pages carrying a tag. It is the
+companion of a content table and answers the other question: a table says what
+a set of notes contains, a page list says which pages belong to a group.
 
 ````markdown
-See [[#trade|]] for the market routes.
+```pagelist {tag="key-concept" type=lore sort=type descriptions=true}
 
-:::caption {#trade}
-Regional trade routes
-:::
+```
+````
+
+**The group is the tag, not an enumeration.** A hand-written list of links is
+a second place the membership is recorded, and the two drift the moment a page
+is written and nobody edits the landing that should name it. A page list reads
+`tags:` instead, so tagging a page files it and untagging it removes it.
+
+**The fence takes no body.** Every statement about the directive is an
+attribute in the shared braced grammar, so there is one grammar to learn; text
+written inside the fence is reported rather than printed, and a fence nobody
+closed is reported rather than swallowing the rest of the note.
+
+| Attribute           | What it does                                                              |
+| ------------------- | ------------------------------------------------------------------------- |
+| `tag=`              | Required. The tag a page carries to join the list.                        |
+| `type=`             | Restricts the list to one note type. Every type by default.               |
+| `sort=name`         | Alphabetical, case and accents folded, tiebroken on address. The default. |
+| `sort=type`         | Groups the note types and orders by name within each.                     |
+| `descriptions=true` | Follows each link with the page's `description`. Default `false`.         |
+| `allow-empty=true`  | Permits a tag no page carries. Default `false`.                           |
+
+The tag is matched the way `tags:` is read everywhere else — a leading `#`,
+surrounding space and letter case are all insignificant, while the spelling of
+the tag itself is exact. Nothing guesses at a near miss.
+
+**What a list holds.** Every note of this package that carries the tag and
+publishes a page. A **stub** publishes no page, so it holds no address and joins
+no list. A documentation journal is not listed beside the note it documents,
+because they are one page. A note tagged `gm` is listed in Foundry and left out
+of the website and the book, which is the same audience rule a content table's
+relations follow.
+
+**Each entry is a link, resolved by the surface that is building.** The
+directive is answered before the body is walked and spliced in where the fence
+sat, so the list reaches a reader as compendium journal links in Foundry and
+page links on the website and in the book — the same resolution an authored
+`[[…]]` gets, including the cue on a link into a `draft` note.
+
+**A tag no page carries is an error at the fence's line and column**, naming
+the tag and, where the directive restricts one, the type. An empty list under
+an authored heading is how a misspelled tag survives a build, so the
+directive's silence is what is refused rather than its output.
+
+##### The figure fence
+
+`:::figure {#anchor .border}` declares what it numbers and, optionally,
+captions: the fence is the unit the counter counts, not the caption text it
+may or may not carry.
+
+````markdown
+:::figure {#trade}
 
 ```sql
 SELECT name.full AS "Market" FROM notes WHERE type = 'place'
 ```
-````
 
-The block displays **Table 1: Regional trade routes** and `[[#trade|]]`
-displays **Table 1** as a link. A nonempty label after the pipe takes precedence.
-The category comes from the following block: a regular code fence is code,
-a Markdown or expanded SQL table is a table, an image is a figure, and any other
-block is prose. The website and Foundry number each category within a note;
-the PDF numbers each category through the book. Foundry gives a captioned block
-its own JournalEntryPage, so its anchor has a page UUID.
+///
+Regional trade routes
+:::
+
+Refer to {{ref "#trade"}} for the market routes.
+````
 
-`:::info` and `:::warn` mark explanatory and cautionary boxes inline. Their
-content is Markdown, and the boxes carry a label and icon on the web, in
-Foundry, and in the book. An optional `{#id}` gives a box an HTML anchor.
-Close each with a whole-line `:::`. Empty, nested, and unclosed boxes are
-errors at the opening line.
+The fence displays **Table 1: Regional trade routes** and `{{ref "#trade"}}`
+displays **Table 1** as a link.
+
+**The grammar.** `:::figure` opens the fence, on a line of its own and
+optionally followed by a braced attribute block in the grammar a heading and
+a named block take too. A line of `:::` alone closes it. Between the
+two, the first `///` written alone on a line, read at the top level — outside
+any nested code fence — divides what the fence holds from its caption; a `///`
+written inside a nested fence is content, not a divider. A second top-level
+`///` is an error, naming the line: a figure holds one caption, so it carries
+one `///` line.
+
+An opening line that is not `:::figure`, optionally followed by one braced
+attribute block and nothing else, is reported at its own line as
+`a figure's attributes are written as {#id .border}`.
+
+**Every part but the fence itself is optional.**
+
+- **No `{#id}`.** The fence is still numbered and drawn; it carries no anchor,
+  so nothing can address it. An id, when written, must be a name unique within
+  the note — a repeat is `duplicate figure id "<id>"` at the fence's opening
+  line, and an id that collides with a heading anchor in the same note is
+  `heading and figure declare the same anchor "<id>"` at the heading's line.
+- **No `///`.** The fence draws its label alone, with no caption beneath it. A
+  `///` with nothing after it before the closing `:::` is an error at the
+  `///` line: a figure's `///` section carries no caption — write no `///` to
+  leave the figure uncaptioned.
+- **No `.border`.** The fence draws without one. `.border` is the only class
+  the construct declares; any other class is reported at the opening line,
+  naming it: a figure takes no such class, and the classes a figure takes
+  are `.border`. A `key="value"` attribute is reported the same way, naming
+  the key: a figure takes an id and classes, nothing else.
+
+**What is never optional.** A fence with nothing between its opening line and
+its `///` or its closing `:::` is `a figure has no contents`, at the opening
+line. An opening `:::figure` with no matching `:::` runs to the end of the
+note and is `a figure needs a closing :::`, also at the opening line, and
+nothing after it is scanned as a second fence.
+
+**The counter is derived, never authored.** The fence's contents decide which
+of four counters it draws from — `Code`, `Table`, `Figure`, `Prose` — read from
+the first top-level block inside the fence: a table is `Table`; a fenced `sql`
+block is `Table`, because its rendered output is one; any other fenced or
+indented code block is `Code`; one or more pictures and nothing else is
+`Figure`; everything else is `Prose`. A table or a picture written outside any
+`:::figure` fence draws no label and is counted nowhere. The website and a
+Foundry journal number each counter within the note; the book numbers each
+counter across the book in reading order.
+
+**A heading that would start its own journal page cannot be written inside a
+fence.** An H1, or a heading at any level carrying an `{#anchor}`, is reported
+at its own line inside one: `a heading that starts a page cannot be written
+inside a figure — keep an H1 or an anchored heading at the top level, or drop
+the anchor and the level to stay inside it`.
+
+**The `ref` expression renders a link to a figure's anchor.**
+`{{ref "#thorn"}}` renders "Figure 13"; `{{ref "#thorn" form="full"}}` renders
+the number and the caption; `{{ref "#thorn" form="title"}}` renders the
+caption alone. `form="number"` is the default and may be written explicitly;
+a `form` outside this closed set is reported naming the three. A link written
+inside the figure's own caption contributes only its label text to a `full`
+or `title` reference, because the reference is itself a link, and emphasis
+inside the caption is kept. `form="full"` or `form="title"` aimed at a figure
+with no caption is reported naming the anchor: that form needs a caption, and
+the figure has none. An address naming no figure in the note is reported
+naming the anchor; an address naming another note's figure —
+`{{ref "other-note#anchor"}}` — is reported as addressing a figure this build
+does not resolve outside the note carrying the reference. Only a same-note
+anchor resolves, on the website and in the book.
+
+Foundry gives a `:::figure` fence its own JournalEntryPage. A fence holding
+exactly one picture, captioned in plain text with nothing else — or carrying
+no caption at all — becomes a page of type `image`: the picture is its `src`,
+a caption, when there is one, is `image.caption`, and the page is named for
+the figure's own number. Every other fence becomes a page of type `text`
+instead: a fence grouping more than one picture; an embedded sound, there
+being no audio page type; a fence whose caption carries inline markup —
+emphasis, a link, an embedded icon or image — because `image.caption` is a
+`StringField` with nowhere to render it; and a fence that shares its split
+with prose that follows it, because an `image` page has nowhere to carry that
+prose either. On a `text` page the render is the fence's own content, scanned
+and labelled as the first of its kind on that page alone and then corrected to
+the number the note-wide scan already assigned, so a second figure with no id
+is still named for its true, note-wide number rather than recounted from one.
+
+##### Named blocks
+
+`:::secret`, `:::info` and `:::warn` set a passage apart from the prose around
+it. The opener and the closing `:::` each take a whole line, the content is
+Markdown and renders normally, and the fences stay outside code blocks. An
+empty, nested or unclosed block is an error at its opening line, as is a name
+that is not one of the three.
+
+A braced attribute block may follow the name. It takes an id as `#id`, classes
+as `.class`, and any other attribute as `key="value"`. `title` is reserved and
+supplies the heading; without it a block heads itself **Secret**, **Info** or
+**Warn**. A title carries its own emphasis and nothing else — a tag written
+there is escaped. `id=` and `class=` are refused in favour of `#id` and
+`.class`, and an attribute beginning `on` is refused as an event handler.
 
 ```markdown
 :::info
 The harbor remains open through winter.
 :::
 
-:::warn {#flood-warning}
+:::warn {#flood-warning title="Seasonal closure"}
 Spring floods close the eastern road.
 :::
-```
 
-```
-:::secret
-This is secret text
+:::secret {#harbor .wide}
+The harbor master is working for the smugglers.
 :::
 ```
 
-Use a whole-line `:::secret` opener and a whole-line `:::` closer to mark a GM passage. Markdown inside the block, including links and emphasis, renders normally. Keep the fences outside code blocks and close each one before starting another. An unclosed or nested block is a build error at the source line.
+The block's name is the first class on the emitted element and the author's
+classes follow it. **No block carries an inline `style`**, so the appearance is
+a stylesheet's. The base stylesheet styles `section.info` and `section.warn`;
+`section.secret` is left to Foundry, which styles it and owns the reveal control
+on it.
 
-In FoundryVTT, the passage is a secret section visible to the GM and owners of the journal:
+In FoundryVTT a block is a section whose first line is its heading, and a
+`secret` is the section Foundry shows to the GM and to owners of the journal:
 
 ```html
-<section class="secret" id="secret-example">
-  <p>This is secret text</p>
+<section class="secret wide" id="harbor">
+  <strong>Secret</strong><br />
+  <p>The harbor master is working for the smugglers.</p>
 </section>
 ```
 
-On webpages, the passage appears as a collapsed spoiler that any reader can open:
+A `secret` that states no id of its own is given one derived from its body, so
+that Foundry can remember the section once a reader reveals it.
+
+On webpages a block is a disclosure any reader can open, titled in its summary:
 
 ```html
-<details>
-  <summary>Spoiler</summary>
-  <p>This is secret text</p>
+<details class="secret wide" id="harbor">
+  <summary class="secret">Secret</summary>
+  <p>The harbor master is working for the smugglers.</p>
 </details>
 ```
 
-In books, the passage is visible under a **GM note** label. A printed page has no reader permissions or interactive disclosure control.
+In a book each block is a coloured box headed by its title. A printed page has
+no reader permissions and no interactive disclosure control, so a `secret` is
+visible there.
+
+**A secret is a presentation distinction and not access control.** It is in the
+same authored note as the prose around it, and a reader who inspects source or
+generated output may see it.
+
+**A malformed block does not silence the blocks around it.** It is reported at
+its own line and left as the author wrote it, and every well-formed block in the
+note still renders.
 
 #### Actors
 
@@ -2432,11 +2803,6 @@ The following H1 headers are treated specially:
 
 - `# ... {#appearance}`: The contents of this header become the `doc.appearance` property in sohl and `doc.description` in hm3.
 - `# ... {#dossier}`: The contents of this header become the `doc.dossier` property in sohl and `doc.biography` in hm3.
-- `# ... {#spoilers}`: The contents of this header are not written to the actor at all.
-
-For JournalEntries, the following rules apply:
-
-- `# ... {#spoilers}`: The contents of this header go into a page which is viewable only by the GM (`CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE`).
 
 **Archetypes** describe characters in broad terms and help match them to an adventure. The list is:
 
@@ -2529,31 +2895,41 @@ data:
 
 #### The bodies a being belongs to, and its standing in each
 
-**Membership**: `{rank: number, office: string}`, both optional.
+**Membership**: `{rank: number, office: string}` — `rank` required, `office` not.
 
 `data.affiliations` is a **map keyed by the body's Address**, and each entry is
 the standing the being holds in that body. The key is what makes the pair
 expressible: a being in two bodies holds a standing in each, and two bodies may
 call a rung the same word.
 
-An entry carries two optional keys and nothing else:
+An entry carries two keys and nothing else:
 
-- **`rank`** — a **number**, the level on that body's own `governance.ranks`
-  ladder. The body declares `{level, title, description}` for every rung, so a
-  number indexes into it and the body stays the single source for what its
-  level 5 is called.
-- **`office`** — a **string**, matched against the keys of that body's
+- **`rank`** — **required**, a **number**, the level on that body's own
+  `governance.ranks` ladder. The body declares `{level, title, description}` for
+  every rung, so a number indexes into it and the body stays the single source
+  for what its level 5 is called.
+- **`office`** — optional, a **string**, matched against the keys of that body's
   `governance.offices` map.
 
-An entry with neither is valid and is the ordinary shape: it says the being
-belongs to the body and nothing more.
+**Every entry states a `rank`**, because belonging to a body is holding some
+standing in it. Where nothing more is known the rung is `1`, the ordinary
+member; `0` is the rung for someone cast out, which is a real answer rather than
+a default — the ladders carry `0 Níding`, `0 Outlaw` and `0 Struck from the
+Roll`. Between them the two ends cover every standing a member can hold, so an
+entry that states no rank is an **error** at the entry's own line, and the
+message names both numbers rather than only the gap.
+
+An entry carrying an **office and no rank** is that same error and not a second
+one, reported once: an office distinguishes a person within a standing rather
+than standing in for one, so such an entry puts a person in a post in nothing.
+An entry carrying a rank and no office is complete.
 
 ```yaml
 data:
   affiliations:
     affiliation-vrystwldtrbs: { rank: 5, office: War Chief }
     affiliation-greenwardens: { rank: 1 }
-    affiliation-silverguild: {}
+    affiliation-silverguild: { rank: 0 }
 ```
 
 Both values are checked against the body the entry is keyed by. A `rank` that
@@ -2942,12 +3318,46 @@ two is the commonest way to get a non-monarchy wrong.
 **Rank**
 Definition of a level within the organization (e.g., Priest, Layperson, Member, Gang Leader, Master, etc.)
 
-| Property      | Values    | Description                                                                                                                          |
-| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `level`       | number    | The ranking within the affiliation, increasing values starting with 1, 0 indicates intentional exclusion (expulsion/excommunication) |
-| `title`       | string    | Title associated with the Rank                                                                                                       |
-| `description` | string    | Description of the Rank                                                                                                              |
-| `lore`        | `Address` | The standing this rank _is_ — a `lore` note of subType `law`, shared with every other body that confers the same thing               |
+| Property      | Required | Values    | Description                                                                                                                          |
+| ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `level`       | yes      | integer   | The ranking within the affiliation, increasing values starting with 1, 0 indicates intentional exclusion (expulsion/excommunication) |
+| `title`       | yes      | string    | Title associated with the Rank                                                                                                       |
+| `description` | yes      | string    | Description of the Rank                                                                                                              |
+| `lore`        | no       | `Address` | The standing this rank _is_ — a `lore` note of subType `law`, shared with every other body that confers the same thing               |
+
+**`level`, `title` and `description` together are a complete statement of a
+rung**, and nothing further is required for a ladder to be correct. Each is an
+**error** when it is missing or empty, and a `level` that is not a whole number
+is an error too: the ladder is what a member's `rank` indexes into, so a rung
+with no title makes a standing that resolves to nothing, and one with no
+description ships a rung that says nothing on a sheet or a page. A rung accepts
+only these four keys, and each problem on a rung is reported separately, so a
+ladder with three is fixed in one pass rather than three builds.
+
+**A level belongs to one rung.** Two rungs claiming one level is an **error** on
+the second, naming the first, because the ladder is read by level: a member whose
+`rank` is that level answers to whichever rung is written higher in the file, and
+moving two lines renames the standing. A body that confers two titles at one
+standing writes them as one rung — `title: Knight or Dame` — or gives each its
+own level.
+
+```yaml
+data:
+  governance:
+    ranks:
+      - { level: 0, title: Vrystrith, description: Kinless and owed nothing. }
+      - { level: 4, title: Fródrád, description: A householder whose word carries. }
+      - level: 5
+        title: Hárár
+        description: First among them, by the assent of the householders.
+        lore: lore-harar-standing
+```
+
+**Reach for `lore` only where the standing needs more said about it than a
+description can hold** — obligations, rights, what it takes to enter it, what
+ends it. Most rungs do not: a description that states what the standing is has
+already said the whole of it, and a note that restates the rung it hangs off
+costs a reader a click and tells them nothing.
 
 **A rank's `lore` is shared; its `title` is not.** A Normen kingdom calls it
 `Thrall` and a Vylarian province calls it `Slave`, and they mean one standing:
@@ -3597,18 +4007,49 @@ the setting itself, rather than instructions or other apparatus for the GM.
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
 
-| `data` property | Values                                                                        | Description                                                  |
-| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `epoch`         | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1         |
-| `months`        | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year           |
-| `weekdays`      | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously |
-| `seasons`       | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                   |
-| `namedDays`     | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                     |
-| `eras`          | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year        |
-| `formats`       | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default           |
-| `event`         | map                                                                           | A dated occurrence and its chronology metadata               |
+| `data` property         | Values                                                                        | Description                                                                         |
+| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                |
+| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                  |
+| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                        |
+| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                          |
+| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                            |
+| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                               |
+| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                  |
+| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields |
+| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                               |
+| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                    |
+| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                 |
+| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                  |
+| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                         |
+
+`data.events` is available on every `lore` subType. Each entry's `kind`, `depth`, `summary`, `sources`, `standing`, `accounts`, `who`, `where`, `unresolved`, `follows` and `names` hold its chronicle detail; their shapes belong to whatever design governs chronicle records, and this format only asks that they sit inside an entry. The shared format checks `when`, `until` and `recurs`; a content package can check the rest. `events` itself does not appear as an infobox row, but a recurring entry's computed next occurrence does.
+
+An entry reads by what it authors beside `when`:
+
+| authored                          | reads as                                        |
+| --------------------------------- | ----------------------------------------------- |
+| `when`                            | happened once                                   |
+| `when` + `until`                  | ran continuously from then to then              |
+| `when` + `recurs`                 | happened then and happens still                 |
+| `when` + `until` + `recurs.every` | happened then, again on the period, and stopped |
+
+`recurs.every` and `recurs.on` are exclusive — a period with named exceptions is written as an enumeration instead. `recurs` is refused beside `born` or `died`, and beside a `when` of year `0`. `until` is refused beside `recurs.on`, whose own last entry already bounds it.
+
+**The period advances the canonical year, never the era-relative year.** There is no year `0` in era-relative numbering — era year `-1` sits immediately before era year `1` — but canonical year `0` is an ordinary integer on the continuous axis `canonicalYear` builds, so a period of whole years steps on it with no special case at an epoch crossing. Precision and approximation carry through untouched: a year-precision anchor yields year-precision occurrences, an approximate anchor's occurrences are approximate too, and an anchor inside a short intercalary month recurs on that same day in every occurrence, with no special case for the month being short. Each occurrence selects its own era by testing its position against the anchor's calendar, so a later occurrence may print in a different era than its anchor, or print bare where no count was proclaimed for that year — neither is ever a finding, since nobody authored the occurrence.
+
+**Year `0` means any year.** An entry whose `when` states year `0` recurs on that day of every year — `when: "0.5"` is the fifth day of the year, in every year. The value must be quoted, for the reason every canonical date stating a day must be: an unquoted `<year>.<day>` reaches the check as a float, and a day's trailing zero is lost before a date is read. Beside a year-`0` entry, `recurs` is refused (the entry is already annual), `until` is allowed and bounds the series, and the entry carries no `canonicalYear`, era or `sort` — it cannot date its own note. A note's date is its first entry stating a real year.
+
+```yaml
+data:
+  events:
+    - when: 412.1
+      recurs: { every: 1 }
+    - when: "0.286"
+      until: 940.1
+```
 
-`data.event` is available on every `lore` subType. It holds structured chronology metadata, including an event's kind, date, sources, and affected places. The shared format checks that it is a map; a content package can check its details. It does not appear as an infobox row.
+The first entry is an anniversary counted from canonical day `412.1`, recurring every year with no end. The second is an autumn rite — the two-hundred-eighty-sixth day of every year — that was kept until canonical year 940 and no longer is.
 
 #### Calendar note structure
 
@@ -3620,7 +4061,7 @@ name: { full: The Common Calendar }
 type: lore
 subType: calendar
 data:
-  epoch: 1.1
+  epoch: "1.1"
   months:
     - { name: Floralis, abbreviation: Flor, days: 30 }
     - { name: Lusenar, abbreviation: Luse, days: 31 }
@@ -3869,7 +4310,7 @@ data:
 # its moon — a note of its own, because a moon is a body and not a property
 data:
   body: { diameterKm: 3800, orbitalRadiusKm: 388600, orbit: circular, inclined: true }
-  moon: { cycle: 30, newOn: 720.1, eclipses: rare }
+  moon: { cycle: 30, newOn: "720.1", eclipses: rare }
 ```
 
 **`year.days` is where the year's length lives, and every calendar in the