@heroiclands/package-build 22.15.1 → 22.16.0

package/docs/configuration.md

@@ -1,3 +1,10 @@
+---
+shortcode: configuration
+name: { full: "Configuration" }
+type: doc
+subType: reference
+---
+
 ## Configuration: `package-build.config.yaml`, key by key
 
 Every repository built by `@heroiclands/package-build` declares itself in one
@@ -7,8 +14,8 @@ validates the object, fills every optional key with its default, and returns a
 deeply frozen copy. It performs no I/O and knows nothing about any particular
 package's content — the configuration is data, and the compilers read it.
 
-The reserved `packageBuild:` section belongs to the packaging half of the
-toolchain and is validated separately, by `resolvePackageBuildConfig` in
+The reserved `packageBuild:` section holds packaging settings and is validated
+by `resolvePackageBuildConfig` in
 `config.mjs`. `content-config.mjs` checks only that the section is a mapping
 and hands it back frozen; its own key-by-key reference is
 [below](#the-packagebuild-section).
@@ -54,29 +61,29 @@ alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
 authoring.
 
-| Key                                         | Type                                                                       | Required                                                                                           | Default                                     |
-| ------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| [`contentPackage`](#contentpackage)         | string                                                                     | yes                                                                                                | —                                           |
-| [`foundryPackage`](#foundrypackage)         | string                                                                     | yes (`.mjs` only — derived in YAML); refused in a `documentation` package                          | —                                           |
-| [`homepage`](#homepage)                     | string                                                                     | no (`.mjs` only — derived in YAML)                                                                 | `null`                                      |
-| [`author`](#author)                         | string, or `{name, email?, url?}`                                          | no (`.mjs` only — derived in YAML)                                                                 | `null`                                      |
-| [`packageKind`](#packagekind)               | `"systems"` \| `"modules"` \| `"documentation"`                            | yes                                                                                                | —                                           |
-| [`stats`](#stats)                           | object                                                                     | yes; refused in a `documentation` package                                                          | —                                           |
-| [`itemBuilders`](#itembuilders)             | object, or list of `{system, builders}` (or a name/list of names, in YAML) | no; refused in a `documentation` package                                                           | `{}`                                        |
-| [`paths`](#paths)                           | object                                                                     | no                                                                                                 | see [`paths`](#paths)                       |
-| [`skipDirectories`](#skipdirectories)       | string[]                                                                   | no                                                                                                 | `[]`                                        |
-| [`icons`](#icons)                           | object, or a path to a file holding one                                    | no                                                                                                 | empty registry                              |
-| [`packs`](#packs)                           | array                                                                      | yes, at least one entry, in a `systems` or `modules` package; refused in a `documentation` package | —                                           |
-| [`docs`](#docs)                             | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
-| [`site`](#site)                             | object                                                                     | no                                                                                                 | see [`site`](#site)                         |
-| [`pdf`](#pdf)                               | object                                                                     | no                                                                                                 | `null`                                      |
-| [`compatibility`](#compatibility)           | object                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
-| [`relationships`](#relationships)           | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
-| [`systems`](#systems)                       | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                                        |
-| [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
-| [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                                        |
-| [`publish`](#publish)                       | object                                                                     | no; **required**, with `site: content`, in a `documentation` package                               | `{site: "homepage", address: {prefix: ""}}` |
-| [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`                            |
+| Key                                         | Type                                                                       | Required                                                                                           | Default                   |
+| ------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------- |
+| [`contentPackage`](#contentpackage)         | string                                                                     | yes                                                                                                | —                         |
+| [`foundryPackage`](#foundrypackage)         | string                                                                     | yes (`.mjs` only — derived in YAML); refused in a `documentation` package                          | —                         |
+| [`homepage`](#homepage)                     | string                                                                     | no (`.mjs` only — derived in YAML)                                                                 | `null`                    |
+| [`author`](#author)                         | string, or `{name, email?, url?}`                                          | no (`.mjs` only — derived in YAML)                                                                 | `null`                    |
+| [`packageKind`](#packagekind)               | `"systems"` \| `"modules"` \| `"documentation"`                            | yes                                                                                                | —                         |
+| [`stats`](#stats)                           | object                                                                     | yes; refused in a `documentation` package                                                          | —                         |
+| [`itemBuilders`](#itembuilders)             | object, or list of `{system, builders}` (or a name/list of names, in YAML) | no; refused in a `documentation` package                                                           | `{}`                      |
+| [`paths`](#paths)                           | object                                                                     | no                                                                                                 | see [`paths`](#paths)     |
+| [`skipDirectories`](#skipdirectories)       | string[]                                                                   | no                                                                                                 | `[]`                      |
+| [`icons`](#icons)                           | object, or a path to a file holding one                                    | no                                                                                                 | empty registry            |
+| [`packs`](#packs)                           | array                                                                      | yes, at least one entry, in a `systems` or `modules` package; refused in a `documentation` package | —                         |
+| [`docs`](#docs)                             | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
+| [`site`](#site)                             | object                                                                     | no                                                                                                 | see [`site`](#site)       |
+| [`pdf`](#pdf)                               | object                                                                     | no                                                                                                 | `null`                    |
+| [`compatibility`](#compatibility)           | object                                                                     | no; refused in a `documentation` package                                                           | `null`                    |
+| [`relationships`](#relationships)           | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
+| [`systems`](#systems)                       | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
+| [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                    |
+| [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                      |
+| [`publish`](#publish)                       | object                                                                     | no                                                                                                 | `{address: {prefix: ""}}` |
+| [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`          |
 
 Any key outside this list is refused:
 
@@ -170,7 +177,7 @@ declares none.
 `homepage` is not itself checked against `contentPackage` by `defineConfig`.
 `checkHomepage` in `config.mjs` is the check: `homepage` is required
 unconditionally — every package publishes a site — and must be an absolute
-URL whose path ends `/<contentPackage>/`. `content-build site` makes it
+URL whose path ends `/<contentPackage>/`. `package-build site` makes it
 before the generated `baseURL` is written, so a missing or mismatched
 `homepage` is a finding on every site build:
 
@@ -352,7 +359,7 @@ optional (either of npm's forms) in an `.mjs` one.
 
 Which kind of package this repository builds. `systems` and `modules` are the
 two Foundry answers — also the directory Foundry installs the package under,
-and what `assetRoot` and the packaging half's `artifact` (`system` or
+and what `assetRoot` and the release `artifact` (`system` or
 `module`) are derived from. `documentation` is the answer "not a Foundry
 package at all": it publishes a site and a book from its notes, installs into
 no Foundry data directory and compiles no compendium.
@@ -596,7 +603,7 @@ Every icon name is checked against the charset a note may write between the
 colons — lowercase letters, digits and hyphens, the same charset an address
 segment uses:
 
-> ``package-build config: `icons.icons.Bad_Name` is not a name a note can write — `:icon-…:` takes lowercase letters, digits and hyphens, the charset an address segment uses.``
+> ``package-build config: `icons.icons.Bad_Name` is not a name a note can write — `:icon …:` takes lowercase letters, digits and hyphens, the charset an address segment uses.``
 
 `defaultFamily`, if set, must name a family the registry actually declares:
 
@@ -641,8 +648,27 @@ packs:
 | `packs[].prebuilt`    | string (directory)                                                    | no       | `null`                                  |
 | `packs[].system`      | string                                                                | no       | `null` — falls back to `stats.systemId` |
 
+`private: true` restricts a Foundry compendium to GMs. A note tagged `gm`
+compiles only into private packs. Set `data.pack` to a private pack for the
+note's own document. A note that also creates a JournalEntry needs one private
+JournalEntry pack; the derived entry routes there automatically when the
+ordinary JournalEntry default is public.
+
 `packs` itself:
 
+The list's order is the order shown in the Foundry manifest. Compilation
+orders its passes by what each compiler reads: for example, Item packs run
+before an Actor pack that embeds their Items, regardless of their positions
+in this list. A run restricted to `package-build package compile <name>`
+requires any pack whose compiled output it reads to be included in the run
+or already present under `build/packs-json/`. If that output is absent, the
+command names the required pack and asks for a whole-package compile or for
+that pack to be compiled first.
+
+`packs[].ownership` is not a pack-spec key. The configuration rejects it;
+neither the compiled pack nor the manifest receives an ownership value from
+this list.
+
 > ``package-build config: `packs` must be an array.``
 
 A package may declare **no** packs. A module that ships assets and compiles
@@ -724,7 +750,7 @@ How this repository frames the documentation pages it generates.
 > ``package-build config: `docs.<key>` is not a recognized option (expected one of: itemFields).``
 
 `docs.itemFields` frames the item-frontmatter reference rendered by
-`content-build docs item-fields` — the tables come from the `itemBuilders`
+`package-build docs item-fields` — the tables come from the `itemBuilders`
 registry and are the same wherever rendered; everything here is the
 consumer's: heading, orientation, where the page is filed.
 
@@ -747,7 +773,7 @@ consumer's: heading, orientation, where the page is filed.
 > ``package-build config: `docs.itemFields.preamble[<index>]` must be a string.``
 
 `frontmatter` is deep-merged over the note envelope written when `out` is
-under the content tree — see [`content-build docs item-fields`](commands.md#content-build-docs-item-fields):
+under the content tree — see [`package-build docs item-fields`](commands.md#package-build-docs-item-fields):
 
 > ``package-build config: `docs.itemFields.frontmatter` must be a mapping.``
 
@@ -759,21 +785,22 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                | Type     | Default                                     |
-| ------------------ | -------- | ------------------------------------------- |
-| `site.base`        | string   | `""`                                        |
-| `site.assets`      | string   | `""`, but required for `content-build site` |
-| `site.description` | string   | `""`, but required for `content-build site` |
-| `site.packages`    | string[] | `[]`                                        |
-| `site.pass`        | string   | `""`                                        |
-| `site.passOptions` | object   | `{}`                                        |
-| `site.notfound`    | object   | `null`                                      |
-| `site.hugo`        | object   | `{}`                                        |
-| `site.search`      | boolean  | `true`                                      |
-| `site.maps`        | boolean  | `true`                                      |
-
-How much of a package reaches the web at all is **not** here — it is
-[`publish.site`](#publish). `site` is framing: which named pass bundle
+| Key                | Type     | Default                                      |
+| ------------------ | -------- | -------------------------------------------- |
+| `site.base`        | string   | `""`                                         |
+| `site.title`       | string   | `""`, required when no manifest title exists |
+| `site.assets`      | string   | `""`, but required for `package-build site`  |
+| `site.description` | string   | `""`, but required for `package-build site`  |
+| `site.packages`    | string[] | `[]`                                         |
+| `site.pass`        | string   | `""`                                         |
+| `site.passOptions` | object   | `{}`                                         |
+| `site.notfound`    | object   | `null`                                       |
+| `site.hugo`        | object   | `{}`                                         |
+| `site.search`      | boolean  | `true`                                       |
+| `site.maps`        | boolean  | `true`                                       |
+
+The authored content tree determines which pages reach the web. `site` is
+framing: which named pass bundle
 supplies the repository's own body rewrites, and the residue of the
 [generated Hugo configuration](#the-generated-hugo-configuration) that is
 genuinely this repository's own.
@@ -810,7 +837,7 @@ listing renders is a content table's to say:
 
 > ``package-build config: `site.list` is retired — a site is its homepage and its pages, and any index between them is a `doc` note: write one with `type: doc`, a `shortcode` and `pack: none`, carrying a content table over the notes it lists, and link it from the homepage. Nothing is generated between the homepage and the pages, so delete the key.``
 
-Where the Hugo tree is written is not a choice. `content-build site` writes
+Where the Hugo tree is written is not a choice. `package-build site` writes
 the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
 the content mount at `build/hugo/content/`, Hugo's own cache — as a sibling
 of the deployment root `build/site/`, so nothing Hugo reads lands in what is
@@ -833,7 +860,7 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
-`content-build site` refuses to generate a configuration with no
+`package-build site` refuses to generate a configuration with no
 `site.assets` at all — there is no defensible default, because the theme
 resolves every relative asset against it:
 
@@ -844,11 +871,14 @@ The generated Hugo configuration carries the same host as
 The two are one value read by two readers: the toolchain emits it into a
 page, and the theme joins it onto anything the toolchain left relative.
 
+`site.title` gives a documentation package its website title. For a Foundry
+package, the site reads `packageBuild.manifest.title` when `site.title` is
+absent.
+
 `site.description` is the site's `<meta name="description">` — one plain
 sentence, distinct from the Foundry package browser's pitch
 ([`packageBuild.manifest.descriptionHtml`](#packagebuildmanifest), which
-allows HTML). Required for `content-build site`, the way `packageBuild.manifest.title`
-is:
+allows HTML). Required for `package-build site`, the way its title is:
 
 > ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
 
@@ -952,7 +982,7 @@ site:
 > ``package-build config: `site.search` must be a boolean.``
 
 `site.maps` is whether every place page carries the map from that place. On
-by default: `content-build site` draws the map `content-build map --from`
+by default: `package-build site` draws the map `package-build map --from`
 draws — the place's borders and routes, each neighbour at its bearing — for
 every place that states a border or a route or is named in one, lays it beside
 the page as `from-<shortcode>.svg`, and names the file in the page's front
@@ -970,13 +1000,13 @@ site:
 
 ### The generated Hugo configuration
 
-`content-build site` writes `build/hugo/hugo.toml` on every run. Every value
+`package-build site` writes `build/hugo/hugo.toml` on every run. Every value
 in it has one source, and that source is where it is edited:
 
 | Key                               | Derived from                                                                                                                                            |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `baseURL`                         | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                     |
-| `title`                           | `packageBuild.manifest.title`, which is required                                                                                                        |
+| `title`                           | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                     |
 | `locale`                          | the organisation's locale, `en-us`, in `engine/site-config.mjs`                                                                                         |
 | `publishDir`                      | `contentPackage`, under the deployment root `build/site` — written relative to `build/hugo/`, so `../site/<contentPackage>`                             |
 | `contentDir`                      | the fixed content mount, `build/hugo/content` — written as `content`                                                                                    |
@@ -991,21 +1021,20 @@ in it has one source, and that source is where it is edited:
 | `params.brand`                    | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                       |
 | `params.notfound`                 | `site.notfound`; absent when undeclared                                                                                                                 |
 | `markup.goldmark.renderer.unsafe` | the toolchain, whose pages carry raw HTML — a `<figure>` for every image, a `<span>` marking an unresolved link                                         |
-| `menu`                            | the navigation `content-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as `parent` entries |
+| `menu`                            | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as `parent` entries |
 
 The site build reads the navigation from the cache only. A cold cache is an
 error naming the command that fills it:
 
-> `the site navigation has not been fetched. Run `content-build deps fetch` first.`
+> `the site navigation has not been fetched. Run `package-build deps fetch` first.`
 
 A missing theme names the package to install:
 
 > `@heroiclands/hugo-theme is not installed anywhere above <rootDir> — add it to `devDependencies`and run`npm ci``
 
-And a site's title reads from the manifest's, so a configuration declaring
-none fails the site build:
+The site needs a title from `site.title` or the package manifest:
 
-> ``package-build config: `packageBuild.manifest.title` is not declared, and the site's `title` reads from it.``
+> ``package-build config: declare `site.title` or `packageBuild.manifest.title` for the site's title.``
 
 `params.description` reads from `site.description` the same way, and fails
 the same way when it is absent:
@@ -1034,9 +1063,8 @@ The content tree published as a book — a **selection**, not a rendering of
 everything: `pdf.document` names the tree that says which notes the volume
 carries and in what order, parsed by `engine/pdf-toc.mjs`'s
 `parseDocumentTree` and not validated here. Whether a book is built at all
-is [`publish.site`](#publish), the same switch that gates the website —
-`content` builds one, `homepage` does not, so a package cannot end up with
-two switches that disagree about whether it publishes its content tree.
+determined by the authored content tree: a tree containing only a homepage has
+no content pages for a book.
 
 Each selected place with a border or route receives a dedicated full-page
 vector itinerary after its entry. A selected authored regional SVG map also
@@ -1113,7 +1141,7 @@ Any other key on `pdf` is refused:
 
 ### `compatibility`
 
-**Type:** object · **Optional** · default `null`. Refused in a
+**Type:** object · **Required for Foundry packages**. Refused in a
 `documentation` package, which installs into no Foundry data directory and so
 has no Foundry core range to support:
 
@@ -1132,23 +1160,22 @@ aspiration.
 compatibility: { minimum: "14.359", verified: "14.364" }
 ```
 
-| Key                      | Type   | Required                               | Default |
-| ------------------------ | ------ | -------------------------------------- | ------- |
-| `compatibility.minimum`  | string | yes, once `compatibility:` is declared | —       |
-| `compatibility.verified` | string | no                                     | none    |
+| Key                      | Type   | Required                 | Default |
+| ------------------------ | ------ | ------------------------ | ------- |
+| `compatibility.minimum`  | string | yes for Foundry packages | —       |
+| `compatibility.verified` | string | no                       | none    |
 
 > ``package-build config: `compatibility` must be a mapping.``
 
 > ``package-build config: `compatibility.minimum` must be a non-empty string.``
 
-> ``package-build config: `compatibility.<key>` is not a recognized option (expected one of: minimum, verified).``
+> ``package-build config: `compatibility.minimum` is required for a Foundry package.``
 
-`compatibility` itself is optional at this validation layer — absent for a
-content-only consumer, which has none to invent — but a repository that
-compiles any pack needs one in practice: reading the floor throws, at
-compile time rather than at configuration time, without it:
+> ``package-build config: `compatibility.<key>` is not a recognized option (expected one of: minimum, verified).``
 
-> ``package-build: the configuration declares no `compatibility.minimum`, so compiled documents have no honest core version to stamp. Declare it at the top level of package-build.config.yaml.``
+`compatibility` belongs to every `systems` or `modules` package, including a
+module that ships only assets. A `documentation` package declares none because
+it installs no Foundry package and stamps no documents.
 
 ### `relationships`
 
@@ -1199,8 +1226,8 @@ Each entry, in any of the four lists:
 
 `contentPackage` names what the other package's _content_ is called, where
 that differs from its Foundry id. A note addresses a file by the content
-package that owns it — `thalorna/assets/images/map.webp` — and the Foundry id
-(`sohl-thalorna`) appears only in the install path that pathname resolves to.
+package that owns it — `harnensemble/assets/images/map.webp` — and the Foundry id
+(`harn-ensemble`) appears only in the install path that pathname resolves to.
 Omit it where the two are the same word, which they are for every system:
 
 > ``package-build config: `relationships.<kind>[<index>].contentPackage` must be a non-empty string.``
@@ -1224,6 +1251,11 @@ this tree never cites — so `deps fetch` fetches nothing for it and a wikilink
 into it fails, naming the key, rather than resolving against a stale
 declaration or an index nobody fetched:
 
+Run `package-build deps fetch` before compiling content that addresses a
+declared dependency's notes or embeds its Items. Compilation reads the cached
+index and Item catalogue for the declared version; it does not fetch them on
+demand.
+
 > ``package-build config: `relationships.<kind>[<index>].contentIndex` must be true or false.``
 
 > ``package-build config: `relationships.<kind>[<index>].contentIndex` cannot be false together with `itemCatalog: true` — a catalogue is fetched from the same index.``
@@ -1311,46 +1343,28 @@ mapping:
 
 ### `publish`
 
-**Type:** object · **Optional** for a `systems` or `modules` package, default
-`{site: "homepage", address: {prefix: ""}}`. **Required** for a
-`documentation` package, with `site: content` — publishing the content tree is
-the whole of what that kind does:
-
-> ``package-build config: `publish` is required in a `documentation` package: publishing the content tree is the whole of what it does. Write `publish: {site: content}`.``
+**Type:** object · **Optional** · default `{address: {prefix: ""}}`.
 
-> ``package-build config: `publish.site` must be `content` in a `documentation` package — `homepage` fences the content surfaces off, and a package that compiles nothing and publishes nothing from its tree would produce a single authored page and no book.``
+`publish.address` controls where content-page addresses mount inside the
+package. The content tree determines which pages are published.
 
-Publishing switches — how much of this package reaches the web, and where
-its content tree's addresses mount inside the package.
-
-| Key                      | Type                        | Required | Default        |
-| ------------------------ | --------------------------- | -------- | -------------- |
-| `publish.site`           | `"homepage"` \| `"content"` | no       | `"homepage"`   |
-| `publish.address`        | object                      | no       | `{prefix: ""}` |
-| `publish.address.prefix` | string                      | no       | `""`           |
+| Key                      | Type   | Required | Default        |
+| ------------------------ | ------ | -------- | -------------- |
+| `publish.address`        | object | no       | `{prefix: ""}` |
+| `publish.address.prefix` | string | no       | `""`           |
 
 > ``package-build config: `publish` must be an object.``
 
-> ``package-build config: `publish.<key>` is not a recognized option (expected one of: site, address).``
-
-Every HeroicLands package publishes at least an authored homepage at
-`https://www.heroiclands.org/<contentPackage>/` — there is no value meaning
-_no web presence at all_. `homepage` is the floor: the authored homepage
-and nothing else, no content-tree walk. `content` is the homepage plus every
-page the content tree publishes. `publishesContentPages(config)`, exported from
-`content-config.mjs` alongside [`compilesFoundryDocuments`](#packagekind),
-answers the one question every reader of the mode actually asks — the site
-build, to decide whether to walk the tree at all, and the content index, to
-decide whether an entry carries a web `path`. It returns
-`config.publish.site === "content"`.
-
-This was a boolean before `5.0.0`, and both spellings are refused rather
-than silently mapped, because a value reinterpreted reads to its author as
-though it still means what it said:
+> ``package-build config: `publish.<key>` is not a recognized option (expected one of: address).``
 
-> ``package-build config: `publish.site` is no longer a boolean — write `site: content`. Every package publishes an authored homepage at /<contentPackage>/, so no value means "no web presence": `homepage` publishes that page and nothing else, and `content` publishes it plus every page the content tree compiles to.``
+Every HeroicLands package publishes an authored homepage at
+`https://www.heroiclands.org/<contentPackage>/`. Each other publishable note in
+the content tree supplies a content page. `publishesContentPages(config)`,
+exported from `content-config.mjs`, checks that tree for notes beyond the
+homepage. Site, PDF, index, and Foundry address emission use this same answer.
+Remove `publish.site` from package configurations:
 
-> ``package-build config: `publish.site` must be one of homepage, content (got "public").``
+> ``package-build config: `publish.site` is not configured; publishing follows the authored content tree.``
 
 `publish.address.prefix` is where the content tree mounts _inside the
 package_ — `"kb/"` for a repository whose knowledgebase is one surface
@@ -1359,6 +1373,11 @@ end in a slash when set (a missing one would silently fuse the prefix to
 the first section) and must not begin with one (which would make the
 recorded address package-absolute):
 
+The site build uses this prefix for its Hugo source mount. Published note
+addresses and content-index paths stay relative to the package root; the
+manifest's package homepage also stays at that root. A page staged under
+`kb/` can therefore publish at `/<contentPackage>/<type>-<shortcode>/`.
+
 > ``package-build config: `publish.address` must be an object.``
 
 > ``package-build config: `publish.address.prefix` must end in a slash when it is set.``
@@ -1418,13 +1437,10 @@ and [`package-build changelog group`](commands.md#package-build-changelog-group)
 
 ## The `packageBuild` section
 
-Validated by `resolvePackageBuildConfig` in `config.mjs`, not by
-`content-config.mjs`. The two halves split by **input** — the content half
-reads the content tree, this one reads `lang/`, `styles/`, `src/`, the
-assets and the manifest template — and neither validates the other's keys.
-`packageBuild` is an ordinary section of the one configuration file; the
-split exists only to stop one key being checked twice against two
-disagreeing ideas of what it means.
+Validated by `resolvePackageBuildConfig` in `config.mjs`. Content settings
+are validated by `content-config.mjs`; packaging settings live in the
+`packageBuild` section of the same configuration file. Each key has one
+validator.
 
 ```yaml
 packageBuild:
@@ -1441,23 +1457,37 @@ packageBuild:
     envPrefix: SOHL
 ```
 
-| Key                                                                                        | Type                                        | Required | Default                           |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | --------------------------------- |
-| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                     |
-| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                              |
-| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                            |
-| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                              |
-| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                            |
-| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                              |
-| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                     |
-| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                         |
-| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`             |
-| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`  |
-| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}` |
-| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                         |
-| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                         |
-
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e).``
+| Key                                                                                        | Type                                        | Required | Default                                |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | -------------------------------------- |
+| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                          |
+| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                   |
+| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                 |
+| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                   |
+| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                 |
+| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                   |
+| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                          |
+| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                              |
+| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`                  |
+| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`       |
+| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}`      |
+| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                              |
+| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                              |
+| [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8}` |
+
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint).``
+
+### `packageBuild.proseLint`
+
+Optional defaults for [`package-build prose lint`](commands.md#package-build-prose-lint-path).
+`age` is the reader age, `threshold` is the number of readability algorithms
+required to flag a sentence (1–7), and `minWords` is the minimum sentence
+length. Each setting is a positive integer; command-line options can override
+them for one analysis.
+
+```yaml
+packageBuild:
+  proseLint: { age: 21, threshold: 5, minWords: 8 }
+```
 
 ### `packageBuild.stageDir` and `packageBuild.assets`
 
@@ -1489,7 +1519,7 @@ filename, without the extension, as a foreign Address shortcode. `package`
 and `type` are required; `system` defaults to `note`. The relationship with
 that package must provide a content index for the build to check the binding.
 The check reads the cached index, reports an unresolved file as an error, and
-does not fetch during compilation. Run `content-build deps fetch` to fill a
+does not fetch during compilation. Run `package-build deps fetch` to fill a
 cold cache.
 
 ### `packageBuild.assetTransform` and `packageBuild.manifestFlags`
@@ -1506,24 +1536,30 @@ repository has to compute. Neither declares anything, both default to
 
 ### `packageBuild.manifest`
 
+`packageBuild.manifest.title` is a required, non-empty string for a Foundry
+system or module. It is the package name Foundry displays during installation;
+`package-build manifest` refuses to write a manifest without it.
+
 Everything declared here is emitted into the generated manifest unchanged —
 **deliberately not key-checked**, so a key Foundry adds in a later version
-can be declared without waiting on a release of this package. The one rule
-that has a wrong answer rather than an unknown one: a key the build
+can be declared without waiting on a release of this package. A key the build
 **derives** must not also be authored, since the authored value would be
 silently overwritten and the two would be free to disagree with nothing to
 say so.
 
+`packageBuild.manifest.packFolders` groups declared packs in Foundry's pack
+browser. When it is set, a folder naming a pack absent from `packs` is an
+error at that folder's pack name. A declared pack named by no folder is a
+warning at `packFolders`: it still ships at the root. With no `packFolders`
+declaration, all packs ship at the root without a finding.
+
 `packageBuild.manifest.descriptionHtml` is the exception worth calling out on
 its own: it is not forbidden, it **is** how `description` is authored. It is
 the pitch Foundry's package browser shows — HTML allowed, any length — and it
 is emitted into the generated manifest as `description`; the key itself never
-survives into the manifest under its own name. `package.json`'s own
-`description` is read by neither this nor the site (see
-[`site.description`](#site)) — a declared one is reported as a warning naming
-both real keys, so it cannot drift back into use:
-
-> `package.json: warning: \`description\` is read by nothing; the Foundry pitch is \`packageBuild.manifest.descriptionHtml\` and the site's is \`site.description\`` — a JSON manifest carries no line to point at, so only the file is named.
+survives into the manifest under its own name. `package.json.description` is
+npm package metadata. It does not supply the Foundry description or the site
+description (see [`site.description`](#site)); each surface has its own copy.
 
 | Forbidden key                         | Derived from                                                     |
 | ------------------------------------- | ---------------------------------------------------------------- |
@@ -1771,5 +1807,5 @@ the source directory:
 | `site.trees`, `site.readmeSections`                                                                                                                                                                                                                                                         | Retired — a page is a note in the content tree.                                                                                                        |
 | `site.sections`, `site.landing`, `site.backfillSections`, `site.list`                                                                                                                                                                                                                       | Retired — a site is its homepage and its pages, and any index between them is a `doc` note.                                                            |
 | `site.hugo.baseURL`, `.title`, `.locale`, `.publishDir`, `.contentDir`, `.themesDir`, `.theme`, `.disableKinds`, `.taxonomies`, `.outputs`, `.params.description`, `.params.author`, `.params.cdnBaseURL`, `.params.brand`, `.params.notfound`, `.markup.goldmark.renderer.unsafe`, `.menu` | Forbidden — each is written by the site build from a source it names; see [the generated Hugo configuration](#the-generated-hugo-configuration).       |
-| `publish.site: true` / `publish.site: false`                                                                                                                                                                                                                                                | Refused rather than mapped — write `homepage` or `content`.                                                                                            |
+| `publish.site` (any value)                                                                                                                                                                                                                                                                  | Refused — publication follows the authored content tree.                                                                                               |
 | `packs`, `itemBuilders`, `docs`, `compatibility`, `relationships`, `systems`, `requiresSystem`, `stats`, `foundryPackage`                                                                                                                                                                   | Forbidden in a `documentation` package — each describes a Foundry package this kind is not; see the key's own section for its located refusal message. |