@heroiclands/package-build 22.24.0 → 22.26.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.26.0
+
+### Minor Changes
+
+Place notes can name their governing affiliation in `data.government`, or state `null` for complete anarchy. A place with positive population and no government now receives an advisory. Places with zero, null or unspecified population no longer receive the old unheld-land warning; holdings remain separate tenure facts. Governments appear in note infoboxes and persist in published metadata.
+
+## 22.25.0
+
+### Minor Changes
+
+Write poems in a `:::poetry` fence to preserve verse lines, relative indentation, and stanza breaks across journals, websites, and books. A poem placed first in a `:::figure` uses the Poem counter and may carry a caption and reference.
+
+The bundled Hugo theme's image-role and banner guards now run as part of package-build lint. Affiliation notes must declare a `data.governance.ranks` rung at level 1; a missing ordinary standing now produces a located error.
+
 ## 22.24.0
 
 ### Minor Changes

package/README.md

@@ -46,4 +46,6 @@ 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).
+
 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

@@ -106,6 +106,51 @@
     }
 }
 
+/* Each verse line breaks in the markup; each paragraph is a stanza. */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry {
+    margin: 1.5rem 0;
+    line-height: 1.7;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry p {
+    margin: 0;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) .poetry p + p {
+    margin-top: 1em;
+}
+
+.poetry .poetry-line {
+    display: inline-block;
+    margin-inline-start: var(--poetry-indent, 0em);
+    white-space: pre-wrap;
+}
+
+.poetry .poetry-line.i1 {
+    --poetry-indent: 1.25em;
+}
+.poetry .poetry-line.i2 {
+    --poetry-indent: 2.5em;
+}
+.poetry .poetry-line.i3 {
+    --poetry-indent: 3.75em;
+}
+.poetry .poetry-line.i4 {
+    --poetry-indent: 5em;
+}
+.poetry .poetry-line.i5 {
+    --poetry-indent: 6.25em;
+}
+.poetry .poetry-line.i6 {
+    --poetry-indent: 7.5em;
+}
+.poetry .poetry-line.i7 {
+    --poetry-indent: 8.75em;
+}
+.poetry .poetry-line.i8 {
+    --poetry-indent: 10em;
+}
+
 /*
  * 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

package/ci/check-banners.mjs

@@ -0,0 +1,183 @@
+/*
+ * This file is part of the Heroic Lands shared Hugo theme.
+ * 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 file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * CI guard: every banner `data/banners.yaml` declares must actually be published.
+ *
+ * `partials/hero-banner.html` needs to know which banner images exist, and Hugo
+ * cannot ask a remote asset host that question at build time — so the answer is
+ * declared in `data/banners.yaml` instead. A declaration nothing
+ * checks is kept in step by hope, and the hole it was written to close reopens
+ * the first time it drifts. It already had: when this check was written, four
+ * names present in a local working copy of the artwork repository were not
+ * published, and three that were published appeared in no local copy at all.
+ *
+ * So this fetches every declared name and fails on any non-200. It is the test
+ * the template cannot make, moved to the one place that can make it.
+ *
+ * Usage:
+ *   node utils/check-banners.mjs [--base <url>] [--concurrency <n>]
+ *
+ * The host defaults to the Heroic Lands CDN and can be pointed anywhere with
+ * `--base` or `BANNER_BASE_URL`, so a consumer publishing its own artwork set
+ * can run the same check against its own `data/banners.yaml`.
+ *
+ * A network failure is reported as a failure rather than skipped: a check that
+ * passes when it could not reach the host is worse than no check at all.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { parse } from "yaml";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DATA_FILE = resolve(HERE, "..", "hugo-theme", "data", "banners.yaml");
+const DEFAULT_BASE = "https://cdn.heroiclands.org";
+
+function parseArgs(argv) {
+    const opts = {
+        base: process.env.BANNER_BASE_URL || DEFAULT_BASE,
+        concurrency: 8,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--base") opts.base = argv[(i += 1)];
+        else if (arg === "--concurrency") opts.concurrency = Number(argv[(i += 1)]);
+        else {
+            console.error(`check-banners: unrecognised argument ${arg}`);
+            process.exit(2);
+        }
+    }
+    if (!opts.base) {
+        console.error("check-banners: no asset host; pass --base or set BANNER_BASE_URL");
+        process.exit(2);
+    }
+    if (!Number.isInteger(opts.concurrency) || opts.concurrency < 1) {
+        console.error("check-banners: --concurrency must be a positive integer");
+        process.exit(2);
+    }
+    return opts;
+}
+
+/** Diagnostics carry the fields they can know and drop the ones they cannot. */
+function diag(line, message) {
+    const where = line ? `${DATA_FILE}:${line}` : DATA_FILE;
+    console.error(`${where}: error: ${message}`);
+}
+
+function fail(message, line) {
+    diag(line, message);
+    process.exit(1);
+}
+
+/** Line number of a declared name, so an editor can jump straight to it. */
+function lineOf(source, name) {
+    const index = source
+        .split("\n")
+        .findIndex((l) => l.trim() === `- ${name}` || l.trim() === `- "${name}"`);
+    return index === -1 ? 0 : index + 1;
+}
+
+/** Read and validate the inventory, so a malformed file fails loudly. */
+function readInventory() {
+    const source = readFileSync(DATA_FILE, "utf8");
+    const data = parse(source);
+    const dir = data?.dir;
+    const fallback = data?.fallback;
+    const available = data?.available;
+
+    if (typeof dir !== "string" || !dir) fail("`dir` must be a non-empty string");
+    if (typeof fallback !== "string" || !fallback) fail("`fallback` must be a non-empty string");
+    if (!Array.isArray(available) || available.length === 0)
+        fail("`available` must be a non-empty list");
+    if (available.some((n) => typeof n !== "string" || !n))
+        fail("`available` must hold only non-empty strings");
+
+    const dupes = [...new Set(available.filter((n, i) => available.indexOf(n) !== i))];
+    if (dupes.length) fail(`duplicate names: ${dupes.join(", ")}`, lineOf(source, dupes[0]));
+
+    const unsorted = available.findIndex((n, i) => i > 0 && available[i - 1] > n);
+    if (unsorted !== -1)
+        fail(
+            "`available` must be sorted, so a diff shows what changed",
+            lineOf(source, available[unsorted]),
+        );
+
+    // The fallback is what every unlisted name resolves to, so its absence would
+    // turn one dead URL into every dead URL.
+    const fallbackName = fallback.replace(/\.[^./]+$/, "");
+    if (!available.includes(fallbackName))
+        fail(`the fallback ${fallback} is not itself listed in \`available\``);
+
+    return { source, dir, available };
+}
+
+async function probe(url) {
+    try {
+        // HEAD first — it is what the question actually is. Some object stores
+        // answer 405 to it, so fall back to a ranged GET rather than reporting a
+        // published file as missing.
+        let res = await fetch(url, { method: "HEAD", redirect: "follow" });
+        if (res.status === 405 || res.status === 501) {
+            res = await fetch(url, {
+                headers: { Range: "bytes=0-0" },
+                redirect: "follow",
+            });
+        }
+        return {
+            ok: res.status === 200 || res.status === 206,
+            status: String(res.status),
+        };
+    } catch (err) {
+        return { ok: false, status: `network error: ${err.message}` };
+    }
+}
+
+async function main() {
+    const { base, concurrency } = parseArgs(process.argv.slice(2));
+    const { source, dir, available } = readInventory();
+    const root = `${base.replace(/\/$/, "")}/${dir.replace(/^\//, "")}`;
+
+    const failures = [];
+    const queue = [...available];
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        for (let name = queue.shift(); name !== undefined; name = queue.shift()) {
+            const url = `${root}/${name}.webp`;
+            const { ok, status } = await probe(url);
+            if (!ok) failures.push({ name, url, status });
+        }
+    });
+    await Promise.all(workers);
+
+    if (failures.length) {
+        failures.sort((a, b) => a.name.localeCompare(b.name));
+        for (const { name, url, status } of failures) {
+            diag(
+                lineOf(source, name),
+                `declared banner ${name} is not published (${status}): ${url}`,
+            );
+        }
+        console.error(
+            `check-banners: ${failures.length} of ${available.length} declared banners are missing from ${base}.`,
+        );
+        console.error(
+            "Publish the artwork, or drop the name — an undrawn name here is a 404 on every page that resolves to it.",
+        );
+        process.exit(1);
+    }
+
+    console.log(`check-banners: all ${available.length} declared banners resolve at ${base}`);
+}
+
+await main();

