@heroiclands/package-build 22.23.0 → 22.25.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @heroiclands/package-build
 
+## 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
+
+**Hero banners** — A page whose note names its own hero image shows that image, in place of the stock banner for its kind; a note naming none gets a band with no image.
+
+**Figures** — A numbered figure, table, listing or map reads as one block, its number and caption set beneath it rather than running on as body text, and a passage set apart as an aside draws as a box.
+
+**Pictures** — A portrait or an emblem draws at half the content column and a banner, plate or map at its full width, never wider than the size the picture was made at; a stated width still overrides the role's measure.
+
+**Installing** — The shared Hugo theme arrives with this package, so a site declares this package alone and needs no separate theme dependency.
+
+**Hero images** — The authoring guide states the three states of a note's hero image: a picture, a deliberate blank that declines one, and an absent key that takes the default for the note's type.
+
 ## 22.23.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,7 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Detailed format rules and examples                | [Format details](docs/reference/format-details.md)           |
 | Compendium routing and document builds            | [Packs](docs/guides/packs.md)                                |
 | Website build and publication                     | [Site](docs/guides/site.md)                                  |
+| What the theme draws on a page                    | [Theme pages](docs/reference/theme-pages.md)                 |
 | PDF book build                                    | [Book](docs/guides/book.md)                                  |
 | Icon generation and use                           | [Icons](docs/guides/icons.md)                                |
 | Reference pages and content indexes               | [Reference pages](docs/guides/reference-pages.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/authoring/assets.md

@@ -38,6 +38,21 @@ role: portrait
 
 **A hero image is 1792×768.** `data.banner` fills one fixed strip wherever it is drawn, so every banner is cut to that size and a picture of any other size is a finding naming both sizes — resize the picture to match. That is the one size any art field requires. A map's `bgImage` sets its own scene's dimensions, so that asks nothing of a picture's dimensions either.
 
+`data.banner` reads in one of three states:
+
+| A note writes      | The page draws                                     |
+| ------------------ | -------------------------------------------------- |
+| an asset Address   | that picture                                       |
+| a blank            | no picture, on purpose, and no default replaces it |
+| nothing, or `null` | a default picture chosen by the note's `type`      |
+
+Omitting the key does not mean "no hero image" — it means artwork chosen for
+the author, which inverts the ordinary reading of an absent key. **A note
+declines with a blank, not with `none`.** `none` parses as an ordinary asset
+Address — a shortcode, not a keyword — and since nothing in the corpus
+answers to it, the build drops the key outright and the page falls through to
+its type's default: the opposite of a decline.
+
 `role` is one of `portrait`, `emblem`, `banner`, `plate` or `map`, and belongs to the `image` type only — declaring it in a `provenance.yaml` under `assets/icons` is a finding, since an icon carries one nominal size per medium whatever the file holds. Leave the key out for an ordinary picture; there is no default role name, only its absence.
 
 **A role decides how large a picture written in prose draws, when nothing else states a size.** Each medium maps a role to a maximum, and the drawn size is the smaller of that slot and what the file's own pixels support — see [what a role draws at](../reference/format-details.md#what-a-role-draws-at). A named `size=` beside the embed still overrides it outright; an icon draws at the medium's nominal icon size whatever role it might otherwise have had, because `role` never reaches an icon address at all.

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/commands.md

@@ -885,8 +885,8 @@ Install it with `npm ci`, which resolves from the lockfile this just moved.
 ```
 
 ```
-$ package-build bump @heroiclands/hugo-theme --check
-@heroiclands/hugo-theme  0.5.0 → 0.6.0
+$ package-build bump @heroiclands/package-build --check
+@heroiclands/package-build  22.6.0 → 22.7.0
 
 Run without --check to take it.
 ```
@@ -2310,9 +2310,9 @@ Three things are written, and nothing outside `build/`:
 - `build/hugo/hugo.toml`, generated on every run from `package.json`
   (`homepage`, `description`, `author`), `package-build.config.yaml`
   (`packageBuild.manifest.title`, `site.assets`, `site.notfound`,
-  `site.hugo`), the organisation's constants, the installed
-  `@heroiclands/hugo-theme`'s location, and the navigation `deps fetch`
-  cached. Every value's source is listed under
+  `site.hugo`), the organisation's constants, the shared theme's own
+  location, and the navigation `deps fetch` cached. Every value's source is
+  listed under
   [the generated Hugo configuration](configuration.md#the-generated-hugo-configuration).
 - `build/hugo/content/`, the content mount — the homepage as its `_index.md`,
   and the content tree's pages flat below `publish.address.prefix`. Wiped on
@@ -2321,13 +2321,13 @@ Three things are written, and nothing outside `build/`:
   deployment root `package-build site-root` writes beside. Nothing Hugo
   reads lands in what is published.
 
-The configuration's sources are read before the output tree is touched, so
-a missing `homepage`, a cold navigation cache or an uninstalled theme fails
-with the previous site intact. Every gate is then checked and reported, and
-the run stops at the first that fires, ordered so the report names the cause
-rather than its symptoms — an unusable dependency manifest, reported after
-the links that failed because of it, would otherwise read as a pile of
-broken notes. Reads the content tree named by `paths.content`.
+The configuration's sources are read before the output tree is touched, so a
+missing `homepage` or a cold navigation cache fails with the previous site
+intact. Every gate is then checked and reported, and the run stops at the
+first that fires, ordered so the report names the cause rather than its
+symptoms — an unusable dependency manifest, reported after the links that
+failed because of it, would otherwise read as a pile of broken notes. Reads
+the content tree named by `paths.content`.
 
 **OPTIONS**
 
@@ -2336,13 +2336,12 @@ None.
 **EXIT STATUS**
 
 1 if `package.json` declares no `homepage`, or one that does not end
-`/<contentPackage>/`; if `packageBuild.manifest.title` is undeclared; if the
-navigation has not been fetched (`package-build deps fetch` fills the cache
-and is named in the message); or if `@heroiclands/hugo-theme` is not
-installed. 1 if any gate fires — no homepage or two competing for it, a
-frontmatter wikilink, an address that cannot be derived, a stale or
-unaddressable dependency manifest, an address published twice, a table that
-failed to expand, or a dead wikilink. Otherwise 0.
+`/<contentPackage>/`; if `packageBuild.manifest.title` is undeclared; or if
+the navigation has not been fetched (`package-build deps fetch` fills the
+cache and is named in the message). 1 if any gate fires — no homepage or two
+competing for it, a frontmatter wikilink, an address that cannot be derived,
+a stale or unaddressable dependency manifest, an address published twice, a
+table that failed to expand, or a dead wikilink. Otherwise 0.
 
 **EXAMPLES**
 

package/docs/configuration.md

@@ -1031,8 +1031,8 @@ in it has one source, and that source is where it is edited:
 | `locale`                          | the organisation's locale, `en-us`, in `engine/site-config.mjs`                                                                                         |
 | `publishDir`                      | `contentPackage`, under the deployment root `build/site` — written relative to `build/hugo/`, so `../site/<contentPackage>`                             |
 | `contentDir`                      | the fixed content mount, `build/hugo/content` — written as `content`                                                                                    |
-| `themesDir`                       | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/`                            |
-| `theme`                           | the installed `@heroiclands/hugo-theme`, so `hugo-theme`                                                                                                |
+| `themesDir`                       | this package's own root, which holds the theme it ships, written relative to `build/hugo/`                                                              |
+| `theme`                           | the theme's directory inside this package, `hugo-theme`                                                                                                 |
 | `disableKinds`                    | the toolchain, which renders a site as its homepage and its pages: `["section", "taxonomy", "term", "RSS"]` on every site, whatever its notes carry     |
 | `taxonomies`                      | the toolchain — never written, because `taxonomy` and `term` are disabled kinds                                                                         |
 | `outputs`                         | the toolchain — never written, because every listing kind is disabled                                                                                   |
@@ -1049,10 +1049,6 @@ error naming the command that fills it:
 
 > `the site navigation has not been fetched. Run `package-build deps fetch` first.`
 
-A missing theme names the package to install:
-
-> `@heroiclands/hugo-theme is not installed anywhere above <rootDir> — add it to `devDependencies`and run`npm ci``
-
 The site needs a title from `site.title` or the package manifest:
 
 > ``package-build config: declare `site.title` or `packageBuild.manifest.title` for the site's title.``

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` |

package/docs/guides/module-project.md

@@ -863,8 +863,8 @@ None of them is needed to build a package.
 **A website.** Every package publishes one — at the least, the homepage note
 from step 5 — at `https://www.heroiclands.org/<contentPackage>/`. Add that
 address to `package.json` as `homepage`, with a `description` and an `author`
-beside it; add `@heroiclands/hugo-theme` under `devDependencies`; and add a
-`packageBuild.manifest.title`. Then `package-build deps fetch` caches the
+beside it, and add a `packageBuild.manifest.title`. The theme the site renders
+through ships with this package, so nothing else is installed. Then `package-build deps fetch` caches the
 organisation's navigation, and `package-build site` writes the whole Hugo
 source tree under `build/hugo/` — the configuration generated from those
 values, and the content mount — for `hugo --source build/hugo` to render

package/docs/guides/site.md

@@ -132,6 +132,47 @@ fenced example remains literal. `site.passOptions` supplies that named pass's
 options. This is a package-specific extension point; keep the general note
 format and link behavior in the [content format](../content-format.md).
 
+## What an emitted page carries
+
+A theme reads the front matter `package-build site` writes: the note's own
+front matter, plus the values the build derives. Which is which matters,
+because an authored value under a derived key is discarded.
+
+The build always writes `title`, `slug`, `url`, `kbfolder`, `package` and
+`infoboxes`. `title` is the note's name, `url` is the page's address, and
+`slug` is that address's last segment. `package` names the package shipping the
+note. `infoboxes` is assembled from the note's own fields, so no note authors
+it and nothing in the note format accepts it.
+
+The build writes `resolvedDates`, `related`, `contains`, `held_by`, `holdings`
+and `map` only when it has something to write. A page with no links either way
+carries no `related`, and a place with no drawing carries no `map`.
+
+An authored `aliases`, `related`, `contains`, `held_by`, `holdings` or `map` is
+dropped. Each states a fact about the whole tree rather than about one note, so
+the build replaces whatever a note wrote.
+
+Artwork addresses are rewritten in place under `data`. A page's `data.icon`,
+`data.bgImage` and `data.banner` carry the URLs the site serves rather than the
+addresses the note authored, and there are four cases to tell apart:
+
+| The note writes              | The page carries |
+| ---------------------------- | ---------------- |
+| an address something answers | the resolved URL |
+| an address nothing answers   | no key at all    |
+| `null`                       | `null`           |
+| `""`                         | `""`             |
+
+An address nothing answers is deleted rather than written through, so an absent
+key is the ordinary case for a theme to render nothing against, and no page
+reaches a reader carrying a broken image source. The two empties are distinct
+and both survive: `null` is a note naming no art, where a default may apply,
+and `""` is a note refusing art, where no default may replace it.
+
+The build writes these keys; [what the theme draws](../reference/theme-pages.md)
+describes the panel each one feeds — the infobox, the hero band, the holdings
+and related cards, the place map, and search.
+
 ## Build and serve
 
 ```bash

package/docs/project-setup.md

@@ -309,10 +309,10 @@ the rendered pages for search into `build/site/<contentPackage>/pagefind/`;
 and `serve:site` does the first and then `hugo server` for a live preview.
 The repository carries no Hugo configuration of its own: `hugo.toml` is
 generated on every run from `package.json`, `package-build.config.yaml`, the
-installed `@heroiclands/hugo-theme` and the navigation `deps fetch` cached,
-and the only file to add is `@heroiclands/hugo-theme` under
-`devDependencies`. Hugo itself is a separate install — the extended edition,
-on the developer's `PATH` and the runner's.
+shared theme that ships with `@heroiclands/package-build`, and the navigation
+`deps fetch` cached — a site declares this one package and needs nothing
+further added for its theme. Hugo itself is a separate install — the
+extended edition, on the developer's `PATH` and the runner's.
 
 The site build reads the cached navigation, so `build:site` in a package with
 no other dependency still runs `deps fetch` first: