@heroiclands/package-build 23.1.0 → 23.2.0

package/docs/authoring/assets.md

@@ -43,15 +43,21 @@ role: portrait
 | A note writes      | The page draws                                     |
 | ------------------ | -------------------------------------------------- |
 | an asset Address   | that picture                                       |
-| a blank            | no picture, on purpose, and no default replaces it |
+| `none`             | 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.
+declines with `none`, and with nothing else.** `none` is a keyword, never an
+asset shortcode, so it is not looked up. A blank (`""`) is an error, and
+`null` is the same as omitting the key. An Address that names no image in
+this package or a declared dependency is a finding at its line and column;
+write `data.banner: none` when the page is meant to carry no hero image.
+
+```yaml
+data:
+  banner: none
+```
 
 `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.
 

package/docs/authoring/frontmatter.md

@@ -31,7 +31,7 @@ The formatter keeps a collection on one line when the full line is under 100 cha
 
 ## Shared facts and game mechanics
 
-The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, `icon`, and `banner` fields. A type such as `being` also has its own fields, including `culture`, `homes`, and `affiliations`. A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
+The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, and `banner` fields. A type such as `being` also has its own fields, including `homes` and `affiliations`. `culture` is shared by `being`, `place`, `affiliation`, `lore` and `doc`: it names a `lore` note of `subType: culture`, is required on a `doc` of `subType: settingguide`, and is inherited down `data.parents` by places and affiliations. See [culture in the index](../reference/format-details.md#culture-in-the-index). A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
 
 A being's `data.archetypes` names the roles it can fill in an adventure. Choose every specific role that fits, such as `entertainer` for a performer or `guildsperson` for someone whose professional training or connections matter. Use `[commoner]` when no specific archetype fits. `commoner` cannot share the list with another value. The [archetype reference](../reference/format-details.md#actors) defines the available roles.
 

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

@@ -487,6 +487,93 @@ A page list names this package's own pages. A **stub** — a note with an empty
 
 See [page-list details](../reference/format-details.md#page-lists) for the directive's full behaviour.
 
+## Theme shortcodes
+
+The Hugo theme that renders every site defines four shortcodes. An author writes one in a note body as `{{< name … >}}`, and only the website renders it. The shared note pipeline leaves a shortcode in the source untouched, so the compendium packs and the printed book carry the call as literal text. Use a shortcode only on a page whose purpose is the website. Where a construct must reach all three surfaces, use one of the constructs earlier on this page, which every surface resolves.
+
+A shortcode takes either positional arguments or named ones, and a single call cannot mix the two. `{{< glyph "anubis" >}}` and `{{< glyph slug="anubis" frame="tablet" >}}` are both valid; `{{< glyph "anubis" frame="tablet" >}}` is refused by Hugo. A call to a shortcode that has a required argument and omits it fails the site build with the note's position.
+
+### `cartouche`
+
+Renders a named SVG seal as an ornamental accent, as a block figure or inline with text. The image is read from `img/cartouches/<slug>.svg` in the consuming site's static files.
+
+| Parameter | Value              | Default            | What it does                                                                                          |
+| --------- | ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------- |
+| `slug`    | the SVG's basename | required           | Names the file. May be given as the first positional argument when no other parameter is used.        |
+| `size`    | `inline`           | block              | `inline` flows the image with the surrounding text. Any other value adds a `cartouche-<value>` class. |
+| `align`   | `left` or `right`  | centered           | Floats the figure so prose wraps around it.                                                           |
+| `height`  | a CSS length       | set by the theme   | Sets the image's height, for example `10rem` or `160px`. The width follows the image's aspect ratio.  |
+| `alt`     | text               | the humanized slug | The image's text alternative.                                                                         |
+| `caption` | text               | none               | A caption under the image. Block mode only; an inline cartouche ignores it.                           |
+
+```markdown
+{{< cartouche "takheperu" >}}
+
+{{< cartouche slug="aukhelathu" height="10rem" align="right" >}}
+
+{{< cartouche slug="anubis" caption="Anpu" >}}
+
+The sign {{< cartouche slug="ra" size="inline" >}} stands for the sun.
+```
+
+The first call centers the `takheperu` seal as a block. The second floats the `aukhelathu` seal to the right at ten rem tall, with the following paragraph wrapping around it. The third adds a caption under the seal. The fourth sets the seal in the line of text.
+
+### `exturl`
+
+Renders a web address as a code-styled string followed by a button that copies it to the clipboard. It exists for an address a reader is meant to paste somewhere, such as a server address or a manifest URL, where a clickable link would be the wrong affordance. The address is the first positional argument and the shortcode takes no other.
+
+| Parameter          | Value                     | Default | What it does                                                           |
+| ------------------ | ------------------------- | ------- | ---------------------------------------------------------------------- |
+| first (positional) | the text to show and copy | none    | The string displayed in the code element and written to the clipboard. |
+
+```markdown
+Install from {{< exturl "https://example.org/module/manifest.json" >}} in the module browser.
+```
+
+The page shows the address in a code element with a copy icon beside it. Selecting the icon copies the address and briefly marks the button as copied. The text is not a link.
+
+### `glyph`
+
+Renders an icon-scale SVG, such as a deity-name cluster, a category icon or an ornamental mark, in the line of text or as a block. The image is `icons/<slug>.svg`, resolved against the consuming site's `params.cdnBaseURL`. This is an image drawn from the site's icon directory; it is a separate construct from the `:icon name:` font glyphs of the [icon guide](../guides/icons.md), which every surface renders from the package's declared `icons` registry.
+
+| Parameter | Value               | Default            | What it does                                                                                                  |
+| --------- | ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `slug`    | the SVG's basename  | required           | Names the file. May be given as the first positional argument when no other parameter is used.                |
+| `frame`   | `tablet`            | none               | Sets the glyph inside a limestone rectangular frame, so rows of different intrinsic width line up in a table. |
+| `size`    | `inline` or `block` | 1.8em tall         | `inline` is small and flows with the text. `block` centers the glyph as a standalone line.                    |
+| `alt`     | text                | the humanized slug | The image's text alternative.                                                                                 |
+
+```markdown
+| God    | Glyph                                      |
+| ------ | ------------------------------------------ |
+| Anubis | {{< glyph slug="anubis" frame="tablet" >}} |
+
+The name {{< glyph "ra" >}} is written with one sign.
+
+{{< glyph slug="ra" size="block" alt="Sun god Ra" >}}
+```
+
+### `pagelist`
+
+Renders the pages carrying a tag as a list of links, ordered as asked. The group is expressed by intent: a page joins by being tagged and leaves by being untagged. The shortcode lists the site's own pages by the tags the site's taxonomy holds.
+
+The ` ```pagelist ` fence described under [Page lists](#page-lists) is a different construct with its own attributes. The fence is answered by the content pipeline and reaches Foundry and the book; the shortcode is the site's alone.
+
+| Parameter | Value                       | Default       | What it does                                                                                          |
+| --------- | --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------- |
+| `tag`     | a tag                       | required      | The taxonomy term to list, matched case-insensitively. May be given as the first positional argument. |
+| `section` | a top-level section name    | every section | Restricts the list to one section of the site, such as `rules`.                                       |
+| `sort`    | `title`, `weight` or `date` | `title`       | The order of the list. `date` puts the newest first.                                                  |
+| `desc`    | `true`                      | off           | Shows each page's description beneath its link. Any other value leaves descriptions out.              |
+
+```markdown
+{{< pagelist tag="key-concept" >}}
+
+{{< pagelist tag="key-concept" section="rules" sort="weight" desc="true" >}}
+```
+
+The first call lists every page tagged `key-concept` alphabetically by title. The second lists only those in the `rules` section, in weight order, each followed by its description. A tag that no page carries produces a build warning naming the tag and the note's position, and the list is left out.
+
 ## Expressions
 
 An expression in `{{ }}` is replaced by a value, inline in a sentence. The note's own frontmatter is the context, so a field is read by the path a note writes it at.

package/docs/commands.md

@@ -909,7 +909,7 @@ package-build yaml [paths..]
 
 **DESCRIPTION**
 
-The check that exists because a duplicate frontmatter key used to parse to
+The check that exists because a duplicate frontmatter key parses to
 nothing and the note it belonged to silently lost every field, with every
 later build pass reporting success. Needs no ESLint configuration of its
 own, so a repository with one for its own source code
@@ -1195,6 +1195,19 @@ Foundry holds its LevelDB packs open and a replacement written underneath it
 corrupts them. `.env.local` and `.env` are loaded first. Reads
 `packageBuild.stageDir`; writes into the stage's data directory.
 
+Once the new tree is in place, the previous one — renamed aside to
+`<id>.old-<pid>` — is removed, along with any `<id>.old-<pid>` an earlier
+deploy left beside the package, whatever its pid. A leftover tree still holds
+a manifest, so Foundry reads it as a second copy of the package and logs it as
+an invalid one on every start. Foundry running in a container writes files
+owned by the container's user, which under rootless Docker is a mapped uid the
+host user cannot unlink. When the host user is refused, a throwaway container
+of the stage's image removes the tree as root on the same data root, the
+mechanism `e2e` uses to hand its install to Foundry. If that fails too — no
+`docker`, or a remote destination — the deploy still succeeds: it prints a
+warning for each leftover tree, naming it and the command that removes it,
+and leaves the tree under its `.old-<pid>` name for the next deploy to sweep.
+
 **OPTIONS**
 
 | Positional | Type   | Default | Description                                     |
@@ -1209,7 +1222,8 @@ only).
 **EXIT STATUS**
 
 1 if `FOUNDRYVTT_<STAGE>_DATA` is unset. 1 on any other thrown error.
