@heroiclands/package-build 22.16.0 → 22.17.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @heroiclands/package-build
 
+## 22.17.1
+
+### Patch Changes
+
+**Prose review**
+
+- Prose lint focuses on difficult sentences by default and skips tables and code; simpler-word suggestions remain available on request.
+- Prose score reports each note's readability and lets a content package define an advisory range for its writing.
+
+## 22.17.0
+
+### Minor Changes
+
+**Calendar dates**
+
+- Calendar notes anchor their first year to a canonical day, count eras from calendar years, and include an era for dates before year one.
+- Named calendar formats control how dates print; the standard format also controls how authored calendar dates are read.
+- Calendars can name special days and divide the year into seasons, with those names available in formatted dates.
+
+**Content dates**
+
+- A date written as a year covers that whole year; a written day covers that day, and a clock time identifies a moment.
+- Calendar starting days and moon phase references require a day so their dates cannot silently shift to the first day of a year.
+
 ## 22.16.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -97,7 +97,7 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { schemaSubtypeOf } from "../engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
-import { lintProse } from "../engine/readability-lint.mjs";
+import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
 import { loadPackageBuildConfig } from "../config.mjs";
 import {
     authoredFrontmatter,
@@ -240,14 +240,14 @@ export function registerContentCommands(cli) {
         .command(addressesCommand());
 }
 
-/** Opt-in readability and plain-language suggestions for Markdown notes. */
+/** Optional sentence findings and note-level readability reports. */
 function proseCommand() {
     return {
         command: "prose <action> [path]",
         describe: "Analyze note prose on demand",
         builder: (yargs) =>
             yargs
-                .positional("action", { choices: ["lint"], describe: "Analyze prose" })
+                .positional("action", { choices: ["lint", "score"], describe: "Analyze prose" })
                 .positional("path", {
                     type: "string",
                     describe: "One Markdown file or a content tree",
@@ -257,17 +257,97 @@ function proseCommand() {
                     type: "number",
                     describe: "Readability algorithms required (1–7)",
                 })
-                .option("min-words", { type: "number", describe: "Minimum words per sentence" }),
+                .option("min-words", {
+                    type: "number",
+                    describe: "Minimum words per sentence or note",
+                })
+                .option("rules", {
+                    choices: ["readability", "simplify", "all"],
+                    describe: "Lint rule set",
+                })
+                .option("fail-on-warning", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Exit unsuccessfully when lint reports suggestions",
+                })
+                .option("fail-outside", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Exit unsuccessfully when a scored note is outside a configured band",
+                }),
         handler: async (argv) => {
             try {
                 const config = loadPackConfig();
-                const defaults = loadPackageBuildConfig().proseLint;
+                const defaults = loadPackageBuildConfig();
+                const root = argv.path ?? config.paths.content;
+                const displayFile = (file) => path.relative(process.cwd(), path.resolve(file));
+                if (argv.action === "score") {
+                    if (
+                        argv.age !== undefined ||
+                        argv.threshold !== undefined ||
+                        argv.rules !== undefined ||
+                        argv.failOnWarning
+                    ) {
+                        throw new Error(
+                            "--age, --threshold, --rules, and --fail-on-warning apply only to prose lint",
+                        );
+                    }
+                    const minWords = argv.minWords ?? defaults.proseScore.minWords;
+                    if (!Number.isInteger(minWords) || minWords < 1) {
+                        throw new Error("minWords must be a positive integer");
+                    }
+                    const result = await scoreProseTree(
+                        root,
+                        { ...defaults.proseScore, minWords },
+                        config.skipDirectories,
+                    );
+                    const fixed = (number, places = 1) => number.toFixed(places);
+                    for (const note of result.notes) {
+                        if (note.insufficient) {
+                            console.log(
+                                `${displayFile(note.file)}: insufficient prose (${note.words}/${minWords} words; coverage=${fixed(note.coveragePercent)}%)`,
+                            );
+                            continue;
+                        }
+                        const metrics = note.metrics;
+                        const detail =
+                            `flesch=${fixed(metrics.flesch)} syl/word=${fixed(metrics.syllablesPerWord, 2)} ` +
+                            `mean=${fixed(metrics.meanSentenceWords)}w longest=${note.longestSentenceWords}w ` +
+                            `unfamiliar=${fixed(metrics.unfamiliarWordPercent)}% ` +
+                            `nominalizations/1k=${fixed(metrics.nominalizationsPer1000Words)} ` +
+                            `words=${note.words} coverage=${fixed(note.coveragePercent)}%`;
+                        if (note.violations.length) {
+                            emitDiagnostic({
+                                file: displayFile(note.file),
+                                severity: "warning",
+                                message: `prose-score/band: ${detail}; ${note.violations.join(", ")}`,
+                            });
+                        } else {
+                            console.log(`${displayFile(note.file)}: ${detail}`);
+                        }
+                    }
+                    const aggregate = result.summary;
+                    console.log(
+                        `Total: ${aggregate.scored} scored, ${aggregate.insufficient} insufficient, ` +
+                            `${aggregate.outside} outside band; ${aggregate.words} words; ` +
+                            `pooled flesch=${aggregate.flesch === null ? "n/a" : fixed(aggregate.flesch)} ` +
+                            `syl/word=${aggregate.words ? fixed(aggregate.syllables / aggregate.words, 2) : "n/a"} ` +
+                            `mean=${aggregate.sentences ? fixed(aggregate.words / aggregate.sentences) : "n/a"}w ` +
+                            `unfamiliar=${aggregate.words ? fixed((100 * aggregate.unfamiliar) / aggregate.words) : "n/a"}% ` +
+                            `nominalizations/1k=${aggregate.words ? fixed((1000 * aggregate.nominalizations) / aggregate.words) : "n/a"}`,
+                    );
+                    if (argv.failOutside && aggregate.outside) process.exitCode = 1;
+                    return;
+                }
+                if (argv.failOutside) throw new Error("--fail-outside applies only to prose score");
                 const options = {
-                    age: argv.age ?? defaults.age,
-                    threshold: argv.threshold ?? defaults.threshold,
-                    minWords: argv.minWords ?? defaults.minWords,
+                    age: argv.age ?? defaults.proseLint.age,
+                    threshold: argv.threshold ?? defaults.proseLint.threshold,
+                    minWords: argv.minWords ?? defaults.proseLint.minWords,
+                    rules: argv.rules ?? defaults.proseLint.rules,
                 };
                 for (const [key, value] of Object.entries(options)) {
+                    if (key === "rules") continue;
                     if (
                         !Number.isInteger(value) ||
                         value < 1 ||
@@ -278,13 +358,12 @@ function proseCommand() {
                         );
                     }
                 }
-                const findings = await lintProse(
-                    argv.path ?? config.paths.content,
-                    options,
-                    config.skipDirectories,
-                );
-                for (const finding of findings) emitDiagnostic(finding);
+                const findings = await lintProse(root, options, config.skipDirectories);
+                for (const finding of findings) {
+                    emitDiagnostic({ ...finding, file: displayFile(finding.file) });
+                }
                 log.info(`${findings.length} prose suggestion(s).`);
+                if (argv.failOnWarning && findings.length) process.exitCode = 1;
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;

package/bin/package-build.mjs

@@ -540,7 +540,10 @@ function datefromCommand() {
                     type: "string",
                     describe: "Calendar Address or shortcode",
                 })
-                .positional("date", { type: "string", describe: "Day in that calendar" }),
+                .positional("date", {
+                    type: "string",
+                    describe: "Day written in that calendar's std format (or first named format)",
+                }),
         handler: handler((args) => {
             console.log(dateFromCalendar(args.calendar, args.date, calendarConversionContext()));
         }),
@@ -561,10 +564,19 @@ function datetoCommand() {
                 .positional("canonical-date", {
                     type: "string",
                     describe: "Canonical <year>.<day>[:HHMMSS]",
+                })
+                .option("format", {
+                    type: "string",
+                    describe: "Named calendar format; defaults to std or the first declared format",
                 }),
         handler: handler((args) => {
             console.log(
-                dateToCalendar(args.calendar, args.canonicalDate, calendarConversionContext()),
+                dateToCalendar(
+                    args.calendar,
+                    args.canonicalDate,
+                    calendarConversionContext(),
+                    args.format,
+                ),
             );
         }),
     };

package/config.mjs

@@ -76,6 +76,7 @@ const SECTION_KEYS = [
     "container",
     "e2e",
     "proseLint",
+    "proseScore",
 ];
 
 /**
@@ -528,7 +529,8 @@ function normalizeExceptions(value, field, where) {
  *
  * @typedef {object} PackageBuildConfig
  * @property {string} rootDir        The repository root, from package-build.
- * @property {{age: number, threshold: number, minWords: number}} proseLint Optional prose analysis settings.
+ * @property {{age: number, threshold: number, minWords: number, rules: string}} proseLint Optional prose lint settings.
+ * @property {{minWords: number, bands: Record<string, {min?: number, max?: number}>}} proseScore Optional note score settings.
  * @property {string} packageKind    `systems` or `modules`.
  * @property {string} packageId      The Foundry package id.
  * @property {string} artifact       Derived: `system` or `module`.
@@ -693,9 +695,20 @@ export function resolvePackageBuildConfig(shared) {
 
     const proseLint = section.proseLint ?? {};
     if (!isMapping(proseLint)) fail("packageBuild.proseLint", "must be a mapping");
-    rejectUnknownKeys(proseLint, ["age", "threshold", "minWords"], "packageBuild.proseLint.");
-    const proseOptions = { age: 21, threshold: 5, minWords: 8 };
+    rejectUnknownKeys(
+        proseLint,
+        ["age", "threshold", "minWords", "rules"],
+        "packageBuild.proseLint.",
+    );
+    const proseOptions = { age: 21, threshold: 5, minWords: 8, rules: "readability" };
     for (const [key, value] of Object.entries(proseLint)) {
+        if (key === "rules") {
+            if (!["readability", "simplify", "all"].includes(value)) {
+                fail("packageBuild.proseLint.rules", "must be readability, simplify, or all");
+            }
+            proseOptions.rules = value;
+            continue;
+        }
         const upper = key === "threshold" ? 7 : Infinity;
         if (!Number.isInteger(value) || value < 1 || value > upper) {
             fail(
@@ -708,6 +721,43 @@ export function resolvePackageBuildConfig(shared) {
         proseOptions[key] = value;
     }
 
+    const proseScore = section.proseScore ?? {};
+    if (!isMapping(proseScore)) fail("packageBuild.proseScore", "must be a mapping");
+    rejectUnknownKeys(proseScore, ["minWords", "bands"], "packageBuild.proseScore.");
+    const scoreMinWords = proseScore.minWords ?? 80;
+    if (!Number.isInteger(scoreMinWords) || scoreMinWords < 1) {
+        fail("packageBuild.proseScore.minWords", "must be a positive integer");
+    }
+    const bands = proseScore.bands ?? {};
+    if (!isMapping(bands)) fail("packageBuild.proseScore.bands", "must be a mapping");
+    const scoreMetrics = [
+        "flesch",
+        "syllablesPerWord",
+        "meanSentenceWords",
+        "longestSentenceWords",
+        "unfamiliarWordPercent",
+        "nominalizationsPer1000Words",
+    ];
+    rejectUnknownKeys(bands, scoreMetrics, "packageBuild.proseScore.bands.");
+    const scoreBands = {};
+    for (const [metric, band] of Object.entries(bands)) {
+        const where = `packageBuild.proseScore.bands.${metric}`;
+        if (!isMapping(band)) fail(where, "must be a mapping");
+        rejectUnknownKeys(band, ["min", "max"], `${where}.`);
+        if (band.min === undefined && band.max === undefined) {
+            fail(where, "must specify min, max, or both");
+        }
+        for (const [limit, value] of Object.entries(band)) {
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                fail(`${where}.${limit}`, "must be a finite number");
+            }
+        }
+        if (band.min !== undefined && band.max !== undefined && band.min > band.max) {
+            fail(where, "min must not exceed max");
+        }
+        scoreBands[metric] = Object.freeze({ ...band });
+    }
+
     if (section.assets !== undefined && !Array.isArray(section.assets)) {
         fail("packageBuild.assets", "must be a list");
     }
@@ -809,6 +859,7 @@ export function resolvePackageBuildConfig(shared) {
     return Object.freeze({
         rootDir: shared.rootDir,
         proseLint: Object.freeze(proseOptions),
+        proseScore: Object.freeze({ minWords: scoreMinWords, bands: Object.freeze(scoreBands) }),
         // Where the package is assembled before it is zipped or deployed. Every
         // asset destination is relative to it, so a repository's table says
         // `lang`, not `build/stage/lang` — the latter is what each consumer's

package/docs/api.md

@@ -623,7 +623,7 @@ The closed registry of system ids, and the `none` that stands for no system at a
 
 ### `engine.calendars`
 
-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.
+The axis every date normalises onto, the arithmetic over a calendar's month list, and the moon. A calendar's `data.epoch` anchors its year 1, day 1 on that axis; its eras declare in-calendar start years. 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` uses a floored modulo on either side of the epoch.
 
 The neutral day spelling is `<year>.<day>[:HHMMSS]`. The pure conversion functions take the world's year length and an explicit origin year, so their arithmetic names no month or era. A caller supplies those values from its content; no setting year is baked into the toolchain.
 
@@ -647,29 +647,29 @@ The neutral day spelling is `<year>.<day>[:HHMMSS]`. The pure conversion functio
 
 ### `engine.noteDates`
 
-A date on a note is one authored string. `<year>.<day>[:HHMMSS]` names a calendar-neutral day; `datefrom vrcal 23 Taranis 326 VR` names a calendar, a named month, and an era. Either form may begin with `~` for an approximate date. A resolved calendar date carries a canonical year, day, span and sort key. Print `prose ?? text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. `resolvedDateFields` supplies identical derived records to JSONL and generated page frontmatter.
-
-| Export                  | Signature                                        | Returns                                            | Use it when                                                    |
-| ----------------------- | ------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------- |
-| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`                             | —                                                  | naming the literal that says a date is not recorded            |
-| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`                        | —                                                  | matching the date grammar directly                             |
-| `DATEFROM_PATTERN`      | `const DATEFROM_PATTERN`                         | —                                                  | recognizing a named calendar conversion in frontmatter         |
-| `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   |
-| `eraCovering`           | `eraCovering(date, eras, daysPerYear)`           | one era or `null`; throws on overlap               | selecting the era covering a resolved date's full precision    |
-| `formatNoteDate`        | `formatNoteDate(date, era, daysPerYear)`         | `{era, year, month, day, text, prose}` or `null`   | printing a resolved date in a chosen era or its authored form  |
-| `formatDateInCalendar`  | `formatDateInCalendar(date, reference, context)` | printable record or `null`                         | selecting a calendar's era and printing a resolved date in it  |
-| `calendarEras`          | `calendarEras(reference, context)`               | ordered era records                                | resolving an addressed calendar or one of its eras             |
-| `resolvedDateFields`    | `resolvedDateFields(fm, context)`                | map of normalized dates                            | deriving being and lore event date records for index and pages |
+A date on a note is one authored scalar. `<year>[.<day>[:HHMMSS]]` names a calendar-neutral year, day, or second; `datefrom vrcal 23 Taranis 326 VR` names a calendar, a named month, and an era. Year and day values span their written interval; a clock time identifies a second. Either form may begin with `~` for uncertainty beyond that interval. The `approximate` field records that explicit marker, while `precision` and `seconds` describe the interval or time. A resolved date carries a canonical year, span, and sort key; a neutral year has no `canonicalDay`, while day-precision dates have one. Print `prose ?? text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. `resolvedDateFields` supplies identical derived records to JSONL and generated page frontmatter.
+
+| Export                  | Signature                                                     | Returns                                            | Use it when                                                    |
+| ----------------------- | ------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------- |
+| `UNKNOWN_DATE`          | `const UNKNOWN_DATE`                                          | —                                                  | naming the literal that says a date is not recorded            |
+| `NOTE_DATE_PATTERN`     | `const NOTE_DATE_PATTERN`                                     | —                                                  | matching the date grammar directly                             |
+| `DATEFROM_PATTERN`      | `const DATEFROM_PATTERN`                                      | —                                                  | recognizing a named calendar conversion in frontmatter         |
+| `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   |
+| `eraCovering`           | `eraCovering(date, eras, daysPerYear)`                        | one era or `null`; throws on overlap               | selecting the era covering a resolved date's full precision    |
+| `formatNoteDate`        | `formatNoteDate(date, era, daysPerYear, formatName?)`         | `{era, year, month, day, text, prose}` or `null`   | printing a resolved date in a chosen era or its authored form  |
+| `formatDateInCalendar`  | `formatDateInCalendar(date, reference, context, formatName?)` | printable record or `null`                         | selecting a calendar's era and printing a resolved date in it  |
+| `calendarEras`          | `calendarEras(reference, context)`                            | ordered era records                                | resolving an addressed calendar or one of its eras             |
+| `resolvedDateFields`    | `resolvedDateFields(fm, context)`                             | map of normalized dates                            | deriving being and lore event date records for index and pages |
 
 ### `engine.dateConversion`
 
-The exact-day conversion functions use the corpus reckoning context. A calendar with several eras requires an era in the named date. They reject dates outside the selected calendar and gaps between its eras. Approximate input keeps its `~` prefix in the result.
+The exact-day conversion functions use the corpus reckoning context. `dateFromCalendar` reads the `std` pattern, or the first named pattern. An era-relative year needs its era label. They reject dates outside the selected era; approximate input keeps its `~` prefix.
 
-| Export             | Signature                                           | Returns               | Use it when                                   |
-| ------------------ | --------------------------------------------------- | --------------------- | --------------------------------------------- |
-| `dateFromCalendar` | `dateFromCalendar(reference, value, context)`       | canonical date string | converting one calendar day to the world axis |
-| `dateToCalendar`   | `dateToCalendar(reference, canonicalDate, context)` | calendar date string  | expressing one canonical day in a calendar    |
+| Export             | Signature                                                        | Returns               | Use it when                                   |
+| ------------------ | ---------------------------------------------------------------- | --------------------- | --------------------------------------------- |
+| `dateFromCalendar` | `dateFromCalendar(reference, value, context)`                    | canonical date string | converting one calendar day to the world axis |
+| `dateToCalendar`   | `dateToCalendar(reference, canonicalDate, context, formatName?)` | calendar date string  | expressing one canonical day in a calendar    |
 
 ### `engine.calendarChoice`
 
@@ -700,7 +700,7 @@ invokes the check during frontmatter lint.
 
 ### `engine.reckoningMarkers`
 
-The corpus registry maps every declared era to its calendar and each marker to exactly one era. Era starts may use the canonical axis or another declared era. Within one calendar, starts increase; the next start bounds the preceding era unless an explicit end leaves a gap. The first era also covers dates before its start and counts them with negative years. Later eras accept only forward year counts. Unknown eras, duplicate markers, invalid bounds, overlapping eras and dependency cycles are findings. Short qualifiers are ambiguous when they name eras in several packages; a full address selects one. This registry governs note dates; calendar definitions emitted for Foundry retain their consumer format.
+The corpus registry anchors each calendar's year 1, day 1 to its canonical `data.epoch` and maps every declared era to that calendar. Exactly one `start: null` era covers earlier years and counts backwards; exactly one `start: 1` era begins the forward count. Other starts are distinct positive calendar years. Numeric order determines bounds, irrespective of array order. Duplicate starts and markers, missing required eras, and invalid epochs are findings. Short qualifiers are ambiguous when they name eras in several packages; a full Address selects one.
 
 | Export                    | Signature                                     | Returns                                  | Use it when                                                 |
 | ------------------------- | --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
@@ -720,7 +720,7 @@ A calendar is a `lore` note with `subType: calendar`, declaring the months it ke
 | `CALENDAR_FORMAT_TOKENS`    | `const CALENDAR_FORMAT_TOKENS`                        | —                                          | checking bare date tokens in a format string                                |
 | `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         |
-| `checkCalendarDateFormats`  | `checkCalendarDateFormats(note)`                      | `object[]` — findings                      | checking display slots and escaped literal words                            |
+| `checkCalendarDateFormats`  | `checkCalendarDateFormats(note)`                      | `object[]` — findings                      | checking named patterns and the readable default                            |
 | `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                                         |

package/docs/authoring/dates-and-calendars.md

@@ -7,27 +7,79 @@ subType: howto
 
 # Dates, calendars, and eras
 
-A canonical date names a day without assuming how a culture divides a year. Write `<year>.<day>[:HHMMSS]`: `720.136` is day 136 of year 720, and `720.136:143005` adds a 24-hour time. A negative year is valid. The day must fit the world's declared year length. The dot separates year from **day of year**, not month from day.
+A canonical date uses the world's year and day count without choosing a culture's calendar. Write `<year>[.<day>[:HHMMSS]]`: `720` covers year 720, `720.136` covers its day 136, and `720.136:143005` identifies 14:30:05 on that day. The dot separates the year from the **day of year**, not a month. Negative years are valid, and the day must fit the world's declared year length. Prefix a date with `~` when its uncertainty extends outside the stated year, day, or second. `unknown` records an occurrence whose date is not known, in fields that permit it.
 
-Authors can instead write a named calendar date in frontmatter:
+## Define a calendar
+
+A `lore` note with `subType: calendar` names months, weekdays, seasons, named days, eras, and date formats. Its `data.epoch` is the **canonical day that equals calendar year 1, day 1**. For a calendar beginning on canonical day `1.91`, write `epoch: 1.91`: calendar year 1 still starts at its own day 1. A calendar does not state the length of the world year: its months must sum to `data.year.days` on the world's `place` note.
 
 ```yaml
+shortcode: commoncal
+name: { full: The Common Calendar }
+type: lore
+subType: calendar
 data:
-  born: datefrom vrcal 23 Taranis 326 VR
-  died: ~326.114
+  epoch: 1.1
+  months:
+    - { name: Floralis, abbreviation: Flor, days: 30 }
+    - { name: Lusenar, abbreviation: Luse, days: 31 }
+    - { name: Murkas, abbreviation: Murk, days: 30 }
+    - { name: Taranis, abbreviation: Tara, days: 31 }
+    - { name: Vulcar, abbreviation: Vulc, days: 30 }
+    - { name: Menaris, abbreviation: Mena, days: 31 }
+    - { name: Venuris, abbreviation: Venu, days: 30 }
+    - { name: Karnavar, abbreviation: Karn, days: 30 }
+    - { name: Morveth, abbreviation: Morv, days: 31 }
+    - { name: Thanaris, abbreviation: Than, days: 30 }
+    - { name: Aetheris, abbreviation: Aeth, days: 31 }
+    - { name: Janar, abbreviation: Jana, days: 30 }
+  weekdays:
+    - { name: Newday, abbreviation: New }
+    - { name: Tillday, abbreviation: Til }
+    - { name: Growday, abbreviation: Gro }
+    - { name: Harvestday, abbreviation: Hrv }
+    - { name: Reapday, abbreviation: Rep }
+    - { name: Slowday, abbreviation: Slo }
+    - { name: Setday, abbreviation: Set }
+  seasons:
+    - { name: Spring, abbreviation: Spr, start: 1 }
+    - { name: Summer, abbreviation: Sum, start: 92 }
+    - { name: Fall, abbreviation: Fal, start: 183 }
+    - { name: Winter, abbreviation: Win, start: 274 }
+  namedDays:
+    - { name: New Years Day, abbreviation: NY, day: 1 }
+  formats:
+    std: "MM/DD/Y GGG"
+    long: "D MMMM Y GGG"
+  eras:
+    - { shortcode: bvr, name: Before Vylarian Reckoning, abbreviation: BVR, start: null }
+    - { shortcode: vr, name: Vylarian Reckoning, abbreviation: VR, start: 1 }
 ```
 
-`datefrom` takes a calendar shortcode or Address, then the date in that calendar. The calendar defines month names and eras. A date can have day, month, or year precision. Prefix either spelling with `~` for an approximate date. `unknown` means an occurrence is known but its date is not recorded, in fields that accept it. These are the frontmatter date forms; do not put a Handlebars expression there.
+The `weekdays` array gives the names in order, starting at index 0. Weeks continue across month and year boundaries. Leave `weekdays` out when the calendar has no week. `seasons[].start` is the one-based day of year on which a season begins. Starts increase in array order. A season continues through the day before the next, and the last wraps through the beginning of the next year when the first season starts after day 1. `namedDays[].day` is also a one-based day of year. Its name appears through `[namedDay]`; `[namedDayAbbr]` prints the abbreviation.
+
+Every calendar has exactly one era with `start: null` and one with `start: 1`. The null era covers the years before calendar year 1 and counts them backwards: under `Y GGG`, package-build prints canonical `-50.2` as `50 BVR` when the epoch is `1.1`. This null-start era is an authoring extension and is omitted from the Calendaria definition; Foundry's calendar represents current time. Each other `start` is a distinct, positive **calendar year**, never a day-precise date: `start: 701` begins on day 1 of calendar year 701. `start: 1` begins on the canonical day given by `epoch`, even when that day is `1.91` or another date. Eras end where the next numeric start begins. Array order does not determine chronology. The optional `marker` identifies an era in authored dates and must be unique across the corpus.
+
+`formats` contains any number of named Calendaria patterns. `std` is the default for `dateto`, `datefrom`, and `dateformat`; if absent, the first named pattern is the default. The default pattern must contain enough information to read a day back: a complete year (`Y`, `YYYY`, or `[yearInEra]`), a day of year (`DDD`) or month and day, and an era label when using `[yearInEra]`. `Y` means the calendar year in Calendaria; `[yearInEra]` means the year counted from the era's start. In package-build's null-start era, `Y`, `YY`, and `YYYY` print the positive historical year. Other named patterns can use display-only Calendaria tokens. Use `package-build dateto <calendar> <canonical-date> --format <name>` or `{{dateformat "commoncal" data.born "long"}}` to select another output format. The [format token reference](../reference/format-details.md#calendar-format-tokens) lists every Calendaria token and the input constraints.
+
+## Write and convert dates
 
-A calendar defines the order and length of months. An era defines where a year count begins. One calendar can have several eras; a multi-era date names its era. Era starts increase on the canonical timeline, with gaps allowed. Dates before the first era use a negative year in that first era; later eras count forward from their own year 1. There is no year zero. A date in a gap has no named era in that calendar.
+A frontmatter date can use the canonical form or `datefrom <calendar> <date in the default format>`. The calendar may be a shortcode or Address. A named date keeps the precision it states: with the sample `std` pattern, `326 VR` covers a year, `04/326 VR` covers Taranis, and `04/23/326 VR` covers its twenty-third day. A date with an era-relative year names its era.
+
+```yaml
+data:
+  born: datefrom commoncal 04/23/326 VR
+  died: ~326.114
+```
 
-Use the CLI to inspect a conversion:
+The conversion commands take the same forms:
 
 ```bash
-package-build datefrom vrcal '23 Taranis 326 VR'
-package-build dateto vrcal 326.114
+package-build datefrom commoncal '04/23/326 VR'
+package-build dateto commoncal 326.114
+package-build dateto commoncal 326.114 --format long
 ```
 
-`datefrom` prints the canonical value; `dateto` prints a named date in the era covering it. The [detailed calendar rules](../reference/format-details.md#dates-and-calendars) explain precision, era markers, bounds, and resolution errors.
+The CLI `datefrom` command requires a day and reads the default (`std`, or first) pattern. `dateto` prints the era covering the canonical day. A clock time makes a date exact; a year or day without one spans the stated interval. `data.epoch` and `data.moon.newOn` require a day. The [detailed date rules](../reference/format-details.md#dates-and-calendars) describe precision and bounds.
 
-In prose, `{{dateformat "vrcal" data.born}}` renders a date in the chosen calendar. `{{dateformat data.calendar data.born}}` uses the note's own calendar Address. A being or place can set `data.calendar`; a being's infobox displays its dates in that calendar, and a place's infobox displays its `present` there.
+In prose, `{{dateformat "commoncal" data.born}}` prints a date in the chosen calendar. `{{dateformat data.calendar data.born}}` uses the note's calendar Address. A third argument chooses another named pattern. A being or place can set `data.calendar`; its infobox uses that calendar for dates.

package/docs/authoring/links-and-markup.md

@@ -134,4 +134,4 @@ The index contains {{digits (sql "SELECT COUNT(*) FROM entries")}} entries.
 {{and (gt 3 5) (lt 4 2)}}
 ```
 
-Use `{{dateformat data.calendar data.born}}` when the note supplies a calendar Address. SQL fences produce tables; the `sql` helper returns one value for an inline expression. Wrap a numeric result in `words` for running prose or `digits` for a grouped numeral. See [date rules](dates-and-calendars.md) and [SQL details](../reference/format-details.md#content-tables) for query options.
+Use `{{dateformat data.calendar data.born}}` when the note supplies a calendar Address. A third argument selects a named output pattern, as in `{{dateformat data.calendar data.born "long"}}`. SQL fences produce tables; the `sql` helper returns one value for an inline expression. Wrap a numeric result in `words` for running prose or `digits` for a grouped numeral. See [date rules](dates-and-calendars.md) and [SQL details](../reference/format-details.md#content-tables) for query options.