@heroiclands/package-build 20.4.0 → 20.5.0

package/CHANGELOG.md

@@ -1,5 +1,281 @@
 # @heroiclands/package-build
 
+## 20.5.0
+
+### Minor Changes
+
+- cbe3266: **A reference for every subpath entry this package exports**
+  
+  `docs/api.md` documents the whole programmatic surface — `engine`, `sohl`
+  and `hm3` included, on the same footing as the packaging half — organized by
+  how a consumer imports it: signature, what it returns, and when to reach
+  for it, with a runnable example per subpath. Most of it is pure — source
+  text or already-loaded data in, findings or values out, leaving discovery,
+  I/O and reporting to the caller — and the reference names the handful of
+  packaging functions that necessarily touch the filesystem or a subprocess.
+- 8e2b5d3: **A key-by-key reference for `package-build.config.yaml`**
+  
+  `docs/configuration.md` documents every top-level key, every nested key, its
+  type, whether it is required, its default, and the exact message an author
+  sees when a value is wrong — quoted from the validator, so the error a build
+  prints is searchable against the page that explains it.
+  
+  It also documents the values a repository never writes: `rootDir` and
+  `foundryPackage` are derived from where the file sits and from the adjacent
+  `package.json`; `stats.systemVersion` is derived from `package.json` or from
+  `systems:`; `itemBuilders` accepts a registry name (`sohl`, `hm3`) in YAML,
+  resolved before validation. Authoring the first three directly is refused,
+  with the message that says so.
+  
+  `packageBuild:` — the section `@heroiclands/package-build`'s own packaging
+  half reads — gets the same treatment: staging assets, the manifest
+  pass-through and the keys it derives and refuses to have overwritten, the
+  localization coverage settings, the container and end-to-end test
+  configuration.
+- cc3d90b: **The content tree publishes as a book**
+  
+  A third surface beside the compendium packs and the website: one searchable,
+  bookmarked PDF, built by `content-build pdf` and attached to a release by
+  `package-build release`.
+  
+  **A book is a selection, not a rendering of everything.** The packs and the site
+  publish the whole tree; a book is a declared structure whose leaves pick notes
+  out of the corpus with a `WHERE` clause, interleaved with prose that need not be
+  in the tree at all. `pdf.document` names that structure.
+  
+  ```yaml
+  pdf:
+    title: The Hârn Ensemble
+    document: book.yaml
+    fonts:
+      serif: Libertinus Serif
+      mono: DejaVu Sans Mono
+  ```
+  
+  **`publish.site` decides whether one is built, and it is the only switch.**
+  `content` builds a book; `homepage` does not — the same fence that stops the
+  tree being walked for pages stops it being walked for a book, so the four
+  packages that publish only a homepage cannot start emitting a content document
+  because a `pdf:` block appeared. A package with no block, no tree, or no
+  compiler builds nothing, says why, and exits 0.
+  
+  | Property                | How it is got                                                       |
+  | ----------------------- | ------------------------------------------------------------------- |
+  | Searchable              | Real text; every embedded font carries a `ToUnicode` map.           |
+  | Bookmark outline        | Every section and entry is a heading, so the sidebar is the way in. |
+  | Page-numbered contents  | Shallower than the bookmarks — 2,500 entries would be 40 pages.     |
+  | Repeating table headers | A property table spilling a page keeps its column names.            |
+  | Internal references     | A wikilink between two notes of the book resolves inside the PDF.   |
+  | External references     | A cross-package link, or a note not selected, stays a URL.          |
+  
+  **Typst is a binary, not a dependency.** It is found on `PATH` or named by
+  `pdf.binary`. Bundling a native compiler would put a platform-specific artefact
+  in the dependency tree of three repositories, only one of which is mostly a
+  book. A missing binary is a finding, and the `.typ` source is written anyway.
+  
+  Proved against `harn-ensemble`: 2,517 entries, 1,270 pages, 10,421 outline
+  nodes, 34 seconds, no findings.
+  
+  Additive — a package that configures no `pdf:` block is unaffected.
+- c9dfa50: **A `doc` has two more genres to choose from**
+  
+  `subType: howto` and `subType: concept` join `rules`, `userguide` and
+  `reference`:
+  
+  - **`howto`** — a task with an outcome, written as the steps that reach it.
+  - **`concept`** — an explanation of how something works and why it is shaped
+    that way, read to understand rather than to follow.
+  
+  Between them they cover the prose a package writes about itself, which had no
+  genre to declare and was left to a directory name to imply.
+  
+  `subType` stays _a genre and only a genre_: it says what kind of page this is,
+  never who reads it. A page written for a developer is a `howto` or a `concept`
+  like any other, and the audience is the section it sits in.
+  
+  Both spellings are one word, as `userguide` is: a `subType` is held to the
+  address charset, so `how-to` is refused for its hyphen.
+- 00ce257: **A package that publishes documentation**
+  
+  `packageKind` takes a third value, `documentation`: a package that publishes a
+  website and the book built from the same notes, and compiles no Foundry
+  documents at all. `systems` and `modules` say where Foundry installs a package;
+  `documentation` says it installs nowhere.
+  
+  ```yaml
+  contentPackage: toolkit
+  packageKind: documentation
+  
+  publish:
+    site: content
+    address: { prefix: guide/ }
+  
+  site:
+    out: site/content
+  ```
+  
+  `publish` is required, and `site: content` — publishing the tree is the whole of
+  what the kind does, and `content` is also what builds the book.
+  
+  **What it refuses, by name and with a locator.** `packs`, `itemBuilders`,
+  `docs`, `compatibility`, `relationships`, `systems`, `requiresSystem`, `stats`
+  and `foundryPackage` each describe a Foundry package, so each fails at load
+  naming the key and the line and column it was written on, rather than being read
+  and ignored. `packs` is otherwise still required to declare at least one pack.
+  
+  **What follows from the kind.**
+  
+  - _No manifest, and no compile._ `package-build manifest` refuses rather than
+    writing a `module.json` for a package Foundry never installs. The compile
+    passes refuse too, rather than exiting 0 having compiled nothing.
+  - _No Foundry ids to author._ A note's id is derived from its address, and no
+    pass here asks for a pinned one.
+  - _`doc` and `homepage` are the whole vocabulary._ Every other note type exists
+    to become a Foundry document, so a note carrying one has no destination;
+    `content-build lint` reports it at its `type:` line.
+  - _No asset root._ `assetRoot` and `foundryPackage` resolve to nothing, so a
+    note's `img:` names the owning package (`systems/…`, `modules/…`) or a URL.
+    A path this package would have to serve itself is refused.
+  - _A content index all the same._ `content-build content-index` emits
+    `<contentPackage>-metadata.jsonl` as it does everywhere else, so another
+    package can resolve an address into this one.
+  
+  Systems and modules are unchanged: the asset root, the `_stats` stamp and the
+  pack requirement all behave exactly as before.
+- 46d6de3: **Getting started** — `docs/getting-started.md` walks an empty directory to a
+  package that builds: identity, configuration, a first note, the checks, the
+  compiled packs, the manifest, the content index and the release archive. Each
+  step says what it produces and how to tell it worked, with the output it
+  actually prints. It was written by walking it.
+  
+  **Project setup** — `docs/project-setup.md` covers what a repository carries
+  beyond the build configuration: `package.json` and what each script in the chain
+  is _for_, the shared Prettier re-export and what `.prettierignore` is really
+  guarding, the packaged git hooks and their per-hook switches, `.changeset/` and
+  the four settings that are decisions rather than preferences, the label registry
+  pair, and the directory layout — what the build reads, and everything it writes
+  under `build/`.
+- f9e0e27: **`content-build pdf --version` is now `--book-version`.**
+  
+  `--version` collided with yargs' own reserved top-level `--version`, so the
+  option could not actually take a value — passing one failed with
+  `Unknown argument`. `--book-version` stamps the title page and the file name
+  exactly as before; the plain `content-build --version` answers this package's
+  own version, unaffected.
+  
+  **A thrown error from `content-build pdf` no longer crashes with a
+  `ReferenceError`.** It now reports the same located diagnostic and non-zero
+  exit every other command's catch block produces.
+- a6c77d2: **A guide to reading this toolchain's diagnostics**
+  
+  `docs/diagnostics.md` explains the `file:line:column: severity: message` form
+  every warning and error carries: why a field is dropped rather than guessed,
+  why both severities print to stderr, how a configuration error is located,
+  and which commands fail a run on an error-severity finding. It closes with a
+  runnable example that parses a command's output programmatically.
+- 51e334a: **A full command reference**
+  
+  `docs/commands.md` documents every command both binaries expose — `package-build`
+  and `content-build`, 25 commands between them — with what each reads, what it
+  writes, its options and their defaults, its exit codes, and a worked example.
+  
+  Several corners never had a home before this: `content-build pdf`, and the
+  options `--coverage`, `--doc`, `--fields`, `--id`, `--references`, `--registry`
+  and `--root`.
+  
+  The document is checked against the actual `yargs` definitions in both
+  binaries, so an option or an action added to either one and left undocumented
+  fails the build.
+
+### Patch Changes
+
+- 6e80fbd: **`content-config.mjs`'s own documentation now matches what `defineConfig` accepts**
+  
+  The worked example at the top of `content-config.mjs` — and its `.mjs` twin in
+  `CONTENT.md` — authored `stats.systemId`, a key `defineConfig` refuses as
+  derived. Both now carry only what loads.
+  
+  The `contentPackage` refusal, and the sibling refusal for a section's
+  `listType` / `listSubType`, named the wrong character class — `[A-Za-z0-9]`
+  when the enforced charset is lowercase only. Both now say `lowercase
+  alphanumeric` and print the pattern actually enforced, so an author who writes
+  `contentPackage: PackageBuild` is told what is wrong with it rather than sent
+  looking for a character they do not have.
+- bd6c20b: **`docs/configuration.md` now matches `packageKind: documentation`**
+  
+  The configuration reference names all three `packageKind` values —
+  `systems`, `modules` and `documentation` — in the summary table and in the
+  `packageKind` section itself, and states which keys a `documentation`
+  package requires, which it refuses (quoting each located refusal message
+  verbatim), and how `foundryPackage`, `assetRoot` and `stats` resolve for it.
+- fb04049: **`content-build docs item-fields --check` reports a stale page in the located form**
+  
+  The stale-page diagnostic now starts with the file's path, unprefixed by a
+  timestamp — matching every other located failure this command line emits, and
+  readable by the same tools that already parse the rest of them.
+- 46b39ef: **The published types match the code they are generated from**
+  
+  The `.d.mts` files ship with `@heroiclands/package-build` and are generated
+  from the JSDoc, so a block that is not the one belonging to a symbol ships as
+  that symbol's type. `packRelease` now declares the `pdf` option it accepts and
+  the `pdf`, `pdfFindings` and `pdfSkipped` fields it returns; `buildSite` and
+  `expandNoteTables` declare `sqlTables`; a compiler's `resolveEmbedded`
+  declares `modelPackage`; and `expandContentTables` declares the `warnings` it
+  returns and the `column` on every error entry. Type-checking the whole
+  published declaration surface is clean.
+  
+  **Every exported symbol carries documentation of its own**
+  
+  `NOTE_VOCABULARY`, `DECLARED_TAGS`, `buildIndexRecord`, `collectContentIndex`,
+  `expandContentTables`, `walkMarkdownTree`, `declaredPredecessors` and the seven
+  pack compiler classes each describe what they take and what they return, so
+  hovering one in an editor answers the question asked of it.
+- de54d45: `docs/commands.md` reads as a manual page. Every command carries the same
+  labelled sections — **NAME**, **SYNOPSIS**, **DESCRIPTION**, **OPTIONS**,
+  **EXIT STATUS**, **EXAMPLES**, **SEE ALSO** — in the same order, so jumping to
+  the right command means jumping to the right label. **SEE ALSO** cross-links
+  the commands that answer a related question, and every command that emits
+  findings or reads a configuration key now points at _Diagnostics_ or
+  _Configuration_ directly.
+  
+  `package-build lang check` / `coverage` / `hardcoded` and
+  `content-build content-format schema` / `fields` / `notes` each get their own
+  section, rather than sharing one.
+- 40fcc1a: **A frontmatter reference resolves in any package the tree can reach.**
+  
+  A `ref:` field — `parentSkillCode`, `assocSkillCode`, `assocAffiliationCode` —
+  holds a shortcode, not an address. The system persists it as written and looks
+  it up at runtime among the items embedded on one actor, and an actor assembled
+  from several packages carries their items side by side. So the reference check
+  now asks only whether _any_ reachable package declares the `type`/`shortcode`
+  pair: local notes first, then the fetched dependency indexes, with package and
+  system wildcarded.
+  
+  This is the rule for a reference alone. A wikilink is unchanged — its target is
+  a document to point at, so an omitted package still means this one, and reaching
+  another package still requires the fully qualified form.
+  
+  A tree whose references name a parent in a dependency saw every one of them
+  reported:
+  
+  | note                    | `sohl.parentSkillCode` | before       | after                      |
+  | ----------------------- | ---------------------- | ------------ | -------------------------- |
+  | a language skill        | `lang`                 | no such note | resolves in the dependency |
+  | a spirit specialisation | `spirit`               | no such note | resolves in the dependency |
+  
+  A reference naming a shortcode no package declares is still an error, and the
+  value a note writes is still the value its document carries.
+  
+  `buildLinkIndex` gains `referenceHit(target)`, which is what performs this
+  lookup.
+- a331709: **The address-segment charset is documented as lowercase, matching what it enforces.**
+  
+  Comments, JSDoc and the reference documentation described `contentPackage`,
+  `type`, `subType` and `shortcode` as `^[A-Za-z0-9]+$` or plainly "alphanumeric",
+  which reads as case-insensitive. The charset every one of them is held to is
+  lowercase-only, and the wording now says so — in prose and in the refusal
+  messages an author hits when a value breaks it.
+
 ## 20.4.0
 
 ### Minor Changes

