@heroiclands/package-build 5.0.0 → 6.1.0

package/CONTENT.md

@@ -77,8 +77,10 @@ paths:
   stage: build/stage/packs
   unpack: build/tmp/packs
 
-# The one pack list. Order is load-bearing where one pass reads another's
-# output, and `packDirectories` is derived from it.
+# The one pack list. `packDirectories` and the manifest's `packs` array are both
+# derived from it, so order it for a reader browsing compendiums — the compile
+# order is worked out separately, from what each pass reads (see "Declaration
+# order is presentation" below).
 packs:
   - { name: items, type: Item, label: Items, folders: item-folders.yaml }
   - { name: journals, type: JournalEntry, label: Journals }
@@ -357,6 +359,55 @@ hand-authored `system.template.json` lived, and the package-id guard and the
 top-level `compatibility.minimum`, the id is derived from `package.json`
 `name`, and `@heroiclands/package-build` writes the manifest from this file.
 
+### Declaration order is presentation, not compile order
+
+`packs:` is the manifest's `packs` array as well, so a consumer orders it for a
+reader browsing compendiums. It is **not** the order the passes run in, and it
+does not have to be: the compile order is derived from what each pass reads.
+
+One pass reads another's output today. The actors pass resolves each being's
+embedded items against the JSON the item passes wrote — a being names an item by
+`(type, shortcode)` and never by the pack it ships in, so **every** Item pack has
+to be compiled before the Actor pass, not merely the first. A compiler states
+that on itself:
+
+```js
+export class Actors extends BasePackCompiler {
+  static readsPackOutputOf = Object.freeze(["Item"]);
+}
+```
+
+The generator schedules each pass after the packs of every type it names, and
+does so with the **smallest** reordering that works — the earliest declared pass
+whose dependencies have all run goes next. A list already in a workable order is
+therefore compiled exactly as declared, and one that is not moves only the
+passes that had to move. When the two orders differ the build says so:
+
+```text
+[INFO]: Pass order: characteristics, mysteries, characters — a pass that reads
+        another's output compiles after it, whatever order `packs:` declares.
+```
+
+This used to be the author's problem, and a nasty one: an Actor pack declared
+first compiled only where an earlier run had already left `build/packs-json`
+populated. `build/` is gitignored, so it was green on every local tree that had
+built once and exit 1 on every fresh checkout and CI runner, over a message that
+named a missing directory rather than the ordering that caused it (#73). A
+consumer registering a compiler of its own declares its dependencies the same
+way; a type no pack of which is declared is simply not waited for.
+
+**Compiling one pack by name is the case ordering cannot answer.**
+`content-build package compile <name>` runs the pass you asked for and no other,
+so a dependency that is neither in the run nor already on disk is reported
+rather than ordered around:
+
+```text
+error: pack "characters" (Actor) reads the compiled output of the Item pack
+       "characteristics", which this run does not compile and which
+       build/packs-json/characteristics does not hold — compile the whole
+       package, or compile "characteristics" first
+```
+
 ### An item type's default art
 
 A note that carries no `img:` gets its type's **default art**, and a type
@@ -423,19 +474,21 @@ npx content-build markdown [paths..] [--fix]
 npx content-build manifest [root] [--out <dir>]
 npx content-build site [--out <dir>]
 npx content-build reachability <dir> [file] [--index <shortcode>]
+npx content-build addresses diff --from <zip|dir> [--strict]
 ```
 
-| Command        | What it does                                                                                                                  |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `package`      | Compile the content tree into LevelDB packs, unpack a shipped pack back to JSON, or clean one. See [Install](#install).       |
-| `docs`         | Render a generated reference from the configured registries. `item-fields` is the item-frontmatter page.                      |
-| `lint`         | Check a content tree's addresses and its frontmatter. See [Linting a content tree](#linting-a-content-tree).                  |
-| `links`        | Check that every link in the tree lands: dead anchors, dead qualified addresses, wikilinks in frontmatter, drifted manifests. |
-| `format`       | Prettier, with the shared configuration. See [Prose: formatting and markdown](#prose-formatting-and-markdown).                |
-| `markdown`     | markdownlint, with the shared rule set — the structure Prettier is indifferent to.                                            |
-| `manifest`     | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).               |
-| `site`         | Publish the content tree as a website. See [Publishing a website](#publishing-a-website).                                     |
-| `reachability` | Walk outward from an index note and report what no path reaches, for a tree meant to be navigable from one entry point.       |
+| Command        | What it does                                                                                                                                                            |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `package`      | Compile the content tree into LevelDB packs, unpack a shipped pack back to JSON, or clean one. See [Install](#install).                                                 |
+| `docs`         | Render a generated reference from the configured registries. `item-fields` is the item-frontmatter page.                                                                |
+| `lint`         | Check a content tree's addresses and its frontmatter. See [Linting a content tree](#linting-a-content-tree).                                                            |
+| `links`        | Check that every link in the tree lands: dead anchors, dead qualified addresses, wikilinks in frontmatter, drifted manifests, and the package homepage's own addresses. |
+| `format`       | Prettier, with the shared configuration. See [Prose: formatting and markdown](#prose-formatting-and-markdown).                                                          |
+| `markdown`     | markdownlint, with the shared rule set — the structure Prettier is indifferent to.                                                                                      |
+| `manifest`     | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).                                                         |
+| `site`         | Publish the content tree as a website. See [Publishing a website](#publishing-a-website).                                                                               |
+| `reachability` | Walk outward from an index note and report what no path reaches, for a tree meant to be navigable from one entry point.                                                 |
+| `addresses`    | Report every published item address this build has stopped publishing. See [Diffing published addresses](#diffing-published-addresses).                                 |
 
 Every path, pack name and root it needs comes from the consuming repository's
 `package-build.config.yaml`, so the usual invocation takes no arguments beyond
@@ -454,7 +507,7 @@ npx content-build lint            # the configured `paths.content`
 npx content-build lint some/tree  # or a tree named outright
 ```
 
-Checks the two rules every note's **identity** is authored against, and reports
+Checks the three rules every note's **identity** is authored against, and reports
 each finding in the located form below:
 
 - **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the identity
@@ -463,12 +516,63 @@ each finding in the located form below:
 - **Uniqueness** — `(type, shortcode)` names one note. A document is addressed
   across _every_ pack of its document type, so routing two same-address notes to
   different packs with `pack:` does not separate them.
+- **The package's own address** — exactly one note claims `/<package>/`. See
+  [Exactly one homepage](#exactly-one-homepage) below.
 
 It compiles nothing, opens no LevelDB and needs no Foundry manifest, so it runs
 in about a second and can gate a commit. An empty or untyped tree **fails**
 rather than passing: "every one of nothing is unique" is a vacuous pass, and it
 is exactly what a tree that failed to check out produces.
 
+What that guard reports is an **empty walk**, not an empty set of addresses. A
+note may be keyless by design — a homepage carries no `shortcode`, because it is
+addressed by the package rather than by a slug — so a package in
+`publish.site: homepage` mode has a content tree that is populated, correct and
+permanently unkeyed. That tree passes; a tree holding no notes at all still
+fails.
+
+### Exactly one homepage
+
+A content tree declares **exactly one** `type: homepage` note (#52). Zero is an
+error and two is an error, at the same severity, because they are one defect: a
+package whose front page is not the page a person chose.
+
+- _Zero_ and the package serves nothing at `/<package>/` — the failure the
+  authored homepage exists to prevent, and a silent one: the site build reports
+  `wrote 0 homepage(s)` and exits 0.
+- _Two_ and it serves a page nobody chose. Every homepage is written to the same
+  `_index.md`, so the second overwrites the first and the front page is decided
+  by the order the walk reached the files in — by _filename_, on a type whose
+  whole point is that it is routed by frontmatter. There is no "first wins"
+  convention to fall back on, so nothing can pick the right one.
+
+Neither has a safe default, so neither is a warning: a build that proceeded past
+either would publish the wrong front page while reporting success, which is
+exactly what a warning tolerates.
+
+**Where it fires: `lint` _and_ `site`.** No single command reaches every
+package — `HarnMaster-3-FoundryVTT` runs `content-build site` and no
+`content-build lint`; `sohl-thalorna` runs `content-build lint` and its own site
+builder — so a rule in one of them is a rule two of the six packages do not
+have. Both call the same function, so there is one rule and two call sites
+rather than two rules. In the site build it runs **before the output tree is
+cleared**, so a failing gate cannot destroy a good site to report a bad tree.
+
+**It does not vary by `publish.site`.** That setting chooses whether the
+_content_ surfaces are published; the homepage is the floor beneath both modes.
+The lint call site reads no `site:` block at all, and so could not vary by mode
+even if the rule wanted to.
+
+Zero has no file to name, so the locator is the **content root** — a real path,
+and the directory the note has to be added to. No line or column is invented for
+it. Two is reported once per offending note, located at its own `type:` value and
+naming the other, because each note is a place an author has to open and edit:
+
+```text
+assets/content: error: holds no `type: homepage` note, so package "sohl" publishes nothing at its own address /sohl/ — a package's front page is one authored note in this tree, routed by `type:` rather than by filename
+assets/content/homepage.md:3:7: error: duplicate `type: homepage` note, also declared by assets/content/Landing.md; a package has one front page, at /sohl/, and every homepage is written to the same `_index.md` — so the one the walk reaches last silently overwrites the rest
+```
+
 ### Frontmatter, against the schema its type declares
 
 The same command also checks that each note's `sohl:` block is what its **type**
@@ -512,6 +616,110 @@ does not exist. Removing it was verified output-neutral first: across 1,735
 stripped notes, `package compile` produced byte-identical `build/packs-json` and
 the site build byte-identical `site/content`.
 
+### The homepage carries no address of its own
+
+A note's URL derives from `name.full` and its identity from
+`(type, shortcode)`. The homepage is the one page for which neither holds: it
+publishes at `/<package>/`, fixed by the package id. So `content-build lint`
+**refuses** `name`, `shortcode` and `id` on a `type: homepage` note (#53) rather
+than ignoring them — an author fluent in the conventions writes them here
+expecting exactly what they do everywhere else, and gets none of it.
+
+They were never inert, which is why ignoring them was the wrong answer. A
+`shortcode` puts the note in the address index and in the `dataview` link
+universe, so `[[homepage-<shortcode>]]` resolves _green_ — to `homepage/<slug>/`,
+an address derived from `name.full` that the site build never writes, because a
+homepage goes to `_index.md` at the package root. A build reporting a live link
+to a 404 is worse than one saying nothing. It also inflates this command's own
+address tally, so the lint and the link manifest disagree about what the package
+publishes: SoHL's tree reports `1607 address(es) across 1607 note(s)` with a
+`shortcode` on its landing and `1606 address(es) across 1607 note(s)` without
+one. That is one defect, not two — the tally is only ever printed on a clean run,
+so refusing the field is what makes the count honest.
+
+Each finding is located at the offending key and says what the field would have
+decided, not merely that it does not belong:
+
+```text
+assets/content/homepage.md:26:1: error: `shortcode` decides nothing on a `type: homepage` note: this page's address is the package's own, `/<package>/`, fixed by the package id. It is not ignored either — it puts the note in the address index, so `[[homepage-<shortcode>]]` resolves to a page the site build never writes. Delete it
+assets/content/homepage.md:28:1: error: `name` decides nothing on a `type: homepage` note: a page's slug derives from `name.full`, and a homepage's destination is fixed — it is written to `_index.md` at the package's own address, `/<package>/`. Write `title:` for what the page is called, and delete `name`
+```
+
+**A named class, not an allow-list.** The documented envelope is `type` plus an
+optional `title`, with `landing`, `description` and `banner` legitimate beside
+them — but an unknown top-level key is **not** refused, and that boundary is the
+decision rather than an omission. A homepage's frontmatter is emitted into the
+published page, so an unrecognised key is a Hugo or theme parameter this build
+has never heard of and has no standing to reject; a closed list would make every
+new theme parameter wait on a package-build release. What is refused is the
+specific class that makes a false claim about _where this page is_. `aliases` is
+not in that class either: it is already dropped from every emitted page, so
+authoring one here is the same no-op it is anywhere else.
+
+**Where it fires: `content-build lint` only.** Unlike a rule about the shape of
+the _tree_, which the site build has its own reason to gate on, this is a
+_frontmatter-schema_ rule and `content-build site` runs none of them — wiring in one type's field
+rule would have the site build refuse `shortcode` on a homepage while accepting
+`weight: heavy` on a weapon. The gap that leaves is `HarnMaster-3-FoundryVTT`,
+which runs no `content-build lint` at all and so receives no frontmatter finding
+of any kind; that is a missing script in that repository, not a rule to duplicate
+one at a time.
+
+### The homepage's own links
+
+The homepage is the page a reader arrives at, and until #54 it was the one page
+nothing checked. SoHL's landing pointed at `kb/creature/` and `kb/character/`
+from the day those two types merged into `being` — two 404s on the package's
+front page, through every build, because a landing's links went through no
+checker at all.
+
+`links` therefore audits a `type: homepage` note as well, and it reads **both**
+halves of it. Of the six homepages authored today four carry every link in the
+body as ordinary markdown and two carry them in `landing:` — and the one whose
+dead links prompted this has an _empty body_. A dead link in a card is exactly
+as broken as one in a paragraph, so `landing.install.url`, every
+`cards…​.url` / `.href`, the markdown links inside the prose fields (`lead`,
+`closing`, `install.intro`, `install.note`, a card's `description`, a link's
+`note`) and the body's own markdown links are all read.
+
+**`url` and `href` are not the same address and are not checked the same way.**
+The theme resolves a `url` against the site with `relURL`, so a package writes
+`kb/rules/` and is served `/sohl/kb/rules/` without naming its own prefix; an
+`href` is an address that is _already_ resolved and is used verbatim, which is
+what `cards.source: sections` fills in. A leading `/` is therefore a defect in a
+`url` — Hugo prefixes it a second time — and correct in an `href`.
+
+Four findings, and each one names the form to write instead:
+
+| Finding                      | Why                                                                               |
+| ---------------------------- | --------------------------------------------------------------------------------- |
+| A **retired content type**   | `kb/creature/` when `creature` became `being`. The engine knows what was retired. |
+| A **hardcoded absolute URL** | Into this package's own prefix, or into one a vendored manifest names.            |
+| A **root-relative `url:`**   | `relURL` prefixes it again. `href:` is exempt — verbatim is what it means.        |
+| A **wikilink**               | Nothing resolves one here: a homepage is published verbatim in every mode.        |
+
+That last one is why a homepage does **not** get the wikilink resolution every
+other note body gets. In `homepage` mode the content tree is never walked, so
+there is no index for a wikilink to resolve against — and giving the page one
+would make the mode depend on exactly the machinery its licensing fence exists
+to not build. So a landing addresses the web the way the web does, and a
+wikilink on one is reported rather than resolved.
+
+**What is checkable, and what is not.** Only an address into this site is, and
+only against facts the build already holds — the retired-type table and the
+package prefixes a vendored manifest names. Two things are deliberately not
+attempted:
+
+- **Whether an external URL answers.** There is no network at build time, and a
+  build must not go red because a third party is down.
+- **Whether a live in-site address names a page that exists.** Several surfaces
+  a landing routes to are produced by other tools entirely — generated API
+  documentation, hand-authored Hugo sections — so this build does not hold the
+  set of published pages and would report a working link as dead. A bare
+  `https://www.heroiclands.org/<package>/` is left alone for the same reason it
+  cannot be improved: a package homepage is in no link manifest, so there is no
+  better form to write.
+
 ## Prose: formatting and markdown
 
 ```bash
@@ -676,6 +884,10 @@ title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.t
 What the module is, which system it needs, how to install it.
 ```
 
+A package declares **exactly one** of these, and both `content-build lint` and
+`content-build site` require it — see
+[Exactly one homepage](#exactly-one-homepage).
+
 That is the whole envelope. A homepage **compiles into no compendium
 document**, appears in no pack and in no link manifest, and is addressed by the
 _package_ rather than by its own name — so `name.full`, `shortcode` and `id`
@@ -740,7 +952,10 @@ site:
   trees:
     - { from: kb/dev-docs, section: dev-docs }
   sections:
-    being: { title: Beings, banner: banners/creature.webp }
+    being:
+      title: Beings
+      banner: banners/creature.webp
+      description: Folk, animals and the things that walk the world.
   readmeSections:
     dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
 ```
@@ -750,7 +965,7 @@ site:
 | `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
-| `sections`         | Landing title and hero per section, so a landing matches the card that links to it.              |
+| `sections`         | What each section says about itself on its landing — see below.                                  |
 | `readmeSections`   | The same, for a section whose landing comes from a `README`.                                     |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.     |
 | `backfillSections` | Write a bare `_index.md` for any other section directly under the mount.                         |
@@ -758,6 +973,42 @@ site:
 | `pass`             | A named bundle of this repository's own body rewrites.                                           |
 | `passOptions`      | That bundle's options.                                                                           |
 
+### What a section may declare
+
+A generated section landing is the **only** place a section can describe itself.
+A content package authors no `_index.md` for `weapongear` or `affliction`, so
+the file the theme reads is the one this build writes from `sections` — and
+whatever that entry may carry is the whole of what the section can say.
+
+| Key           | Required | What it does                                                              |
+| ------------- | -------- | ------------------------------------------------------------------------- |
+| `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
+| `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
+| `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
+
+`readmeSections` takes the same three, for a section whose landing comes from a
+`README` rather than from nothing. What the section declares wins over what the
+`README` happens to carry — the landing has to match the card that links to it.
+
+**The vocabulary is closed, and a key outside it is refused by name:**
+
+```text
+package-build config: `site.sections.affliction.descrption` is not a
+recognized option (expected one of: title, banner, description).
+```
+
+That refusal is the point. `landing` is passed through unvalidated because it is
+written once, for the mount, in one landing template's own vocabulary. A section
+entry is written fourteen to twenty times per build against a contract every
+package and every section shares, so an unbounded one would let a mistyped
+`descrption:` publish into front matter, be read by nobody, and say nothing to
+anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
+buys a build that cannot quietly emit a key no theme reads.
+
+The **writers** name no keys: a section's `_index.md` is whatever the entry
+resolved to, `title` first. So extending the vocabulary is a change to the
+schema alone, and the two can no longer drift apart.
+
 ### Why `out` is required
 
 The output tree is a build artifact and is **deleted on every run**, so that a
@@ -778,6 +1029,16 @@ rewrites repository-relative links in the developer docs to their published or
 GitHub addresses. Neither rewrite can fail a build; an unknown `{@link}` degrades
 to a code span.
 
+`symbolMap` is resolved **against the repository root**, not the process cwd, so
+`content-build site` reads the same map whatever directory it was invoked from.
+Leaving it unset is the legitimate empty case — every `{@link}` degrades, and
+nothing is reported. Setting it to a path that cannot be read, cannot be parsed,
+or does not hold a name → page object **fails the build**, naming the file and
+the reason: those were all indistinguishable from "no symbols" until #75, so a
+site could publish 224 dead `{@link}` tags at exit 0. A map that is read reports
+its symbol count at info level, which is the only way to tell a map that loaded
+from one that loaded empty without reading the emitted HTML.
+
 A bundle supplies up to two hooks, and their order around the shared work is the
 point:
 
@@ -808,6 +1069,72 @@ None of them exits the process from inside the library; the command decides. Tha
 is what makes them testable, which the consumer scripts' inline `process.exit`
 calls were not.
 
+## Diffing published addresses
+
+```bash
+gh release download v0.8.2 -p system.zip -D build/baseline
+npx content-build addresses diff --from build/baseline/system.zip
+npx content-build addresses diff --from build/baseline/system.zip --strict
+```
+
+A package's `(type, shortcode)` addresses are a **published interface**. Every
+satellite declaring `itemCatalog: true` assembles its beings out of them —
+`attribute:str`, `skill:awar`, `weapongear:Tabri` — resolving each against the
+Item packs of the release its `compatibility.verified` pins. Renaming a
+shortcode is therefore a breaking change to something other repositories
+consume, and it used to cost nothing and produce no signal: the check that got
+made was a repository-local grep, which cannot see the other repositories and
+reports the reassuring answer.
+
+`sohl` renamed one weapon's shortcode from `Tabri` to `Taburi` two days after
+the `v0.8.2` tag, on the stated ground that "nothing referenced the old value".
+True of that repository. Both satellites pin `v0.8.2` and address
+`weapongear:Tabri` on their copy of the same character — five lookups that
+resolve today and fail the moment either pin moves, reporting a missing item.
+
+**A rename is told from a removal by the document id, and that is an identity
+match rather than an inference.** A note authors its `_id` in frontmatter; it is
+not derived from the shortcode, so it survives a rename. An address that
+disappeared while its document is still published elsewhere _is_ a rename:
+
+```text
+assets/content/Weapons/Melee/Taburi.md:12:1: warning: since sohl@0.8.2, weapongear:Tabri is no longer published; the same document (s5D6QJbw7ZbETxdN) is now published as weapongear:Taburi. Every package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
+```
+
+Where the id is published under no address at all, that is all it says —
+**withdrawn**, with no successor named. A split, a deletion and a merge are
+indistinguishable at that point, and a "did you mean" guessed from string
+similarity would be worse than silence, because a wrong one sends the reader to
+the wrong fix.
+
+| Finding     | What it means                                            | Severity                                |
+| ----------- | -------------------------------------------------------- | --------------------------------------- |
+| `renamed`   | Address gone; the same document publishes under another. | `warning` — legitimate, but not silent  |
+| `withdrawn` | Address gone; its document publishes under none.         | `warning` — retiring content is allowed |
+
+Neither fails a build. Retiring content is legitimate, and so is renaming — the
+shortcode charset rule forces some. What a rename must not do is happen without
+anyone noticing. `--strict` reports both as errors and exits non-zero, for a
+release workflow that wants a gate.
+
+**A finding is placed against the note, not the pack it was read from.** The
+address space is read from compiled output because that is what actually ships;
+the content tree is read only to find the note carrying the id, so the reader
+lands on the `shortcode:` line they just edited. A withdrawal has no such note,
+so it degrades to the baseline document — and where neither is readable the
+position is dropped rather than guessed.
+
+**The baseline is named, never derived, and never downloaded.** `--from` takes
+the artifact for the same reason `deps fetch --from` does: a command that
+reaches the network on its own is not reproducible and fails strangely offline.
+A baseline that yields **no** addressable item is refused rather than read as
+"nothing changed" — it would report a clean result for every possible input,
+which is the one failure a check like this can never catch.
+
+Item packs only, because that is the address space consumers resolve against: a
+being's embedded items are the only cross-package resolution by
+`(type, shortcode)`.
+
 ## Diagnostics
 
 Every warning or error a build reports **about a content note** is emitted in the

package/MIGRATING.md

@@ -1,3 +1,44 @@
+# Migrating to `@heroiclands/package-build` 6.0.0
+
+**No configuration change to make, and one build check that may now fail.**
+`packageBuild.manifest.packFolders` is compared against the `packs[]` the build
+derives, and a folder naming a pack the package does not ship is an error.
+
+## 1. Check what `package-build manifest` says
+
+Nothing to edit up front — run it, and the build names anything wrong:
+
+```text
+package-build.config.yaml:164:23: error: packFolders: folder "HârnMaster 3 System" names pack "character", which this package does not ship (packs: items, system-help)
+```
+
+Every name in a folder's `packs` must appear in the top-level `packs:` list —
+companions included, since Foundry sees no difference. Delete a name that no
+longer resolves, or correct it. An error stops the manifest being written, so
+nothing half-right reaches the stage.
+
+## 2. The advisory needs no action
+
+A pack no folder names is a **warning**, and the build continues:
+
+```text
+package-build.config.yaml:162:13: warning: packFolders: pack "items" is named by no folder, so it ships outside every folder this package declares
+```
+
+Shipping one pack at the root can be deliberate, so this is not an error. But a
+package that bothered to declare a folder rarely meant to leave one out — that
+is exactly how `HarnMaster-3-FoundryVTT` shipped 1,577 of 1,597 documents loose
+beside its folder. Add the pack to a folder, or leave it and take the advisory.
+
+A package that declares no `packFolders` at all is unaffected, and says nothing.
+
+## 3. Nothing else
+
+- **No configuration key changed**, and no CLI command, flag or exit code beyond
+  `manifest` failing on the error above.
+- `writeManifest` takes an optional `configFile`, so a finding names the line it
+  is about. Omitting it costs the position, not the finding.
+
 # Migrating to `@heroiclands/package-build` 5.0.0
 
 **One configuration change: `publish.site` is a mode, not a boolean.** And one

package/README.md

@@ -255,6 +255,36 @@ comes from.
 a companion is only a pack written by another pass rather than one of its own.
 Give each pack the `label` you want Foundry to show.
 
+#### `packFolders` is checked against the packs you ship
+
+`packFolders` is the one **declared** key that names something the build
+**derives**. Every other declared key states a fact about the package (`title`,
+`socket`, `grid`) or addresses a staged file (`esmodules`, `styles`,
+`languages`) — a staged file being a different relation, answered against the
+stage rather than against configuration. So it is the one place a declaration
+can quietly go stale against a value the build already computed, and it did:
+`HarnMaster-3-FoundryVTT` shipped a folder naming four packs, three of which had
+not existed since its compendium was consolidated, while `items` — 1,577 of
+1,597 documents — sat in no folder at all, with the build reporting nothing.
+
+`package-build manifest` now compares the two, descending through nested folders
+(Foundry allows three levels), and reports in the usual
+`file:line:column: severity: message` form:
+
+| Finding                                         | Severity    | Why                                                                                                                 |
+| ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| a folder names a pack the package does not ship | **error**   | Foundry silently skips a name it cannot resolve, so the declaration does nothing; no arrangement intends it         |
+| a pack no folder names                          | **warning** | legal, and a root-level pack can be deliberate — but a package that declared a folder rarely meant to leave one out |
+| no `packFolders` declared at all                | nothing     | everything at the root is an arrangement, not an omission                                                           |
+
+An error **stops the write**: a manifest already known to describe packs that do
+not exist should not reach the stage, where the next command would deploy it.
+
+```text
+package-build.config.yaml:164:23: error: packFolders: folder "HârnMaster 3 System" names pack "character", which this package does not ship (packs: items, system-help)
+package-build.config.yaml:162:13: warning: packFolders: pack "items" is named by no folder, so it ships outside every folder this package declares
+```
+
 `compatibility` and `relationships` are read from the **top level** of the
 shared configuration, not from this section — content-build consumes them
 (`supportedCoreVersion`, and a module'''s `stats.systemVersion`) and the