-Otherwise 0.
+Otherwise 0, including when the previous tree is left behind with a warning:
+the new package is installed either way.
 
 **EXAMPLES**
 
@@ -1220,6 +1234,11 @@ package-build: No destination configured for stage 'dev'. Set FOUNDRYVTT_DEV_DAT
 $ FOUNDRYVTT_DEV_DATA=/tmp/pb-docs-demo-410-data package-build deploy dev
 Deploying /private/tmp/pb-docs-demo-410/build/stage → /tmp/pb-docs-demo-410-data/Data/modules/demo-package (local copy)
 Deployed stage 'dev' successfully.
+
+$ package-build deploy test
+Deploying /srv/pkg/build/stage → /srv/fvtt-test/Data/systems/sohl (local copy)
+Deployed stage 'test' successfully.
+/srv/fvtt-test/Data/systems/sohl.old-4242: warning: the new package is installed, but its previous tree could not be removed (docker was not found on PATH. Install Docker and make sure the `docker` CLI is available.); remove it with `docker run --rm --user 0:0 --volume /srv/fvtt-test:/data --entrypoint rm felddy/foundryvtt:14 -rf /data/Data/systems/sohl.old-4242`
 ```
 
 **SEE ALSO**
@@ -1248,16 +1267,30 @@ first.
 
 `start` requires the stage's data root to exist and runs the image, passing
 through `FOUNDRYVTT_<STAGE>_VERSION`, `FOUNDRYVTT_<STAGE>_WORLD` and
-`FOUNDRYVTT_<STAGE>_LICENSE_KEY` when set. `stop` stops it. `restart` stops
+`FOUNDRYVTT_<STAGE>_LICENSE_KEY` when set. Every other `FOUNDRY_*` and
+`CONTAINER_*` variable passes through too, except that `FOUNDRY_USERNAME` and
+`FOUNDRY_PASSWORD` are withheld when the image has no use for them: the pinned
+build's `foundryvtt-<version>.zip` is already in the cache (`FOUNDRYVTT_CACHE`,
+or `container_cache` beneath the data root when that is unset) and a licence
+is available without the account (a licence key of 24 characters or more, or
+`Config/license.json` in the data root). Given an account, the image signs in
+to foundryvtt.com and requests a download URL on every container it creates,
+cached or not, and a request refused with HTTP 429 stops it before Foundry
+starts. `stop` stops it. `restart` stops
 it, clears a stale lock left by an unclean shutdown, and starts it again —
 not `docker restart`, which leaves no window to clear the lock. `recreate`
 removes the container first, so a changed world, license or cache
 environment variable actually takes effect, then starts fresh. `rm` removes
 the container. `status` runs `docker ps` filtered to this stage's container
-name. `logs` follows its log. `pull` pulls the configured image
-(`FOUNDRYVTT_CONTAINER_IMAGE`, then `packageBuild.container.image`, then a
-floating `felddy/foundryvtt:release` tag when the package declares no
-`compatibility.minimum`).
+name. `logs` follows its log. `pull` pulls the configured image.
+
+The image is `FOUNDRYVTT_CONTAINER_IMAGE`, then `packageBuild.container.image`,
+then felddy's tag for the pinned build (`felddy/foundryvtt:14.359` for a stage
+pinned to `14.359`), because each image installs its own build by default and
+warns that a different `FOUNDRY_VERSION` may not work with it. A stage with no
+exact pin takes the major tag of its pin or of `compatibility.minimum`
+(`felddy/foundryvtt:14`), and a package that declares neither floats on
+`felddy/foundryvtt:release`.
 
 **OPTIONS**
 
@@ -1270,7 +1303,10 @@ floating `felddy/foundryvtt:release` tag when the package declares no
 `FOUNDRYVTT_<STAGE>_PORT`, `FOUNDRYVTT_<STAGE>_VERSION`,
 `FOUNDRYVTT_<STAGE>_WORLD`, `FOUNDRYVTT_<STAGE>_LICENSE_KEY`,
 `FOUNDRYVTT_CONTAINER_IMAGE`, `FOUNDRYVTT_CACHE` (a shared download-cache
-mount).
+mount), `FOUNDRYVTT_CONTAINER_USER` (passed to `docker run --user`; `0:0`
+under rootless Docker makes the data root's files belong to the host user,
+because the image otherwise runs Foundry as user 1000 and ignores
+`FOUNDRY_UID` and `FOUNDRY_GID`).
 
 **EXIT STATUS**
 
@@ -1455,7 +1491,9 @@ 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 or
+the **content index** of every declared dependency and of every
+`recommends` or `conflicts` relationship that declares `itemCatalog: true`,
+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
@@ -1897,13 +1935,13 @@ $ package-build lint
 
 `package-build links [root]`, `package-build reachability <dir> [file]`,
 `package-build content-format schema`, `package-build content-format fields`,
-`package-build content-format notes`, [Diagnostics](diagnostics.md),
+[Diagnostics](diagnostics.md),
 [Configuration](configuration.md).
 
 `package-build content-format <action>` checks `docs/content-format.md` —
 the content-format specification this package ships — against reality, in
-three ways that fail for different reasons at different times: `schema`,
-`fields` and `notes`, one section below per action. All three read the
+two ways that fail for different reasons at different times: `schema`
+and `fields`, one section below per action. Both read the
 specification named by `--spec`, defaulting to the one this package ships,
 and write nothing.
 
@@ -1949,8 +1987,8 @@ $ package-build content-format schema --schema sohl=schema.json
 
 **SEE ALSO**
 
-`package-build content-format fields`, `package-build content-format notes`,
-`package-build schema`, [Configuration](configuration.md).
+`package-build content-format fields`, `package-build schema`,
+[Configuration](configuration.md).
 
 ### `package-build content-format fields`
 
@@ -2004,59 +2042,7 @@ $ package-build content-format fields --fields sohl --coverage
 
 **SEE ALSO**
 
-`package-build content-format schema`, `package-build content-format notes`,
-[Configuration](configuration.md).
-
-### `package-build content-format notes`
-
-**NAME**
-
-Measure a content tree against the specification's vocabulary.
-
-**SYNOPSIS**
-
-```
-package-build content-format notes [root] [--strict] [--spec <path>]
-```
-
-**DESCRIPTION**
-
-Measures a content tree against the vocabulary the specification declares
-per type. A report by default rather than a gate — every authored note
-predates the specification, so a failing check would be red from the day it
-landed and stay red for the length of a migration nobody could act on;
-`--strict` raises its findings to errors, turned on slice by slice as each
-class of finding reaches zero.
-
-**OPTIONS**
-
-| Positional | Type   | Default                        | Description              |
-| ---------- | ------ | ------------------------------ | ------------------------ |
-| `root`     | string | the configured `paths.content` | Content tree to measure. |
-
-| Option     | Type    | Default                                  | Description                                          |
-| ---------- | ------- | ---------------------------------------- | ---------------------------------------------------- |
-| `--spec`   | string  | the shipped `engine/content-format.yaml` | The specification to read.                           |
-| `--strict` | boolean | `false`                                  | Fail on the findings instead of only reporting them. |
-
-**EXIT STATUS**
-
-1 if the content index could not be built for any note. Without `--strict`,
-findings never fail the run. With `--strict`, 1 if there are any findings.
-Otherwise 0.
-
-**EXAMPLES**
-
-```
-$ package-build content-format notes
-[…] 0 finding(s) across 4 note(s) measured against docs/content-format.md.
-```
-
-**SEE ALSO**
-
-`package-build content-format schema`, `package-build content-format fields`,
-`package-build lint [root]`, [Diagnostics](diagnostics.md),
-[Configuration](configuration.md).
+`package-build content-format schema`, [Configuration](configuration.md).
 
 ### `package-build links [root]`
 
@@ -2073,8 +2059,7 @@ package-build links [root]
 **DESCRIPTION**
 
 Checks that every link in a content tree lands: a dead `#anchor`, a dead
-qualified address, a link with no label (the bare `[[Name]]` alias form is
-retired — every link is an address), a wikilink authored in frontmatter
+qualified address, a link with no label (every link is an address), a wikilink authored in frontmatter
 (which is data and is never resolved), and a package homepage's markdown
 links and `landing:` addresses, which are published verbatim and use no
 wikilink at all. Also reports a vendored foreign-package content index that
@@ -2192,16 +2177,20 @@ checks Prettier cannot make: a heading level that skips, two sibling
 headings sharing an anchor, a reversed link, an emphasis marker other than
 the one these repositories write. Runs over the repository rather than the
 content tree, taking its rules from this package unless the consumer
-declares its own. `--fix` applies the fixes markdownlint can make. Reads
-every matched file; `--fix` rewrites them.
-Installed dependencies under `node_modules` are excluded even when the
-repository has no `.gitignore` or supplies its own markdownlint ignore list.
+declares its own. `--fix` applies the fixes markdownlint can make, then
+reports what remains. Reads every matched file; `--fix` rewrites them.
+Files excluded by any `.gitignore` are skipped, and `node_modules` and `.git`
+are never entered, even when the repository supplies its own markdownlint ignore
+list. A `.markdownlint-cli2.*` options file or `.markdownlint.*` rule file
+overrides the rules and the ignore list; an option the file cannot mean is
+refused as `file:line:column: error:` and nothing is linted. See
+[Project setup](project-setup.md) for the accepted keys.
 
 **OPTIONS**
 
-| Positional | Type      | Default                               | Description    |
-| ---------- | --------- | ------------------------------------- | -------------- |
-| `paths`    | string(s) | every markdown file in the repository | Globs to lint. |
+| Positional | Type      | Default                               | Description                     |
+| ---------- | --------- | ------------------------------------- | ------------------------------- |
+| `paths`    | string(s) | every markdown file in the repository | Globs, or directories, to lint. |
 
 | Option  | Type    | Default | Description                            |
 | ------- | ------- | ------- | -------------------------------------- |
@@ -2308,8 +2297,8 @@ content table, authored where every other page is.
 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`,
+  (`homepage`, `description`), `package-build.config.yaml`
+  (`authors`, `packageBuild.manifest.title`, `site.assets`, `site.notfound`,
   `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
@@ -2363,17 +2352,18 @@ $ package-build site
 
 **NAME**
 
-Build the book the content tree publishes as.
+Build the books the content tree publishes as.
 
 **SYNOPSIS**
 
 ```
-package-build pdf [--out <path>] [--book-version <version>] [--compile]
+package-build pdf [--book <id>] [--out <path>] [--book-version <version>] [--compile] [--list-assets]
 ```
 
 **DESCRIPTION**
 
-Builds the book the content tree publishes as — the third surface beside
+Builds every book `pdf.books` declares, in the order declared, or with
+`--book <id>` the one book with that `id` — the third surface beside
 `package compile` and `site`, reporting in the same `file:line:column:
 severity: message` shape both of those use. **Not building a book is a
 normal outcome and exits 0**: a package publishing only a homepage, one
@@ -2381,26 +2371,68 @@ with no `pdf:` block, and one with no content tree have each said they
 publish no book, and failing the command over that would break the release
 of every package that is not a book. `--compile` (on by default) runs the
 Typst compiler; `--no-compile` emits the Typst source and stops there,
-which is what lets the source be inspected or compiled by hand. Reads the
-content tree named by `pdf.document` and `paths.content`; writes the
-`.typ` source and, unless `--no-compile`, the `.pdf`, to `--out` or the
-configured `pdf.out`.
+which is what lets the source be inspected or compiled by hand.
+
+A reference to a note that another book is home to prints that book and page,
+`Name (_Book title_, p. 12)`. A compile renders and lays out every book, writes
+`pages.json` (each note's home book and the page its entry starts on) into the
+output directory, and renders again with those pages; `--no-compile` runs
+neither pass and prints `p. ?`. See the
+[book guide](guides/book.md#a-reference-to-a-note-in-another-book).
+
+Each book reads its tree from its inline `contents` or the file its
+`document` names, and the notes under `paths.content`. It writes
+`<out>-<version>.typ` and, unless `--no-compile`, `<out>-<version>.pdf`, where
+`<out>` is the book's file stem (default `<contentPackage>-<id>`) and
+`<version>` is `--book-version`; with no version the files are `<out>.typ` and
+`<out>.pdf`. Every book is written into `--out`, or the configured `pdf.out`,
+or `build/dist`.
+
+A book's `coverImage`, `document` and `front` files are checked first; a
+missing one is an error at its key in the configuration, and that book is not
+built while the others are. An `--book` naming no declared book is an error at
+`pdf.books` that lists the declared ids.
+
+Every declared book's queries run before any book is written, so coverage is
+reported over the whole set even with `--book`: a printable note no book selects
+is a finding at its `type:` line, at the severity `pdf.coverage` names. A book
+whose queries select no note is an error at `pdf.books[].id` and is not built.
+A section whose queries select none is left out without a finding. Each book's
+pictures are staged under a directory named for its file stem beside its
+source.
+
+For each book written, the command prints a line of counts and the paths of
+its source and PDF, each prefixed with the book's `id`. It then prints, per
+declared book, its entries, distinct notes and notes without a culture, the
+totals, and one line per note several books select, naming its home book.
+
+`--list-assets` builds nothing. It prints a JSON array on standard output with
+one object per declared book, in configuration order — `id`, `title` and the
+`file`, the path the build writes it to at `--book-version`, relative to the
+working directory and inside `--out` or the configured `pdf.out` — and an empty
+array for a package that publishes no book. The release workflow attaches
+exactly these files and lists them in the release notes.
 
 **OPTIONS**
 
-| Option           | Type    | Default                  | Description                                                        |
-| ---------------- | ------- | ------------------------ | ------------------------------------------------------------------ |
-| `--out`          | string  | the configured `pdf.out` | Write the book here instead.                                       |
-| `--book-version` | string  | —                        | Stamp this version on the title page and in the file name.         |
-| `--compile`      | boolean | `true`                   | Run the Typst compiler. `--no-compile` emits the source and stops. |
+| Option           | Type    | Default                  | Description                                                             |
+| ---------------- | ------- | ------------------------ | ----------------------------------------------------------------------- |
+| `--book`         | string  | every declared book      | Build only the book with this `id`.                                     |
+| `--out`          | string  | the configured `pdf.out` | Write the books here instead.                                           |
+| `--book-version` | string  | —                        | Stamp this version on the title page and in each file name.             |
+| `--compile`      | boolean | `true`                   | Run the Typst compiler. `--no-compile` emits the source and stops.      |
+| `--list-assets`  | boolean | `false`                  | Print each book's `id`, `title` and output path as JSON; build nothing. |
 
 **EXIT STATUS**
 
 0 when there is a stated reason not to build (only a homepage note, no `pdf:`
-block, no content tree). 1 if the document tree
-`pdf.document` names cannot be read or parsed, or on any other thrown
-error. Otherwise 0 — findings inside a book that did build (a filter that
-matched nothing, for instance) are reported but never fail the command.
+block, no content tree). 1 when any finding is an error — an unknown `--book`,
+a missing `coverImage`, `document` or `front` file, a tree that cannot be read
+or parsed, a book that selects no note, an uncovered note under
+`pdf.coverage: error`, a link that resolves nowhere — when a requested book was not
+written or did not compile, or on any other thrown error. Otherwise 0:
+warnings, such as a picture the book cannot carry, are reported but do not
+fail the command.
 
 **EXAMPLES**
 
@@ -2408,8 +2440,14 @@ matched nothing, for instance) are reported but never fail the command.
 $ package-build pdf
 […] No book built: no `pdf:` block is configured, so this package publishes no book
 
-$ package-build pdf --no-compile
-demo-book: error: the document tree named by `pdf.document` cannot be read
+$ package-build pdf --book nope --no-compile
+package-build.config.yaml:12:5: error: --book `nope` names no declared book; declared: core, vedyara
+
+$ package-build pdf --book-version 1.4.0 --no-compile
+[…] core: 1734 entr(ies) and 3 prose file(s) across 41 section(s)
+[…] core: Typst source: build/pdf/thalorna-1.4.0.typ
+[…] vedyara: 28 entr(ies) and 1 prose file(s) across 4 section(s)
+[…] vedyara: Typst source: build/pdf/thalorna-vedyara-1.4.0.typ
 ```
 
 **SEE ALSO**
@@ -2456,9 +2494,10 @@ from them.
 
 A map note is a different thing: it carries a Scene exported from Foundry under
 `data.scene`, on every map subtype. The pack compiler passes it through, binds
-pins marked `#anchor` to pages from the map note's Markdown, and applies
-`data.fixup`, which resolves asset Addresses into selected fields of the
-exported Scene; a missing path or asset is a build error.
+pins marked `#anchor` to pages from the map note's Markdown, and applies the
+fixups — `data.fixup` and `data.thumbnail`, the Scene's `thumb` — which resolve
+asset Addresses into selected fields of the exported Scene; a missing path or
+asset is a build error.
 
 The four drawings, any of which may be asked for in one run: