@heroiclands/package-build 22.21.0 → 22.22.0

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`
 

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.
 

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

@@ -17,7 +17,11 @@ An Address names content independently of its filename or folder. Its full form
 
 The part after `|` is the displayed link text or an embed's alternative text. An empty label uses the target's current name in a regular link and marks an embed decorative. A missing pipe is an error. Search may use `name.full` and aliases; authored links use Addresses. The [Address reference](../reference/format-details.md#addresses) explains short forms, package qualification, and ambiguity diagnostics.
 
-A link to a note tagged `draft` retains its target and carries a visible draft cue. In a book, the cue reads `(draft)` after the link. A link that resolves nowhere produces a diagnostic and reads `(unresolved link)` after its label in the book.
+A link to a note tagged `draft` retains its target and carries a visible draft cue. In a book, the cue reads `(draft)` after the link.
+
+**An address that resolves nowhere is an error on all three surfaces**, worded the same way by each. The pack build refuses the note and produces no pack from it. The site build and the book build write what they can and fail the run: a page marks the link for the reader, and a book sets `(unresolved link)` after its label. The book is written so the page carrying the mistake can be found, not because the mistake is tolerated there.
+
+An HTML comment is an aside to whoever reads the note next, and no surface shows one — the packs and the website emit it into the HTML, where it stays a comment, and a book leaves it out. Write a `markdownlint` pragma or a note about a quoted passage freely. A comment inside a fence or a code span is an example and is printed as written, and a comment that is never closed is an error.
 
 ## Journal pages and anchors
 
@@ -33,7 +37,29 @@ The harbor faces west.
 Travelers present their papers here. See [[#harbor|the harbor]].
 ```
 
-Another note can link to `[[lore-harbor#customs-house|Customs House]]`. The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields. For Items, `{#description}` selects the JournalEntryPage both systems reference. A map note can use an anchored heading for a scene pin; the compiler replaces the pin's exported JournalEntry and page IDs with the built note's IDs and uses the heading text as its label. See [map notes](../reference/format-details.md#type-map) for scene fields.
+A `:::caption` block starts a JournalEntryPage too, named for the caption's own label, in Foundry alone — the web and the book keep the caption in the flow of the page around it. The prose introducing a captioned block and the block itself land on two different Foundry pages, so a reference such as `[[#trade|]]` written just above a caption sends a Foundry reader to a different page than the one carrying the sentence. Give the introducing prose its own heading, or accept that following the reference leaves the page, before relying on a caption to sit inside a longer page's flow.
+
+A heading's braces hold an attribute block, not an anchor alone: `#slug` names the anchor, `.class` adds a CSS class, and `key="value"` writes an attribute. The website and a Foundry journal carry all three onto the heading; a book keeps the anchor and drops the rest, because Typst has no stylesheet to name a class in. Braces holding anything but an attribute block — `# The set {a, b}` — are reported at the heading's line and set as written.
+
+Another note can link to `[[lore-harbor#customs-house|Customs House]]`. For Items, `{#description}` selects the JournalEntryPage both systems reference, and accepts a heading at any level. A map note can use an anchored heading for a scene pin; the compiler replaces the pin's exported JournalEntry and page IDs with the built note's IDs and uses the heading text as its label. See [map notes](../reference/format-details.md#type-map) for scene fields.
+
+### A section players must not read
+
+Write `.secret` on the heading that opens the section:
+
+```markdown
+# The Cellar {#cellar .secret}
+
+The contraband is behind the false wall.
+```
+
+The section runs from that heading to the next heading that opens a page. In Foundry the page is the GM's alone. On the website and in the book the section sits inside the same expandable spoiler and the same labelled block a `:::secret` block gets. The heading keeps its id, so `[[lore-inn#cellar|the cellar]]` still resolves to it.
+
+**On the website this is a spoiler, not access control.** The withheld section is in the published page, so anyone who opens the element or reads the page source reads it. Foundry is the only surface that withholds anything. Write nothing in a `.secret` section that would matter if a player read it on the web.
+
+A `:::secret` block inside the section is legal and renders as it does anywhere else. `.secret` on a heading that opens no page — a lower-level heading with no anchor — covers no page, and is reported at its own line: give that heading an anchor, or raise it to the top level.
+
+The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
 ## Captions and numbered references
 
@@ -55,29 +81,77 @@ The table displays **Table 1: Regional trade routes**, and the reference display
 
 ## Images and protected content
 
-An image or icon embed stands on its own line. `size` accepts `auto`, `small`, `medium`, `large`, and `xlarge`; the medium maps those names to suitable dimensions. `float` controls placement. The asset remains an Address, so moving the file within its asset root does not change the link. See [assets](assets.md) and [image directives](../reference/format-details.md#images).
+An image or icon embed stands on its own line; one that does not is a lint error naming the line, because a width or a position means nothing applied to a word in the middle of a sentence. `size` accepts `auto`, `small`, `medium`, `large`, `xlarge` and `full-width`; the medium maps those names to suitable dimensions, and `full-width` is the full page in the book and the full content width elsewhere. `float` controls placement and takes `top-left`, `top-right`, `bottom-left`, `bottom-right` or `center`; on a page a float occupies the column measure, so only the vertical half of a corner position has an effect there. The asset remains an Address, so moving the file within its asset root does not change the link. See [assets](assets.md) and [image directives](../reference/format-details.md#images).
+
+### Named blocks
 
-A `:::secret` block marks GM material while keeping it in the same authored note:
+Three named blocks set a passage apart from the prose around it. `:::secret`
+marks GM material, `:::info` a neutral note, and `:::warn` a caution:
 
 ```markdown
-:::secret
-The harbor master is working for the smugglers.
+:::warn
+The bridge closes during the spring flood.
 :::
 ```
 
-Players who deliberately inspect source or generated output may see it; the block is a presentation distinction, not access control. The [detailed reference](../reference/format-details.md#what-a-note-produces) describes each medium's handling.
+Each heads itself with its own name — **Secret**, **Info**, **Warn** — and takes
+a closing `:::`. A name that is not one of the three is reported.
+
+**A GM-only section holds a box.** A `:::secret` is a container for whatever the
+GM reads, boxes included, and a box written inside one stays inside it. A box
+holds no named block of its own, so a second box inside a box is reported. A
+`:::caption` belongs to the caption construct and may be written inside any of
+them.
 
-Use `:::info` for a neutral note and `:::warn` for a caution. Both render as
-labelled, colored boxes on the web and in Foundry, and as print boxes in a book:
+**An attribute block follows the name.** It is the same braced grammar the other
+body extensions use, so it carries an id, classes, and any attribute the element
+should have. `title` is reserved and supplies the heading in place of the default:
 
 ```markdown
-:::warn
-The bridge closes during the spring flood.
+:::secret {#harbor title="For the GM" .wide data-stage="two"}
+The harbor master is working for the smugglers.
 :::
 ```
 
-An optional `{#id}` gives the box an HTML anchor. These blocks need a closing
-`:::` and cannot be nested.
+That block carries the classes `secret wide`, the id `harbor`, and
+`data-stage="two"`, and it heads **For the GM**. A title carries emphasis of its
+own — `title="The *Genzet* only"` — and nothing else: a tag written there is
+shown rather than obeyed. Set the id with `#id` and classes with `.class` rather
+than through an `id=` or `class=` key, and note that an event handler such as
+`onclick=` is refused rather than written.
+
+**The name is the first class on the element, and the appearance belongs to a
+stylesheet.** No block is emitted with an inline `style`, so a package restyles
+one from its own sheet. `info` and `warn` are styled by the base stylesheet;
+`secret` is left to Foundry, which styles `section.secret` itself and owns the
+reveal control on it.
+
+Each surface renders the same block its own way:
+
+| Surface | Output                                                                             |
+| ------- | ---------------------------------------------------------------------------------- |
+| Foundry | `<section class="secret" id="harbor">` with the title as its first line            |
+| Web     | `<details class="secret" id="harbor">` the reader opens, titled in its `<summary>` |
+| Book    | a coloured print box headed by the title                                           |
+
+A `secret` with no id of its own is given one derived from its body on the
+Foundry surface, because Foundry remembers a revealed section by its id.
+
+**A secret is a presentation distinction, not access control.** Players who
+deliberately inspect source or generated output may see it. The
+[detailed reference](../reference/format-details.md#what-a-note-produces)
+describes each medium's handling.
+
+**One malformed block does not silence the others.** A block whose attributes do
+not parse is reported at its own line and left as written; every well-formed
+block in the same note still renders.
+
+**A heading that would start its own journal page cannot be written inside a
+block, or inside a caption.** An H1, or a heading of any level carrying an
+`{#anchor}`, is reported at its own line there — starting a page would tear
+the block in two, and a reader could open the second half with none of the
+box around it. A lower heading with no anchor is unaffected and is the
+ordinary way to structure a long box.
 
 ## Footnotes and definition lists
 
@@ -95,14 +169,18 @@ The road is passable in summer.[^season] The bridge has a toll.[^2]
 [^2]: The toll is collected at the eastern gate.
 ```
 
-Definitions can appear anywhere at the top level of the note. Indent a
-following paragraph or code block by four spaces to include it in the same
-footnote. Keep definitions outside lists, block quotes, and tables. On the web,
-linked footnotes appear in a Footnotes section at the bottom of the HTML page.
-In Foundry, each JournalEntryPage places its referenced footnotes in a Footnotes
-section at the bottom of that page; definitions remain available across pages
-of the same note. In a book, footnotes appear in smaller type at the bottom of
-the page that contains their reference.
+A reference may be written anywhere prose can be written — a word in a
+quotation, a bullet, a table cell, a heading, a named block, a caption. A
+definition belongs at the top level of the note: indent a following paragraph
+or code block by four spaces to include it in the same footnote, but never
+inside a list, a block quote, or a table. A definition written there, or a
+reference with none at the top level to resolve against, is reported at its
+own line rather than rendered. On the web, linked footnotes appear in a
+Footnotes section at the bottom of the HTML page. In Foundry, each
+JournalEntryPage places its referenced footnotes in a Footnotes section at the
+bottom of that page; definitions remain available across pages of the same
+note. In a book, footnotes appear in smaller type at the bottom of the page
+that contains their reference.
 
 A definition list gives a term one or more definitions:
 
@@ -115,9 +193,19 @@ Janapada
 The web and Foundry render a definition list with HTML `<dl>`, `<dt>`, and
 `<dd>` elements. The book renders it as a term list.
 
-## Tables and expressions
+## Lists
+
+A list item's text begins right after its marker. `[ ]` and `[x]` there are
+plain words, not a checkbox — write what is done into the item itself:
+
+```markdown
+- the harbor toll: paid
+- the ferry crossing: owed
+```
+
+## SQL generated tables
 
-Use a SQL fence to render a table from the content index. The table reads frontmatter from indexed notes. A zero-row result is an error unless the fence explicitly permits an empty result.
+A fence marked `sql` is replaced by a table built from the content index. The query reads the frontmatter of every indexed note, so a table is written once and stays true as notes are added.
 
 ````markdown
 ```sql
@@ -125,13 +213,134 @@ SELECT name.full AS "Name" FROM notes WHERE type = 'lore' ORDER BY name.full
 ```
 ````
 
-Inline expressions can read the note, format dates, combine values, or run scalar SQL:
+A column's heading is its SQL alias, so `AS "Name"` is what a reader sees. A cell that is absent prints an em dash. A `|` or a line break inside a value is escaped, so neither breaks the table.
+
+### What a query can read
+
+| Relation          | What it holds                                                                                                                 |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `notes`           | Every note except a stub. This is the one to use unless a stub is wanted.                                                     |
+| `entries`         | Every note, stubs included.                                                                                                   |
+| `market`          | The market scale as three columns — `value`, `name`, `trade` — so a table can print `village` beside the number a note wrote. |
+| `<package>.notes` | The same two relations for each package this one declares a dependency on, in a schema named for it.                          |
+
+Nested frontmatter is addressed exactly as a note writes it: `name.full`, `sohl.weight`, `data.born`. Every note carries a computed `state` column of `full`, `draft` or `stub`. Notes tagged `gm` are absent from the relations on public surfaces.
+
+### Fence attributes
+
+A braced list may follow the language on the opening fence. Two attributes are accepted, and anything else is reported by name.
+
+| Attribute       | Value                       | Default | What it does                                                                                                                                                                            |
+| --------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allow-empty`   | `true` or `false`           | `false` | Whether a query selecting no rows is allowed. A zero-row result is a finding otherwise, because a table that silently prints nothing is the commonest way a query goes wrong unnoticed. |
+| `section-level` | an integer from 1 through 6 | `2`     | The heading level given to each group a `_section` column creates.                                                                                                                      |
+
+````markdown
+```sql {allow-empty=true section-level=3}
+SELECT name.full AS "Name" FROM notes WHERE type = 'being' AND data.gender = 'none'
+```
+````
+
+A zero-row result reports which relation was queried: a query over `notes` that would have found rows in `entries` says so, so the fix is `FROM entries` rather than `{allow-empty=true}`.
+
+### Two column names the renderer reads
+
+Two aliases are instructions rather than columns, and neither is printed.
+
+| Alias      | What it does                                                                                                                                                       |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `_ref`     | The note a row points at, written as the `type-shortcode` address a wikilink resolves. The row's first column becomes a link to that note.                         |
+| `_section` | Partitions the result into separate tables, each under a heading of its own. Order the query by the same expression, because a group ends where the value changes. |
+
+```sql
+SELECT type AS "_section", name.full AS "Name", address.slug AS "_ref"
+FROM notes WHERE type IN ('lore', 'place') ORDER BY type, name.full
+```
+
+See [SQL details](../reference/format-details.md#content-tables) for query options.
+
+## Page lists
+
+A fence marked `pagelist` is replaced by a list of the pages carrying a tag. Where a content table answers "what do these notes say?", a page list answers "which pages belong to this group?" — and the group is expressed by intent rather than enumerated, so a page joins it by being tagged and leaves it by being untagged.
+
+````markdown
+```pagelist {tag="key-concept"}
+
+```
+````
+
+**The fence holds nothing.** Everything the directive says about itself is written in the braced attribute block, in the same grammar every other body extension uses. Text written inside the fence is reported rather than printed.
+
+Each page comes out as a link to the note, so one authored directive reaches a reader as a compendium link in Foundry, a page link on the website, and a page reference in the book. A link into a note tagged `draft` carries the same cue an authored link to it would.
+
+### Page-list attributes
+
+<!-- page-list-attributes:start -->
+
+| Attribute      | Value             | Default    | What it does                                                                                                                                              |
+| -------------- | ----------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tag`          | a tag             | required   | The tag a page carries to join the list. Matched the way `tags:` is read — case and a leading `#` are not significant, the spelling of the tag itself is. |
+| `type`         | a note type       | every type | Restricts the list to one note type. A page's address is `<type>-<shortcode>`, so the type is what divides the corpus into kinds of page.                 |
+| `sort`         | `name` or `type`  | `name`     | The order the pages come out in. `name` is alphabetical; `type` groups the note types and orders by name within each.                                     |
+| `descriptions` | `true` or `false` | `false`    | Whether each page's `description` follows its link. A page that states none carries its link alone.                                                       |
+| `allow-empty`  | `true` or `false` | `false`    | Whether a tag carried by no page is allowed. It is a finding otherwise, because a heading with nothing under it is how a misspelled tag goes unnoticed.   |
+
+<!-- page-list-attributes:end -->
+
+````markdown
+```pagelist {tag="key-concept" type=lore sort=type descriptions=true}
+
+```
+````
+
+That list names the `lore` notes tagged `key-concept`, grouped by type and alphabetical within each, with every page's `description` after its link. A page that states no description carries its link alone.
+
+**A tag no page carries is a finding** at the fence's own line, naming the tag it looked for. A misspelled tag is the whole of what goes wrong here, and a heading with an empty list under it is how one goes unnoticed. Write `{allow-empty=true}` where a group that is genuinely empty is intended; the directive then leaves nothing behind rather than an empty list.
+
+A page list names this package's own pages. A **stub** — a note with an empty body — publishes no page, so it joins no list. A note tagged `gm` is listed in Foundry and left out of the website and the book, exactly as it is left out of a content table's relations.
+
+See [page-list details](../reference/format-details.md#page-lists) for the directive's full behaviour.
+
+## Expressions
+
+An expression in `{{ }}` is replaced by a value, inline in a sentence. The note's own frontmatter is the context, so a field is read by the path a note writes it at.
 
 ```markdown
-{{name.full}} was born on {{dateformat "vrcal" data.born}}.
+{{name.full}} was born on {{dateformat data.calendar data.born}}.
 There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} beings.
-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. 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.
+### The rules of the construct
+
+- **A field that the note does not carry is a finding, not a blank.** Expressions are compiled strictly, so a misspelled path is reported rather than quietly printing nothing.
+- **An expression is one line.** It may not contain a line break or a brace.
+- **A failed expression leaves its own text in the page** and reports the line and column it is written on, so the page is readable and the fault is locatable.
+- **`\{{` writes an expression without evaluating it**, for an example in prose.
+- **`{{{…}}}`, `{{<…}}` and `{{%…}}` are left alone.** A Hugo shortcode is not an expression.
+- **An expression inside a code fence is left alone.**
+- Helpers nest, with the inner call in parentheses: `{{words (sql "…")}}`.
+
+### Helpers
+
+<!-- expression-helpers:start -->
+
+| Helper       | Parameters                 | What it gives you                                                                                                                                                         |
+| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eq`         | `a b`                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                 |
+| `gt`         | `a b`                      | True when a is greater than b. Both must be finite numbers.                                                                                                               |
+| `gte`        | `a b`                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                   |
+| `lt`         | `a b`                      | True when a is less than b. Both must be finite numbers.                                                                                                                  |
+| `lte`        | `a b`                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                      |
+| `not`        | `value`                    | True when the value is false, zero, empty or absent.                                                                                                                      |
+| `and`        | `value …`                  | True when every value given is true. Takes two or more.                                                                                                                   |
+| `or`         | `value …`                  | True when any value given is true. Takes two or more.                                                                                                                     |
+| `words`      | `number`                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                   |
+| `digits`     | `number`                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                    |
+| `sql`        | `"query"`                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                              |
+| `dateformat` | `calendar date ["format"]` | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern. |
+
+<!-- expression-helpers:end -->
+
+A helper that is given the wrong kind of value reports it rather than printing something wrong: `words` refuses a decimal, the four comparisons refuse anything that is not a finite number, and `dateformat` refuses a date it cannot resolve in the calendar it was given.
+
+See [date rules](dates-and-calendars.md) for what `dateformat` accepts and the patterns its third argument names.