@heroiclands/package-build 23.1.0 → 23.2.0

package/docs/diagnostics.md

@@ -109,13 +109,11 @@ different lines or columns instead of collapsing onto the first.
 frontmatter key** by searching the fence rather than the whole file — a bare
 search for a key like `name` or `type` would routinely match a line of prose
 first. Passing `value` narrows the match to the entry that carries it, which
-is what a list-valued key (`aliases`) needs: the finding belongs on the
+is what a list-valued key (`tags`) needs: the finding belongs on the
 wrong entry, not on the key that introduces the list. `opts.topLevel`
 requires the match at column 1, for a key name that is legal both at the top
-level and nested (`aliases` is both a retired top-level field and a
-permitted `name.aliases`) — without it, a finding about the retired field
-could resolve to the nested one and tell an author to delete a field they are
-allowed to write.
+level and nested — without it, a finding about the top-level key could
+resolve to the nested one.
 
 **`positionOfYamlPath(text, keyPath, opts)`** and
 **`positionOfFrontmatterPath(raw, keyPath, opts)`** locate a node by
@@ -214,6 +212,48 @@ and the summary carries no position because it has none.
 thalorna: 2572 notes — 2089 full, 464 draft, 19 stub.
 ```
 
+## A worked case: a note's culture
+
+`data.culture` has four findings, all errors. Three come from `package-build
+lint` reading what a note wrote, and each sits on the line that makes the note
+wrong. A setting guide with no culture is located at its `subType:` line, the key
+whose value made it a setting guide:
+
+```text
+assets/content/Guides/G1.md:5:1: error: a setting guide introduces one culture, so this note must state `data.culture`, naming a culture lore note
+```
+
+The field on a `doc` of any other subType is located at the `culture:` key:
+
+```text
+assets/content/Guides/G2.md:8:3: error: `data.culture` is stated by a setting guide, and this note's `subType` is not `settingguide`
+```
+
+A `lore` note of `subType: culture` is its own culture. It may leave the field
+out or name itself, by its shortcode or by any longer form of its Address; a
+value naming any other note is located at the value, and the message gives the
+Address the value names:
+
+```text
+assets/content/Lore/Hillfolk.md:8:12: error: data.culture reedflats-note-lore-reedfolk names another note; a culture note's data.culture names the note itself
+```
+
+The fourth comes from resolving cultures into the content index. A place or
+affiliation with no culture of its own whose `data.parents` resolve to different
+cultures is located at its `parents:` key, and names each culture with the
+parent it came through:
+
+```text
+assets/content/Places/Causeway.md:8:3: error: data.parents resolve to different cultures (reedflats-note-lore-reedfolk via reedflats, reedflats-note-lore-hillfolk via stonecrest); state data.culture
+```
+
+A polity whose seat and governed places disagree is located at `seat:`, or at
+`data:` when it states no seat. Because the index is read by every build, the
+conflict fails the index and each command that reads it without collecting
+problems, listing every conflict at once. Stating `data.culture` on the note
+resolves it. The rules are under
+[Culture in the index](reference/format-details.md#culture-in-the-index).
+
 ## Summary counts and prose are not findings
 
 A run's progress and summary lines — `42 address(es) across 10 note(s).`,
@@ -256,18 +296,14 @@ all fails the run.
 
 **A corpus problem always fails, regardless of severity or a `--strict`
 flag.** When the content tree itself cannot be indexed — a note the walk
-cannot record, most often a retired `package:` key — the note is absent from
+cannot record, most often a declared `package:` key — the note is absent from
 every other answer a command gives. Reporting it and still exiting `0` would
 call the tree clean while silently omitting a note, so every command that
-indexes a corpus (`lint`, `links`, `reachability`, `content-format notes`,
-`addresses diff`) fails on a corpus problem unconditionally, before it
+indexes a corpus (`lint`, `links`, `reachability`, `addresses diff`) fails on a corpus problem unconditionally, before it
 evaluates anything else.
 
 **A few commands report advisory findings that never fail the run on their
-own**, and say so where they emit them: `content-format notes` measures a
-content tree against the format specification as a progress report during a
-migration, printing every finding as a `warning` and passing `--strict` to
-promote a class to `error` only once that class has reached zero; `format`
+own**, and say so where they emit them: `format`
 reports where this repository's Prettier configuration diverges from the
 shared convention as a `warning`, because a repository's own configuration
 is allowed to win on purpose; `addresses diff` reports a withdrawn or renamed
@@ -283,7 +319,6 @@ over one would teach people to stop reading the report.
 | command                                          | fails when                                                                                                                                                                                                                                                         |
 | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `package-build lint [root]`                      | an address, frontmatter, schema, charset, icon or HTML finding is `error`-severity, or the corpus cannot be indexed                                                                                                                                                |
-| `package-build content-format notes [root]`      | `--strict` was passed and it reported any finding (all findings are `error`-severity only under `--strict`), or the corpus cannot be indexed                                                                                                                       |
 | `package-build content-format schema`            | it reports any finding at all                                                                                                                                                                                                                                      |
 | `package-build content-format fields`            | it reports any finding at all                                                                                                                                                                                                                                      |
 | `package-build links [root]`                     | it reports any finding at all, an index is unusable (a stale or unaddressable foreign manifest), or the corpus cannot be indexed                                                                                                                                   |

package/docs/guides/book.md

@@ -9,7 +9,7 @@ subType: howto
 
 `package-build pdf` selects notes from a content package and sets them as a
 PDF. The website can publish the whole content tree; the book follows the
-ordered document tree named by `pdf.document`. This makes the book's contents
+ordered document tree each book declares. This makes the book's contents
 an editorial choice. A note outside every selection remains in the content
 package and on its site, but it has no book entry.
 
@@ -18,23 +18,36 @@ produce the PDF. Typst must be available on `PATH`, or named with `pdf.binary`.
 The [command reference](../commands.md) lists the CLI options; the
 [configuration reference](../configuration.md) lists the `pdf` keys.
 
-## Declare the book
+## Declare the books
 
-Give the book a title and document tree:
+`pdf.books` lists one entry per PDF. A package that publishes one book lists
+one; a package that publishes a world book and a book for each culture lists
+them all, and `package-build pdf` builds every one. Each book needs an `id`, a
+`title` and its tree of contents:
 
 ```yaml
 pdf:
-  title: The Setting Guide
-  document: book.yaml
   out: build/pdf
+  books:
+    - id: guide
+      title: The Setting Guide
+      subtitle: A Reader's Companion
+      document: book.yaml
+      out: setting
 ```
 
 A tree containing only a homepage has no content pages for a book. With no
-`pdf` block or no content tree, the command has nothing to build. `pdf.title`
-and `pdf.document` are required together when `pdf` is declared.
+`pdf` block or no content tree, the command has nothing to build and exits 0.
 
-`book.yaml` contains an ordered list of sections. Each section contains prose
-files, note filters, or nested sections:
+### The tree: `document` or `contents`
+
+The tree is an ordered list of sections. Each section contains prose files,
+note filters, or nested sections. A book gives its tree in exactly one of two
+ways: `document` names a file that holds it, and `contents` writes it inline
+in the configuration. A file suits a long tree; inline suits a short book that
+reads best beside the other books it shares a package with.
+
+`book.yaml` holds the tree under a `contents:` key:
 
 ```yaml
 contents:
@@ -49,17 +62,299 @@ contents:
           - filter: "type = 'place' AND subType = 'settlement'"
 ```
 
+The same tree written inline sits under the book's own `contents`, without the
+outer key:
+
+```yaml
+pdf:
+  books:
+    - id: guide
+      title: The Setting Guide
+      contents:
+        - sectionName: Introduction
+          contents:
+            - file: prose/introduction.md
+        - sectionName: Places
+          contents:
+            - filter: "type = 'place'"
+```
+
+A finding about an inline tree names `package-build.config.yaml` at the line
+of the offending key; a finding about a tree file names that file.
+
 The build keeps the order of prose and subsections as written. Notes selected
 by a filter are ordered by their folded display name. The filter is a SQL
 `WHERE` clause over this package's `notes` table; the build supplies
-`SELECT * FROM notes`. A filter cannot choose another package's notes. It is
-an error when a filter selects no printable note, while notes that no filter
-selects are simply outside this volume. A note selected more than once prints
-at each selected position; inbound book links reach its first occurrence.
+`SELECT * FROM notes`. A filter cannot choose another package's notes. A
+book's `front` lists Markdown files placed before its contents.
+
+### The file stem and `--book`
+
+A book's PDF is named `<out>-<version>.pdf`, where `out` is the book's **file
+stem**. Without an `out`, the stem is `<package>-<id>`. A stem is one path
+segment with no directory, and two books may not resolve to the same stem. The
+version comes from `--book-version`; with none, the file is `<out>.pdf`. Every
+book is written into the directory `pdf.out` names. A package that publishes
+one book and keeps a file name of the form `<package>-<version>.pdf` declares
+`out: <package>`.
+
+`package-build pdf` builds every declared book in the order declared. `--book
+<id>` builds the one book with that `id`:
+
+```bash
+package-build pdf --book vedyara
+```
+
+Coverage and home books, described below, are computed over every declared
+book even when `--book` renders only one.
+
+### Sections that select nothing
+
+A section whose filters select no printable note is left out of the book
+without a finding. A tree can therefore carry a section for a culture or a
+period before any note belongs to it, and the book prints nothing for it.
+
+A section that holds prose and no selected notes, such as a preface, prints
+its prose. A **book** whose filters select no note at all, whatever prose it
+holds, is an error at its `id`, and that book is not built while the others
+are:
+
+```text
+package-build.config.yaml:9:15: error: book `sinale` selects no note
+```
+
+## Coverage and home books
+
+Several books draw on one content package, so the question "is every note in
+some book?" belongs to the set of books, not to any one of them. After every
+book's filters have run against the one corpus, the build reports each
+printable note that no book selects. A **printable** note is a note that is
+neither a stub nor tagged `gm`, and that `pdf.unprinted` does not name.
+
+Two shared keys under `pdf` control the report:
+
+- `pdf.unprinted` is a `WHERE` clause over `notes` that names notes belonging
+  in no book, such as folder notes: `unprinted: "type = 'folder'"`. Coverage
+  skips them. It has no default, so set it for any note type that has no place
+  in a book.
+- `pdf.coverage` is `warning` (the default), `error` or `off`. A printable note
+  no book selects is reported at that severity, at the note's `type:` line.
+  `off` reports nothing. `error` makes the command exit 1.
+
+The finding carries the standard shape, `file:line:column: severity: message`,
+with the path of the note relative to the working directory:
+
+```text
+assets/content/Guides/Fieldcraft.md:2:1: warning: no book selects this note; add it to a book's query or to `pdf.unprinted`
+```
+
+To clear the finding, add the note to a book's query or name it in
+`pdf.unprinted`.
+
+### A note several books select
+
+A note may be selected by more than one book, and it prints in each. Its
+**home book** is the first book in `pdf.books` that selects it. A note a book
+selects twice counts as that one book's and prints at each position.
+
+The home is a property of the order the books are listed in and the queries
+they hold. To move a note's home, reorder the books, or narrow the query of the
+book that currently holds it so that it does not select the note. Nothing
+else sets a home.
+
+### A reference to a note in another book
+
+A PDF link cannot reach into another file, so a wikilink to a note that another
+book is home to is not a link. It prints the words the link carried, then the
+home book's title and the page the note's entry starts on there:
+
+```text
+the Lyrebird Inn (The Tenebrae Volume, p. 214)
+```
+
+Which form a wikilink takes depends on where its target is printed:
+
+| The target is                                                 | The link prints                           |
+| ------------------------------------------------------------- | ----------------------------------------- |
+| An entry of the same book, including a note the book reprints | An internal destination                   |
+| An entry of another book, and not of this one                 | `Name (_Book title_, p. N)`, with no link |
+| A note in no book                                             | The web address of the note's page        |
+
+The page is the page the PDF itself numbers, which is the number printed in the
+footer and used by the contents and the index, so the printed `p. N` is the
+physical page of the PDF. A note the book reprints, or prints in two places,
+has one page in its home book: a reference from a third book names the home
+book and the page of the home book's first entry for it. Infobox links and
+generated sections follow the same table.
+
+The page is read from the laid-out book, so the build makes two passes:
+
+1. **Pass one** renders every declared book, with `p. ?` in place of each
+   cross-book page, lays each out with `typst eval`, and writes
+   `pages.json` beside the books in `pdf.out`:
+
+   ```json
+   {
+     "sohl-thalorna-place-lyrebird-inn": { "book": "tenebrae", "page": 214 }
+   }
+   ```
+
+   The keys are the notes' canonical addresses in sorted order; the file is
+   identical across builds of unchanged sources.
+
+2. **Pass two** renders every book again with those pages and lays them out
+   again. The words `(The Tenebrae Volume, p. 214)` are wider than `p. ?`, so a
+   page can move. When no page moved, pass two is the output. When one did, the
+   build renders once more with the new pages and reports every note whose page
+   still differs from the page printed for it, as a warning at the note's file.
 
-The document tree can include a section with prose and no selected notes, for
-example a preface. Empty sections do not print. `pdf.front` lists Markdown
-files placed before the book's contents.
+A build that prints no cross-book reference, such as a package with one book,
+is laid out once. Rendering and laying out every book happens for each build
+with `--book` too, because a page in one book is read from another; only the
+requested books are compiled. `--no-compile` runs neither pass: the source
+prints `p. ?` for each cross-book reference and no `pages.json` is written.
+
+Two builds produce identical PDFs only when Typst embeds the same creation
+time. Set `SOURCE_DATE_EPOCH` for a reproducible build.
+
+### Worked example: two culture books and a World book
+
+A package publishes a book for each of two cultures and a World book that
+gathers every region:
+
+```yaml
+pdf:
+  out: build/pdf
+  unprinted: "type = 'folder'"
+  books:
+    - id: vedyara
+      title: Vedyara
+      contents:
+        - sectionName: Vedyara
+          contents:
+            - filter: "data.culture = 'thalorna-note-lore-vedyariclt'"
+    - id: okharin
+      title: Okharin
+      contents:
+        - sectionName: Okharin
+          contents:
+            - filter: "data.culture = 'thalorna-note-lore-okharinclt'"
+    - id: world
+      title: The World of Thalorna
+      contents:
+        - sectionName: Regions
+          contents:
+            - filter: "type = 'place' AND subType = 'region'"
+```
+
+The content tree holds these notes:
+
+| Note                   | Type and subtype  | Culture | Selected by      |
+| ---------------------- | ----------------- | ------- | ---------------- |
+| `Places/Ashmere.md`    | place, region     | Vedyara | `vedyara`, world |
+| `Places/Fordholm.md`   | place, settlement | Vedyara | `vedyara`        |
+| `Places/Stormhaven.md` | place, settlement | Okharin | `okharin`        |
+| `Places/The Reach.md`  | place, region     | none    | `world`          |
+| `Guides/Fieldcraft.md` | doc, howto        | none    | no book          |
+| `Folders/Places.md`    | folder            | none    | `pdf.unprinted`  |
+
+`Ashmere` is a region of the Vedyara culture, so both the `vedyara` book and
+the `world` book select it. `vedyara` is listed first, so it is Ashmere's home.
+`Fieldcraft` matches no filter, so it is the one coverage finding. The folder
+note is named by `pdf.unprinted` and is not a candidate at all.
+
+Running `package-build pdf` first reports one finding on stderr:
+
+```text
+assets/content/Guides/Fieldcraft.md:2:1: warning: no book selects this note; add it to a book's query or to `pdf.unprinted`
+```
+
+then, for each book, a line counting its entries, prose files and sections and
+the path of its Typst source (and of its PDF when Typst compiles it), and then
+the summary:
+
+```text
+vedyara: 2 entries, 2 notes, 0 without a culture
+okharin: 1 entry, 1 note, 0 without a culture
+world: 2 entries, 2 notes, 1 without a culture
+5 printable notes, 1 in no book, 1 in pdf.unprinted
+Ashmere (Places/Ashmere.md) is printed by vedyara, world; home: vedyara
+```
+
+Each book line gives its entries (a note printed at two positions is two
+entries), its distinct notes, and how many of those carry no `data.culture`.
+The `world` book's count of one is `The Reach`. The note path in the summary is
+relative to the content root, while a finding's path is relative to the working
+directory. The totals line counts the
+printable notes that are not in `pdf.unprinted`, the ones among them that no
+book selects, and the notes `pdf.unprinted` names. A final line appears for
+every note that several books select, in book order and then path order,
+naming the books that print it and its home.
+
+To make `world` the home of Ashmere, list it before `vedyara`. To keep
+`vedyara` first and still have `world` own the region, narrow the `vedyara`
+filter with `AND NOT (type = 'place' AND subType = 'region')`; Ashmere is then
+selected by `world` alone, its home is `world`, and its summary line
+disappears.
+
+## The cover page and the title page
+
+A book opens on a **cover page** when it declares a `coverImage`, a path
+resolved against the directory the configuration sits in:
+
+```yaml
+books:
+  - id: world
+    title: The World of Thalorna
+    subtitle: A Song of Heroic Lands Sourcebook
+    coverImage: assets/images/covers/world.webp
+    document: world.yaml
+```
+
+The image fills the page, cropped to fit, and is page 1. The book's title and
+subtitle are centred in white in the upper third, over a translucent dark band
+so they read over any art. The cover carries no running footer and no page
+number. A book without `coverImage` begins on its title page.
+
+The **title page** shows the book's title, subtitle and version, then the
+package's people, one per line. The people come from the top-level `authors`
+list, shared by every book, each entry a `name` and an optional `role`:
+
+```yaml
+authors:
+  - name: Tom Rodriguez
+    role: author
+  - name: Tom Rodriguez
+    role: artist
+  - name: Ada Quill
+```
+
+A person with a role prints as `Name, Role` with the role in title case, and
+one without prints as `Name`. The role is one of `author`, `designer`,
+`developer`, `editor`, `proofreader`, `artist`, `cartographer`, `layout`,
+`playtester` and `translator`. A person who holds two roles is listed twice.
+
+```text
+Tom Rodriguez, Author
+Tom Rodriguez, Artist
+Ada Quill
+```
+
+At the foot of the title page sit the copyright and licence statements, set
+under `pdf` and shared by every book:
+
+```yaml
+pdf:
+  copyright: © 2026 Tom Rodriguez
+  license: |
+    Text is licensed under CC BY-SA 4.0.
+    Code is licensed under GPL-3.0-or-later.
+```
+
+Both are optional, and the foot prints whichever is given. `copyright` is one
+line; `license` may run to several. The [configuration
+reference](../configuration.md#authors) lists the `authors` keys and the
+closed role list.
 
 ## Control a section's page
 
@@ -123,6 +418,25 @@ the book prints adds the page it appears on. A term mentioned several times on
 one page lists that page once, and a note printed under more than one section
 is listed once, with every page it occupies.
 
+**An index lists the notes its own book is home to.** A note's home is the
+first book in `pdf.books` that selects it. In a package of several books:
+
+- A note a book reprints from another book's home has no entry in the
+  reprinting book. Its term, with its aliases and event names, is in its home
+  book's index, and a link to it from the reprinting book adds nothing there.
+- The pages an index lists are those of its own book, taken from the same table
+  as the cross-book references (`pages.json`), so the page a reference prints
+  for a note is the page its home book's index lists for the note's own entry.
+- A mention of a note another book prints is not a term of the mentioning
+  book. The mention reads `Name (_Book title_, p. N)` in the text, and the note's
+  entry and its page are in the other book's index.
+
+Set [`pdf.indexSeeAlso`](../configuration.md) to `true` to list those mentions
+too. Each note another book prints that this book mentions in authored prose
+then has a line, filed under its name:
+
+> Sword: _Book A_, p. 12
+
 Two kinds of link add nothing:
 
 - **Links in generated sections** such as "Within" or "Governed by". They name
@@ -155,8 +469,10 @@ for them. A package can choose families and add a font directory:
 
 ```yaml
 pdf:
-  title: The Setting Guide
-  document: book.yaml
+  books:
+    - id: guide
+      title: The Setting Guide
+      document: book.yaml
   fonts:
     serif: Libertinus Serif
     sans: Libertinus Sans
@@ -181,10 +497,11 @@ the font registry.
 package-build pdf
 package-build pdf --no-compile
 package-build pdf --out build/book
+package-build pdf --book vedyara
 ```
 
 `--no-compile` emits the Typst source and staged images without invoking
-Typst. The source and assets sit under the output directory, because Typst
+Typst, and so without measuring pages. The source and assets sit under the output directory, because Typst
 reads paths relative to its compilation root. An authored image from this
 package can be staged into the book. A remote image or one owned by another
 package cannot be read by this build; the build reports that limitation.
@@ -203,7 +520,10 @@ so their links follow their own rule, because a book is often a selection:
 - A name whose note is in the book is an internal link followed by the page
   that note's entry starts on, printed as the contents prints it:
   `Ford (p. 12)`. The number is Typst's own, read after layout.
-- A name whose note is not in the book is printed as plain text, with no link,
-  no page and no finding.
+- A name whose note is printed by another book is followed by that book and
+  page, `Ford (_The Tenebrae Volume_, p. 12)`, with no link; see
+  [a reference to a note in another book](#a-reference-to-a-note-in-another-book).
+- A name whose note is in no book is printed as plain text, with no link, no
+  page and no finding.
 
 Links an author wrote keep the rules above and carry no page number.

package/docs/guides/e2e.md

@@ -57,6 +57,9 @@ this harness and a Foundry license available to the test container:
 FOUNDRYVTT_TEST_DATA=/path/to/isolated-foundry-test-data
 FOUNDRYVTT_TEST_LICENSE_KEY=replace-with-test-license-key
 FOUNDRYVTT_TEST_PORT=30003
+FOUNDRYVTT_CACHE=/path/to/foundry-release-cache
+FOUNDRY_USERNAME=your-foundryvtt-com-account
+FOUNDRY_PASSWORD=replace-with-account-password
 # FOUNDRYVTT_TEST_VERSION=14.367
 ```
 
@@ -82,8 +85,16 @@ own `.env.local` because that ignored file is not copied with the branch.
 The test data path is a Foundry data root, beneath which the harness creates
 `Data/worlds/` and installs the package. Use an absolute path; `~` and shell
 variables are not expanded in `.env.local`. Set `FOUNDRYVTT_TEST_VERSION` to
-select a specific Foundry build for routine runs. With the local settings in
-place, seed the world:
+select a specific Foundry build for routine runs; the container then runs the
+image made for that build. The first run downloads the release, which needs
+`FOUNDRY_USERNAME` and `FOUNDRY_PASSWORD`, and the image keeps the archive in
+`FOUNDRYVTT_CACHE`, or in `container_cache` beneath the data root when that is
+unset. Once the archive is cached and the stage has a licence, later runs
+start without signing in to foundryvtt.com, so its rate limit never stops a
+run. Under rootless Docker, set
+`FOUNDRYVTT_CONTAINER_USER=0:0`: container root is then the host user, so every
+file under the data root belongs to them, where the image would otherwise run
+Foundry as user 1000. With the local settings in place, seed the world:
 
 ```bash
 package-build e2e seed

package/docs/guides/icons.md

@@ -49,6 +49,11 @@ slots. A pathname with slashes or an extension is not an art-slot address.
 | `data.tokenIcon` | Actor token art; follows `data.icon` when unset |
 | `data.banner`    | Page hero image for the site                    |
 
+A map's picture in Foundry's Scene lists is not an art slot: a `map` note names
+it with `data.thumbnail`, an `image` Address the build writes into the Scene's
+`thumb`. The [map reference](../reference/format-details.md#the-thumbnail)
+describes it.
+
 An Item without `data.icon` uses its builder's configured default art. An
 Actor without `data.icon` uses its compiled default art. Write `data.icon`
 when the note needs a particular image. A portrait within the prose is an
@@ -58,7 +63,10 @@ it does not set a document's profile art. The
 slot's type and document destination.
 
 A being's `subType` selects its compiled default art: `character` and `npc`
-use person art, and `creature` uses creature art.
+use person art, and `creature` uses creature art. HM3's built-in Actor and Item
+defaults point into the system's `assets/images/` and `assets/icons/` trees,
+introduced by [HM3's asset-path migration](https://git.pupluppy.org/HeroicLands/HarnMaster-3-FoundryVTT/pulls/60).
+Use these defaults with an HM3 release that includes those assets.
 
 ## Write an inline icon in prose
 
@@ -98,8 +106,10 @@ book:
 
 ```yaml
 pdf:
-  title: The Setting Guide
-  document: book.yaml
+  books:
+    - id: guide
+      title: The Setting Guide
+      document: book.yaml
   iconFonts:
     fontawesome: assets/fonts/fa-solid-900.ttf
 ```
@@ -123,6 +133,6 @@ The content index assigns addresses to image assets. The lint reports unknown
 inline names and invalid art addresses. A documentation package has no packs,
 so it skips `package compile`. Inspect a compiled Actor or Item's
 `img`, an Actor's `prototypeToken.texture.src`, and a map's `background.src`
-when checking document art. Inspect the site page and emitted Typst source for
+and `thumb` when checking document art. Inspect the site page and emitted Typst source for
 inline icons and banners. The [command reference](../commands.md) gives the
 available build and lint options.

package/docs/guides/module-project.md

@@ -366,7 +366,9 @@ order.
 gives a usable overview of areas, peoples, institutions, and daily life, then
 links to the detailed notes. Use `subType: settingguide` for that entry point;
 `concept` explains one subject, `reference` serves lookup, and `userguide`
-explains the Foundry controls. For example, a guide at
+explains the Foundry controls. A setting guide is a culture's guide to the
+setting, so it names its culture in `data.culture`, the Address of a `lore` note
+of `subType: culture`; a setting guide without one is an error. For example, a guide at
 `assets/content/Guides/Reed_Flats.md` can begin:
 
 ```markdown
@@ -376,6 +378,8 @@ name: { full: The Reed Flats Guide }
 type: doc
 subType: settingguide
 description: A starting point for adventures in the Reed Flats.
+data:
+  culture: lore-reedfolk
 ---
 
 The river trade links the settlements of the Reed Flats. Their routes and
@@ -630,9 +634,7 @@ packageBuild:
 
   manifest:
     title: Acme Bestiary
-    description: Creatures of the reed flats, as compendium journals.
-    authors:
-      - name: Acme
+    descriptionHtml: Creatures of the reed flats, as compendium journals.
     license: LICENSE.md
     readme: README.md
     languages:
@@ -649,14 +651,21 @@ packageBuild:
 `assets:` is a copy list, from the repository into the stage. `manifest:` is
 everything about the manifest that cannot be derived from `package.json` or from
 the keys above — the human-facing identity, and the files Foundry links to.
-`title` is required by Foundry and has no derivation; supply it.
+`title` is required by Foundry and has no derivation; supply it. The manifest's
+`authors` is derived too, from the top-level `authors` list, which names the
+package's people once for the manifest, the site and the book:
+
+```yaml
+authors:
+  - name: Acme
+```
 
 `packFolders` may name only packs this package ships, and the build compares the
 two lists rather than trusting them to agree:
 
 ```console
 $ npx package-build manifest
-package-build.config.yaml:36:21: error: packFolders: folder "Acme Bestiary" names pack "items", which this package does not ship (packs: journals)
+package-build.config.yaml:34:21: error: packFolders: folder "Acme Bestiary" names pack "items", which this package does not ship (packs: journals)
 package-build: packFolders names 1 pack this package does not ship (reported above). Foundry skips a name it cannot resolve, so the folder would ship missing those packs — correct `packageBuild.manifest.packFolders`.
 ```
 
@@ -862,8 +871,9 @@ 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, and add a `packageBuild.manifest.title`. The theme the site renders
+address to `package.json` as `homepage`, with a `description` beside it, list
+the package's people in `authors` in `package-build.config.yaml`, 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