@heroiclands/package-build 20.3.1 → 20.5.0

package/README.md

@@ -14,13 +14,6 @@ The content half is documented separately in **[CONTENT.md](CONTENT.md)** — th
 note format, the pack pipeline, and the configuration contract a content tree
 declares itself with.
 
-> **This package was two.** Until 3.0.0 the content half shipped as
-> `@heroiclands/content-build`. No consumer ever installed one without the
-> other, and the packaging half depended on the content half besides, so the
-> boundary bought nothing and cost a configuration file with two owners and a
-> two-repository dance for single changes. See
-> [MIGRATING.md](MIGRATING.md) to move a consumer from 1.x.
-
 ## Install
 
 ```
@@ -234,7 +227,7 @@ packageBuild:
 ### The manifest is generated, not stamped
 
 `package-build manifest` writes `system.json` / `module.json` into the stage.
-**There is no template file.** A manifest used to be hand-authored JSON that the
+**There is no template file.** A hand-authored JSON manifest is one the
 build stamped a few fields into — the one build input still written by hand, per
 repository, with no schema and nothing checking it. It also declared facts the
 configuration already declared: the pack list twice, in two formats, with
@@ -324,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
 
 ```
@@ -334,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
@@ -495,7 +506,7 @@ own to call a run green. Every way of stopping a runner before it starts — a
 corrupt install, a missing browser, a killed process, an `npm ci` racing the
 run and taking `node_modules` with it — produces a run that executed nothing,
 and a harness that reports that as 0 makes the evidence unfalsifiable in the
-one direction that matters (#153).
+one direction that matters.
 
 So the suite is bracketed rather than trusted: