@heroiclands/package-build 22.20.0 → 22.22.0

package/config.mjs

@@ -65,6 +65,7 @@ const SECTION_KEYS = [
     "stageDir",
     "assets",
     "assetTransform",
+    "baseStyles",
     "manifest",
     "manifestFlags",
     "schema",
@@ -205,6 +206,23 @@ function requireNonEmptyString(value, where) {
     return /** @type {string} */ (value);
 }
 
+/**
+ * A declared switch, with the behaviour that applies when it is not declared.
+ *
+ * A truthy string is refused rather than coerced: `baseStyles: "false"` reads
+ * as off and would be on, which is the one wrong answer available here.
+ *
+ * @param {unknown} value - What was declared, or `undefined`.
+ * @param {boolean} fallback - The undeclared behaviour.
+ * @param {string} where - Dotted path, for the error.
+ * @returns {boolean} The setting.
+ */
+function requireBoolean(value, fallback, where) {
+    if (value === undefined) return fallback;
+    if (typeof value !== "boolean") fail(where, "must be true or false");
+    return value;
+}
+
 /**
  * One staging copy: a source path in the repository, and where it lands under
  * the staged package root.
@@ -537,6 +555,9 @@ function normalizeExceptions(value, field, where) {
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {boolean} baseStyles    Whether the package takes the shared base
+ *                                   stylesheet, staged into `stageDir` and
+ *                                   named first in the manifest's `styles`.
  * @property {Readonly<Record<string, unknown>>} manifest  The manifest
  *                                   specification, emitted as declared.
  * @property {string|null} manifestFlags  Module to load a `flags` function
@@ -877,6 +898,11 @@ export function resolvePackageBuildConfig(shared) {
                 ARTIFACT_OF_KIND[/** @type {"systems"|"modules"} */ (shared.packageKind)]
             :   requireNonEmptyString(releaseInput.artifact, "packageBuild.release.artifact"),
         assets: Object.freeze(assets),
+        // On by default, because the rules it carries are what compiled content
+        // needs to be legible and a package that declined them by omission
+        // would ship the content unstyled without anything saying so. A package
+        // that wants the surface entirely to itself says so.
+        baseStyles: requireBoolean(section.baseStyles, true, "packageBuild.baseStyles"),
         schema: normalizeSchema(section.schema),
         assetTransform:
             section.assetTransform === undefined ?

package/content-config.mjs

@@ -1580,6 +1580,7 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
     "params.notfound": "`site.notfound`",
     "markup.goldmark.renderer.unsafe": "the toolchain, whose pages carry raw HTML",
+    "markup.goldmark.extensions.taskList": "the toolchain, whose format has no checkbox",
     menu: "the navigation `package-build deps fetch` caches from heroiclands.org",
 });
 
@@ -1903,6 +1904,44 @@ function normalizePdf(value, rootDir) {
     });
 }
 
+/**
+ * A dotted version string as the three-element tuple Foundry compares.
+ *
+ * A missing component reads as `0`, so `"14"` compares as `14.0.0` — the
+ * common way an author writes a major-only floor or pin. A non-numeric
+ * component reads as `0` too, rather than throwing: this runs on values
+ * {@link requireNonEmptyString} has already accepted as non-empty strings,
+ * and a version with a qualifier (`"14.359.0-beta"`) is not this function's
+ * place to refuse.
+ *
+ * @param {string} version - A dotted version string.
+ * @returns {readonly [number, number, number]} Major, minor, patch.
+ */
+function versionTriple(version) {
+    const parts = version.split(".");
+    return [0, 1, 2].map((index) => {
+        const n = Number.parseInt(parts[index] ?? "0", 10);
+        return Number.isNaN(n) ? 0 : n;
+    });
+}
+
+/**
+ * Whether `verified` names a build below `minimum`, compared as version
+ * triples.
+ *
+ * @param {string} minimum - The declared floor.
+ * @param {string} verified - The declared verified build.
+ * @returns {boolean} `true` when `verified` sorts below `minimum`.
+ */
+function verifiedBelowMinimum(minimum, verified) {
+    const a = versionTriple(verified);
+    const b = versionTriple(minimum);
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i]) return a[i] < b[i];
+    }
+    return false;
+}
+
 /**
  * Validate a Foundry version range.
  *
@@ -1912,6 +1951,12 @@ function normalizePdf(value, rootDir) {
  * load-bearing there is `verified`, and a relationship may reasonably name a
  * package without pinning a floor at all.
  *
+ * **The two keys are a range, not two independent facts.** Foundry reads
+ * `verified` as the build inside `minimum`'s floor that was actually tested,
+ * so a `verified` below `minimum` names a build the package already refuses
+ * to install on. Caught only when both are present — a relationship naming
+ * `verified` alone has nothing to compare it against.
+ *
  * @param {unknown} value - The declared range, or `undefined`.
  * @param {string} where - Dotted path, for the error.
  * @param {boolean} [requireMinimum] - Whether `minimum` must be present.
@@ -1929,6 +1974,18 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
     if (input.verified !== undefined) {
         out.verified = requireNonEmptyString(input.verified, `${where}.verified`);
     }
+    if (
+        out.minimum !== undefined &&
+        out.verified !== undefined &&
+        verifiedBelowMinimum(out.minimum, out.verified)
+    ) {
+        fail(
+            `${where}.verified`,
+            `declares \`${out.verified}\`, below \`${where}.minimum\`'s \`${out.minimum}\` — ` +
+                "Foundry reads the two as one range, so a build below the floor is " +
+                "never the one verified against it",
+        );
+    }
     return Object.freeze(out);
 }
 
@@ -2022,6 +2079,21 @@ function normalizeSystems(value) {
         // declaration that cannot answer "which version was this built
         // against" is the gap this block exists to close.
         const verified = requireNonEmptyString(compat.verified, `${at}.compatibility.verified`);
+        const minimum =
+            compat.minimum === undefined || compat.minimum === null ?
+                null
+            :   requireNonEmptyString(compat.minimum, `${at}.compatibility.minimum`);
+        // Caught here too: the shape is the one {@link normalizeCompatibility}
+        // validates, and the same contradiction is possible wherever it
+        // appears.
+        if (minimum !== null && verifiedBelowMinimum(minimum, verified)) {
+            fail(
+                `${at}.compatibility.verified`,
+                `declares \`${verified}\`, below \`${at}.compatibility.minimum\`'s ` +
+                    `\`${minimum}\` — Foundry reads the two as one range, so a build ` +
+                    "below the floor is never the one verified against it",
+            );
+        }
 
         out[id] = Object.freeze({
             manifest:
@@ -2029,10 +2101,7 @@ function normalizeSystems(value) {
                     null
                 :   requireNonEmptyString(spec.manifest, `${at}.manifest`),
             compatibility: Object.freeze({
-                minimum:
-                    compat.minimum === undefined || compat.minimum === null ?
-                        null
-                    :   requireNonEmptyString(compat.minimum, `${at}.compatibility.minimum`),
+                minimum,
                 verified,
             }),
         });

package/docs/api.md

@@ -347,7 +347,7 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 ### `engine.noteVocabulary`
 
-An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`, `dnd5e`. A key outside this list is an error. The address vocabulary recognizes three systems: `sohl`, `hm3`, and `dnd5e`. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
+An addressed content note accepts exactly these top-level keys, in this order: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `dnd5e`, `hm3`, `sohl`. A key outside this list is an error at its own line. The system blocks are one per system the address vocabulary recognizes, sorted by name after the fixed keys, so a further system is a change to `SYSTEM_IDS` alone. No dnd5e-specific document types are declared. Within that shape, the closed vocabularies are the `data:` container and each type's `subType`.
 
 | Export                    | Signature                                    | Returns                                  | Use it when                                                                                  |
 | ------------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
@@ -355,6 +355,9 @@ An addressed content note accepts exactly these top-level keys, in this order: `
 | `GM_TAG`                  | `const GM_TAG`                               | —                                        | naming the declared tag that marks a GM-only note                                            |
 | `BEING_ARCHETYPES`        | `const BEING_ARCHETYPES`                     | `Readonly<Record<string, string>>`       | looking up the case-sensitive being archetypes and their meanings                            |
 | `NOTE_VOCABULARY`         | `const NOTE_VOCABULARY`                      | —                                        | looking up, per content type, its `data:` field list and its closed `subType` values         |
+| `NOTE_TOP_LEVEL_FIELDS`   | `const NOTE_TOP_LEVEL_FIELDS`                | `readonly TopLevelFieldSpec[]`           | reading the top-level keys a note accepts, in formatted order, with what each one means      |
+| `NOTE_TOP_LEVEL_KEYS`     | `const NOTE_TOP_LEVEL_KEYS`                  | `readonly string[]`                      | reading just the key names, in the order the formatter writes them                           |
+| `NOTE_TOP_LEVEL_KEY_SET`  | `const NOTE_TOP_LEVEL_KEY_SET`               | `ReadonlySet<string>`                    | testing whether a top-level key is one the note format declares                              |
 | `SHARED_DATA_FIELDS`      | `const SHARED_DATA_FIELDS`                   | `readonly DataFieldSpec[]`               | reading the `data:` keys every type accepts, whatever it is — the art slots legal everywhere |
 | `DECLARED_TAGS`           | `const DECLARED_TAGS`                        | —                                        | looking up the tags a note type may declare, grouped                                         |
 | `declaredTags`            | `declaredTags(type, groups)`                 | `readonly string[]`                      | reading the declared tags a note of a type may carry, flattened                              |
@@ -420,15 +423,15 @@ The infobox declarations this toolchain ships, one per system, and the single ca
 
 Drawing a declared infobox: HTML for separate Foundry pages appended after authored pages, Typst panels after each note’s authored body in the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
 
-| Export                 | Signature                             | Returns   | Use it when                                                              |
-| ---------------------- | ------------------------------------- | --------- | ------------------------------------------------------------------------ |
-| `infoboxTypstPreamble` | `infoboxTypstPreamble()`              | `string`  | emitting the panel definitions the book's bodies call, once per document |
-| `infoboxesToHtml`      | `infoboxesToHtml(boxes, options)`     | `string`  | drawing the boxes as `<details>` disclosures, open by default            |
-| `infoboxesToTypst`     | `infoboxesToTypst(boxes, options)`    | `string`  | drawing the boxes as panels that break between their sections            |
-| `linkToHtml`           | `linkToHtml(value)`                   | `string`  | drawing a link value as an anchor on its URL                             |
-| `linkToTypst`          | `linkToTypst(value, links, labelFor)` | `string`  | drawing a link value as a cross-reference into the book                  |
-| `linkToUuid`           | `linkToUuid(value)`                   | `string`  | drawing a link value as a Foundry document reference                     |
-| `sectionHasContent`    | `sectionHasContent(section)`          | `boolean` | deciding whether a section holds anything worth drawing                  |
+| Export                 | Signature                                   | Returns   | Use it when                                                              |
+| ---------------------- | ------------------------------------------- | --------- | ------------------------------------------------------------------------ |
+| `infoboxTypstPreamble` | `infoboxTypstPreamble()`                    | `string`  | emitting the panel definitions the book's bodies call, once per document |
+| `infoboxesToHtml`      | `infoboxesToHtml(boxes, options)`           | `string`  | drawing the boxes as `<details>` disclosures, open by default            |
+| `infoboxesToTypst`     | `infoboxesToTypst(boxes, options)`          | `string`  | drawing the boxes as panels that break between their sections            |
+| `linkToHtml`           | `linkToHtml(value)`                         | `string`  | drawing a link value as an anchor on its URL                             |
+| `linkToTypst`          | `linkToTypst(value, links, labelFor, site)` | `string`  | drawing a link value as a cross-reference into the book                  |
+| `linkToUuid`           | `linkToUuid(value)`                         | `string`  | drawing a link value as a Foundry document reference                     |
+| `sectionHasContent`    | `sectionHasContent(section)`                | `boolean` | deciding whether a section holds anything worth drawing                  |
 
 ### `engine.noteState`
 
@@ -692,12 +695,14 @@ invokes the check during frontmatter lint.
 
 ### `engine.markdownExpressions`
 
-`renderMarkdownExpressions(body, { fm, dates, sqlResults, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, file, bodyLine })` expands scalar frontmatter references and registered Handlebars helpers outside Markdown code. The `dateformat` helper uses `formatDateInCalendar`; `gt`, `gte`, `lt`, `lte`, `eq`, `and`, `or`, and `not` evaluate explicit comparisons. The `sql` helper reads a prepared scalar result, which must contain one row and one column. `sqlQueriesInMarkdown` discovers SQL calls, including nested calls; `prepareInlineSqlExpressions` evaluates them through the same DuckDB connection as SQL tables. `EXPRESSION_HELPERS` is the one list of helpers: the engine registers from it and the authoring document is checked against it, so each name there carries the parameters it takes and a sentence on what it does. The renderer returns `{ markdown, findings }`, with source positions for invalid expressions. Site, Foundry and PDF passes invoke it after generated tables expand and before links resolve. Hugo shortcodes remain literal for the site renderer.
 
-| Export                      | Signature                                  | Returns                | Use it when                                     |
-| --------------------------- | ------------------------------------------ | ---------------------- | ----------------------------------------------- |
-| `renderMarkdownExpressions` | `renderMarkdownExpressions(body, options)` | `{markdown, findings}` | expanding authored expressions in prose         |
-| `sqlQueriesInMarkdown`      | `sqlQueriesInMarkdown(body)`               | query strings          | preparing inline SQL alongside generated tables |
+| Export                      | Signature                                  | Returns                | Use it when                                      |
+| --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
+| `renderMarkdownExpressions` | `renderMarkdownExpressions(body, options)` | `{markdown, findings}` | expanding authored expressions in prose          |
+| `sqlQueriesInMarkdown`      | `sqlQueriesInMarkdown(body, fm?)`          | query strings          | preparing inline SQL alongside generated tables  |
+| `EXPRESSION_HELPERS`        | `EXPRESSION_HELPERS`                       | helpers by name        | listing what an expression may call              |
+| `EXPRESSION`                | `const EXPRESSION`                         | `RegExp`               | recognising an expression a pass has yet to read |
 
 ### `engine.reckoningMarkers`
 
@@ -1070,6 +1075,17 @@ An image saying how wide it is and where it sits. A directive in the curly-attri
 | `renderImageFigures`  | `function renderImageFigures(body, resolveSrc)` | {string} The same body, with each block image as a `<figure>`.                                                                                   | Rewrite every block image in a body into the figure the website publishes.   |
 | `imagePlugin`         | `function imagePlugin()`                        | {(md: object) => void} A markdown-it plugin.                                                                                                     | A markdown-it plugin that reads an image's directive and renders its figure. |
 
+### `engine.contentTaskLists`
+
+A list item opened with `[ ]` or `[x]`, reported. The format has no checkbox: a list is written in plain markdown, and the two characters right after a list item's marker are read as the start of its own text on every surface.
+
+| Export                 | Signature                                    | Returns                                                                                                                                                              | Use it when                                                                |
+| ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `TASK_LIST_MARKER`     | `const TASK_LIST_MARKER`                     | —                                                                                                                                                                    | A list item's marker, immediately followed by `[ ]` or `[x]` and a space.  |
+| `taskListMessage`      | `function taskListMessage(marker)`           | {string} The message, unpunctuated at the end as a finding is.                                                                                                       | What a note opening a list item with `[ ]` or `[x]` is told.               |
+| `checkTaskLists`       | `function checkTaskLists(body, file,`        | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} One finding per item, in source order.                                   | Every list item opened with `[ ]` or `[x]` in one note's body.             |
+| `lintContentTaskLists` | `function lintContentTaskLists(contentBase,` | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` The findings, and how many files were read. | Walk a content tree and report every list item opened with `[ ]` or `[x]`. |
+
 ### `engine.pathnames`
 
 One authored pathname, and the four addresses it resolves to. A note names a file once — in `img:`, in `data.portrait:`, in the body of a markdown image — and the first segment says which package owns it when an `assets/` follows. Every surface derives its own address from that one statement: the path inside a Foundry install, the file in the owning repository's tree, the address the website serves, and where the book stages its copy.
@@ -1111,9 +1127,9 @@ Prepared SQL content tables are expanded into Markdown before link resolution.
 A query selecting no rows reports an error unless its fence states
 `{allow-empty=true}`.
 
-| Export                | Signature                                              | Returns                                                                       | Use it when                                                |
-| --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `expandContentTables` | `expandContentTables(markdown, { source, sqlTables })` | `{markdown: string, errors: object[], lineMap: object[], warnings: object[]}` | Replace prepared SQL fences and preserve source locations. |
+| Export                | Signature                                                         | Returns                                                                       | Use it when                                                                |
+| --------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `expandContentTables` | `expandContentTables(markdown, { source, sqlTables, pageLists })` | `{markdown: string, errors: object[], lineMap: object[], warnings: object[]}` | Replace prepared SQL fences and page lists, and preserve source locations. |
 
 ### `engine.helpers`
 
@@ -1250,6 +1266,8 @@ A note's markdown, and a document plan, rendered as Typst source. **This module
 | `iconNamesIn`           | `function iconNamesIn(markdown)`                                                          | {string[]} The names, in order of appearance, with repeats.  | Every icon name a body uses, so a build can resolve them once.           |
 | `BOOK_IMAGE_WIDTHS`     | `const BOOK_IMAGE_WIDTHS`                                                                 | —                                                            | The book measure requested by each named image size.                     |
 | `bookTypstPreamble`     | `function bookTypstPreamble()`                                                            | {string} Typst markup.                                       | The Typst definitions the book's page furniture is drawn with.           |
+| `stripHtmlComments`     | `function stripHtmlComments(markdown)`                                                    | {string} The same body, its comments replaced by newlines.   | A markdown body with its HTML comments taken out.                        |
+| `absolutePageUrl`       | `function absolutePageUrl(url, site)`                                                     | {string} An absolute URL a reader of the book can follow.    | A page address as a reader of the book can follow it.                    |
 
 ### `engine.pdfFonts`
 
@@ -1288,15 +1306,15 @@ The content tree, built into a book. The I/O half of the PDF surface: it reads t
 
 Journals pack compiler — produces JSON pack files for the "journals" Foundry compendium from markdown notes in the `assets/content/` tree. The content root (`contentBase`) is walked recursively; any `.md` file whose frontmatter declares either `type: doc` or a **doc-carrying type** ({@link sohl.utils.packs.docEntryTypes} — every item type, plus `macro`) is compiled into one JournalEntry document. Each note's body is split on top-level H1 headings; the optional content before the first H1 becomes a lead page, and each subsequent H1 starts a new page named after its heading text. All page bodies are rendered to HTML.
 
-| Export                | Signature                                                                   | Returns                                                                                                                                                                        | Use it when                                                                                                                      |
-| --------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
-| `splitPages`          | `function splitPages(body, leadName`                                        | —                                                                                                                                                                              | Splits a markdown body into pages by top-level H1 headings.                                                                      |
-| `assertUniquePages`   | `function assertUniquePages(rawPages, noteName)`                            | —                                                                                                                                                                              | Two pages in one note that would derive the same id, which the LevelDB packer reports only as an opaque duplicate-key collision. |
-| `assertUniqueAnchors` | `function assertUniqueAnchors(rawPages, noteName)`                          | —                                                                                                                                                                              | The anchor half of {@link assertUniquePages}, under its former name.                                                             |
-| `journalPageId`       | `function journalPageId(entryId, page)`                                     | {string} A 16-character Foundry id.                                                                                                                                            | The id of one page within its entry.                                                                                             |
-| `buildPages`          | `function buildPages(rawPages, entryId, noteName)`                          | {Array<{_id: string, name: string, type: string, title: {show: boolean, level: number}, text: {format: number, content: string}, _key: string}>} The page documents, in order. | Compile split pages into JournalEntryPage documents.                                                                             |
-| `buildJournalEntry`   | `buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats })` | {object} The JournalEntry document, keyed for the pack.                                                                                                                        | Assemble one JournalEntry document from a note's converted markdown.                                                             |
-| `Journals`            | `class Journals extends BasePackCompiler`                                   | —                                                                                                                                                                              | not called directly — imported and driven by `engine/generate.mjs` as the "journals" pack compiler                               |
+| Export                | Signature                                                                   | Returns                                                                                                                                                                          | Use it when                                                                                                                      |
+| --------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `splitPages`          | `function splitPages(body, leadName`                                        | —                                                                                                                                                                                | Splits a markdown body into pages by top-level H1 headings.                                                                      |
+| `assertUniquePages`   | `function assertUniquePages(rawPages, noteName)`                            | —                                                                                                                                                                                | Two pages in one note that would derive the same id, which the LevelDB packer reports only as an opaque duplicate-key collision. |
+| `assertUniqueAnchors` | `function assertUniqueAnchors(rawPages, noteName)`                          | —                                                                                                                                                                                | The anchor half of {@link assertUniquePages}, under its former name.                                                             |
+| `journalPageId`       | `function journalPageId(entryId, page)`                                     | {string} A 16-character Foundry id.                                                                                                                                              | The id of one page within its entry.                                                                                             |
+| `buildPages`          | `function buildPages(rawPages, entryId, noteName)`                          | {Array<{\_id: string, name: string, type: string, title: {show: boolean, level: number}, text: {format: number, content: string}, \_key: string}>} The page documents, in order. | Compile split pages into JournalEntryPage documents.                                                                             |
+| `buildJournalEntry`   | `buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats })` | {object} The JournalEntry document, keyed for the pack.                                                                                                                          | Assemble one JournalEntry document from a note's converted markdown.                                                             |
+| `Journals`            | `class Journals extends BasePackCompiler`                                   | —                                                                                                                                                                                | not called directly — imported and driven by `engine/generate.mjs` as the "journals" pack compiler                               |
 
 ### `engine.macros`
 
@@ -1361,7 +1379,7 @@ Bundles, as notes — the Foundry `Adventure` a `type: bundle` note compiles int
 | `BUNDLE_TYPE`             | `const BUNDLE_TYPE`                                                                       | —                                                             | The note type a bundle is authored as.                                       |
 | `ADVENTURE_CONTENT_FIELD` | `const ADVENTURE_CONTENT_FIELD`                                                           | —                                                             | Foundry's `Adventure.contentFields`, keyed by the document class each holds. |
 | `CONTENTS_FIELD`          | `const CONTENTS_FIELD`                                                                    | —                                                             | The `data:` key a bundle lists its members under.                            |
-| `stripAdventureKeys`      | `function stripAdventureKeys(value)`                                                      | {*} The same shape with every `_key` removed.                 | Strip the LevelDB keys from a document tree.                                 |
+| `stripAdventureKeys`      | `function stripAdventureKeys(value)`                                                      | {\*} The same shape with every `_key` removed.                | Strip the LevelDB keys from a document tree.                                 |
 | `bareAddress`             | `function bareAddress(value)`                                                             | {string\|null} The bare address, or `null` for a blank entry. | An authored address with any wikilink brackets and label stripped.           |
 | `bundleContents`          | `function bundleContents(fm)`                                                             | {string[]} The bare addresses.                                | The addresses a bundle note names, in the order it names them.               |
 | `missingMemberVerdict`    | `function missingMemberVerdict(packSystem)`                                               | {"omit"\|"fail"} What to do about a member the sources lack.  | What a pass should do about a member its sources do not hold.                |

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

@@ -9,9 +9,11 @@ subType: howto
 
 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.
 
+**Put a date that states a day in quotes.** Write `born: "667.130"`, not `born: 667.130`. Unquoted, YAML reads the scalar as a number, and a number keeps no trailing zero — `667.130` becomes `667.13`, which is day 13 rather than day 130, and the authored digits are gone before any reader of the date can object. A date whose lost zero would still name a day inside the world's year is therefore refused, naming the line and both readings, so quoting it is the fix. A bare year such as `born: 667` loses nothing and needs no quotes.
+
 ## 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.
+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"` — quoted, like every canonical date that states a day: 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
@@ -19,7 +21,7 @@ name: { full: The Common Calendar }
 type: lore
 subType: calendar
 data:
-  epoch: 1.1
+  epoch: "1.1"
   months:
     - { name: Floralis, abbreviation: Flor, days: 30 }
     - { name: Lusenar, abbreviation: Luse, days: 31 }

package/docs/authoring/frontmatter.md

@@ -7,7 +7,7 @@ subType: howto
 
 # Frontmatter and system blocks
 
-HeroicLands notes begin with YAML frontmatter. A file is recognized as a note when its opening frontmatter has nonempty `shortcode` and `type` values. Ordinary Markdown files need neither. Keep top-level keys in this order, omitting keys that do not apply: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Any other top-level key is an error.
+HeroicLands notes begin with YAML frontmatter. A file is recognized as a note when its opening frontmatter has nonempty `shortcode` and `type` values. Ordinary Markdown files need neither. Keep top-level keys in this order, omitting keys that do not apply: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `dnd5e`, `hm3`, `sohl`. Any other top-level key is an error at its own line, naming the closed vocabulary and the declared key it was most likely meant to be. The [note-type reference](../reference/note-types.md#top-level-keys) says what each one means.
 
 ```yaml
 ---
@@ -35,7 +35,7 @@ The [note-type reference](../reference/note-types.md) lists every field accepted
 
 A being's `data.archetypes` names the roles it can fill in an adventure. Choose every specific role that fits, such as `entertainer` for a performer or `guildsperson` for someone whose professional training or connections matter. Use `[commoner]` when no specific archetype fits. `commoner` cannot share the list with another value. The [archetype reference](../reference/format-details.md#actors) defines the available roles.
 
-A `sohl:` or `hm3:` block holds values for that Foundry system. Its `system:` child contains values sent to the system's DataModel. The system block can override shared routing and art where the declared field permits it. `data.pack` and `data.packFolder` are shared routes; a system-specific route belongs in that system block. The [detailed mapping reference](../reference/format-details.md#mappings-every-type-shares) and [system-block explanation](../reference/format-details.md#frontmatter-has-three-regions) cover precedence and emitted fields.
+A `sohl:`, `hm3:` or `dnd5e:` block holds values for that Foundry system. Its `system:` child contains values sent to the system's DataModel. The system block can override shared routing and art where the declared field permits it. `data.pack` and `data.packFolder` are shared routes; a system-specific route belongs in that system block. The [detailed mapping reference](../reference/format-details.md#mappings-every-type-shares) and [system-block explanation](../reference/format-details.md#frontmatter-has-three-regions) cover precedence and emitted fields.
 
 One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.