@heroiclands/package-build 22.22.0 → 22.24.0

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

@@ -37,7 +37,9 @@ The harbor faces west.
 Travelers present their papers here. See [[#harbor|the harbor]].
 ```
 
-A `:::caption` block starts a JournalEntryPage too, named for the caption's own label, in Foundry alone — the web and the book keep the caption in the flow of the page around it. The prose introducing a captioned block and the block itself land on two different Foundry pages, so a reference such as `[[#trade|]]` written just above a caption sends a Foundry reader to a different page than the one carrying the sentence. Give the introducing prose its own heading, or accept that following the reference leaves the page, before relying on a caption to sit inside a longer page's flow.
+A `:::figure` fence starts a JournalEntryPage too, in Foundry alone — the web and the book keep the fence in the flow of the page around it. A fence holding exactly one picture, captioned with plain text and nothing else, becomes a page of type `image`: the picture is its `src`, the caption is `image.caption`, and the page is named for the figure's own number, such as "Figure 3". A fence carrying no caption still takes the `image` type when it holds one picture, named the same way. Every other fence takes a page of type `text` instead — a grouped fence holding more than one picture, an audio embed, a fence whose caption carries emphasis, an icon, or a link, and a fence that shares its page with trailing prose before the next heading or fence.
+
+The prose introducing a fence and the fence itself land on two different Foundry pages, so a reference such as `{{ref "#trade"}}` written just above a fence sends a Foundry reader to a different page than the one carrying the sentence. Give the introducing prose its own heading, or accept that following the reference leaves the page, before relying on a fence to sit inside a longer page's flow.
 
 A heading's braces hold an attribute block, not an anchor alone: `#slug` names the anchor, `.class` adds a CSS class, and `key="value"` writes an attribute. The website and a Foundry journal carry all three onto the heading; a book keeps the anchor and drops the rest, because Typst has no stylesheet to name a class in. Braces holding anything but an attribute block — `# The set {a, b}` — are reported at the heading's line and set as written.
 
@@ -61,23 +63,98 @@ A `:::secret` block inside the section is legal and renders as it does anywhere
 
 The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields, and take an H1 only — not the lower-level heading a journal page may otherwise start from. The section runs to the next H1, nested headings included. An anchor declared on a lower heading is still found, and is a build error rather than a quietly empty field: move the heading to the top level, or drop the anchor if the section is meant to stay unaddressed prose.
 
-## Captions and numbered references
+## Figures and numbered references
 
-A caption fence labels the next Markdown block. Give it an ID so prose can refer to the block without hard-coding its number:
+A `:::figure` fence numbers whatever it holds and, written with an id, makes it a target `{{ref}}` can point to:
 
 ````markdown
-Refer to [[#trade|]] for the market routes.
-
-:::caption {#trade}
-Regional trade routes
-:::
+:::figure {#trade}
 
 ```sql
 SELECT name.full AS "Market" FROM notes WHERE type = 'place'
 ```
+
+///
+Regional trade routes
+:::
+
+Refer to {{ref "#trade"}} for the market routes.
 ````
 
-The table displays **Table 1: Regional trade routes**, and the reference displays **Table 1**. The number is assigned by the output. An explicit link label, such as `[[#trade|the trade table]]`, displays the written label. A caption can precede a code fence, table, image, or any prose block. An ordinary code fence is code; an SQL result is a table; an image is a figure; every other block is prose. Web pages and Foundry journals number each kind within the note. Books number each kind across the book in reading order. A caption needs a unique ID, nonempty text, a closing `:::`, and a following block.
+The fence displays **Table 1: Regional trade routes**, and `{{ref "#trade"}}` displays **Table 1** as a link. **A figure is numbered because it is a fence, not because it carries caption text** — an ordinary table or picture written outside any fence is numbered not at all.
+
+**The construct is `:::figure`**, with an optional `{#id .border}` attribute block, closed by `:::`. Everything between the opening line and the closing `:::` is the captioned thing.
+
+**The first `///` at the top level of the fence separates the captioned thing from its caption.** A second `///` at the top level is an error — a figure holds one caption. A `///` written inside a nested code fence is content, not a separator, so a captioned code listing can carry `///` as a comment of its own.
+
+**The caption is optional.** A fence with no `///` draws its label alone, with nothing under it. So the counter and the label come from the fence itself, whether or not an author writes a caption.
+
+**`{#id}` is optional too.** A fence that declares none is still numbered and drawn; it carries no anchor, so nothing can refer to it. Give a figure an id only when prose needs to point at it.
+
+**`.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.
+
+**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`.
+
+**A reference is written `{{ref "#thorn"}}`**, rendering as a link reading "Figure 13". `form="full"` renders the number and the caption; `form="title"` renders the caption alone; `form="number"` is the default, and may be written explicitly. A link written inside the caption contributes only its label text to a `full` or `title` reference, because the reference is itself a link and an anchor cannot nest inside another.
+
+**A reference may name another note's figure**, writing the note's address before the anchor: `{{ref "place-thornford#trade"}}` points at the figure `#trade` in `place-thornford`. It renders the number that figure carries **on the surface doing the rendering** — its own count within `place-thornford` on the website and in a Foundry journal, and its place in the book's reading order in the book, which may differ from the number it carries on its own page. An anchor matching no figure in the addressed note is refused, and so is an address naming no note at all.
+
+In a Foundry journal, a reference resolves to the figure's own JournalEntryPage — the `image` page a solitary, plainly captioned picture becomes, or the `text` page any other fence becomes — addressed exactly as an authored `[[#anchor|Text]]` link to the same anchor would be. A reference naming another note's figure is not resolved there: a journal addresses a page by UUID, and has none for a note outside the one compiling.
+
+**A figure needs contents and a closing `:::`.** Its id, when one is given, must be unique in the note; its caption, when one is given, is the one `///` section the fence carries.
+
+A few worked examples. A captioned picture:
+
+```markdown
+:::figure {#thorn}
+![[being-foobar|The Great Beast]]
+///
+The great beast, as drawn by [[person-havard|Havard]].
+:::
+```
+
+This draws **Figure 1**, labelled "Figure 1: The great beast, as drawn by Havard." beneath the picture.
+
+A grouped fence holding two pictures as one figure — a plate rather than two separate plates:
+
+```markdown
+:::figure {#passes}
+![[image-northpass|Northern approach]]
+![[image-southpass|Southern approach]]
+///
+The two approaches to the pass.
+:::
+```
+
+Both pictures draw together under one label, **Figure 2**, because the fence is the unit the counter numbers — not the pictures inside it.
+
+A fence with no caption:
+
+```markdown
+:::figure {#anvil}
+![[icon-anvil|A worn anvil]]
+:::
+```
+
+This draws **Figure 3**, with no caption line beneath it, and still carries the anchor `#anvil`.
+
+A reference in running prose:
+
+```markdown
+See {{ref "#thorn"}} for the plate, or {{ref "#thorn" form="full"}} for the full description.
+```
+
+This displays as "See [Figure 1](#thorn) for the plate, or [Figure 1: The great beast, as drawn by Havard.](#thorn) for the full description," each bracketed phrase a link to the figure.
+
+A reference to a figure in another note:
+
+```markdown
+The market routes are drawn in {{ref "place-thornford#trade"}}.
+```
+
+On the website this links into `place-thornford`'s own page, reading "Table 1" — the number that fence carries there, whatever number it carries in the book or in a note of its own.
 
 ## Images and protected content
 
@@ -100,8 +177,10 @@ a closing `:::`. A name that is not one of the three is reported.
 **A GM-only section holds a box.** A `:::secret` is a container for whatever the
 GM reads, boxes included, and a box written inside one stays inside it. A box
 holds no named block of its own, so a second box inside a box is reported. A
-`:::caption` belongs to the caption construct and may be written inside any of
-them.
+`:::figure` fence may be written inside any of them. The two draw a box for
+different reasons: a named block says what kind of aside a passage is, while a
+`:::figure` fence makes a passage numbered and referable — nesting one inside
+the other gives a passage both.
 
 **An attribute block follows the name.** It is the same braced grammar the other
 body extensions use, so it carries an id, classes, and any attribute the element
@@ -147,11 +226,11 @@ not parse is reported at its own line and left as written; every well-formed
 block in the same note still renders.
 
 **A heading that would start its own journal page cannot be written inside a
-block, or inside a caption.** An H1, or a heading of any level carrying an
-`{#anchor}`, is reported at its own line there — starting a page would tear
-the block in two, and a reader could open the second half with none of the
-box around it. A lower heading with no anchor is unaffected and is the
-ordinary way to structure a long box.
+block, or inside a `:::figure` fence.** An H1, or a heading of any level
+carrying an `{#anchor}`, is reported at its own line there — starting a page
+would tear the block 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.
 
 ## Footnotes and definition lists
 
@@ -170,7 +249,8 @@ The road is passable in summer.[^season] The bridge has a toll.[^2]
 ```
 
 A reference may be written anywhere prose can be written — a word in a
-quotation, a bullet, a table cell, a heading, a named block, a caption. A
+quotation, a bullet, a table cell, a heading, a named block, a figure's
+caption. A
 definition belongs at the top level of the note: indent a following paragraph
 or code block by four spaces to include it in the same footnote, but never
 inside a list, a block quote, or a table. A definition written there, or a
@@ -324,20 +404,21 @@ There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} bein
 
 <!-- expression-helpers:start -->
 
-| Helper       | Parameters                 | What it gives you                                                                                                                                                         |
-| ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eq`         | `a b`                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                 |
-| `gt`         | `a b`                      | True when a is greater than b. Both must be finite numbers.                                                                                                               |
-| `gte`        | `a b`                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                   |
-| `lt`         | `a b`                      | True when a is less than b. Both must be finite numbers.                                                                                                                  |
-| `lte`        | `a b`                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                      |
-| `not`        | `value`                    | True when the value is false, zero, empty or absent.                                                                                                                      |
-| `and`        | `value …`                  | True when every value given is true. Takes two or more.                                                                                                                   |
-| `or`         | `value …`                  | True when any value given is true. Takes two or more.                                                                                                                     |
-| `words`      | `number`                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                   |
-| `digits`     | `number`                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                    |
-| `sql`        | `"query"`                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                              |
-| `dateformat` | `calendar date ["format"]` | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern. |
+| Helper       | Parameters                                 | What it gives you                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eq`         | `a b`                                      | True when both are the same value. Compares exactly, so 1 and "1" differ.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `gt`         | `a b`                                      | True when a is greater than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `gte`        | `a b`                                      | True when a is greater than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `lt`         | `a b`                                      | True when a is less than b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `lte`        | `a b`                                      | True when a is less than or equal to b. Both must be finite numbers.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `not`        | `value`                                    | True when the value is false, zero, empty or absent.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `and`        | `value …`                                  | True when every value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `or`         | `value …`                                  | True when any value given is true. Takes two or more.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `words`      | `number`                                   | The number spelled out for running prose — `1200` becomes one thousand two hundred. Whole numbers only; a decimal is a finding, and `digits` takes one.                                                                                                                                                                                                                                                                                                                               |
+| `digits`     | `number`                                   | The number as a grouped numeral — `1200` becomes 1,200, and a fractional part is kept.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `sql`        | `"query"`                                  | The single value a query returns, for use inside a sentence. The query is a quoted string, the same SQL a table fence takes.                                                                                                                                                                                                                                                                                                                                                          |
+| `dateformat` | `calendar date ["format"]`                 | A date written in a calendar. The calendar is an Address or its shortcode, the date is the value a note carries, and the optional third argument names an output pattern.                                                                                                                                                                                                                                                                                                             |
+| `ref`        | `address [form="number"\|"full"\|"title"]` | A link to a `:::figure` fence, by its anchor — `"#thorn"` on this note, `"note-address#thorn"` on another. `form` is `number` (the default, and admitted explicitly), rendering "Figure 13"; `full`, the number and the caption; or `title`, the caption alone. Always renders as a link to the figure, and a link inside the caption contributes only its label text. The number rendered is the one the figure carries on the surface doing the rendering, whichever note names it. |
 
 <!-- expression-helpers:end -->
 

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.
 ```
@@ -1455,15 +1455,17 @@ package-build deps fetch [--from <zip|dir>] [--id <id>]
 **DESCRIPTION**
 
 The only action is `fetch`, which fills three caches under `build/cache/`:
-the **content index** of every declared dependency, the **item catalogue**
-of those that additionally declare `itemCatalog: true`, and the **site
-navigation** — `https://www.heroiclands.org/nav.json`, the header menu
-every package site renders, fetched for every package because every package
-publishes a site. Its own command rather than a step of `package compile`
-or `site`, so neither reaches the network — a build that downloads silently
-is not reproducible and hides a dependency's version change behind a
-passing run. Each cache is stamped complete only once its fetch finishes,
-so a half-finished one reads as cold.
+the **content index** of every declared dependency, the **item catalogue or
+asset archive** of those that additionally declare `itemCatalog: true` or
+`assetArchive: true`, and the **site navigation** —
+`https://www.heroiclands.org/nav.json`, the header menu every package site
+renders, fetched for every package because every package publishes a site.
+A relationship declaring both `itemCatalog: true` and `assetArchive: true`
+is fetched once. Its own command rather than a step of `package compile` or
+`site`, so neither reaches the network — a build that downloads silently is
+not reproducible and hides a dependency's version change behind a passing
+run. Each cache is stamped complete only once its fetch finishes, so a
+half-finished one reads as cold.
 
 `lint`, `links`, `site`, `pdf`, `map`, `reachability`, and `package compile`
 check the declared dependencies' content-index cache before reading notes or
@@ -1501,7 +1503,7 @@ including when the repository declares no dependencies at all.
 ```
 $ package-build deps fetch
 […] Fetched the site navigation to build/cache/navigation/nav.json.
-[…] No relationship declares `itemCatalog: true`; nothing to fetch.
+[…] No relationship declares `itemCatalog: true` or `assetArchive: true`; nothing to fetch.
 […] This package declares no dependencies.
 
 $ package-build deps fetch --from build/dist/module.zip
@@ -2308,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
@@ -2319,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**
 
@@ -2334,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

@@ -55,7 +55,7 @@ around its own evaluation.
 
 ### Quick reference
 
-22 top-level keys. `rootDir` is not one of them — a data configuration never
+23 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -72,6 +72,7 @@ authoring.
 | [`itemBuilders`](#itembuilders)             | object, or list of `{system, builders}` (or a name/list of names, in YAML) | no; refused in a `documentation` package                                                           | `{}`                      |
 | [`paths`](#paths)                           | object                                                                     | no                                                                                                 | see [`paths`](#paths)     |
 | [`skipDirectories`](#skipdirectories)       | string[]                                                                   | no                                                                                                 | `[]`                      |
+| [`forbidGeneratedArt`](#forbidgeneratedart) | boolean                                                                    | no                                                                                                 | `false`                   |
 | [`icons`](#icons)                           | object, or a path to a file holding one                                    | no                                                                                                 | empty registry            |
 | [`packs`](#packs)                           | array                                                                      | yes, at least one entry, in a `systems` or `modules` package; refused in a `documentation` package | —                         |
 | [`docs`](#docs)                             | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
@@ -87,7 +88,7 @@ authoring.
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -515,7 +516,7 @@ HeroicLands layout, resolved against `rootDir`:
 | `paths.packJson`        | `build/packs-json`       | Build-only per-entry JSON intermediate.                                                         |
 | `paths.stage`           | `build/stage/packs`      | Compiled LevelDB packs.                                                                         |
 | `paths.unpack`          | `build/tmp/packs`        | Where `unpack` extracts JSON back to.                                                           |
-| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` is unpacked.                                   |
+| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` or `assetArchive: true` is unpacked.           |
 | `paths.metadataCache`   | `build/cache/metadata`   | Where a dependency's published content index is fetched to, for every declared dependency.      |
 | `paths.navigationCache` | `build/cache/navigation` | Where the site navigation heroiclands.org publishes is fetched to, for the generated Hugo menu. |
 
@@ -547,6 +548,26 @@ skipDirectories: [Templates]
 
 > ``package-build config: `skipDirectories[<index>]` must be a non-empty string.``
 
+### `forbidGeneratedArt`
+
+**Type:** boolean · **Optional** · default `false`.
+
+With it `true`, `package-build lint` refuses every asset record of this
+package whose `ai` field states `true` — a licensing stance, not a build
+detail: this package carries no machine-generated art. With it absent or
+`false`, `lint` reports nothing extra about an `ai: true` record.
+
+```yaml
+forbidGeneratedArt: true
+```
+
+`lint` reports a located error naming the record and its file for each one it
+finds:
+
+> ``<file>: error: `<address>` is machine-generated art (`ai: true`), and `forbidGeneratedArt` refuses it in this package``
+
+> ``package-build config: `forbidGeneratedArt` must be a boolean.``
+
 ### `icons`
 
 **Type:** object (`{families, icons, defaultFamily?}`), or a string naming a
@@ -1010,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                                                                                   |
@@ -1028,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.``
@@ -1205,15 +1222,17 @@ system relationship it declares — see [`stats.systemVersion`](#statssystemvers
 
 Each entry, in any of the four lists:
 
-| Key (under `relationships.<kind>[]`)     | Type                            | Required | Default |
-| ---------------------------------------- | ------------------------------- | -------- | ------- |
-| `relationships.systems[].id`             | string                          | yes      | —       |
-| `relationships.systems[].contentPackage` | string                          | no       | the id  |
-| `relationships.systems[].type`           | string                          | no       | none    |
-| `relationships.systems[].manifest`       | string                          | no       | none    |
-| `relationships.systems[].compatibility`  | object, `{minimum?, verified?}` | no       | none    |
-| `relationships.systems[].itemCatalog`    | boolean                         | no       | `false` |
-| `relationships.systems[].contentIndex`   | boolean                         | no       | `true`  |
+| Key (under `relationships.<kind>[]`)       | Type                            | Required | Default |
+| ------------------------------------------ | ------------------------------- | -------- | ------- |
+| `relationships.systems[].id`               | string                          | yes      | —       |
+| `relationships.systems[].contentPackage`   | string                          | no       | the id  |
+| `relationships.systems[].type`             | string                          | no       | none    |
+| `relationships.systems[].manifest`         | string                          | no       | none    |
+| `relationships.systems[].compatibility`    | object, `{minimum?, verified?}` | no       | none    |
+| `relationships.systems[].itemCatalog`      | boolean                         | no       | `false` |
+| `relationships.systems[].assetArchive`     | boolean                         | no       | `false` |
+| `relationships.systems[].contentIndex`     | boolean                         | no       | `true`  |
+| `relationships.systems[].assetReplacement` | boolean                         | no       | `false` |
 
 (the same keys apply under `requires[]`, `recommends[]` and
 `conflicts[]`.)
@@ -1222,7 +1241,7 @@ Each entry, in any of the four lists:
 
 > ``package-build config: `relationships.<kind>[<index>].id` must be a non-empty string.``
 
-> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, contentIndex).``
+> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, assetArchive, contentIndex, assetReplacement).``
 
 `contentPackage` names what the other package's _content_ is called, where
 that differs from its Foundry id. A note addresses a file by the content
@@ -1241,6 +1260,31 @@ item catalogue at build time. It requires a `manifest`:
 
 > ``package-build config: `relationships.<kind>[<index>].itemCatalog` needs a `manifest` naming the package to fetch.``
 
+`assetArchive` opts into unpacking the named package's release archive for
+its asset bytes alone — the sibling of `itemCatalog`, for a dependency whose
+bytes are wanted and whose items are not. It builds no item catalogue from
+the archive, which is what distinguishes it from `itemCatalog: true`. It
+requires a `manifest`:
+
+> ``package-build config: `relationships.<kind>[<index>].assetArchive` must be true or false.``
+
+> ``package-build config: `relationships.<kind>[<index>].assetArchive` needs a `manifest` naming the package to fetch.``
+
+A relationship with no items of its own to extract, such as an asset
+replacement module, declares only `assetArchive: true`:
+
+```yaml
+relationships:
+  requires:
+    - id: thalornaaltart
+      manifest: https://…/releases/latest/download/module.json
+      compatibility: { verified: "1.0.0" }
+      assetArchive: true
+```
+
+A relationship declaring both `itemCatalog: true` and `assetArchive: true` is
+fetched once: `deps fetch` does not download the archive twice for one entry.
+
 `contentIndex` and `itemCatalog` are the two edges a relationship may declare,
 and a package may have either without the other. `itemCatalog` says a
 dependency supplies _items_; `contentIndex`, `true` by default, says
@@ -1260,6 +1304,35 @@ demand.
 
 > ``package-build config: `relationships.<kind>[<index>].contentIndex` cannot be false together with `itemCatalog: true` — a catalogue is fetched from the same index.``
 
+`assetReplacement` opts a relationship into serving this package's own asset
+addresses from the named dependency's tree instead of its local one —
+`engine/asset-replacement.mjs`'s `resolveAssetReplacement` is what reads the
+declaration. Off by default: declaring a dependency is not the same as
+wanting its pictures in place of the ones this package ships itself. It
+requires a fetched index to check the replacement against, so it cannot pair
+with `contentIndex: false`:
+
+```yaml
+relationships:
+  requires:
+    - id: thalornaaltart
+      manifest: https://…/releases/latest/download/module.json
+      assetReplacement: true
+      contentIndex: true
+```
+
+With that declared, an address `thalorna` would otherwise answer itself —
+`thalorna-none-image-thorn` — resolves against
+`thalornaaltart-none-image-thorn` first, falling back to `thalorna`'s own
+record when `thalornaaltart` carries no file at that address. A package
+declaring more than one `assetReplacement: true` relationship is tried in
+the order the relationships are declared, and the first one carrying the
+address wins.
+
+> ``package-build config: `relationships.<kind>[<index>].assetReplacement` must be true or false.``
+
+> ``package-build config: `relationships.<kind>[<index>].assetReplacement` cannot be true together with `contentIndex: false` — a replacement with no fetched index to check against resolves nothing.``
+
 ### `systems`
 
 **Type:** object (`{id: spec}`) · **Optional** · default `{}`. Refused in a

package/docs/content-format.md

@@ -25,7 +25,7 @@ Start with [your first note](authoring/first-note.md). It explains the smallest
 
 A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
-A `:::caption {#anchor}` fence labels the next prose, code, table, or image block. Its anchor makes the block addressable; `[[#anchor|]]` displays the generated kind and number, such as **Figure 12**. Foundry gives the captioned block a JournalEntryPage. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references) for the syntax.
+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.
 
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with

package/docs/guides/book.md

@@ -88,10 +88,11 @@ finding.
 Each section and each selected entry starts on its own page. The PDF has a
 contents page and an outline for section and entry navigation. A note's
 `description` appears as an epigraph when present. Wider tables span both
-columns; an uncaptioned wide table starts on a new page so it stays after its
-introduction. A captioned wide table may float to the page top, and its numbered
-caption stays with it. A table too tall for one page takes pages of its own.
-Caption numbers run through the whole book in reading order. Maps attached
+columns; a wide table outside a figure fence starts on a new page so it stays
+after its introduction. A wide table inside one may float to the page top, and
+its label stays with it. A table too tall for one page takes pages of its own.
+A figure's number runs through the whole book in reading order, counted within
+its own kind. Maps attached
 to selected places use landscape pages after those entries. Regional, theatre
 of the mind, battle, and local map backgrounds also print on landscape pages.
 Battle and local maps print each Scene level's background on its own page.

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: