@heroiclands/package-build 22.8.0 → 22.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.9.0
+
+### Minor Changes
+
+**Calendars are content, not configuration.** The `calendar:` block retires from `package-build.config.yaml`, and a configuration that still declares it is refused by name.
+
+**A calendar is a note.** A `lore` note with `subType: calendar` states the months it keeps, the weekdays it names, the seasons it marks and the year-counts kept in it, and a date names one of those by writing `<calendar shortcode>.<era shortcode>`. Days that belong to no month are a short month like any other, sitting in the list where they fall in the year.
+
+**The world states its own year.** How long the year is, how the day divides and how the moon moves are written once on the world's own `place` note and on its moon's, so no calendar restates them — and a calendar whose months do not add up to that year is refused, naming the year rather than the arithmetic.
+
+**A body is a place.** `place` gains `celestial`, for something observed from a world rather than located on one.
+
+**A written day is bounded by the month it names.** A five-day month accepts five days and a thirty-day month accepts thirty, in whatever order a calendar keeps them; a package that names no calendar bounds nothing.
+
 ## 22.8.0
 
 ### Minor Changes

package/content-config.mjs

@@ -76,7 +76,6 @@ import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.m
 import { MAP_TYPES, NO_PACK, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
-import { UNKNOWN_DATE, parseNoteDate } from "./engine/note-dates.mjs";
 
 /**
  * What kind of package this is.
@@ -726,10 +725,6 @@ export function publishesContentPages(config) {
  * @property {readonly string[]} packDirectories  Derived: every pack directory
  *                                     the build produces, in compile order —
  *                                     each pack followed by its companions.
- * @property {Readonly<{months: number|null, monthDays: number|null, present: string|null}>} calendar
- *                                     How this package's year is divided, and
- *                                     the date it calls the present. Every
- *                                     value `null` when none is declared.
  * @property {Readonly<PackageBuildSection>} packageBuild  Passed through
  *                                     frozen, uninterpreted. `{}` when absent.
  * @property {Readonly<DocsSpec>} docs   Frozen; `{}` when absent.
@@ -759,13 +754,11 @@ const CONFIG_KEYS = [
     "relationships",
     "systems",
     "requiresSystem",
-    "calendar",
     "packageBuild",
     "publish",
     "changelog",
 ];
 const SYSTEM_KEYS = ["manifest", "compatibility"];
-const CALENDAR_KEYS = ["months", "monthDays", "present"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const CHANGELOG_KEYS = ["labels"];
@@ -2077,76 +2070,6 @@ function normalizeRequiresSystem(value) {
     return requireNonEmptyString(value, "requiresSystem");
 }
 
-/**
- * How this package's year is divided, and the date it calls the present.
- *
- * **Nothing here is about which people count from what.** A reckoning is an
- * era, declared by the affiliation that proclaimed it, and its epoch is the
- * `start` written on that note — so the only things configuration states are
- * the ones no note could.
- *
- * `months` and `monthDays` bound a written month and day. Both are optional,
- * and an absent one is checked against nothing: a toolchain that assumed a
- * Gregorian year here would refuse `667/2/30`, an ordinary date in a year of
- * twelve thirty-day months. One subdivision to a package — an era moves where
- * year 1 sits, it does not divide the year differently.
- *
- * `present` is the date the package computes an age against, written in the
- * same grammar a note's dates use, so a package whose present is best said in
- * an era says it that way. A package that states none computes no age, which
- * is the right answer for a corpus that has no present.
- *
- * @param {unknown} value - The declared `calendar:` mapping.
- * @returns {Readonly<{months: number|null, monthDays: number|null, present: string|null}>}
- *   Frozen; every value `null` when absent.
- */
-function normalizeCalendar(value) {
-    if (value === undefined || value === null) {
-        return Object.freeze({ months: null, monthDays: null, present: null });
-    }
-    if (!isPlainObject(value)) fail("calendar", "must be a mapping");
-    const input = /** @type {Record<string, unknown>} */ (value);
-    rejectUnknownKeys(input, CALENDAR_KEYS, "calendar.");
-
-    const bound = (key) => {
-        const held = input[key];
-        if (held === undefined || held === null) return null;
-        if (!Number.isInteger(held) || /** @type {number} */ (held) < 1) {
-            fail(`calendar.${key}`, "must be a positive integer");
-        }
-        return /** @type {number} */ (held);
-    };
-    const months = bound("months");
-    const monthDays = bound("monthDays");
-
-    // Read through the parser the notes use rather than a second grammar, and
-    // against this package's own bounds — a present outside the year it
-    // declares is the one date nothing downstream would report.
-    let present = null;
-    if (input.present !== undefined && input.present !== null) {
-        if (typeof input.present !== "string" && typeof input.present !== "number") {
-            fail("calendar.present", "must be a date written as a string");
-        }
-        if (String(input.present).trim() === UNKNOWN_DATE) {
-            fail(
-                "calendar.present",
-                `must be a date — a package that states no present computes no age, ` +
-                    `so leave the key out rather than writing \`${UNKNOWN_DATE}\``,
-            );
-        }
-        const { date, findings } = parseNoteDate(input.present, {
-            calendar: { months, monthDays },
-            allowUnknown: false,
-        });
-        const refused = findings.find((finding) => finding.severity === "error");
-        if (refused)
-            fail("calendar.present", `is not a date this package can read — ${refused.message}`);
-        present = /** @type {{text: string}} */ (date).text;
-    }
-
-    return Object.freeze({ months, monthDays, present });
-}
-
 /**
  * Validate the declared relationships.
  *
@@ -2878,7 +2801,6 @@ export function defineConfig(config) {
         relationships: normalizeRelationships(input.relationships),
         systems,
         requiresSystem,
-        calendar: normalizeCalendar(input.calendar),
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
         changelog: normalizeChangelog(input.changelog),

package/docs/api.md

@@ -606,18 +606,23 @@ The closed registry of system ids, and the `none` that stands for no system at a
 
 ### `engine.calendars`
 
-The axis every date normalises onto, and the one function that puts a reckoning on it. A reckoning is an **era** declared by the affiliation that proclaimed it, and its epoch is the `start` written on that note — nothing is registered in configuration. The conversion is piecewise on the sign, because the authored numbering has no year zero while the normalised value does: authored `-1` is `0`, and `-1` and `1` are adjacent.
-
-| Export              | Signature                       | Returns                                       | Use it when                                                                     |
-| ------------------- | ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
-| `CANONICAL_EPOCH`   | `const CANONICAL_EPOCH`         | —                                             | naming where the canonical axis's own year 1 sits                               |
-| `canonicalYear`     | `canonicalYear(year, epoch?)`   | `number` — the signed year on the axis        | converting a year written in one reckoning to the number everything compares on |
-| `dateSortKey`       | `dateSortKey(year, month, day)` | `number`                                      | ordering mixed-precision dates against a single number                          |
-| `calendarStructure` | `calendarStructure(calendar)`   | `{months, monthDays}` — `null` where unstated | reading the month bounds a package declares, before phrasing a finding          |
+The axis every date normalises onto, the arithmetic over a calendar's month list, and the moon. A reckoning is an **era** declared on the note about the calendar that counts those years, and its epoch is the `start` written on that row — nothing is registered in configuration. The year conversion is piecewise on the sign, because the authored numbering has no year zero while the normalised value does: authored `-1` is `0`, and `-1` and `1` are adjacent. `lunarPhase` takes a floored modulo for the same reason the conversion branches: a truncated one is right on one side of an epoch and wrong on the other.
+
+| Export              | Signature                          | Returns                                | Use it when                                                                     |
+| ------------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `CANONICAL_EPOCH`   | `const CANONICAL_EPOCH`            | —                                      | naming where the canonical axis's own year 1 sits                               |
+| `canonicalYear`     | `canonicalYear(year, epoch?)`      | `number` — the signed year on the axis | converting a year written in one reckoning to the number everything compares on |
+| `dateSortKey`       | `dateSortKey(year, month, day)`    | `number`                               | ordering mixed-precision dates against a single number                          |
+| `calendarStructure` | `calendarStructure(calendar)`      | `{months}` — `null` where unstated     | reading the months a calendar keeps, before phrasing a finding                  |
+| `daysInMonth`       | `daysInMonth(calendar, month)`     | `number` — `null` where unstated       | bounding a written day against the month it names                               |
+| `daysInYear`        | `daysInYear(months)`               | `number`                               | asking what a month list claims the year is                                     |
+| `monthStarts`       | `monthStarts(months)`              | `number[]`                             | reading the same sum as a sequence, which is what an ordering error moves       |
+| `dayOfYear`         | `dayOfYear(months, month, day)`    | `number`                               | placing a written month and day in the year                                     |
+| `lunarPhase`        | `lunarPhase(day, epochDay, cycle)` | `number` — `0` to `cycle - 1`          | asking how far into its cycle a moon is, on either side of the epoch            |
 
 ### `engine.noteDates`
 
-A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era shortcode>]` — and every field holding one parses through a single grammar into a single record. Print `text`, order on `sort`, do arithmetic on `canonicalYear`. A bare value sits on the canonical axis and carries `era: null`; one naming an era carries the qualifier and no `canonicalYear` or `sort` keys at all until the era is resolved against the corpus. The literal `unknown` parses to the same record with the year half empty, carrying a null `sort` and a null `canonicalYear`, so nothing can order it to one end of a list.
+A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<calendar shortcode>.<era shortcode>]` — and every field holding one parses through a single grammar into a single record. Print `text`, order on `sort`, do arithmetic on `canonicalYear`. A bare value sits on the canonical axis and carries `era: null`; one naming an era carries the qualifier and no `canonicalYear` or `sort` keys at all until the era is resolved against the corpus. The literal `unknown` parses to the same record with the year half empty, carrying a null `sort` and a null `canonicalYear`, so nothing can order it to one end of a list.
 
 | Export                  | Signature                       | Returns                                            | Use it when                                                   |
 | ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
@@ -626,6 +631,24 @@ A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<affiliation
 | `ERA_QUALIFIER_PATTERN` | `const ERA_QUALIFIER_PATTERN`   | —                                                  | checking that a string is an era qualifier a date could carry |
 | `parseNoteDate`         | `parseNoteDate(value, options)` | `{date, findings}` — `date` is `null` when refused | reading a note's authored date, with every finding it earned  |
 
+### `engine.calendarNotes`
+
+A calendar is a `lore` note with `subType: calendar`, declaring the months it keeps, the weekdays it names, the seasons it marks and the eras it counts years in. How long the year is, how the day divides and how the moon moves are facts about the **world**, written on its `place` note and its moon's, and no calendar may restate them — which is why the months summing to the world's year is the only arithmetic a calendar note is held to. One definition is emitted per calendar, in array shape: Foundry core prunes the keys outside its schema, and Calendaria converts the arrays to its own keyed collections.
+
+| Export               | Signature                                             | Returns                                    | Use it when                                                                 |
+| -------------------- | ----------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
+| `CALENDAR_SUBTYPE`   | `const CALENDAR_SUBTYPE`                              | —                                          | naming the `lore` subType whose notes are calendars                         |
+| `INVARIANT_SUBTYPES` | `const INVARIANT_SUBTYPES`                            | —                                          | naming the `place` subTypes a world fact may be written on                  |
+| `CALENDAR_FIELDS`    | `const CALENDAR_FIELDS`                               | —                                          | reading the closed list of what a calendar note may declare                 |
+| `INVARIANT_FIELDS`   | `const INVARIANT_FIELDS`                              | —                                          | reading the closed list of what a body may declare about itself             |
+| `checkCalendarNote`  | `checkCalendarNote(note, opts)`                       | `object[]` — findings                      | holding a `lore` note to the family and to the year the world keeps         |
+| `checkWorldFacts`    | `checkWorldFacts(note, opts)`                         | `object[]` — findings                      | holding a `place` note's world facts to one body, one year and one moon     |
+| `worldInvariants`    | `worldInvariants(index)`                              | `{year, present, moon, body, moonName, …}` | reading the year, the present and the moon a package's own notes state      |
+| `quarterDays`        | `quarterDays(daysPerYear)`                            | `number[]` — four days of the year         | asking which days the year turns on                                         |
+| `compileCalendar`    | `compileCalendar({note, invariants, contentPackage})` | `object` — the definition                  | building the one object both a core consumer and Calendaria read            |
+| `compileCalendars`   | `compileCalendars(index, opts)`                       | `{calendars, invariants}`                  | building every calendar a package declares, or none where it states no year |
+| `calendariaEnvelope` | `calendariaEnvelope(definition, opts)`                | `object` — the import envelope             | wrapping a definition for a hand import through Calendaria's settings       |
+
 ### `engine.contentAddress`
 
 Where a content note publishes on the web. One rule, in one place, because two builds need the same answer: the knowledgebase build renders the page, and the link manifest records the address other packages link to. Stating it twice is how a manifest comes to assert a URL that resolves at build time and 404s for the reader.

package/docs/configuration.md

@@ -74,14 +74,13 @@ authoring.
 | [`relationships`](#relationships)           | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`systems`](#systems)                       | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
 | [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
-| [`calendar`](#calendar)                     | object                                                                     | no                                                                                                 | no bounds, no present                       |
 | [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                                        |
 | [`publish`](#publish)                       | object                                                                     | no; **required**, with `site: content`, in a `documentation` package                               | `{site: "homepage", address: {prefix: ""}}` |
 | [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`                            |
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, calendar, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -1298,59 +1297,6 @@ With one, naming what it does declare instead:
 
 > ``package-build config: `requiresSystem` must be a non-empty string.``
 
-### `calendar`
-
-**Type:** object · **Optional** · default: no bounds and no present.
-
-How this package's year is divided, and the date it calls the present:
-
-```yaml
-calendar:
-  months: 12
-  monthDays: 30
-  present: 720/6/19
-```
-
-**Nothing here is about which people count from what.** A reckoning is an
-**era**, declared by the affiliation that proclaimed it, and its epoch is the
-`start` written on that note — so the only things this block states are the ones
-no note could.
-
-| Key (under `calendar`) | Type             | Required | Default |
-| ---------------------- | ---------------- | -------- | ------- |
-| `calendar.months`      | positive integer | no       | `null`  |
-| `calendar.monthDays`   | positive integer | no       | `null`  |
-| `calendar.present`     | date string      | no       | `null`  |
-
-`months` and `monthDays` bound a written month and day. **Both are optional, and
-an absent one is checked against nothing** — a year of twelve thirty-day months
-is as ordinary here as a Gregorian one, so the bound is declared or it is not
-applied. One subdivision to a package: an era moves where year 1 sits, it does
-not divide the year differently.
-
-`present` is the date an age is computed against. It is written in the same
-grammar a note's dates use — `[~][-]YYYY[/MM[/DD]] [<affiliation shortcode>.<era
-shortcode>]` — so a package whose present is best said in an era says it that
-way, and one that states no present computes no age at all.
-
-An age is a function of two **dates**, not two years: subtracting years alone
-reds every note whose birthday falls later in the year than the present date, so
-the day is part of what is declared.
-
-> ``package-build config: `calendar` must be a mapping.``
-
-> ``package-build config: `calendar.months` must be a positive integer.``
-
-> ``package-build config: `calendar.monthDays` must be a positive integer.``
-
-> ``package-build config: `calendar.present` must be a date written as a string.``
-
-> ``package-build config: `calendar.present` must be a date — a package that states no present computes no age, so leave the key out rather than writing `unknown`.``
-
-> ``package-build config: `calendar.present` is not a date this package can read — `720/13/1` writes month 13, and `calendar.months` declares a year of 12.``
-
-> ``package-build config: `calendar.<key>` is not a recognized option (expected one of: months, monthDays, present).``
-
 ### `packageBuild`
 
 Reserved for `@heroiclands/package-build`'s own packaging half — see

package/docs/content-format.md

@@ -3217,8 +3217,65 @@ 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 |
-| --------------- | ------ | ----------- |
+| `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>` |
+
+#### What a calendar note declares
+
+**Those five keys belong to `subType: calendar` and to no other genre of
+`lore`.** A note carrying one under any other subType is refused, and a calendar
+note that states no `months` and no `epoch` is refused too: a calendar divides
+the year and says where the count begins, and one that does neither is prose
+about time rather than a calendar.
+
+```yaml
+type: lore
+subType: calendar
+shortcode: commoncal
+name:
+  full: The Common Calendar
+data:
+  epoch: 720/1/1
+  months:
+    - { name: Floralis, abbreviation: Flor, days: 30 }
+    - { name: Lusenar, abbreviation: Luse, days: 31 }
+    # … ten more, summing to the world's year
+  seasons:
+    - { name: Spring, monthStart: 1, monthEnd: 3 }
+  eras:
+    - shortcode: founding
+      name: After the Founding
+      abbreviation: AF
+      proclaimedBy: vylarinmpr
+      start: 1
+```
+
+**Position in the list is position in the year.** Days that belong to no month
+are a short month like any other: a five-day festival is one entry, and where it
+sits in the list is where it falls in the year. There is no intercalary
+mechanism, because there is nothing for one to do.
+
+**How long the year is, how the day divides and how the moon moves are facts
+about the world, not about a calendar**, so no calendar note states any of them
+— they are written once on the world's own `place` note and on its moon's, and
+every calendar is compiled against them. The one arithmetic check follows from
+that: `months` must sum to `year.days`, and a list that does not describes a
+different world rather than a different calendar.
+
+**An era is a way of counting years within a calendar**, so its rows sit beside
+the months. Each states its own `shortcode`, unique within the note, and a date
+names one by writing it after the calendar's address — `3 commoncal.founding`.
+`proclaimedBy` is optional: a reckoning whose proclaiming body is unknown, or
+whose body has no note, says so by leaving it out.
+
+**A calendar with no week writes no `weekdays`.** An empty list and an absent
+one say the same thing, and nothing downstream shows a weekday for a calendar
+that names none.
 
 ### type: map
 
@@ -3370,16 +3427,72 @@ three maps, and none of those maps needs to know it is a keep.
 - site: A place significant by what was made or done there — ruins, monoliths, henges, works, battlefields.
 - structure: A single building or habitation — halls, keeps, temples, inns, towers.
 - feature: A place significant by its terrain — forests, rivers, falls, passes, fords.
+- celestial: A body observed from a world rather than located on one — a sun, a planet, a comet.
+
+| `data` property                   | Values                                              | Description                                                                  |
+| --------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `demonym`                         | `string`                                            | What a person from this place is called — a Vylarian                         |
+| `lore`                            | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
+| `parents`                         | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
+| `population`                      | `number`                                            | Approximate population (precision 2 significant digits)                      |
+| `market`                          | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
+| `borders`                         | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
+| `routes`                          | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
+| `world.equatorialCircumferenceKm` | `number`                                            | The distance round the body at its equator, in kilometres                    |
+| `world.surfaceGravityG`           | `number`                                            | Surface gravity, as a multiple of Earth's                                    |
+| `world.axialTiltDegrees`          | `number`                                            | The tilt of the axis, in degrees                                             |
+| `year.days`                       | `number`                                            | How many days the body's year holds                                          |
+| `year.hoursPerDay`                | `number`                                            | How many hours the day divides into                                          |
+| `year.minutesPerHour`             | `number`                                            | How many minutes the hour divides into                                       |
+| `year.secondsPerMinute`           | `number`                                            | How many seconds the minute divides into                                     |
+| `present`                         | `date`                                              | The day the setting stops and play begins                                    |
+| `body.diameterKm`                 | `number`                                            | The body's diameter, in kilometres                                           |
+| `body.orbitalRadiusKm`            | `number`                                            | How far it orbits from the body it circles, in kilometres                    |
+| `body.orbit`                      | `string`                                            | The orbit's shape — `circular` means the cycle never varies                  |
+| `body.inclined`                   | `boolean`                                           | Whether the orbit is inclined to the plane the world orbits in               |
+| `moon.cycle`                      | `number`                                            | How many days it takes to return to the same phase                           |
+| `moon.newOn`                      | `date`                                              | A day it was new, written in the reference calendar                          |
+| `moon.eclipses`                   | `string`                                            | `never`, `rare`, `occasional` or `frequent`                                  |
+
+#### What a body states about itself
+
+**The four groups above are the world's own facts, and they are legal on a
+`world` or a `celestial` note and nowhere else.** A region, a settlement, a
+site, a structure or a feature is somewhere _within_ a world and says nothing
+about the world's year.
+
+```yaml
+# the world — type: place, subType: world
+data:
+  world: { equatorialCircumferenceKm: 40000, surfaceGravityG: 1.0, axialTiltDegrees: 23.5 }
+  year: { days: 365, hoursPerDay: 24, minutesPerHour: 60, secondsPerMinute: 60 }
+  present: 720
+
+# its moon — a note of its own, because a moon is a body and not a property
+data:
+  body: { diameterKm: 3800, orbitalRadiusKm: 388600, orbit: circular, inclined: true }
+  moon: { cycle: 30, newOn: 720/1/1, eclipses: rare }
+```
 
-| `data` property | Values                                              | Description                                                                  |
-| --------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `demonym`       | `string`                                            | What a person from this place is called — a Vylarian                         |
-| `lore`          | `WikiLink[]`                                        | Lore concerning this place — its peoples, its law, its calendar, its history |
-| `parents`       | `WikiLink[]`                                        | Enclosing places within which this place is located                          |
-| `population`    | `number`                                            | Approximate population (precision 2 significant digits)                      |
-| `market`        | `number`                                            | Market class, 1 to 6 — what trade a settlement supports                      |
-| `borders`       | `{ to, bearing }[]`                                 | Places sharing a frontier with this one, and where each lies from here       |
-| `routes`        | `{ to, bearing, mode, days, terrain?, leagues? }[]` | Journeys from this place's centre to another place                           |
+**`year.days` is where the year's length lives, and every calendar in the
+package is compiled against it.** A package whose notes state no `year` has no
+calendar mechanism at all: no sum is checked, and nothing is emitted. That is
+the right answer for a package building a setting whose world facts somebody
+else wrote down.
+
+**One year and one moon to a package.** Two years is two settings and nothing
+can say which one a calendar divides; a `moon` with no `year` anywhere is
+refused, because a cycle counted in days has no year to be measured against.
+
+**`present` is the day an age is computed against**, written in the grammar a
+note's dates are written in, so a setting whose present is best said in an era
+says it that way.
+
+**`world.axialTiltDegrees`, the circumference, the gravity, the moon's diameter
+and its orbital radius are read by nobody.** They are there so a reader knows
+what kind of world this is. What the build consumes is the year, the day's
+divisions, the present, the moon's cycle and epoch, and whether its orbit is
+circular and inclined.
 
 #### What a settlement's market supports