package/ci/ci-steps.mjs

@@ -139,7 +139,7 @@ function prTriggeredWorkflows() {
  * @param {string} file - The workflow.
  * @returns {{run: Array<{name: string, run: string}>, skipped: string[]}} Its steps.
  */
-function stepsIn(file) {
+export function stepsIn(file) {
     const lines = fs.readFileSync(file, "utf8").split("\n");
     const run = [];
     const skipped = [];
@@ -164,25 +164,32 @@ function stepsIn(file) {
             continue;
         }
 
-        const inline = /^-?\s*run:\s*(?!\|)(.+)$/.exec(text);
-        if (inline) {
-            run.push({ name: name ?? inline[1], run: inline[1].trim() });
-            name = null;
-            continue;
-        }
         // A `run: |` block scalar: every following line indented deeper.
-        if (/^-?\s*run:\s*\|\s*$/.test(text)) {
+        if (/^-?\s*run:\s*\|[+-]?\s*$/.test(text)) {
             const base = indentOf(line);
             const body = [];
             while (i + 1 < lines.length) {
                 const next = lines[i + 1];
                 if (next.trim() !== "" && indentOf(next) <= base) break;
-                body.push(next.trim());
+                body.push(next);
                 i += 1;
             }
-            const command = body.filter(Boolean).join(" && ");
+            const margin = Math.min(
+                ...body.filter((line) => line.trim()).map((line) => indentOf(line)),
+            );
+            const command = body
+                .map((line) => line.slice(margin))
+                .join("\n")
+                .trimEnd();
             if (command) run.push({ name: name ?? command, run: command });
             name = null;
+            continue;
+        }
+        const inline = /^-?\s*run:\s*(.+)$/.exec(text);
+        if (inline) {
+            run.push({ name: name ?? inline[1], run: inline[1].trim() });
+            name = null;
+            continue;
         }
     }
     return { run, skipped };
@@ -223,7 +230,10 @@ function main() {
 
     for (const [i, step] of run.entries()) {
         console.log(`\nci-steps: [${i + 1}/${run.length}] ${step.name}\n  $ ${step.run}`);
-        const result = spawnSync(step.run, { cwd: ROOT, shell: true, stdio: "inherit" });
+        const result = spawnSync("bash", ["-e", "-o", "pipefail", "-c", step.run], {
+            cwd: ROOT,
+            stdio: "inherit",
+        });
         if (result.status !== 0) {
             console.error(
                 `\nci-steps: FAILED at "${step.name}" — this is what GitHub would report.\n` +

package/docs/api.md

@@ -348,6 +348,8 @@ The note types the engine itself declares — vocabulary that is a fact about th
 
 ### `engine.noteVocabulary`
 
+`DataFieldSpec.nullText` declares the infobox text for an explicitly authored null. The place `government` field uses “Complete anarchy”; omitted fields remain absent. Its Address targets must be affiliations.
+
 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                                                                                  |
@@ -495,17 +497,18 @@ 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 tenure check `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[]`     | the place subTypes tenure is checked on — `settlement`, `site`, `structure`                                                  |
-| `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  |
-| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | linting a place's tenure — a settlement, site or structure no affiliation's `domains` names is a warning at its `type:` line |
+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.
+
+| 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                                |
 
 ### `engine.populations`
 

package/docs/authoring/frontmatter.md

@@ -39,6 +39,27 @@ A `sohl:`, `hm3:` or `dnd5e:` block holds values for that Foundry system. Its `s
 
 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.
 
+## 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:
+
+```yaml
+data:
+  population: 1200
+  government: crown
+```
+
+Write `government: null` for **complete anarchy**. Omitting the key leaves government unspecified. Null is retained in published metadata and displayed as “Complete anarchy” in website, Foundry and book infoboxes; an omitted key has no Government row. A reference displays a link to the governing affiliation.
+
+| Population            | Government          | Governance advisory              |
+| --------------------- | ------------------- | -------------------------------- |
+| Positive              | Omitted             | Warning at `data.population`     |
+| Missing, zero or null | Omitted             | None                             |
+| 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.
+
 ## Publication and summaries
 
 A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; the book places boxes after the authored body, Foundry appends one page per box, and the website places boxes in its responsive side rail. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.

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

@@ -93,7 +93,7 @@ The fence displays **Table 1: Regional trade routes**, and `{{ref "#trade"}}` di
 
 **`.border` draws the figure and its label inside a border.** It is the only class the construct accepts — any other class, such as `.wide`, is an error naming the class. `key="value"` is refused outright: a figure takes an id and classes, nothing else.
 
-**The counter is derived from the fence's contents, never authored.** A table is a table; an `sql` fence is a table, because its rendered output is one; any other fence or code block is code; pictures alone, one or several, are a figure; everything else is prose. A fence around prose with `.border` is a numbered, referable boxed aside — the `Prose` counter's whole purpose. The counters are `Code`, `Table`, `Figure`, `Map`, and `Prose`. The website and a Foundry journal number each counter within the note; a book numbers each counter across the book in reading order.
+**The counter is derived from the fence's contents, never authored.** A table is a table; an `sql` fence is a table, because its rendered output is one; any other fence or code block is code; pictures alone, one or several, are a figure; a `:::poetry` fence written first makes it a poem; everything else is prose. A fence around prose with `.border` is a numbered, referable boxed aside — the `Prose` counter's whole purpose. The counters are `Code`, `Table`, `Figure`, `Map`, `Poem`, and `Prose`. The website and a Foundry journal number each counter within the note; a book numbers each counter across the book in reading order.
 
 **A picture counts as `Map` instead of `Figure` when the asset it draws declares `role: map`** in its provenance — see [the asset provenance reference](../reference/format-details.md). The fence's own markup cannot say so; a picture of a map looks like any other picture, so the fact rides entirely on the asset's own record. A fence grouping several pictures counts as `Map` only when every one of them declares the role; one picture without it keeps the whole fence a `Figure`.
 
@@ -172,7 +172,7 @@ The bridge closes during the spring flood.
 ```
 
 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 closing `:::`. Poetry has its own fence below; other names are 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
@@ -232,6 +232,73 @@ would tear the block or the figure 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.
 
+### Poetry
+
+Use `:::poetry` to preserve verse lines and stanzas. Every nonblank source line
+is one verse line; blank lines separate stanzas. Inline emphasis, links and
+footnotes work as they do in prose. The fence itself adds no title, caption or
+number.
+
+Leading spaces indent individual verse lines. The least-indented nonblank line
+sets level zero for the whole poem, so a common indentation on every line has no
+visual effect. Each additional two spaces adds one level, up to `i8`; an odd
+extra space rounds down. Each medium sets the actual width of a level, with
+every higher level wider than the preceding one. Tabs anywhere in the poem are
+an error. Interior spaces are preserved on a best-effort basis.
+
+| Extra leading spaces | Indent class |
+| -------------------- | ------------ |
+| 0–1                  | none         |
+| 2–3                  | `i1`         |
+| 4–5                  | `i2`         |
+| 6–7                  | `i3`         |
+| 8–9                  | `i4`         |
+| 10–11                | `i5`         |
+| 12–13                | `i6`         |
+| 14–15                | `i7`         |
+| 16 or more           | `i8`         |
+
+For example, a line with four leading spaces and a line with six leading spaces
+render at levels zero and `i1` respectively. This also works when the entire
+fence is indented inside a list item. Poetry is upright by default; use normal
+Markdown emphasis when italics are part of the poem.
+
+```markdown
+:::poetry {form=ballad meter="common meter" rhyme=ABCB syllables="8,6,8,6" lang=en}
+The lantern burns beside the gate,
+The harbor sleeps below.
+
+The keeper guards the road till dawn,
+And keeps a light aglow.
+:::
+```
+
+The optional `form`, `meter` and `rhyme` attributes record the author's intent;
+the build does not infer stress, rhyme or pronunciation. `syllables` gives a
+positive count for each verse line in order, separated by commas, with blank
+stanza lines omitted. The build checks the number of counts, not the syllables
+spoken. `lang` is a language tag for the rendered HTML. An optional `#id`
+addresses the poem itself. There are no `title` or `lines` attributes, and no
+special punctuation for stress, pauses or refrains.
+
+To number and caption a poem, put it first inside a `:::figure`:
+
+```markdown
+:::figure {#watch-song}
+:::poetry {form=ballad}
+The watch has gone to sea,
+The lantern marks the shore.
+:::
+///
+A song sung by the harbor watch.
+:::
+```
+
+The inner `:::` closes the poem; the outer one closes the figure. That figure
+uses the **Poem** counter, so `{{ref "#watch-song"}}` reads **Poem 1**. The
+caption after `///` belongs to the figure. A poem outside a figure is
+unnumbered. Prose written before the poem makes the figure a **Prose** figure.
+
 ## Footnotes and definition lists
 
 Write a footnote reference as `[^id]` and its definition as `[^id]: text`.

package/docs/content-format.md

@@ -27,6 +27,8 @@ A nonempty note body creates one system-agnostic Foundry JournalEntry. Content b
 
 A `:::figure {#anchor}` fence numbers whatever it holds — prose, code, a table, or an image. Its anchor makes the fence a target `{{ref "#anchor"}}` can point to, displaying the generated kind and number, such as **Figure 12**. Foundry gives the fence its own JournalEntryPage. See [figures and numbered references](authoring/links-and-markup.md#figures-and-numbered-references) for the syntax.
 
+A `:::poetry` fence keeps each authored line as a verse line and blank lines as stanza breaks. Inside a `:::figure`, a poem written first gives that figure the **Poem** counter and an optional caption. See [poetry](authoring/links-and-markup.md#poetry) for attributes and examples.
+
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
 `{allow-empty=true}` are examples. Inline font glyphs use the package's icon
@@ -49,6 +51,13 @@ explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
 
+An `affiliation` note declares `data.governance.ranks` with at least one rung at
+`level: 1`. Each rung states `level`, `title`, and `description`. A being's
+`data.affiliations` entry names a rank on that body's ladder; level 1 is the
+ordinary standing when no higher rank applies. A single level-1 rung is enough
+when the body expresses its hierarchy through `governance.offices` instead.
+Missing ranks, an empty list, or a ladder without level 1 are build errors.
+
 | Authored section | SoHL Actor          | HM3 Actor            |
 | ---------------- | ------------------- | -------------------- |
 | `{#appearance}`  | `system.appearance` | `system.description` |
@@ -76,3 +85,5 @@ A sheltered place where ships load and unload.
 The note's readable Address is `<package>-note-lore-harbor`. In prose, link to it with `[[lore-harbor|Harbor]]`. The package segment comes from `package-build.config.yaml`; a regular wikilink defaults to the readable `note` system. An image embed such as `![[icon-harbor|Harbor]]` defaults to `none` instead.
 
 The [first-note guide](authoring/first-note.md) shows the build commands and how to add a system document. Use the [command reference](commands.md) for exact flags and the [diagnostics guide](diagnostics.md) for located errors.
+
+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](authoring/frontmatter.md#place-governments).