@heroiclands/package-build 22.14.3 → 22.15.0

package/docs/content-format.md

@@ -326,6 +326,42 @@ flow collection is formatted into one of those forms; folded collections are
 not used. `content-build format --write` applies this rule and the top-level
 order without changing the Markdown body.
 
+#### Dates and reckoning markers
+
+A calendar names and orders the days within a year. An **era** states where its
+year count begins. Several eras may use one calendar; each has its own origin.
+An era may declare a short, uppercase `marker` for authored dates. The marker
+selects that era and the calendar whose months interpret the date inside it:
+
+```yaml
+data:
+  born: VR(676/12/5)
+```
+
+`VR` is a marker declared on an era row of the Common Calendar. `VR(720/5/14)`
+means its year 720, fifth month, fourteenth day. `VR(720/5)` states month
+precision, and `VR(720)` states year precision. The parser retains that
+precision; it does not invent a first day when the author only knows a year.
+`VR(~-480)` keeps an approximate year. A date whose occurrence is known but
+whose value is not recorded is `unknown`, with no marker.
+
+The calendar-neutral spelling is `<year>.<day>[:HHMMSS]`: `720.136` names day
+136 of canonical year 720, and `720.136:143005` adds 14:30:05. The dot means
+**day of year**, not a month. Its day must fit the world's `data.year.days`,
+and its time must fit a 24-hour day. A bare year is also accepted. Unmarked
+slash dates are accepted as calendar-neutral numeric month/day values; their
+month division has no named calendar, so use a marker when the month is part
+of a people's reckoning.
+
+An era's `start` locates its first year on the canonical timeline. The marker's
+own start is written canonically, such as `start: 1`, so its definition has no
+circular reference. Another era may place its start using a marker already
+defined in the corpus. A year-precision start anchors the reckoning at the
+first day of that canonical year for conversion; it does not date the event
+that gave the era its name. A marker must be unique across the corpus and contain
+uppercase letters or digits, beginning with a letter. An optional `end` bounds
+dates in that era; a year-precision end includes the whole named year.
+
 **`data:` is closed.** It holds the type-specific facts about the
 subject — a weapon's weight, an affliction's transmission, a being's species —
 and every note type declares which keys it may carry. A misspelled key is a
@@ -2066,10 +2102,10 @@ place for those words and this is it.
 
 ##### Width is a class, and the ordinary width carries no marker
 
-| `class` value | book          | website            | Foundry journal  |
-| ------------- | ------------- | ------------------ | ---------------- |
-| _(none)_      | one column    | the text measure   | the page measure |
-| `.full-width` | the full page | full content width | full page width  |
+| `class` value | book                          | website            | Foundry journal |
+| ------------- | ----------------------------- | ------------------ | --------------- |
+| _(none)_      | natural width within a column | natural width      | natural width   |
+| `.full-width` | page measure                  | full content width | full page width |
 
 The simple case needs no spelling, which is why the ordinary width has no name.
 
@@ -2080,21 +2116,24 @@ refused.
 
 ##### Named size is `size:`
 
-| `size` value | display                  |
-| ------------ | ------------------------ |
-| `auto`       | same as omitting `size:` |
-| `small`      | same as omitting `size:` |
-| `medium`     | same as omitting `size:` |
-| `large`      | same as omitting `size:` |
-| `xlarge`     | same as omitting `size:` |
-| `full-width` | same as omitting `size:` |
-
-The parser accepts and records these names for Markdown images and embedded
-assets. **A `size:` value does not change the displayed dimensions** on the
-website, in Foundry, or in the book. With no `size:`, the parser records `auto`;
-the existing rendering rules apply. In particular, book images occupy a column
-unless they carry `.full-width`. A `size:` may sit before or after `float:` in
-the same directive, and neither changes the other's behavior.
+| `size` value | website and Foundry | book         |
+| ------------ | ------------------- | ------------ |
+| `auto`       | natural size        | natural size |
+| `small`      | 64 CSS pixels       | 1.6 cm       |
+| `medium`     | 128 CSS pixels      | 3.2 cm       |
+| `large`      | 256 CSS pixels      | 5.6 cm       |
+| `xlarge`     | 512 CSS pixels      | 8 cm         |
+| `full-width` | content measure     | page measure |
+
+These are maximum display widths for Markdown images and embedded assets;
+height follows the file's aspect ratio. The available column, page, or browser
+measure caps every size, and print also caps image height within the page.
+Omitting `size:` means `auto`, which uses the file's natural dimensions within
+those bounds. `full-width` spans the book's page rather than one column. The
+`.full-width` class also grants page scope in print; when it accompanies a
+bounded `size:`, the image keeps that bounded width inside the page figure.
+A `size:` may sit before or after `float:` in the same directive, and neither
+changes the other's behavior.
 
 ##### Position is `float:`
 
@@ -2449,6 +2488,19 @@ an acquaintance knows them without a strong disposition; a rival opposes them
 without implacable hostility; a nemesis opposes them personally and
 implacably. The infobox groups targets by term and links to their notes.
 
+```yaml
+data:
+  socialTies:
+    being-kaldor: patron
+    being-alys: dependent
+    affiliation-silverguild: nemesis
+    kethira-note-being-kaldas: rival
+```
+
+The full Address names a target in another package. Each target has one tie:
+writing its short and full Address in the same map still names one target and is
+an error.
+
 Each tie is one-sided. The target need not name the subject back, even when
 `patron` and `dependent` would describe opposite ends of the same support.
 Kinship, household membership, organizational membership, rank, and office are
@@ -3422,15 +3474,15 @@ In-world information about people, places, or concepts.
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
 
-| `data` property | Values                                                                  | Description                                                                       |
-| --------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `epoch`         | `date`                                                                  | Which in-world day the world's clock reads zero on                                |
-| `months`        | `{ name, abbreviation?, days }[]`                                       | The months this calendar keeps, in order — the list sums to the world's year      |
-| `weekdays`      | `{ name, abbreviation? }[]`                                             | The days of the week it names, in order; a calendar with no week writes none      |
-| `seasons`       | `{ name, abbreviation?, monthStart?, monthEnd?, dayStart?, dayEnd? }[]` | The seasons it marks, bounded by month or by day of year                          |
-| `eras`          | `{ shortcode, name, abbreviation?, proclaimedBy?, start, end? }[]`      | The year-counts kept in it, each addressed `<calendar shortcode>.<era shortcode>` |
-| `dateFormats`   | `Map<slot, format>`                                                     | Calendaria display formats for this calendar                                      |
-| `event`         | `Map<field, value>`                                                     | A dated occurrence, with its sources, locations, reach, and relationships         |
+| `data` property | Values                                                                      | Description                                                                        |
+| --------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `epoch`         | `date`                                                                      | Which in-world day the world's clock reads zero on                                 |
+| `months`        | `{ name, abbreviation?, days }[]`                                           | The months this calendar keeps, in order — the list sums to the world's year       |
+| `weekdays`      | `{ name, abbreviation? }[]`                                                 | The days of the week it names, in order; a calendar with no week writes none       |
+| `seasons`       | `{ name, abbreviation?, monthStart?, monthEnd?, dayStart?, dayEnd? }[]`     | The seasons it marks, bounded by month or by day of year                           |
+| `eras`          | `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, end? }[]` | The year-counts kept in it; a marker names one era and uses this calendar's months |
+| `dateFormats`   | `Map<slot, format>`                                                         | Calendaria display formats for this calendar                                       |
+| `event`         | `Map<field, value>`                                                         | A dated occurrence, with its sources, locations, reach, and relationships          |
 
 `data.event` is available on every `lore` subType. It holds structured
 chronology metadata, including the event's kind, date, sources, and the places
@@ -3447,13 +3499,13 @@ the year and says where the count begins, and one that does neither is prose
 about time rather than a calendar.
 
 ```yaml
-type: lore
-subType: calendar
 shortcode: commoncal
 name:
   full: The Common Calendar
+type: lore
+subType: calendar
 data:
-  epoch: 720/1/1
+  epoch: VR(720/1/1)
   months:
     - { name: Floralis, abbreviation: Flor, days: 30 }
     - { name: Lusenar, abbreviation: Luse, days: 31 }
@@ -3463,6 +3515,7 @@ data:
   eras:
     - shortcode: founding
       name: After the Founding
+      marker: VR
       abbreviation: AF
       proclaimedBy: vylarinmpr
       start: 1
@@ -3489,8 +3542,10 @@ that: `months` must sum to `year.days`, and a list that does not describes a
 different world rather than a different calendar.
 
 **An era is a way of counting years within a calendar**, so its rows sit beside
-the months. Each states its own `shortcode`, unique within the note, and a date
-names one by writing it after the calendar's address — `3 commoncal.founding`.
+the months. Each states its own `shortcode`, unique within the note. A date
+names an era with its marker, such as `VR(720/5/14)`. A calendar may contain
+several era rows, each with its own marker and year origin. The marker is an
+authoring identifier; the `abbreviation` is its printed label.
 `proclaimedBy` is optional: a reckoning whose proclaiming body is unknown, or
 whose body has no note, says so by leaving it out.
 
@@ -3500,115 +3555,96 @@ that names none.
 
 ### type: map
 
-A map — the visual rendering of a place or an encounter, plus the pinned
-locations described in its own body. Produces a Foundry **Scene**, and a web page carrying the map image
-and its description.
+A map note has its own prose and a Foundry Scene. A map can depict a place or an encounter. Several maps can depict the same place; the map names that place with `sohl.place`, while the place note does not list its maps.
 
-A map is a note in its own right rather than a property of a `place`, for three
-reasons. A place commonly has **several** maps — a floor per level of a keep, or
-a feature's detail map alongside its local-area map — and a scene nested in a
-place could only ever be one. A Scene is a substantial document in itself: walls,
-doors, lights, tiles, sounds, region shapes and pins, authored in two deliberate
-unit conventions. And a map has prose and named locations of its own, which makes
-it a document rather than a field.
+**subType**:
 
-A map may also exist with no place at all — an ambush on a road is an encounter
-map and not a named location.
+- `battlemap`: A tactical Scene built in Foundry.
+- `localmap`: A settlement or local-area Scene built in Foundry.
+- `regionalmap`: A large-scale chart with an authored image and scale.
+- `totm`: A gridless image Scene for theatre-of-the-mind play.
+
+| `data` property   | Values       | Description                                                |
+| ----------------- | ------------ | ---------------------------------------------------------- |
+| `scene`           | object       | Exported Foundry Scene for battle and local maps           |
+| `fixup`           | object[]     | Asset address replacements in an exported Scene            |
+| `bgImage`         | Address      | Background image for regional and theatre-of-the-mind maps |
+| `scale`           | object       | Regional distance and unit per grid unit                   |
+| `dimensions`      | `[int, int]` | Optional shared dimensions metadata                        |
+| `pxPerGrid`       | number       | Optional shared grid size metadata                         |
+| `navName`         | string       | Short Scene navigation name                                |
+| `levelName`       | string       | Embedded Level name                                        |
+| `backgroundColor` | string       | Colour outside the art                                     |
+| `overlay`         | string       | Foreground art path                                        |
+| `walls`           | object       | Regional wall geometry                                     |
+| `doors`           | object       | Regional door geometry                                     |
+| `lights`          | object       | Regional light geometry                                    |
+| `tiles`           | object       | Regional tile geometry                                     |
+| `sounds`          | object       | Regional sound geometry                                    |
+| `regions`         | object       | Regional region geometry                                   |
+| `notes`           | object       | Regional pin geometry                                      |
+| `place`           | Address      | Depicted place, when one exists                            |
+
+#### Battle and local maps
+
+Author the Scene in Foundry, export it, convert the export to YAML, and put the resulting object at `data.scene`. Preserve its walls, lights, tiles, regions, levels, environment, flags, and canvas settings. The export can name art from another Foundry package; that path is used as authored in Foundry. The Scene needs positive whole-number `width` and `height`, at least one Level, a valid `initialLevel` when present, and a unique 16-character `_id` on each embedded document. The build derives the top-level Scene `_id` from the map note, adds compendium keys and build metadata, and otherwise preserves the exported fields.
+
+A pin's `text` can contain `#anchor`, where the map note has a heading such as `# Big Bad Wolf {#myanchor1}`. With `text: '#myanchor1'`, the compiled pin opens the JournalEntry and page generated from this map note and displays **Big Bad Wolf**. Its position, icon, other settings, and embedded `_id` remain as exported. A missing anchor is a build error. Pins whose text does not use `#anchor` retain their exported text and references.
+
+`data.fixup` replaces exported asset paths without editing the Scene object by
+hand. Each entry has `path`, `type: address`, and `value`, an asset Address in
+the local or a fetched content index. Paths start at `data.scene` and use a
+property path with array indices or stable embedded `_id` selectors. A path
+must name one existing string or null field, and the address must resolve; any
+mistake fails the build. An `_id` selector remains stable when Foundry reorders
+an array on export.
 
-**The place is named on the map, not the other way round.** A place commonly has
-several maps, so listing them from the place is the end that goes stale; naming
-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.
+```yaml
+data:
+  fixup:
+    - { path: ".notes[NNNNNNNNNNNNNNNN].texture.src", type: address, value: sohl-none-icon-book }
+    - { path: ".sounds[0].path", type: address, value: sohl-none-audio-forest }
+```
 
-**subType**:
+Fixups change the compiled copy only. The exported Scene in the note stays
+intact, and pin anchor binding runs after fixups. A package name such as
+`fvtt` is an ordinary address package name: it needs published asset records
+before its addresses can resolve.
 
-- battlemap: Tactical scale, for a scene played out square by square.
-- localmap: Roughly a kilometre across — a settlement, a holding, a small valley.
-- regionalmap: Large scale, covering a region or a journey between places.
-
-The three differ only in the canvas defaults derived for them, which is why they
-are subTypes of one type rather than three types.
-
-**NoteLocation** is `[GridLocation, anchor]` where the `anchor` is an anchor identified in the body of the note, and `GridLocation` represents a particular grid location on the document.
-
-The `data:` fields, of which three are required:
-
-| `data` property   | Values           | Description                                                                                                                                                  |
-| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `bgImage`         | `Address`        | **Required.** The map art — an `image` address. Becomes the level's `background.src`, what tokens stand on                                                   |
-| `dimensions`      | `[int, int]`     | **Required.** `[width, height]` in whole pixels, the art's own size                                                                                          |
-| `pxPerGrid`       | `integer`        | **Required.** Whole pixels per grid square; must match the art                                                                                               |
-| `navName`         | `string`         | Short name for Foundry's scene navigation bar                                                                                                                |
-| `levelName`       | `string`         | The name of the embedded level. Defaults to `Ground`                                                                                                         |
-| `backgroundColor` | `ColorHexValue`  | Shown where the art does not reach. Defaults to `#999999`                                                                                                    |
-| `overlay`         | `string`         | Path to **foreground** art                                                                                                                                   |
-| `walls`           | `WallSegment[]`  | List of wall segments                                                                                                                                        |
-| `doors`           | `Door[]`         | List of doors                                                                                                                                                |
-| `lights`          | `Light[]`        | List of lights                                                                                                                                               |
-| `tiles`           | `Tile[]`         | List of tiles, each naming its art in `image`                                                                                                                |
-| `sounds`          | `Sound[]`        | List of sounds, each naming its clip in `audio`                                                                                                              |
-| `regions`         | `SceneRegion[]`  | List of scene regions                                                                                                                                        |
-| `place`           | `Address`        | The place this map depicts. Optional, because an encounter map depicts no named place — but that is the exception, and a map without one is a map of nowhere |
-| `notes`           | `NoteLocation[]` | grid coordinates of note markers mapped to anchors in this document                                                                                          |
-
-Everything else a Scene holds is **derived**, not authored: padding, grid type,
-grid distance and units, token vision and fog mode all come from the subType, and
-ids, ordering and elevation are synthesised. A map note carries the map's
-essence, not a Scene's schema — the same division a weapon note makes against an
-Item's.
-
-**`levels:` is never authored, and must never be.** A Scene has to ship at least
-one Level or it has no map at all, and nothing supplies one after the fact: the
-client-side `_preCreate` that would create it does not run during offline pack
-compilation, and the server-side migration shim is version-gated on
-`_stats.coreVersion`, so a pack stamped 14.x or later skips it entirely. The
-single Level is synthesised from `bgImage`, `overlay`, `levelName` and
-`backgroundColor`.
-
-> **`bgImage` is an `Address` under `data:`, as every other type's artwork is.**
-> Art is not system-specific — a Scene is a core Foundry document, and a second
-> system would want the identical art — so the field sits under `data:` rather
-> than inside a system block.
->
-> **A map has no `img`.** `bgImage` is the only key naming a map's background,
-> and a note writing `img:` or `data.img:` is refused. The two are not
-> alternative spellings: `img` is a Foundry destination and no Scene has one.
-
-**Every art key inside a map is an address, and each is named for the type it
-reaches.** A map's geometry is authored in Foundry's own units, and its art is
-not authored in Foundry's own paths.
-
-| authored             | default type | emitted as                   |
-| -------------------- | ------------ | ---------------------------- |
-| `data.bgImage`       | `image`      | the level's `background.src` |
-| `tiles.<key>.image`  | `image`      | the tile's `texture.src`     |
-| `sounds.<key>.audio` | `audio`      | the `AmbientSound`'s `path`  |
-
-Naming each key for the type it references is what makes the default worth
-having: `audio:` reaches an `audio` address without a note ever writing the
-type segment. Where a tile places a glyph rather than artwork it qualifies —
-`image: sohl-none-icon-chest` — which is the ordinary short-form ladder rather
-than an exception to it.
-
-**The authored key and the emitted field differ where Foundry's name differs.**
-An `AmbientSound` stores its clip in `path`, and that is what the compiled
-document carries; the note writes `audio` because the note is naming an
-address, not filling in a Foundry field.
-
-**Two unit conventions, deliberately.** Geometry — walls, doors, lights, tiles,
-sounds, region shapes — is authored in **pixels**, Foundry's native storage,
-because traced walls often fall between grid intersections. Map pins are
-authored in **grid squares**, commonly
-half-integers, because that is how a person reads a position off a map. The two
-are told apart by their key: `position:` and segment or shape coordinates are
-pixels, `at:` is grid squares. Mixing them fails silently and visually in
-Foundry, so the build refuses rather than resolving.
-
-**Map pins stay within the map.** `notes:` names anchors in this map note's own
-body, so a pin opens the journal page describing that spot. `data.place` names
-the place depicted by the map when one exists. A place's map listing is derived
-from those map notes, so each map states the relationship once.
+```yaml
+shortcode: wolfden
+name: { full: The Wolf's Den }
+type: map
+subType: battlemap
+data:
+  scene:
+    name: Wolf Den Scene
+    width: 1900
+    height: 2600
+    grid: { type: 1, size: 100, distance: 5, units: ft }
+    initialLevel: defaultLevel0000
+    levels:
+      - { _id: defaultLevel0000, background: { src: modules/maps/den.webp } }
+    notes:
+      - { _id: NNNNNNNNNNNNNNNN, text: "#myanchor1", x: 950, y: 2350 }
+---
+# Big Bad Wolf {#myanchor1}
+```
+
+When the Scene has pins, its Adventure bundle carries the Scene and the JournalEntry generated from its Markdown. Importing that bundle preserves the IDs the pins address.
+
+#### Regional maps
+
+A `regionalmap` uses `data.bgImage`, an image Address, and `sohl.dimensions: [width, height]` plus `sohl.pxPerGrid` to build a gridless Scene. `data.scale: {distance: positive number, unit: nonempty string}` sets the distance per grid unit. Its shared `data` fields can also name `overlay`, `backgroundColor`, `levelName`, `navName`, `walls`, `doors`, `lights`, `tiles`, `sounds`, `regions`, and `notes`; the latter geometry uses the map-note conventions described in the SoHL map authoring guide. `data.scene` is not used for a regional map.
+
+An SVG `data.bgImage` remains vector art on the site and in the book. The Foundry build stages a PNG at the note's stated dimensions with the installed SVG renderer; the source SVG is unchanged. Its aspect ratio must match the stated dimensions. A selected regional SVG map takes a full page in the PDF.
+
+#### Theatre-of-the-mind maps
+
+A `totm` map names its background with `data.bgImage` and its canvas size with
+`sohl.dimensions: [width, height]`. It builds a gridless Scene with token vision
+off. It needs no `sohl.pxPerGrid` or `data.scale`. The Markdown body remains the
+map's prose.
 
 ### type: place
 
@@ -3761,9 +3797,10 @@ data:
   on a land route — or a road on a ship route — is an error.
 - `leagues` — optional on a route; a distance, only where the note states one.
 
-**Regions border; settlements are days apart.** A frontier is a fact about two
-regions, and a journey is a fact about two places a traveller sets out from and
-arrives at. A pair appears in `routes` once per `mode` — a port and its
+**A border is a shared frontier between areas.** Regions commonly state one;
+a settlement does so only when it actually shares a frontier with another
+place. Most settlements use `parents` for where they sit and `routes` for
+journeys between them. A pair appears in `routes` once per `mode` — a port and its
 neighbour may be three days by land and one by ship — and in `borders` once.
 **A place never borders its own parent or child**: containment is `parents`,
 and restating it as adjacency makes the two contradict each other.
@@ -3778,6 +3815,16 @@ neighbour that states a different bearing, a different `days` or a different
 tell which. Every `to` must resolve to a place, every value must come from its
 closed set, and each finding is located at the entry that states it.
 
+The terrain names form one shared registry in package-build. A route crossing
+a package boundary uses the same terrain and mode rules at both ends.
+
+For every place that participates in a border or route, the map builder draws
+an itinerary from that place. A site page carries it as a linked SVG. A PDF
+book that includes the place gives its map a separate full page after the
+entry. A configured Foundry Scene pack carries a gridless map backed by a
+generated PNG, with Notes linked to importable place journals. Places with no
+relations create no itinerary output.
+
 **A relation that crosses a package boundary is written in full at both ends.**
 An omitted `<package>` segment is the package being built, in whatever note the
 value is read from — a note of this package's own, or a record a consumer fetched

package/docs/diagnostics.md

@@ -286,7 +286,7 @@ over one would teach people to stop reading the report.
 | `content-build markdown [paths..]`               | it reports any markdownlint finding                                                                                                                                                                                                                                |
 | `content-build site`                             | any gate finding (no homepage, a wikilink in frontmatter, an address that cannot be derived, an unusable or unaddressable foreign manifest, a conflicting address) or any table or wikilink error while writing pages — the run stops at the first gate that fires |
 | `content-build pdf`                              | it could not build the book for a reason other than a deliberate no-op — never on a reported finding by itself                                                                                                                                                     |
-| `content-build map`                              | `--tree` reports an `error`-severity finding (a place with no parent, a parent that does not resolve, a cycle), a named place is not one, the GraphViz engine a drawing needs is not installed, or the corpus cannot be indexed — never on a warning               |
+| `content-build map`                              | `--tree` reports an `error`-severity finding (a place with no parent, a parent that does not resolve, a cycle), a named place is not one, the renderer fails, or the corpus cannot be indexed — never on a warning                                                 |
 | `content-build docs item-fields --check`         | the generated page differs from what is committed                                                                                                                                                                                                                  |
 | `content-build package compile`                  | pack JSON generation reported any `error`-severity finding (checked, and the compile refused, before any pack is written), or a compiled pack fails its Scene/Level integrity check                                                                                |
 | `content-build deps fetch`                       | the fetch itself throws — it emits no diagnostics                                                                                                                                                                                                                  |

package/docs/getting-started.md

@@ -370,9 +370,10 @@ position together:
 ```
 
 The accepted sizes are `auto`, `small`, `medium`, `large`, `xlarge`, and
-`full-width`. Omitting `size:` means `auto`. The build checks the name, but
-`size:` does not change the displayed dimensions on the website, in Foundry, or
-in the book. See [Images](content-format.md#images) for the rendering rules.
+`full-width`. Omitting `size:` means `auto`, which uses the image's natural
+dimensions within the available measure. The other names set maximum display
+widths for the website, Foundry, and book. See
+[Images](content-format.md#images) for the surface sizes and layout rules.
 
 ## Step 6 — check the tree
 
@@ -738,6 +739,29 @@ compiles to a page, so there is no document to address.
 The index is derived and disposable; it is written under `build/` and rebuilt
 from the tree every time.
 
+### Calendar files for a setting module
+
+A content package with `lore` notes of `subType: calendar` can emit Foundry
+calendar definitions after the content index is built:
+
+```console
+$ npx package-build calendars --calendaria-version 1.4.2
+✅ 5 calendars emitted (10 files).
+```
+
+The command writes `build/calendars/<shortcode>.json` and
+`build/calendars/<shortcode>.calendaria.json` for each calendar. The first is a
+calendar definition; the second wraps the same definition for import through
+Calendaria's settings. The version argument names the Calendaria import format
+the package targets. The envelope uses a fixed `exportedAt` sentinel because
+these files are reproducible build artifacts. A package with no calendars gets
+an empty `build/calendars/` directory.
+
+To ship the files in a Foundry package, add
+`{ from: build/calendars, to: calendars }` to `packageBuild.assets` and run the
+calendar command before `package-build assets`. Running the command requires
+the current content index; regenerate it after changing calendar notes.
+
 ## Step 11 — the release archive
 
 ```console

package/engine/base-compiler.mjs

@@ -100,6 +100,7 @@ import { locateFrontmatterKey } from "./retired-fields.mjs";
 // present before this pass reads `data:` for anything else — see
 // `engine/being-age.mjs`.
 import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 
 /**
  * The tallies one pass accumulates while walking the tree.
@@ -1078,6 +1079,7 @@ export class BasePackCompiler {
         // to have the body anyway. So the read is one this pass was already
         // making; what it no longer does is decide for itself which files to
         // make it over.
+        const dates = reckoningContext({ notes: this.corpus.records });
         for (const record of this.corpus.records) {
             if (!isNoteRecord(record)) continue;
             const absPath = noteFile(this.contentBase, record);
@@ -1091,7 +1093,7 @@ export class BasePackCompiler {
                 stats.skippedOther++;
                 continue;
             }
-            applyComputedBeingAge(fm, this.worldPresent);
+            applyComputedBeingAge(fm, this.worldPresent, dates);
             // The retired frontmatter fields, refused before `selects` so a
             // note is answered whichever pass would have claimed it — and
             // whatever the declared value says.

package/engine/being-age.mjs

@@ -36,17 +36,10 @@
  *
  * A year subtracted from a year is wrong whenever the birthday has not yet
  * happened in the present's year — the common shape, not the exception. So
- * {@link computeAge} compares `born`'s month and day against `present`'s,
- * **ordinally**, and drops a year where born's has not yet arrived. That
- * ordinal comparison needs no month-length table: two dates written in one
- * calendar order the same way whether the comparison counts days-of-year
- * through the calendar's month lengths or simply reads `(month, day)` as a
- * pair, because a calendar's months keep the same lengths every year — this
- * package's calendars carry no leap rule (`calendar-notes.mjs`'s
- * `years.leapYear` is always `null`). So the comparison is calendar-agnostic
- * by construction, and correct for a twelve-month calendar of thirty-day
- * months, a ten-month calendar, or none at all — a bare `born` with no era
- * names no calendar to consult in the first place.
+ * {@link computeAge} compares the two dates' canonical day ordinals where an
+ * era marker supplies them. The birthday that still lies ahead in the current
+ * year does not count as a completed year. An unmarked slash date has no
+ * calendar to convert, so it uses its written month and day as its ordinal.
  *
  * ## `~` follows the convention {@link module:engine/note-dates} sets
  *
@@ -65,6 +58,7 @@
 import { worldInvariants } from "./calendar-notes.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 // `born`'s retired spelling is still read during its retirement window — see
 // `docs/content-format.md`'s "`birthday:` is the retired spelling of `born:`"
 // — so a being on the old spelling still computes an age rather than reading
@@ -124,23 +118,21 @@ export function parseAgeMagnitude(raw) {
  * @returns {number|null} The age, or `null` where `born` is `unknown` or
  *   absent, where no present is declared, or where either date fails to parse.
  */
-export function computeAge(bornRaw, presentRaw) {
+export function computeAge(bornRaw, presentRaw, dateContext = {}) {
     if (bornRaw === undefined || bornRaw === null) return null;
     if (presentRaw === undefined || presentRaw === null) return null;
 
-    const born = parseNoteDate(bornRaw, { allowUnknown: true }).date;
+    const born = parseNoteDate(bornRaw, { ...dateContext, allowUnknown: true }).date;
     if (!born || !born.known || born.canonicalYear == null) return null;
 
-    const present = parseNoteDate(presentRaw, { allowUnknown: false }).date;
+    const present = parseNoteDate(presentRaw, { ...dateContext, allowUnknown: false }).date;
     if (!present || !present.known || present.canonicalYear == null) return null;
 
-    // Ordinal position within the year, day of year or not: see the module
-    // doc for why `(month, day)` alone orders correctly here. Missing month or
-    // day reads as the year's first day — the earliest a birthday could fall —
-    // so a `born` written to less precision than `present` never counts as
-    // "not yet happened".
-    const bornOrdinal = (born.month ?? 1) * 100 + (born.day ?? 1);
-    const presentOrdinal = (present.month ?? 1) * 100 + (present.day ?? 1);
+    // A resolved marker supplies a canonical day. An unmarked slash date uses
+    // its written month and day. Missing parts read as the first day that the
+    // value can name.
+    const bornOrdinal = born.canonicalDay ?? (born.month ?? 1) * 100 + (born.day ?? 1);
+    const presentOrdinal = present.canonicalDay ?? (present.month ?? 1) * 100 + (present.day ?? 1);
     const notYetHappened = bornOrdinal > presentOrdinal;
 
     return present.canonicalYear - born.canonicalYear - (notYetHappened ? 1 : 0);
@@ -163,7 +155,7 @@ export function computeAge(bornRaw, presentRaw) {
  *   `undefined`/`null` where it states none.
  * @returns {void}
  */
-export function applyComputedBeingAge(fm, presentRaw) {
+export function applyComputedBeingAge(fm, presentRaw, dateContext = {}) {
     if (!isBeingType(fm?.type)) return;
     const data = dataOf(fm);
     if (!data) return;
@@ -179,7 +171,7 @@ export function applyComputedBeingAge(fm, presentRaw) {
     }
 
     const born = readAliasedField(fm, "born", { inData: true });
-    const computed = computeAge(born, presentRaw);
+    const computed = computeAge(born, presentRaw, dateContext);
     if (computed !== null) data.age = computed;
 }
 
@@ -251,7 +243,7 @@ export function checkBeingAge(note, { index } = {}) {
     if (!index) return [];
 
     const present = worldInvariants(index).present;
-    const computed = computeAge(bornRaw, present);
+    const computed = computeAge(bornRaw, present, reckoningContext(index));
     if (computed === null) return [];
 
     const authored = parseAgeMagnitude(ageRaw);