@heroiclands/package-build 4.0.0 → 6.0.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 }
@@ -128,9 +130,11 @@ packageBuild:
     - { from: assets/icons, to: assets/icons }
 
 # Three independent switches — every combination is real — plus the address
-# scheme both `manifest` and `site` derive addresses under.
+# 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.
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
@@ -147,8 +151,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`, every
-publishing switch off),
+(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, both
+manifest switches off 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, so it fails at load rather than as an empty pack much later.
@@ -355,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,17 +476,17 @@ npx content-build site [--out <dir>]
 npx content-build reachability <dir> [file] [--index <shortcode>]
 ```
 
-| 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.                                                 |
 
 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
@@ -467,6 +520,13 @@ 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.
+
 ### Frontmatter, against the schema its type declares
 
 The same command also checks that each note's `sohl:` block is what its **type**
@@ -510,6 +570,61 @@ 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'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
@@ -594,10 +709,11 @@ It reads its whole input from configuration and takes nothing else:
 | `publish.address`           | The address scheme those paths are derived under — see below. |
 
 **Both addresses are optional, independently.** A note that compiles into no
-document has no `uuid`, and a package that ships compendiums and publishes no
-site (`publish.site: false`) has no `path` on any entry. Neither is an error, and
-neither is guessed: inventing the missing one asserts a target that does not
-exist, which is the silent dead link the manifest exists to prevent.
+document has no `uuid`, and a package that ships compendiums and publishes only
+a homepage (`publish.site: homepage`) has no `path` on any entry — its notes are
+not pages. Neither is an error, and neither is guessed: inventing the missing one
+asserts a target that does not exist, which is the silent dead link the manifest
+exists to prevent.
 
 **`publish.manifests.publish` is a declaration, not a preference.** The file is
 vendored by other repositories and read as authoritative, so emitting one is a
@@ -615,7 +731,7 @@ time and 404s for the reader.
 
 ```yaml
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
@@ -658,6 +774,64 @@ address derivation, the address index, table expansion, wikilink resolution,
 code-fence protection, the foreign-manifest merge, the page emission and the
 section-landing backfill.
 
+### The homepage, and how much else is published
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and what a reader finds there is a note in the content tree — one markdown file,
+written by a person:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+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`
+decide nothing on it. It is dispatched on `type` like every other note, not on a
+filename: `README.md` is already a section landing under `landing: readme`, and
+in `sohl-thalorna` it is a developer explainer about the source tree.
+
+`type: homepage` is declared by the **engine**, not by the `sohl` item registry,
+so a package that configures no `itemBuilders` at all — `HarnMaster-3-FoundryVTT`
+and every HM3 module — can author one. The `engine/` ÷ `sohl/` line is
+note-format knowledge against game-system knowledge, and a homepage carries no
+`system` block.
+
+`publish.site` then says how much _else_ is published:
+
+| Mode       | What is published                                                               |
+| ---------- | ------------------------------------------------------------------------------- |
+| `homepage` | The authored homepage, and no other page. **The default, and the floor.**       |
+| `content`  | The homepage plus every page the content tree compiles to, and its extra trees. |
+
+There is no value meaning "no web presence": every package publishes its
+homepage. It was a boolean until 5.0.0, and both spellings are now refused
+naming the mode to write instead — see [MIGRATING.md](MIGRATING.md).
+
+**Homepage-only is a first-class mode, not an accommodation.**
+`sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's terms)
+must each publish a homepage and nothing beneath it. The boundary is _published
+content_ — journal text, artwork, item descriptions, compiled notes — and a page
+announcing the module discloses none of it. Because the failure mode is silent,
+the mode **fences the content surfaces off** rather than trusting a
+configuration to stay empty: in `homepage` mode the tree is never walked for
+pages, and `sections`, `trees`, `landing` and `backfillSections` emit nothing
+even when they are declared.
+
+That is separate from `publish.manifests.publish`, which stays off for both for
+an unrelated reason: a link manifest is the dependency edge that would stop the
+module being withdrawable, and a homepage is one row in a routing table.
+
+The homepage is written at the root of `site.out` — the package's own address —
+one level above the content mount, which is where `publish.address.prefix` puts
+everything else.
+
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the link manifest reads, so a page and its manifest entry cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
@@ -686,7 +860,7 @@ site:
 
 | Key                | What it decides                                                                                  |
 | ------------------ | ------------------------------------------------------------------------------------------------ |
-| `out`              | The Hugo content root. **Required**, and wiped on every run — see the safety note below.         |
+| `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.              |
@@ -717,6 +891,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:
 

package/MIGRATING.md

@@ -1,3 +1,117 @@
+# 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
+new authoring capability that needs no migration: a `type: homepage` note.
+
+## 1. Respell `publish.site`
+
+```yaml
+publish:
+  site: content # was `site: true`
+```
+
+```yaml
+publish:
+  site: homepage # was `site: false`, or absent
+```
+
+`homepage` is the default, so a repository that never set the key needs no edit.
+A repository that set it to either boolean gets a `TypeError` at load naming the
+mode to write:
+
+```text
+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.
+```
+
+Both spellings are **refused rather than mapped** onto the nearest mode. `false`
+read as _this package has no web presence_, which now describes no package at
+all, and a value silently reinterpreted reads to its author as though it still
+means what it said.
+
+Nothing else about publishing moved: `publish.address`, `publish.manifests` and
+the whole `site:` block are unchanged, and every address `sohl` and `thalorna`
+already publish is byte-identical across the upgrade.
+
+## 2. Author a homepage (optional here, required by #52)
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and the page there is a note in the content tree:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+It 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. It is
+written to the root of `site.out`, one level above the content mount.
+
+A repository with no homepage note publishes none, and the site build says so in
+its count. Requiring exactly one is a separate change (#52).
+
+## 3. What homepage-only means
+
+`homepage` mode does not merely leave the content configuration unused — it
+**fences the content surfaces off**. The tree is never walked for pages, and
+`site.sections`, `site.trees`, `site.landing` and `site.backfillSections` emit
+nothing even when they are declared.
+
+That is deliberate, and it is a licensing requirement rather than a preference.
+`sohl-kethira-basic` (Keléstia Productions' Fan Material Guidelines) and
+`harn-adventures` (HârnFanon under Lythia's terms) publish a homepage and no
+other page; the failure mode is silent — a `site:` block added later ships
+licensed content with nobody noticing — so the property is asserted by the code
+path rather than left to configuration.
+
+`publish.manifests.publish` is a separate decision and stays `false` for both: a
+link manifest is the dependency edge that would stop a module being withdrawable,
+and a homepage is not.
+
 # Migrating to `@heroiclands/package-build` 4.0.0
 
 **One authoring change: delete `package:` from every content note.** A note's

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

package/bin/content-build.mjs

@@ -76,6 +76,9 @@ import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
 import { NOTE_SCHEMAS } from "../sohl/note-schemas.mjs";
+// The engine's own types, merged under the registry's so the vocabulary stands
+// in a package that configures no `itemBuilders` at all (#51).
+import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
 import {
@@ -346,7 +349,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
                 const frontmatter = lintFrontmatter(index, {
-                    schemas: NOTE_SCHEMAS,
+                    schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
                     references: argv.references,
                 });
 
@@ -363,7 +366,8 @@ function lintCommand() {
                 } else {
                     log.info(
                         `Addresses and frontmatter are well-formed ` +
-                            `(${addresses.keys} across ${addresses.notes} note(s)).`,
+                            `(${addresses.keys} address(es) across ` +
+                            `${addresses.notes} note(s)).`,
                     );
                 }
             } catch (err) {
@@ -579,6 +583,7 @@ function linksCommand() {
                     deadAnchors,
                     deadAddresses,
                     frontmatterLinks,
+                    homepageLinks,
                     usedManifest,
                 } = auditLinks(index);
 
@@ -611,10 +616,24 @@ function linksCommand() {
                     });
                 }
 
+                // The package homepage. Its addresses are markdown links and
+                // `landing:` url/href fields rather than wikilinks — it is
+                // published verbatim, so nothing resolves a wikilink on it —
+                // and until #54 nothing looked at them at all.
+                for (const h of homepageLinks) {
+                    emitDiagnostic({
+                        file: h.note.file,
+                        ...positionOfLiteral(h.note.raw, h.text, h.occurrence),
+                        severity: "error",
+                        message: `${h.field}: ${h.message}`,
+                    });
+                }
+
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
-                    frontmatterLinks.length;
+                    frontmatterLinks.length +
+                    homepageLinks.length;
                 if (failures) {
                     log.error(
                         `${failures} link problem(s) across ${index.notes.length} note(s).`,
@@ -625,7 +644,8 @@ function linksCommand() {
                         `${index.notes.length} notes: every anchor link lands ` +
                             `and every qualified address resolves ` +
                             `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no wikilink in frontmatter.`,
+                            `via manifest), no wikilink in frontmatter, ` +
+                            `every homepage address resolvable.`,
                     );
                 }
             } catch (err) {
@@ -823,7 +843,8 @@ function siteCommand() {
 
                 const s = result.stats;
                 log.info(
-                    `wrote ${s.content ?? 0} content page(s) + ` +
+                    `wrote ${s.homepages ?? 0} homepage(s) + ` +
+                        `${s.content ?? 0} content page(s) + ` +
                         `${s.tree ?? 0} tree page(s) + ${s.landings} ` +
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );

package/bin/package-build.mjs

@@ -78,7 +78,7 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
-import { loadPackConfig } from "../engine/pack-config.mjs";
+import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { validateLangSource } from "../lang.mjs";
 import {
@@ -354,6 +354,8 @@ function manifestCommand() {
                 artifact: config.artifact,
                 outDir: path.join(config.rootDir, config.stageDir),
                 flags,
+                // So a `packFolders` finding names the line it is about.
+                configFile: packConfigPath(),
             });
             console.log(
                 `✅ Wrote ${path.relative(config.rootDir, written)} ` +