@heroiclands/package-build 22.26.0 → 22.28.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @heroiclands/package-build
 
+## 22.28.0
+
+### Minor Changes
+
+Notes now require a nonempty body, including drafts, folders and homepages. Short written notes still warn unless tagged as drafts.
+
+## 22.27.0
+
+### Minor Changes
+
+- Governing bodies list the places they govern from each place’s stated government, keeping those lists consistent with place descriptions.
+- Tables that listed governing bodies through affiliation territory lists must query each place’s government instead.
+- Captions now precede the item they describe; use `:@` for numbered captions or `:` for captions without numbers.
+- Write poetry in a `poetry` code fence, and use attributed divs and inline spans to group or style text.
+- Replace former figure wrappers with leading captions; the old figure and poetry div fences are no longer supported.
+- Blockquote alerts provide note, tip, important and warning callouts; the former info and warn div fences are removed.
+
 ## 22.26.0
 
 ### Minor Changes

package/README.md

@@ -46,6 +46,8 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Error locations and severities                    | [Diagnostics](docs/diagnostics.md)                           |
 | Architectural rationale                           | [Design](docs/design.md)                                     |
 
-Place notes may declare a governing affiliation with `data.government`, or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](docs/authoring/frontmatter.md#place-governments).
+Place notes may declare a governing affiliation with `data.government` (`Address`, default target type `affiliation`), or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](docs/authoring/frontmatter.md#place-governments) and [government migration](docs/guides/government-migration.md).
+
+Leading captions, generic fenced divs, inline spans, and poetry code fences are described in [links and markup](docs/authoring/links-and-markup.md).
 
 The package is GPL-3.0-or-later for code and CC-BY-SA-4.0 for original content. See [LICENSE.md](LICENSE.md).

package/assets/styles/content-base.css

@@ -152,9 +152,8 @@
 }
 
 /*
- * Named body blocks. `:::info` and `:::warn` emit a `<section>` carrying the
- * block's name as its class, so the appearance belongs here rather than in an
- * inline `style` a consumer cannot override.
+ * Historical info/warn section classes remain available for styled prose.
+ * New alerts use the separate alert classes below.
  *
  * `secret` is deliberately absent: Foundry styles `section.secret` itself and
  * owns the reveal control on it, and a rule here would fight both.
@@ -205,3 +204,47 @@
         --pb-block-edge: #7a5100;
     }
 }
+
+/* Alerts share ordinary body colors, with an accent on their edge and title. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert {
+    border-inline-start: 0.25rem solid var(--pb-alert-color);
+    padding: 0.5rem 1rem;
+    margin: 1rem 0;
+    color: inherit;
+    background: transparent;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5em;
+    margin: 0 0 0.5rem;
+    font-weight: 600;
+    color: var(--pb-alert-color);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-icon {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+    fill: currentColor;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    .alert
+    > :last-child {
+    margin-bottom: 0;
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-note {
+    --pb-alert-color: #0969da;
+    --pb-alert-color: light-dark(#0969da, #4493f8);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-tip {
+    --pb-alert-color: #1a7f37;
+    --pb-alert-color: light-dark(#1a7f37, #3fb950);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-important {
+    --pb-alert-color: #8250df;
+    --pb-alert-color: light-dark(#8250df, #ab7df8);
+}
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .alert-warning {
+    --pb-alert-color: #9a6700;
+    --pb-alert-color: light-dark(#9a6700, #d29922);
+}

package/bin/content-commands.mjs

@@ -226,7 +226,12 @@ const SHIPPED_ITEM_FIELDS = { sohl: ITEM_FIELDS, hm3: HM3_ITEM_FIELDS };
 /** Register the content operations on the package command line. */
 export function registerContentCommands(cli) {
     return cli
-        .command(withIndexPreflight(packageCommand(), (_config, argv) => argv.action === "compile"))
+        .command(
+            withIndexPreflight(
+                withBodyPreflight(packageCommand(), (_config, argv) => argv.action === "compile"),
+                (_config, argv) => argv.action === "compile",
+            ),
+        )
         .command(depsCommand())
         .command(docsCommand())
         .command(withIndexPreflight(lintCommand()))
@@ -235,11 +240,17 @@ export function registerContentCommands(cli) {
         .command(withIndexPreflight(linksCommand()))
         .command(formatCommand())
         .command(markdownCommand())
-        .command(contentIndexCommand())
-        .command(withIndexPreflight(siteCommand(), publishesContentPages))
+        .command(
+            withBodyPreflight(
+                contentIndexCommand(),
+                () => true,
+                (config, argv) => argv.root || config.paths.content,
+            ),
+        )
+        .command(withIndexPreflight(withBodyPreflight(siteCommand()), publishesContentPages))
         .command(
             withIndexPreflight(
-                pdfCommand(),
+                withBodyPreflight(pdfCommand(), (config) => Boolean(config.pdf)),
                 (config) => config.pdf && publishesContentPages(config),
             ),
         )
@@ -380,6 +391,43 @@ function proseCommand() {
     };
 }
 
+/** Refuse invalid note bodies before emitting metadata, packs, pages or a book. */
+function withBodyPreflight(
+    command,
+    shouldCheck = () => true,
+    contentRoot = (config) => config.paths.content,
+) {
+    const handler = command.handler;
+    return {
+        ...command,
+        handler: async (argv) => {
+            try {
+                const config = loadPackConfig();
+                if (shouldCheck(config, argv)) {
+                    const contentBase = contentRoot(config, argv);
+                    if (!fs.existsSync(contentBase)) return handler(argv);
+                    const records = indexRecordsFor({ config, contentBase });
+                    const { findings } = lintNoteStates(contentBase, {
+                        records,
+                        contentPackage: config.contentPackage,
+                    });
+                    const errors = findings.filter((finding) => finding.severity === "error");
+                    if (errors.length) {
+                        for (const finding of errors) emitDiagnostic(finding);
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+                return;
+            }
+            return handler(argv);
+        },
+    };
+}
+
 /** Check declared dependency indexes before an index-consuming command does any work. */
 function withIndexPreflight(command, shouldCheck = () => true) {
     const handler = command.handler;
@@ -1167,7 +1215,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
 
-                // Whether every empty body is a stub on purpose, and how
+                // Whether every note has a body, and how
                 // finished the tree is. The counts and the oldest drafts are
                 // prose rather than findings: a note nobody has finished is not
                 // wrong, and 464 warnings a reader cannot clear is how a report

package/ci/publish-npm.mjs

@@ -0,0 +1,49 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Publish this package to npm, with provenance wherever it can be generated.
+ *
+ * `publishConfig.provenance` is `true`, and npm refuses a publish with
+ * `Automatic provenance generation not supported for provider: null` anywhere
+ * that cannot mint a Sigstore identity. That is a CI runner holding an OIDC
+ * token: GitHub Actions with `id-token: write`, which exposes
+ * `ACTIONS_ID_TOKEN_REQUEST_URL`, or GitLab CI with `SIGSTORE_ID_TOKEN`.
+ * Everywhere else — a desk — this passes `--provenance=false`, so the publish
+ * goes ahead unattested rather than failing.
+ *
+ * Arguments after `--` reach `npm publish` unchanged, so
+ * `npm run deploy:npm -- --dry-run` shows the tarball without publishing it.
+ * `prepack` builds the declarations and the asset index on the way.
+ *
+ * Not a `package-build` subcommand: it publishes this package and no other.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const env = process.env;
+const provenance =
+    (env.GITHUB_ACTIONS === "true" && Boolean(env.ACTIONS_ID_TOKEN_REQUEST_URL)) ||
+    (env.GITLAB_CI === "true" && Boolean(env.SIGSTORE_ID_TOKEN));
+
+if (!provenance) {
+    console.log("deploy:npm: no OIDC identity here; publishing without provenance.");
+}
+
+const args = ["publish", ...(provenance ? ["--provenance"] : ["--provenance=false"])];
+const result = spawnSync("npm", [...args, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+});
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);

package/docs/api.md

@@ -372,6 +372,7 @@ An addressed content note accepts exactly these top-level keys, in this order: `
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
 | `assertVocabularyCharset` | `assertVocabularyCharset(vocabulary, where)` | throws                                   | refusing a vocabulary declaration whose type or subType breaks the address charset           |
+| `isLegacyDataField`       | `isLegacyDataField(type, key)`               | `boolean`                                | testing accepted but ignored transitional affiliation `data.domains` input                   |
 | `dataFields`              | `dataFields(type, vocabulary)`               | `readonly DataFieldSpec[] \| undefined`  | looking up the `data:` keys a note type may carry                                            |
 | `subTypes`                | `subTypes(type, vocabulary)`                 | `readonly string[] \| null \| undefined` | looking up the closed `subType` values a note type declares                                  |
 
@@ -440,16 +441,16 @@ Drawing a declared infobox: HTML for separate Foundry pages appended after autho
 
 The three states of a note — **stub**, **draft**, **full** — and the one observable fact they rest on. A note whose body is empty is a stub: it carries its facts into the index and is queryable there, and it has no page, no address and no link target. Nothing is stored: the ladder is derived once in the SQL `entries` view and no note can assert its own state.
 
-| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                |
-| --------------------- | ------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                    |
-| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                   |
-| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` are structural and exempt                |
-| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                   |
-| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all |
-| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                             |
-| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
-| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words     |
+| Export                | Signature                                   | Returns                                 | Use it when                                                                                                                                               |
+| --------------------- | ------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NOTE_STATES`         | `const NOTE_STATES`                         | `ReadonlyArray<string>`                 | naming the three states in ladder order                                                                                                                   |
+| `isEmptyBody`         | `isEmptyBody(body)`                         | `boolean`                               | asking the exact question: is everything after the closing frontmatter fence whitespace?                                                                  |
+| `isStubbableType`     | `isStubbableType(type, vocabulary)`         | `boolean`                               | asking whether an empty body suppresses this type's page; `folder` and `homepage` retain their addresses in this classification, but still require bodies |
+| `isStubNote`          | `isStubNote(frontmatter, body, vocabulary)` | `boolean`                               | deciding whether one note is a stub, which is what the index and the site build both ask                                                                  |
+| `journalHasContent`   | `journalHasContent(body)`                   | `boolean`                               | asking whether the JournalEntry a body compiles into would hold anything, which is what decides whether one is made at all                                |
+| `PLACEHOLDER_PHRASES` | `const PLACEHOLDER_PHRASES`                 | `ReadonlyArray<string>`                 | reading the phrases that stand in for prose nobody has written                                                                                            |
+| `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                                                   |
+| `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting rendered prose, with wikilinks as one word and closed dashes, slashes, and ellipses separating adjacent words                                    |
 
 ### `engine.draftNotice`
 
@@ -470,7 +471,7 @@ What a draft note says about itself, in one sentence, on every surface it reache
 
 ### `engine.stubLint`
 
-An empty body must be deliberate. Four rules hold the state honest — a stub states what it is, a stub is not tagged `draft`, a body that renders to nothing is an abandoned draft, and a short unmarked body is asked whether it forgot its marker — and two reports say what the rules cannot decide.
+Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
 
 | Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
 | ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |
@@ -497,22 +498,24 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 
 ### `engine.holdings`
 
-What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the population-based government advisory `package-build lint` runs on a place.
+What lies within a place and which affiliation explicitly governs it — read off `data.parents` and resolved explicit `data.government` across this package and every fetched index, inverted into the `contains`, `governed_by` and `governed_places` lists the site build writes — and the population-based government advisory `package-build lint` runs on a place.
 
-| Export                 | Signature                            | Returns                 | Use it when                                                                                                                 |
-| ---------------------- | ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                | `readonly string[]`     | the three derived keys — `contains`, `held_by`, `holdings` — which a note cannot author                                     |
-| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                | `readonly string[]`     | deprecated historical tenure subtypes; government checks apply to every place subtype                                       |
-| `holdingsNode`         | `holdingsNode(fm, { title, url })`   | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation              |
-| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)` | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                  |
-| `holdingsPages`        | `holdingsPages(nodes)`               | `Map<string, Holdings>` | inverting `parents` and `domains` into each page's sorted lists, keyed by URL, for every page with at least one entry       |
-| `shortcodesOf`         | `shortcodesOf(value)`                | `string[]`              | the shortcodes a `parents` or `domains` value names — bare, addressed or wikilinked — empties dropped and repeats collapsed |
-| `checkGovernment`      | `checkGovernment(note)`              | `object[]`              | warning at `data.population` for positive population with no own `data.government` key; explicit null means anarchy         |
-| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | deprecated compatibility wrapper for `checkGovernment`; holdings do not determine government                                |
+| Export                 | Signature                                           | Returns                 | Use it when                                                                                                                                |
+| ---------------------- | --------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                               | `readonly string[]`     | derived `contains`, `governed_by`, `governed_places` and retired `held_by`/`holdings` keys removed from authored page metadata             |
+| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                               | `readonly string[]`     | deprecated historical tenure subtypes; government checks apply to every place subtype                                                      |
+| `holdingsNode`         | `holdingsNode(fm, { title, url, package, system })` | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation                             |
+| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)`                | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                                 |
+| `holdingsPages`        | `holdingsPages(nodes, { governmentNodes })`         | `Map<string, Holdings>` | inverting `parents` and resolved explicit `government` into each page's sorted lists, keyed by URL, for every page with at least one entry |
+| `shortcodesOf`         | `shortcodesOf(value)`                               | `string[]`              | the shortcodes a `parents` value names — bare or qualified Addresses — empties dropped and repeats collapsed                               |
+| `checkGovernment`      | `checkGovernment(note)`                             | `object[]`              | warning at `data.population` for positive population with no own `data.government` key; explicit null means anarchy                        |
+| `checkHeld`            | `checkHeld(note, { index })`                        | `object[]`              | deprecated compatibility wrapper for `checkGovernment`; holdings do not determine government                                               |
+
+Government-only supplemental records passed in `holdingsPages` options include public local stubs in the reverse lists without adding them to the geographical graph. Published nodes retain precedence; stubs without URLs render as plain text.
 
 ### `engine.populations`
 
-Whether a world's population figures agree from the region down — the polities and regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `package-build lint` runs all four as warnings.
+Whether a world's population figures agree from the region down — the regions inside a place against what it states, a settlement against every place containing it, and a `doc` note's cited figures against the notes that own them. `package-build lint` runs all three as warnings.
 
 | Export                  | Signature                                | Returns                | Use it when                                                                                                  |
 | ----------------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -700,7 +703,7 @@ invokes the check during frontmatter lint.
 
 ### `engine.markdownExpressions`
 
-`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, 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. The `ref` helper links to a `:::figure` fence by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `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.
+`renderMarkdownExpressions(body, { fm, dates, sqlResults, figures, 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. The `ref` helper links to a captioned item by its anchor — `"#thorn"` on the same note — in `number` (the default, and admitted explicitly), `full` or `title` form; `figures` is a `Map` of this note's own figures, by id, to `{label, caption, hasCaption}`, and an address naming another note is reported as unresolved rather than looked up. `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                                      |
 | --------------------------- | ------------------------------------------ | ---------------------- | ------------------------------------------------ |
@@ -1964,3 +1967,20 @@ The Changesets changelog generator, loaded with `require` — a CommonJS module
 ## `./package.json`
 
 Not a JavaScript module — this subpath entry exists so tooling (bundlers, `import.meta.resolve`, a script reading the installed version) can resolve the package's own `package.json` through Node's package-exports resolution instead of reaching outside the declared export map.
+
+## Markup parsing modules
+
+The engine wildcard subpath also exposes the body parsers below. Historical figure API names now operate on leading captions; `:::figure` is removed.
+
+| Module                       | Exports                                                                                      | Contract                                                                                                                                                                                                                               |
+| ---------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engine/content-figures.mjs` | `FIGURE_NAMES`, `FIGURE_CLASSES`, `scanFigures`, `numberFigures`, `renderFigureBlocks`       | Scan leading captions and their next supported blocks; `numbered` distinguishes `:` and `:@`. `type` may override inference; `example` is supported. `FIGURE_CLASSES` retains built-in styled classes, not a closed author vocabulary. |
+| `engine/content-blocks.mjs`  | `BLOCK_NAMES`, `BLOCK_CONTAINERS`, `scanBlocks`, `renderBlocks`, `renderWithheldSections`    | Read div and secret fences; info/warn names are retired; generic div records have `name: "div"` and no generated title. Scanning includes poetry errors.                                                                               |
+| `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
+| `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans and located errors; the renderer preserves inline Markdown in attributed HTML spans.                                                                             |
+
+`scanFigures` retains `line` (1-based caption line), `bodyStart`/`bodyEnd` (0-based, exclusive-end target range), and `close` (last consumed target line), plus caption attributes, kind, label and number. Unnumbered captions have an empty label and consume no number. `collectAnchors` discovers heading, caption, div, poem and span identifiers; `markupAnchorFindings(body)` reports collisions involving non-page identifiers; Foundry maps non-page anchors to the actual containing page UUID. An unnumbered `ref` requires `form="title"` or `form="full"`.
+
+`engine/content-alerts.mjs` exposes `ALERT_TYPES`, `scanAlerts(source)` and `renderAlerts(source, target)` and `alertMarkdownPlugin(md)`. The scanner returns `{blocks, errors}`; alert records carry `type`, `id`, `classes`, `attributes`, `title`, `body` and inclusive zero-based `start`/`end` source lines. The renderer produces attributed `aside.alert` wrappers while leaving alert body Markdown in the document's scope. Alert validation and anchor discovery run in site, Foundry and book pipelines.
+
+Alert `title` is the displayed heading override; absent, it defaults to the label in `ALERT_TYPES`. It does not change the alert type’s icon or color.

package/docs/authoring/first-note.md

@@ -45,4 +45,4 @@ The full Address is `<package>-note-lore-harbor`; `<package>` comes from `conten
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.
 
-A note with an empty body is a stub. It remains addressable as data, while a document that would have no content is omitted. See [note states](../reference/format-details.md#three-states-of-a-note) for the precise emission rules.
+Every typed note must have a nonempty body after its frontmatter. An empty or whitespace-only body is an error, even with `tags: [draft]` or a description. This includes folder and homepage notes. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. See [note states](../reference/format-details.md#three-states-of-a-note).

package/docs/authoring/frontmatter.md

@@ -41,7 +41,7 @@ One body describes the subject for both systems. A being's `{#appearance}` and `
 
 ## Place governments
 
-A place may state its governing affiliation in `data.government`. Use an affiliation Address, either a local shortcode or a fully qualified Address from this package or a fetched dependency:
+A place may state its governing affiliation in `data.government`. The field type is `Address`, with `affiliation` as the default target type when the type is omitted. Use either a local shortcode or a fully qualified affiliation Address from this package or a fetched dependency:
 
 ```yaml
 data:
@@ -58,7 +58,7 @@ Write `government: null` for **complete anarchy**. Omitting the key leaves gover
 | Any                   | Explicit `null`     | None; complete anarchy           |
 | Any                   | Affiliation Address | None; the reference must resolve |
 
-These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. Holdings remain tenure facts; the former unconditional “unheld land” warning is retired.
+These rules apply to every place subtype, including settlements, sites, structures, features, regions and worlds. Empty strings, numbers, lists, maps, references to another note type and unresolved references are errors. They do not declare anarchy. `domains`, `parents`, containment and capitals do not supply a government. The generated `governed_by` and `governed_places` lists use only explicit government references. Legacy affiliation `data.domains` is accepted temporarily but ignored; record any distinct ownership or influence in prose. See [government migration](../guides/government-migration.md).
 
 ## Publication and summaries