package/CONTENT.md

@@ -25,8 +25,10 @@ A consuming repository declares one `package-build.config.yaml` at its root:
 # every canonical address, the name of the content index it emits, and the
 # package a cross-package wikilink writes to reach one of its notes.
 contentPackage: thalorna
-# Where Foundry installs it: "systems" or "modules". Also decides the served
-# asset root a note's `img:` resolves to — `modules/sohl-thalorna/assets/…`.
+# What kind of package this is. "systems" and "modules" are where Foundry
+# installs it, and each decides the served asset root a note's `img:` resolves
+# to — `modules/sohl-thalorna/assets/…`. "documentation" is a package Foundry
+# never installs; see "A package that compiles nothing" below.
 packageKind: modules
 
 # The Foundry core range this package supports. `minimum` is stamped into every
@@ -161,13 +163,13 @@ packageBuild:
   assets:
     - { from: assets/icons, to: assets/icons }
 
-# Three independent switches — every combination is real — plus the address
-# scheme both `manifest` and `site` derive addresses under. `site` is a mode,
-# not a boolean: `homepage` (the default) publishes the authored homepage and
-# no other page; `content` publishes it plus every page the tree compiles to.
+# How much of the package reaches the web, plus the address scheme both
+# `manifest` and `site` derive addresses under. `site` is a mode, not a
+# boolean: `homepage` (the default) publishes the authored homepage and no
+# other page; `content` publishes it plus every page the tree compiles to, and
+# is also what builds the book.
 publish:
   site: content
-  manifests: { publish: true, consume: true }
   address:
     prefix: kb/
 
@@ -182,8 +184,8 @@ site:
 
 The loader validates the document, resolves every path against the directory
 the file sits in, fills the optional halves with their defaults
-(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, both
-manifest switches off and `publish.site` at its `homepage` floor),
+(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths` and
+`publish.site` at its `homepage` floor),
 derives `assetRoot`, `packDirectories`, `itemTypes` and `docEntryTypes`, and
 freezes the result. A malformed configuration throws a `TypeError` naming the
 offending field — and the line and column it was written on, in the
@@ -212,6 +214,69 @@ never existed. A module declaring no usable system relationship fails the build
 rather than guessing — a wrong `_stats.systemVersion` is invisible until
 something migrates on it.
 
+### A package that compiles nothing
+
+`packageKind: documentation` is the answer "not a Foundry package at all". It
+publishes a website and the book built from the same notes, and compiles no
+compendium: nothing is installed into a Foundry data directory, so there is no
+manifest, no pack and no document.
+
+```yaml
+contentPackage: toolkit
+packageKind: documentation
+
+# Required, and `content`: publishing the tree is the whole of what this kind
+# does. `homepage` would leave one authored page, no book and nothing compiled.
+publish:
+  site: content
+  address: { prefix: guide/ }
+
+site:
+  out: site/content
+
+pdf:
+  title: The Toolkit
+  document: book.yaml
+  fonts: { serif: Libertinus Serif }
+```
+
+`contentPackage`, `paths`, `skipDirectories`, `icons`, `site`, `pdf` and
+`packageBuild` mean exactly what they mean anywhere else. **Every key that
+describes a Foundry package is refused**, by name, with the line and column it
+was written on — `packs`, `itemBuilders`, `docs`, `compatibility`,
+`relationships`, `systems`, `requiresSystem`, `stats` and `foundryPackage`:
+
+```text
+package-build.config.yaml:7:1: error: package-build config: `packs` is refused in a `documentation` package, which compiles no compendium, so there are no packs to declare.
+```
+
+A key that cannot mean anything in this shape fails at load rather than being
+read and ignored, which is the difference between a configuration that is wrong
+and a build that is quietly wrong.
+
+What follows from the kind:
+
+- **`foundryPackage` is not derived.** For every other kind the loader reads it
+  from the adjacent `package.json`; there is no Foundry package here to carry an
+  id, so `foundryPackage` and `assetRoot` are both `null`. A note's `img:`
+  therefore names the owning package (`systems/…`, `modules/…`) or a URL — a
+  path this package would have to serve itself is refused, because Foundry
+  serves no files for a package it does not install.
+- **`package-build manifest` refuses**, rather than emitting a `module.json`
+  advertising an installable package with no id, no packs and no compatibility
+  range. So does `content-build package compile`, which would otherwise exit 0
+  having compiled nothing.
+- **Notes need no `id:`.** An id is derived from a note's address, and a
+  hand-assigned one is only ever a pin for a document that already shipped —
+  which needs a compendium, and there is none.
+- **The note vocabulary is `doc` and `homepage`.** Every other type exists to
+  become a Foundry document, so a note carrying one has no destination;
+  `content-build lint` reports it at its `type:` line.
+- **A content index is still published.** `content-build content-index` emits
+  `<contentPackage>-metadata.jsonl` exactly as it does elsewhere, so another
+  package can resolve an address into this one and a wikilink from its notes can
+  reach a page here.
+
 ### A note's package is the repository's, not the note's
 
 `contentPackage` is the **address namespace** every note in the tree is
@@ -240,7 +305,7 @@ package's id to _be_ its system id.
 Because it is a segment of an address, the value is **validated** rather than
 taken as written, and a violation fails the build naming the line it is on:
 
-- **Alphanumeric** (`^[A-Za-z0-9]+$`). An address is read by counting
+- **Lowercase alphanumeric** (`^[a-z0-9]+$`). An address is read by counting
   hyphen-separated segments, so the hyphen has to be purely a separator — which
   is why `harn-adventures` is configured as `harnadventures`. This is the same
   rule `shortcode` is already held to, and the two are one constant.
@@ -257,7 +322,7 @@ taken as written, and a violation fails the build naming the line it is on:
   refused.
 
 ```text
-package-build.config.yaml:1:1: error: package-build config: `contentPackage` is `harn-adventures`, which is not alphanumeric. It is the first segment of every address this package publishes (`harn-adventures-<system>-<type>-<shortcode>`), and an address is read by counting hyphen-separated segments — so anything outside `[A-Za-z0-9]` here makes those addresses unreadable rather than merely ugly. `harn-adventures` became `harnadventures`.
+package-build.config.yaml:1:1: error: package-build config: `contentPackage` is `harn-adventures`, which is not lowercase alphanumeric (^[a-z0-9]+$). It is the first segment of every address this package publishes (`harn-adventures-<system>-<type>-<shortcode>`), and an address is read by counting hyphen-separated segments — so anything outside that here makes those addresses unreadable rather than merely ugly. `harn-adventures` became `harnadventures`.
 ```
 
 **`package:` in a note's frontmatter is retired, and declaring it fails the
@@ -312,7 +377,7 @@ export default defineConfig({
   foundryPackage: "sohl-kethira-basic",
   packageKind: "modules",
   compatibility: { minimum: "14.359", verified: "14.364" },
-  stats: { systemId: "sohl", systemVersion: "0.4.3", lastModifiedBy: "…" },
+  stats: { lastModifiedBy: "…" },
   itemBuilders: ITEM_BUILDERS,
   packs: [{ name: "items", type: "Item" }],
 });
@@ -658,7 +723,9 @@ and there are exactly three answers:
 
 `assetRoot` is derived, never authored: it is
 `<packageKind>/<foundryPackage>/assets`, and it is the one place `systems/sohl`
-(or `modules/sohl-thalorna`) is ever spelled. So `icons/relic.svg` in a module's
+(or `modules/sohl-thalorna`) is ever spelled. The derivation is **conditional on
+the kind** — a `documentation` package has no asset root, and the third row is
+refused there rather than rooted. So `icons/relic.svg` in a module's
 registry compiles to `modules/sohl-relics/assets/icons/relic.svg`, and the same
 string in the system's compiles to `systems/sohl/assets/icons/relic.svg`. An
 already-served `systems/sohl/assets/icons/…` passes through untouched — which is
@@ -977,9 +1044,10 @@ npx content-build lint some/tree  # or a tree named outright
 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
-  key referenced from saved world data, and half of the `type-shortcode`
-  address, whose parse needs the separating hyphen to be the only hyphen.
+- **Shape** — a `shortcode` is strictly lowercase ASCII-alphanumeric. It is
+  the identity key referenced from saved world data, and half of the
+  `type-shortcode` address, whose parse needs the separating hyphen to be the
+  only hyphen.
 - **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.
@@ -1149,7 +1217,7 @@ values. A `weapon` declares none — SoHL distinguishes a weapon's uses by strik
 mode rather than by kind — so `subType` on one is a finding; a `skill` declares
 ten, so `subType: crafte` is a finding naming `craft`.
 
-**A `type` and a `subType` are both held to `^[A-Za-z0-9]+$`** — the same
+**A `type` and a `subType` are both held to `^[a-z0-9]+$`** — the same
 constant a `shortcode` is held to, read rather than restated. A type is a
 segment of every address — the first of the short form an author writes, the
 third of the canonical `package-system-type-shortcode` — so a hyphen in one is
@@ -1160,7 +1228,7 @@ rule is checked ahead of the closed-set check, which is what makes it reach a
 type whose values are declared but not yet enumerated:
 
 ```text
-assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. …
+assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not a well-formed subType — a subType is letters and digits only (^[a-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. …
 ```
 
 One declared value broke that rule: a `doc`'s `user-guide`, now **`userguide`**.
@@ -1221,7 +1289,7 @@ that harmless: three segments name a _system_ whatever the first segment could
 also have meant, and four is the full form.
 
 **Parsing is plain segment counting**, the same rule the canonical key follows,
-and it is sound because every segment is `^[A-Za-z0-9]+$` — so a hyphen is
+and it is sound because every segment is `^[a-z0-9]+$` — so a hyphen is
 purely a separator. A target with five segments is not a hyphenated shortcode;
 it is a name, and not an address.
 
@@ -2228,7 +2296,7 @@ Three things about the spelling, each of them load-bearing:
   site chose; a type and a subType are addresses. They need not agree, and on
   `sohl` they do not: the section is `user-guide`, because that is a published
   URL, while the subType is `userguide` because an address segment is
-  alphanumeric. Both values are checked against that charset here, so
+  lowercase alphanumeric. Both values are checked against that charset here, so
   copying the section's name in is refused rather than quietly matching nothing.
 - **`listSubType` needs a `listType`.** A subType only tells pages apart within
   a type — `rules`, `userguide` and `reference` are all `doc` — so alone it
@@ -2316,6 +2384,131 @@ 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.
 
+## Publishing a book
+
+The third surface the content tree publishes, beside the compendium packs and
+the website: one PDF, built by `content-build pdf` and by `package-build release`.
+
+```bash
+npx content-build pdf                    # build it where `pdf.out` says
+npx content-build pdf --out build/book   # somewhere else
+npx content-build pdf --no-compile       # emit the Typst source and stop
+npx content-build pdf --version 1.4.0    # stamp a version on the title page
+```
+
+### A book is a selection, not a rendering of everything
+
+The packs and the website publish the _whole_ tree: every note becomes a
+document and a page, and the three surfaces agreeing about what the content is
+is the point. **A book is not that.** It is a declared structure whose leaves
+pick notes out of the corpus, interleaved with prose that need not live in the
+content tree at all.
+
+`pdf.document` names that structure — a YAML file of nested sections, each
+holding some mixture of prose files and `filter:` clauses:
+
+```yaml
+contents:
+  - sectionName: Gear
+    contents:
+      - file: prose/gear-preamble.md
+      - filter: "type = 'weapongear'"
+      - sectionName: Armour
+        contents:
+          - filter: "type = 'armorgear'"
+  - sectionName: The Cast
+    contents:
+      - filter: "type = 'being' AND subType = 'npc'"
+```
+
+Three consequences follow, and each is behaviour rather than oversight:
+
+- **A note no clause selects is not in the book.** A project decides what its
+  own volume carries, so an omission is an editorial act and nothing reports it.
+- **A note several clauses select appears several times**, each occurrence its
+  own page, outline node and anchor. Inbound wikilinks are pointed at the
+  first, so `[[weapongear-dagger]]` reaches one place however often it prints.
+- **A filter that selects nothing _is_ reported.** A note nobody asked for is
+  expected; a clause matching nothing is either wrong or left over from a
+  structure that has moved on.
+
+The `WHERE` clause runs against the same content index the SQL tables read, and
+the build owns the `SELECT … FROM notes` — so a filter cannot name a table, and
+cannot reach another package's notes.
+
+### What it is fenced by
+
+**`publish.site` decides whether a book is built, and it is the only switch.**
+`content` builds one; `homepage` does not — the same fence that stops the tree
+being walked for pages stops it being walked for a book. A PDF of the content
+tree is a content surface by any reading, arguably the most portable one there
+is, so a package that publishes only a homepage publishes no book however its
+`pdf:` block is written. The command says so and exits 0.
+
+That is also the opt-out: a package with no `pdf:` block, no content tree, or
+`publish.site: homepage` builds nothing and fails nothing.
+
+### Configuration
+
+```yaml
+pdf:
+  title: The Hârn Ensemble # required
+  subtitle: a roster of the ready-made
+  document: book.yaml # required — the document tree above
+  out: build/dist # default
+  front: # prose before the contents
+    - prose/colophon.md
+  fonts:
+    serif: Libertinus Serif
+    sans: Libertinus Sans
+    mono: DejaVu Sans Mono
+    path: assets/fonts # where to find them, beyond the system's
+  iconFonts: # icon family → the font carrying its glyphs
+    fontawesome: assets/fonts/fa-solid-900.ttf
+  binary: typst # when it is not simply `typst` on PATH
+```
+
+Nothing here is an address or a brand: the title, the front matter and the faces
+are the publishing repository's to choose, which is why they are configuration.
+
+### Typst is a binary, not a dependency
+
+The compiler is an external program, found on `PATH` or named by `pdf.binary`.
+Bundling a native compiler would put a platform-specific artefact into the
+dependency tree of three repositories, only one of which is mostly a book, and
+it would have to resolve on every consumer's CI runner before any of them could
+install the toolchain at all.
+
+A missing binary is a **finding**, not a failure: the `.typ` source is written
+anyway, which is both the diagnostic and the thing a consumer can compile by
+hand.
+
+### What the book gets right, and why each matters
+
+| Property                 | How                                                                           |
+| ------------------------ | ----------------------------------------------------------------------------- |
+| Searchable               | Real text, not page images — a roster nobody can search for a name is no use. |
+| Bookmark outline         | Every section and entry is a heading, so a viewer's sidebar is the way in.    |
+| Page-numbered contents   | `#outline()`, shallower than the bookmarks — 2,500 entries would be 40 pages. |
+| Repeating table headers  | `table.header`, so a property table spilling a page keeps its column names.   |
+| Internal cross-reference | A wikilink between two notes of the book becomes an internal destination.     |
+| External cross-reference | A cross-package link, and a note the book did not select, stay URLs.          |
+
+`{#anchor}` on a heading becomes an internal destination namespaced by its
+entry, so `[[being-jaslyne#appearance]]` reaches the section and two notes may
+both declare `{#appearance}`. A reference to a destination the book does not
+carry falls back to the entry that would have held it, or to plain text, and is
+reported — because Typst treats a dangling reference as fatal, and one mistyped
+anchor should not take a thousand-page book down at the last step.
+
+### The charset is what makes a face choosable
+
+A PDF embeds the faces it sets, so every character in the corpus is a claim on
+the book's typeface — and Typst does not warn about a missing glyph, it falls
+back and exits 0. That is why `content-build lint` holds content to a charset,
+and why `:icon-…:` names an icon rather than pasting one. Both exist for this
+surface. See _Prose: formatting and markdown_.
+
 ## Diffing published addresses
 
 ```bash

package/README.md

@@ -317,6 +317,13 @@ other's schema — they split by input, and the dependency runs one way.
 | the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json`        |
 | the bundle entry           | `packageId` — `<id>.mjs`, unless `packageBuild.bundle.entry` says otherwise |
 
+**`packageKind: documentation` has no packaging half.** That kind publishes a
+website and a book and installs into no Foundry data directory, so there is no
+artifact to name and no id to derive one from: `manifest` refuses rather than
+writing a manifest for a package Foundry never installs, and the whole of such a
+package's build is `content-build`. See
+[A package that compiles nothing](CONTENT.md#a-package-that-compiles-nothing).
+
 ## Command line
 
 ```
@@ -327,12 +334,23 @@ npx package-build lang check
 npx package-build lang coverage [--unused]
 npx package-build lang hardcoded
 npx package-build bundle check
-npx package-build release
+npx package-build release [--no-pdf]
 npx package-build deploy <stage>
 npx package-build container <stage> <start|stop|restart|recreate|rm|status|logs|pull>
 npx package-build e2e <seed|run|open|fast|sweep>
 ```
 
+`package-build release` writes `<artifact>.zip` and `<artifact>.json` into
+`build/dist`, the content index the manifest advertises, and — when the package
+publishes a content tree — the book that tree compiles to, as
+`<artifact>-<version>.pdf`.
+
+The book is **built by default and never fatal**. A package publishing only a
+homepage, one with no `pdf:` block, and one with no content tree each build
+none and say so; `--no-pdf` is for a release that has a tree and does not want
+the book. What the book is and how it is configured is `CONTENT.md`, under
+_Publishing a book_ — it is a content surface, and the content half owns it.
+
 Wrapped as npm scripts — SoHL spells them:
 
 ```json