@heroiclands/package-build 22.14.4 → 22.15.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @heroiclands/package-build
 
+## 22.15.0
+
+### Minor Changes
+
+**Place maps** — Site pages, books, and Foundry itinerary Scenes render their maps with the installed build package, without a separate Graphviz installation.
+
+**Regional maps** — Foundry stages authored SVG backgrounds as PNGs without a separate SVG converter.
+
+**Content relationships**
+
+- A being's social ties now reject two entries naming the same target, even when one uses a shorter address.
+
+### Patch Changes
+
+**Content dates**
+
+- Notes can name a calendar era with a short marker such as `VR(720/5/14)`, while canonical dates use year and day of year.
+
+**Place maps** — Books give mapped places a full-page itinerary, and Foundry offers gridless itinerary Scenes with linked place journals.
+
+**Regional maps** — Hand-drawn SVG charts appear in books and use raster backgrounds in Foundry while retaining their stated scale.
+
+**Scenes** — Battle and local maps can use full Foundry Scene exports, with marked pins opening their note's journal pages and asset fixups resolving paths.
+
+**Theatre of the mind** — Image-led maps can create gridless Scenes for narration-focused play.
+
 ## 22.14.4
 
 ### Patch Changes

package/CONTENT.md

@@ -1277,7 +1277,9 @@ is from a closed set: the eight bearings, `land | boat | ship`, a days scale of
 terrain names the modes that cross it. Every `to` must be the shortcode of a
 place, here or in a fetched index. The other end must state the pair back —
 at the opposite bearing, and for a route by the same mode in the same days.
-A neighbour stating nothing is a warning naming both notes; one stating a
+A settlement states a border only when it shares a frontier; most settlements
+use `parents` for location and `routes` for journeys. The terrain registry is
+shared across packages. A neighbour stating nothing is a warning naming both notes; one stating a
 different bearing, mode or days is an error, as is a border to the note's own
 parent or child, or a pair listed twice by one mode. Each finding lands on the
 entry that states it. The keys, the sets and the days scale are specified under
@@ -2683,6 +2685,24 @@ What the build guarantees:
 `map` is derived, never authored: a note that writes one has it replaced when
 the build draws a map, and dropped when there is none to draw.
 
+The same relations supply a PDF book's full-page vector map immediately after
+each selected place entry. When a Scene pack is configured, they also supply
+gridless Foundry Scenes with raster backgrounds and pins to journals in an
+Adventure. A place from a dependency receives a pin through an importable
+journal link when its published index includes a JournalEntry UUID. An
+authored `regionalmap` with SVG art keeps the SVG for site and book while the
+Foundry build stages a PNG. Its `data.scale` states the distance and unit per
+grid unit.
+
+Battle and local maps can carry a Foundry Scene export in `data.scene`. The
+Scene's canvas and embedded documents stay as authored. A pin whose text is
+`#anchor` opens the JournalEntry page with that heading in the map note and
+displays the heading text. A `totm` map uses a background image and dimensions
+to create a gridless Scene for theatre-of-the-mind play.
+An exported Scene can declare `data.fixup` entries that resolve asset Addresses
+into specific Scene fields. A fixup path can select an embedded document by its
+stable `_id`, so reordering the export does not redirect the replacement.
+
 ### Why the output location is fixed
 
 The content mount is a build artifact and is **deleted on every run**, so that a
@@ -2803,6 +2823,10 @@ columns is set across the page. Two columns are print's answer and print's
 alone — a scrolling page has no fixed viewport, so the website keeps one
 measure with a side rail.
 
+An itinerary map uses a separate full-width page after its place entry. The
+vector drawing fits the printable area and carries a heading naming the
+viewpoint. A selected authored regional SVG map takes a page in the same way.
+
 A note's `description:` sets as an epigraph between short rules under the
 plate. It disappears rather than leave a shell: a note with no description has
 no epigraph. The running foot carries the section's name, an ornament and the

package/bin/content-build.mjs

@@ -1531,7 +1531,7 @@ function pdfCommand() {
  * wikilink resolution, code-fence protection and the foreign-manifest merge —
  * happens here, from configuration. So does the Hugo configuration: the whole
  * source tree Hugo reads lands under `build/hugo/`, and the consumer's script
- * runs Hugo over it. With `site.maps` on and GraphViz installed, every place
+ * runs Hugo over it. With `site.maps` on, every place
  * page with a border or a route carries the map from that place.
  *
  * **The Hugo configuration is generated before anything is written.** Its
@@ -1674,10 +1674,7 @@ function siteCommand() {
                     return;
                 }
 
-                // What drawing the maps found: warnings, every one. A site
-                // never fails for want of a map, so none of these touches the
-                // exit code — GraphViz absent is one line naming what to
-                // install, and every page is written as it would be without.
+                // Relation warnings do not fail a site build.
                 for (const f of result.mapFindings) emitDiagnostic(f);
 
                 const s = result.stats;
@@ -1707,8 +1704,7 @@ function siteCommand() {
  * check, whose anomalies are reported as findings), the map from a place
  * from its `borders` and `routes` (`--from`), the chart from a place — the
  * same drawing at a larger horizon (`--chart`, `--horizon`) — and the whole
- * route graph (`--travel`). GraphViz draws; when it is absent the command
- * says what to install and stops.
+ * route graph (`--travel`). The installed Graphviz runtime draws each map.
  *
  * @returns {object} The yargs command module.
  */

package/bin/package-build.mjs

@@ -49,6 +49,7 @@
  * Usage:
  *   npx package-build clean [--distclean]
  *   npx package-build assets
+ *   npx package-build calendars --calendaria-version <version>
  *   npx package-build manifest
  *   npx package-build lang check
  *   npx package-build lang coverage [--unused]
@@ -88,6 +89,7 @@ import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
+import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
@@ -316,6 +318,28 @@ function assetsCommand() {
     };
 }
 
+/** Emit the package's calendar definitions from its content index. */
+function calendarsCommand() {
+    return {
+        command: "calendars",
+        describe: "Emit calendar definitions and Calendaria import files",
+        builder: (y) =>
+            y.option("calendaria-version", {
+                type: "string",
+                demandOption: true,
+                describe: "Calendaria import format version",
+            }),
+        handler: handler((args) => {
+            const config = loadPackConfig();
+            const result = emitCalendarArtifacts({
+                config,
+                calendariaVersion: args.calendariaVersion,
+            });
+            console.log(`✅ ${result.calendars} calendars emitted (${result.files} files).`);
+        }),
+    };
+}
+
 /**
  * Format generated text the way the repository formats everything else.
  *
@@ -1386,6 +1410,7 @@ yargs(hideBin(process.argv))
     .scriptName("package-build")
     .command(cleanCommand())
     .command(assetsCommand())
+    .command(calendarsCommand())
     .command(manifestCommand())
     .command(siteRootCommand())
     .command(schemaCommand())

package/docs/api.md

@@ -558,36 +558,33 @@ The drawings of `content-build map` as DOT text, sharing one style table: shape,
 
 ### `engine.mapGraphviz`
 
-GraphViz, as the map command reaches it: a build-time tool of that command alone, found once, named plainly when absent, and run over a `.dot` file the command keeps beside the rendering.
+The npm-installed Graphviz runtime draws SVG maps and supplies the plain positions used by Foundry itinerary pins. PNG backgrounds are rasterized from the same SVG layout. The `.dot` source stays beside each rendering.
 
-| Export                   | Signature                                               | Returns             | Use it when                                                                                |
-| ------------------------ | ------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
-| `GRAPHVIZ_ENGINES`       | `const GRAPHVIZ_ENGINES`                                | `readonly string[]` | the engines the map command may ask for — `dot`, `twopi`, `neato`                          |
-| `GRAPHVIZ_INSTALL`       | `const GRAPHVIZ_INSTALL`                                | `string`            | what installs GraphViz, as the clause every "not installed" message ends with              |
-| `findGraphviz`           | `findGraphviz(engine, { env, fallbacks })`              | `string\|undefined` | finding an engine's binary on `PATH` or in the directories a package manager installs into |
-| `graphvizMissingMessage` | `graphvizMissingMessage(engine)`                        | `string`            | saying an engine is not installed, and what installs it                                    |
-| `renderDot`              | `renderDot(dotPath, outPath, { binary, format, args })` | `{warnings}`        | rendering a `.dot` file, the engine's warnings returned and a non-zero exit thrown         |
+| Export             | Signature                                                   | Returns             | Use it when                                            |
+| ------------------ | ----------------------------------------------------------- | ------------------- | ------------------------------------------------------ |
+| `GRAPHVIZ_ENGINES` | `const GRAPHVIZ_ENGINES`                                    | `readonly string[]` | choosing `dot`, `twopi`, or `neato`                    |
+| `renderDot`        | `renderDot(dotPath, outPath, { engine, format, nop, dpi })` | `{warnings}`        | rendering a DOT source to SVG, plain positions, or PNG |
 
 ### `engine.mapBuild`
 
-`content-build map` as a function: the drawings written under an output directory, always the `.dot` beside the `.svg`, the tree's anomalies returned as findings, and a missing GraphViz either an error or — for a build that would rather skip — one warning.
+`content-build map` as a function: drawings written under an output directory, with each `.dot` beside its `.svg` and tree anomalies returned as findings.
 
-| Export          | Signature                                                                                                                                             | Returns                        | Use it when                                                                   |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
-| `MAP_DIR`       | `const MAP_DIR`                                                                                                                                       | `string`                       | where the maps land below a package's root, `build/map`                       |
-| `FROM_ALL`      | `const FROM_ALL`                                                                                                                                      | `string`                       | the `--from` or `--chart` value that means every place with a relation, `all` |
-| `relatedPlaces` | `relatedPlaces(places)`                                                                                                                               | `string[]`                     | every place that states, or is named in, a border or a route                  |
-| `buildMaps`     | `buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz })` | `{written, findings, skipped}` | drawing any of the four from a loaded world                                   |
+| Export          | Signature                                                                                                                    | Returns               | Use it when                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------- |
+| `MAP_DIR`       | `const MAP_DIR`                                                                                                              | `string`              | where the maps land below a package's root, `build/map`                       |
+| `FROM_ALL`      | `const FROM_ALL`                                                                                                             | `string`              | the `--from` or `--chart` value that means every place with a relation, `all` |
+| `relatedPlaces` | `relatedPlaces(places)`                                                                                                      | `string[]`            | every place that states, or is named in, a border or a route                  |
+| `buildMaps`     | `buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities })` | `{written, findings}` | drawing any of the four from a loaded world                                   |
 
 ### `engine.siteMaps`
 
-The map from each place, drawn for the site: `content-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. GraphViz absent is one warning and no map; `site.maps: false` draws none.
+The map from each place, drawn for the site: `content-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. `site.maps: false` draws none.
 
-| Export         | Signature                                                       | Returns            | Use it when                                                                                                     |
-| -------------- | --------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `SITE_MAP_DIR` | `const SITE_MAP_DIR`                                            | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
-| `inlineSvg`    | `inlineSvg(svg)`                                                | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
-| `drawSiteMaps` | `drawSiteMaps({ records, foreignIndex, config, base, locate })` | `{maps, findings}` | drawing the map from every related place of this package, keyed by the URL of the page that carries it          |
+| Export         | Signature                                               | Returns            | Use it when                                                                                                     |
+| -------------- | ------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `SITE_MAP_DIR` | `const SITE_MAP_DIR`                                    | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
+| `inlineSvg`    | `inlineSvg(svg)`                                        | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
+| `drawSiteMaps` | `drawSiteMaps({ records, foreignIndex, config, base })` | `{maps, findings}` | drawing the map from every related place of this package, keyed by the URL of the page that carries it          |
 
 ### `engine.systems`
 
@@ -609,21 +606,28 @@ The closed registry of system ids, and the `none` that stands for no system at a
 
 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            |
+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.
+
+| 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                                     |
+| `monthDayOfYear`          | `monthDayOfYear(months, ordinal)`                          | `{month, day}` or `null`               | reading an ordinal day in a calendar's month layout                             |
+| `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            |
+| `canonicalDayOffset`      | `canonicalDayOffset(year, day, originYear, daysPerYear)`   | signed whole-day offset                | placing a canonical date against a chosen origin                                |
+| `canonicalDateFromOffset` | `canonicalDateFromOffset(offset, originYear, daysPerYear)` | `{year, day}`                          | recovering a canonical date, including days before the origin                   |
+| `formatCanonicalDate`     | `formatCanonicalDate(date, daysPerYear)`                   | canonical date string                  | printing a day and optional 24-hour time without calendar months                |
+| `parseCanonicalDate`      | `parseCanonicalDate(value, daysPerYear)`                   | `{year, day, seconds?}` or `null`      | reading that spelling without accepting a month date                            |
 
 ### `engine.noteDates`
 
-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.
+A date on a note is one authored string. `<year>.<day>[:HHMMSS]` names a calendar-neutral day; `VR(720/5/14)` names an era marker and a date in that era's calendar. A marker is resolved from calendar notes in the corpus and contributes a canonical year, day, and sort key. Print `text`, order on `sort`, and do arithmetic on `canonicalYear`. The literal `unknown` has no sort key or canonical year. Unmarked slash dates and the addressed era qualifier are also accepted by the parser; a caller supplies the corpus marker map and world year length when it needs a marker resolved.
 
 | Export                  | Signature                       | Returns                                            | Use it when                                                   |
 | ----------------------- | ------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
@@ -632,6 +636,15 @@ A date on a note is one authored string — `[~][-]YYYY[/MM[/DD]] [<calendar sho
 | `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.reckoningMarkers`
+
+The corpus registry maps each declared marker to exactly one era and its calendar. An era start may use the canonical axis or a marker already resolvable from the corpus; duplicate markers and cycles are findings.
+
+| Export                    | Signature                                     | Returns                            | Use it when                                                 |
+| ------------------------- | --------------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
+| `resolveReckoningMarkers` | `resolveReckoningMarkers(index, daysPerYear)` | `{markers, findings}`              | resolving authored era markers and their starts             |
+| `reckoningContext`        | `reckoningContext(index)`                     | `{markers, daysPerYear, findings}` | sharing one resolved date context across checks on a corpus |
+
 ### `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.
@@ -653,6 +666,20 @@ A calendar is a `lore` note with `subType: calendar`, declaring the months it ke
 | `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.calendarArtifacts`
+
+`emitCalendarArtifacts` reads the package's current content index and writes
+calendar files under `build/calendars/`. Each calendar produces a definition
+and an import envelope containing that same definition. The command line entry
+point is `package-build calendars --calendaria-version <version>`; run
+`content-build content-index` first. The generated import envelope carries a
+fixed ISO `exportedAt` sentinel so repeated builds of unchanged source emit
+identical bytes.
+
+| Export                  | Signature                                            | Returns                         | Use it when                                          |
+| ----------------------- | ---------------------------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| `emitCalendarArtifacts` | `emitCalendarArtifacts({config, calendariaVersion})` | `{directory, calendars, files}` | writing calendar files for a package's Foundry stage |
+
 ### `engine.beingAge`
 
 The middle state of a being's `age`: absent beside a dated `born`, it is computed against the package's declared present — the two dates compared, not the two years subtracted, so a birthday later in the year than the present counts one less. `applyComputedBeingAge` fills it in on the frontmatter object a pass already holds, never on the note; `checkBeingAge` is `being`'s `NOTE_VOCABULARY` check, raising a warning where an authored `age` disagrees with what a dated `born` computes to. An estimate's `~` is read the way a date's is: the authored string stays verbatim, and `ageYears` carries the magnitude beside it.
@@ -864,7 +891,7 @@ Publishing a content tree as a website. Compiling a content tree into compendium
 | `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                                                                        |
 | `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                                                                   |
 | `sitePageDecorator`   | `sitePageDecorator(config, index)`                | Function                                                                                                                               | Add the site's infobox and being metadata to a rendered page.                                                         |
-| `buildSite`           | `buildSite({ config, sqlTables, locate })`        | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
+| `buildSite`           | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
 
 ### `engine.sitePreview`
 

package/docs/commands.md

@@ -157,6 +157,50 @@ $ package-build assets
 
 [Configuration](configuration.md).
 
+### `package-build calendars`
+
+**NAME**
+
+Emit calendar definitions and Calendaria import files from the content index.
+
+**SYNOPSIS**
+
+```
+package-build calendars --calendaria-version <version>
+```
+
+**DESCRIPTION**
+
+Reads the package's current JSONL content index and writes
+`build/calendars/<shortcode>.json` and
+`build/calendars/<shortcode>.calendaria.json` for each calendar note. The
+import file contains the same definition and a fixed `exportedAt` sentinel,
+making both files reproducible. A package with no calendars gets an empty
+`build/calendars/` directory. Run `content-build content-index` after changing
+notes and before this command. Stage the generated directory with
+`packageBuild.assets` when the Foundry package should ship it.
+
+**OPTIONS**
+
+`--calendaria-version` is required and identifies the Calendaria
+import format targeted by the envelope. It has the form `major.minor.patch`.
+
+**EXIT STATUS**
+
+1 if the index is missing or invalid, a calendar shortcode is invalid or
+duplicated, a calendar has no world year, or the version is invalid. Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build calendars --calendaria-version 1.4.2
+✅ 5 calendars emitted (10 files).
+```
+
+**SEE ALSO**
+
+`content-build content-index`, [Getting started](getting-started.md).
+
 ### `package-build schema`
 
 **NAME**
@@ -1885,12 +1929,25 @@ index — this package's records and every declared dependency's fetched
 index — so a consumer's map draws its dependencies' places beside its own
 and no note is opened except to locate a finding. Everything lands under
 `build/map/`, always the `.dot` beside the `.svg`, so a drawing can be
-re-rendered, diffed or read without the index. GraphViz draws: `dot` (or
-`twopi`, `neato`) for the tree, `neato` for the others. It is a build-time
-tool of this command alone; when the engine a run needs is not installed
-the command says so, names what to install, and stops. A build that asks
-for maps as one step of a larger job — a site build — writes the `.dot`
-files, emits one warning and skips the renderings rather than failing.
+re-rendered, diffed or read without the index. The npm-installed Graphviz runtime draws with `dot` (or `twopi`, `neato`)
+for the tree and `neato` for the other drawings.
+
+The containment tree draws every `world` note as a separate root. A map from a
+place follows that place's own relations, so another world in the package does
+not change its viewpoint.
+
+Site builds put a linked SVG in each eligible place page. PDF builds put a
+vector map on its own page immediately after each selected place entry with
+relations. A configured Scene pack stages PNG backgrounds and emits gridless
+itinerary Scenes and an Adventure containing the journals their pins open.
+The installed SVG renderer also stages PNG backgrounds for authored regional SVG maps.
+
+Battle and local map notes can carry a Foundry Scene export under `data.scene`.
+The pack compiler preserves its fields and binds pins marked `#anchor` to pages
+from the map note's Markdown. A `totm` map uses an image Address and canvas
+dimensions to make a gridless Scene.
+`data.fixup` resolves asset Addresses into selected fields of an exported Scene;
+a missing path or asset is a build error.
 
 The four drawings, any of which may be asked for in one run:
 
@@ -2019,8 +2076,7 @@ page can inline the SVG. Without it the names are plain text.
 
 1 when no drawing is asked for, when a `--from`, `--chart` or `--root`
 names no place, when `--horizon` is not a marker of the days scale, when
-the GraphViz engine a drawing needs is not installed, when a
-dependency's index cannot be read, when a note the index cannot record is
+the renderer fails, when a dependency's index cannot be read, when a note the index cannot record is
 met, on any error finding from `--tree` (a place with no parent, a parent
 that does not resolve, a cycle), or on any other thrown error. Otherwise 0
 — the warnings are reported and never fail the command.
@@ -2040,7 +2096,7 @@ $ content-build map --chart takheperurgn --horizon 90
 […] 394 place(s) → 1 drawing(s) under build/map
 
 $ content-build map --travel
-[…] GraphViz's `neato` is not installed, and `content-build map` draws with it; install GraphViz (`brew install graphviz` on macOS, `apt-get install graphviz` on Debian or Ubuntu) and run the command again
+[…] 394 place(s) → 1 drawing(s) under build/map
 ```
 
 **SEE ALSO**

package/docs/configuration.md

@@ -958,9 +958,8 @@ every place that states a border or a route or is named in one, lays it beside
 the page as `from-<shortcode>.svg`, and names the file in the page's front
 matter as `map`, which the theme inlines so every place name on it is a link
 to that place's page. A place with no relation carries no map and no key.
-GraphViz draws; when it is not installed the build says so once, as a
-warning, and writes every page as it would without maps — a site never fails
-for want of one. `false` draws nothing and asks nothing of GraphViz.
+The Graphviz runtime installed with package-build draws the maps. `false`
+draws nothing.
 
 ```yaml
 site:
@@ -1039,6 +1038,10 @@ is [`publish.site`](#publish), the same switch that gates the website —
 `content` builds one, `homepage` does not, so a package cannot end up with
 two switches that disagree about whether it publishes its content tree.
 
+Each selected place with a border or route receives a dedicated full-page
+vector itinerary after its entry. A selected authored regional SVG map also
+prints on its own page. The npm-installed Graphviz runtime draws itineraries.
+
 ```yaml
 pdf:
   title: The Hârn Ensemble