@heroiclands/package-build 22.3.1 → 22.4.1

package/docs/commands.md

@@ -261,7 +261,7 @@ package-build: `packageKind: documentation` ships no Foundry package, so there i
 
 **NAME**
 
-`package-build site-root` — write the deployment's `_headers` and `_redirects`.
+`package-build site-root` — write the deployment's `_headers`.
 
 **SYNOPSIS**
 
@@ -278,13 +278,18 @@ and Cloudflare Pages reads `_headers` and `_redirects` from there and nowhere
 else — a copy inside the prefix is published as a text file and never applied.
 Hugo owns everything under the prefix; this owns what sits beside it.
 
-Two things are written. Indexing is suppressed on every address a deployment
-answers on but nobody advertises — the project's `pages.dev`, the per-deployment
-`pages.dev`, and the custom domain the routing layer fetches — each of which
-would otherwise compete with the canonical URL in search results. And both
-spellings of the prefix root redirect to the landing, with a lifetime pinned on
-the 301, because Pages sets no `Cache-Control` on a redirect it generates and a
-301 without one is cached indefinitely on the most-linked URL there is.
+One file is written, `_headers`, and it says one thing: indexing is
+suppressed on every address a deployment answers on but nobody advertises —
+the project's `pages.dev`, the per-deployment `pages.dev`, and the custom
+domain the routing layer fetches — each of which would otherwise compete with
+the canonical URL in search results. No `Cache-Control` is pinned on the
+prefix root: it is the homepage, and a lifetime on it would hold a stale copy
+at the most-linked address after a deploy.
+
+No `_redirects` is written: the prefix root _is_ the homepage, which the site
+build writes as the mount's `_index.md`, so nothing redirects. A `_redirects`
+left beside the site by an earlier build is removed, since Pages would apply
+it.
 
 The rules are scoped to those hostnames, so a site deployed under a domain of
 its own stays indexable.
@@ -304,7 +309,6 @@ under the prefix. Otherwise 0.
 ```
 $ package-build site-root
 ✅ Wrote build/site/_headers.
-✅ Wrote build/site/_redirects.
 ```
 
 **SEE ALSO**
@@ -607,6 +611,73 @@ package-build: 2 file(s) checked · 0 error(s) · 0 warning(s)
 
 [Diagnostics](diagnostics.md).
 
+### `package-build changelog check`
+
+**NAME**
+
+Lint release prose — pending changesets, or a `CHANGELOG.md` release section
+— against the rules a changeset is actually held to (`check` is the only
+action).
+
+**SYNOPSIS**
+
+```
+package-build changelog check [--release] [paths..]
+```
+
+**DESCRIPTION**
+
+A changeset answers one question — who notices, and what do they see — and
+nothing enforced that, so a pull-request description pasted into one ships
+verbatim as a release note: commit hashes, issue references, code fences,
+"Verified" paragraphs, byte counts and test tallies, a paragraph disguised as
+a bullet, a nested checklist, a `#` heading that outranks the version heading
+above it once wrapped into a list item, or simply too many bullets or too
+many lines for one entry. Each finding names the rule it tripped and says
+what to write instead.
+
+Default reads every pending changeset (`.changeset/*.md`; `config.json` and
+`README.md` excluded) and checks each one's body, frontmatter fence dropped.
+`--release` reads the first `## <version>` section of `CHANGELOG.md` instead
+— the section a **Version Packages** branch is about to publish — with its
+generated `## <version>` and `### <Bump> Changes` scaffold lines exempted
+from the heading rule, since neither is authored.
+
+A token that reads as code — `camelCase()`, a `path/with/slashes.ext`,
+`SCREAMING_SNAKE` — outside any code span is a warning, not a failure: a
+user-facing note sometimes needs one (`Compendium.hm3.items.Item.<id>`), but
+rarely. Every other finding is an error. Reads the files given, or resolves
+its own defaults; writes nothing.
+
+**OPTIONS**
+
+| Positional  | Type      | Default                                                                                     | Description                                                                             |
+| ----------- | --------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `paths`     | string(s) | `.changeset/*.md` (`config.json`, `README.md` excluded), or `CHANGELOG.md` with `--release` | Files to check.                                                                         |
+| `--release` | boolean   | `false`                                                                                     | Check the first `## <version>` section of `CHANGELOG.md` instead of pending changesets. |
+
+**EXIT STATUS**
+
+1 if a named file does not exist. 1 if any finding is an error. A run with
+only warnings — the code-like-token case — exits 0.
+
+**EXAMPLES**
+
+```
+$ package-build changelog check
+package-build: 1 file(s) checked · 0 error(s) · 0 warning(s)
+```
+
+```
+$ package-build changelog check --release
+CHANGELOG.md:5:3: error: changelog-check/commit-hash a commit hash is a commit-log artefact; the changelog generator should not write one — set `changelog` to `@changesets/cli/changelog`
+package-build: 1 file(s) checked · 1 error(s) · 0 warning(s)
+```
+
+**SEE ALSO**
+
+[Diagnostics](diagnostics.md).
+
 ### `package-build bundle check`
 
 **NAME**
@@ -1564,23 +1635,31 @@ Writes the whole Hugo source tree under `build/hugo/` — the sibling of
 `package compile`: the same tree, rendered as pages instead of compiled
 into packs. Everything a consumer would otherwise write for itself happens
 here: the walk, address derivation, the address index, table expansion,
-wikilink resolution, code-fence protection, the foreign-manifest merge, the
-section-landing backfill, and the Hugo configuration itself. The consumer's
-script then runs Hugo over the tree — `hugo --source build/hugo` — and this
-command never does.
+wikilink resolution, code-fence protection, the foreign-manifest merge, and
+the Hugo configuration itself. The consumer's script then runs Hugo over the
+tree — `hugo --source build/hugo` — and this command never does.
+
+**A site is its homepage and its pages.** The `type: homepage` note is
+written as the mount's `_index.md`, so Hugo renders it at
+`/<contentPackage>/`; every other note is one page at
+`/<contentPackage>/<type>-<shortcode>/`. Nothing is generated between them —
+no section directory, no listing, no tag page — and the generated
+configuration disables the `section`, `taxonomy`, `term` and `RSS` kinds on
+every site. An index of what the package publishes is a `doc` note carrying a
+content table, authored where every other page is.
 
 Three things are written, and nothing outside `build/`:
 
 - `build/hugo/hugo.toml`, generated on every run from `package.json`
   (`homepage`, `description`, `author`), `package-build.config.yaml`
-  (`packageBuild.manifest.title`, `site.assets`, `site.list`,
-  `site.notfound`, `site.hugo`), the organisation's constants, the installed
+  (`packageBuild.manifest.title`, `site.assets`, `site.notfound`,
+  `site.hugo`), the organisation's constants, the installed
   `@heroiclands/hugo-theme`'s location, and the navigation `deps fetch`
   cached. Every value's source is listed under
   [the generated Hugo configuration](configuration.md#the-generated-hugo-configuration).
-- `build/hugo/content/`, the content mount — the homepage at its root, and
-  the content tree's pages below `publish.address.prefix`. Wiped on every
-  run.
+- `build/hugo/content/`, the content mount — the homepage as its `_index.md`,
+  and the content tree's pages flat below `publish.address.prefix`. Wiped on
+  every run.
 - `publishDir` pointing Hugo at `build/site/<contentPackage>/`, the
   deployment root `package-build site-root` writes beside. Nothing Hugo
   reads lands in what is published.
@@ -1612,7 +1691,7 @@ failed to expand, or a dead wikilink. Otherwise 0.
 
 ```
 $ content-build site
-[…] wrote 1 homepage(s) + 1 content page(s) + 0 tree page(s) + 0 landing(s) to build/hugo/content
+[…] wrote 1 homepage(s) + 1 content page(s) to build/hugo/content
 […] wrote build/hugo/hugo.toml
 
 $ content-build site

package/docs/configuration.md

@@ -758,36 +758,54 @@ 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.sections`         | object   | `{}`                                        |
-| `site.landing`          | object   | `null`                                      |
-| `site.pass`             | string   | `""`                                        |
-| `site.passOptions`      | object   | `{}`                                        |
-| `site.backfillSections` | boolean  | `false`                                     |
-| `site.list`             | object   | `{shortcodes: false}`                       |
-| `site.notfound`         | object   | `null`                                      |
-| `site.hugo`             | object   | `{}`                                        |
+| 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   | `{}`                                        |
 
 How much of a package reaches the web at all is **not** here — it is
-[`publish.site`](#publish). `site` is framing: what a section is called,
-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.
+[`publish.site`](#publish). `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.
 
-What the site publishes is the content tree, and nothing beside it. A page of
-documentation is a note — `type: doc`, addressed by its shortcode, and
-`pack: none` where it compiles into no Foundry document — so there is no
-second mechanism for mounting a directory of markdown, and a configuration
-that names one is refused with a message saying where the page goes instead:
+**A site is its homepage and its pages.** The `type: homepage` note is the
+package's front page at `/<contentPackage>/`, and every other note is one page
+at `/<contentPackage>/<type>-<shortcode>/`. Nothing is generated between
+them: no section directory, no listing of a type, no tag page. Every
+structure above the pages — which notes belong together, in what order,
+under which headings — is authored, as a `doc` note carrying a content table
+over the content index, and linked from the homepage like any other page.
 
-> ``package-build config: `site.trees` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and declare the section that lists it under `site.sections`.``
+So a page of documentation is a note — `type: doc`, addressed by its
+shortcode, and `pack: none` where it compiles into no Foundry document — and
+there is no second mechanism for mounting a directory of markdown. A
+configuration that names one is refused with a message saying where the page
+goes instead:
 
-> ``package-build config: `site.readmeSections` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and declare the section that lists it under `site.sections`.``
+> ``package-build config: `site.trees` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and link it from the homepage or from a `doc` note that indexes it.``
+
+> ``package-build config: `site.readmeSections` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and link it from the homepage or from a `doc` note that indexes it.``
+
+A configuration that asks the build to generate an index between the
+homepage and the pages is refused the same way, by name and with one message
+— `site.sections` (and the `listType` / `listSubType` an entry carried),
+`site.landing`, `site.backfillSections` and `site.list` alike, since how a
+listing renders is a content table's to say:
+
+> ``package-build config: `site.sections` 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.``
+
+> ``package-build config: `site.landing` 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.``
+
+> ``package-build config: `site.backfillSections` 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.``
+
+> ``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
 the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
@@ -799,7 +817,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, landing, pass, passOptions, backfillSections, list, notfound, hugo).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -845,62 +863,8 @@ names a registry):
 
 > ``package-build config: `site.packages[<index>]` must be a non-empty string.``
 
-`site.sections` is a closed vocabulary — a section's _only_ place to speak,
-since it exists solely as the generated `_index.md` this build writes for it:
-
-| Key (under `site.sections.<name>`) | Type                       | Required | Default |
-| ---------------------------------- | -------------------------- | -------- | ------- |
-| `site.sections.<name>.title`       | string                     | yes      | —       |
-| `site.sections.<name>.banner`      | string                     | no       | none    |
-| `site.sections.<name>.description` | string                     | no       | none    |
-| `site.sections.<name>.listType`    | string, an address segment | no       | none    |
-| `site.sections.<name>.listSubType` | string, an address segment | no       | none    |
-
-> ``package-build config: `site.sections.<name>` must be a mapping.``
-
-> ``package-build config: `site.sections.<name>.title` must be a non-empty string.``
-
-`listType` / `listSubType` say what the section **lists** — a content type
-and subType, which are address segments and therefore checked against
-`^[a-z0-9]+$`, deliberately distinct from the section's own name (a URL
-this site chose; `user-guide` is the section, `userguide` the subType):
-
-> ``package-build config: `site.sections.<name>.listType` is `Not Ok`, which is not lowercase alphanumeric. It names a content type or subType, and those are address segments (^[a-z0-9]+$) — not the section's own name, which is a URL this site chose and need not match (`user-guide` is the section, `userguide` the subType). A value no page carries selects nothing and leaves the landing empty.``
-
-`listSubType` alone, without `listType`, names no query — a subType only
-distinguishes _within_ a type:
-
-> ``package-build config: `site.sections.<name>.listSubType` is declared without a `listType`. A subType tells pages apart only within a type — `rules`, `userguide` and `reference` are all `doc` — so on its own it names no query for a layout to run.``
-
-Any other key on a section entry is refused:
-
-> ``package-build config: `site.sections.<name>.<key>` is not a recognized option (expected one of: title, banner, description, listType, listSubType).``
-
-`site.landing` is different from a section entry — it is the mount's own
-landing page frontmatter, passed through verbatim to Hugo rather than
-validated field by field, since its vocabulary is the theme's and not this
-package's:
-
-> ``package-build config: `site.landing` must be a mapping.``
-
-`site.passOptions` and `site.backfillSections` have no further shape of
-their own — `passOptions` is passed to the resolved `site.pass` bundle
-unchanged, and `backfillSections` is a plain boolean:
-
-> ``package-build config: `site.backfillSections` must be a boolean.``
-
-`site.list` is how a listing page renders, written into the generated Hugo
-configuration as `params.list`:
-
-| Key                    | Type    | Required | Default |
-| ---------------------- | ------- | -------- | ------- |
-| `site.list.shortcodes` | boolean | no       | `false` |
-
-> ``package-build config: `site.list` must be a mapping.``
-
-> ``package-build config: `site.list.shortcodes` must be a boolean.``
-
-> ``package-build config: `site.list.<key>` is not a recognized option (expected one of: shortcodes).``
+`site.passOptions` has no further shape of its own — it is passed to the
+resolved `site.pass` bundle unchanged.
 
 `site.notfound` is the wording of the "page not found" page, written into
 the generated Hugo configuration as `params.notfound`. The theme renders
@@ -972,26 +936,25 @@ the block cannot grow into a second configuration file:
 `content-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                                                                                                            |
-| `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`                                                                                        |
-| `themesDir`                       | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/`                                |
-| `theme`                           | the installed `@heroiclands/hugo-theme`, so `hugo-theme`                                                                                                    |
-| `disableKinds`                    | whether any note in the tree carries `tags:`, which the site walk discovers: `["taxonomy", "term", "RSS"]` when none does, `["RSS"]` when at least one does |
-| `taxonomies`                      | the same fact — written as `{ tag = "tags" }` when at least one note carries `tags:`, absent otherwise                                                      |
-| `outputs`                         | the same fact — written as `{ taxonomy = ["HTML"], term = ["HTML"] }` when at least one note carries `tags:`, absent otherwise                              |
-| `params.description`              | `site.description`, which is required                                                                                                                       |
-| `params.author`                   | `package.json` `author`, its `name`; absent when the package declares none                                                                                  |
-| `params.cdnBaseURL`               | `site.assets`, which is required                                                                                                                            |
-| `params.brand`                    | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                           |
-| `params.list`                     | `site.list`                                                                                                                                                 |
-| `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     |
+| Key                               | Derived from                                                                                                                                            |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `baseURL`                         | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                     |
+| `title`                           | `packageBuild.manifest.title`, which is required                                                                                                        |
+| `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`                                                                                    |
+| `themesDir`                       | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/`                            |
+| `theme`                           | the installed `@heroiclands/hugo-theme`, so `hugo-theme`                                                                                                |
+| `disableKinds`                    | the toolchain, which renders a site as its homepage and its pages: `["section", "taxonomy", "term", "RSS"]` on every site, whatever its notes carry     |
+| `taxonomies`                      | the toolchain — never written, because `taxonomy` and `term` are disabled kinds                                                                         |
+| `outputs`                         | the toolchain — never written, because every listing kind is disabled                                                                                   |
+| `params.description`              | `site.description`, which is required                                                                                                                   |
+| `params.author`                   | `package.json` `author`, its `name`; absent when the package declares none                                                                              |
+| `params.cdnBaseURL`               | `site.assets`, which is required                                                                                                                        |
+| `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 |
 
 The site build reads the navigation from the cache only. A cold cache is an
 error naming the command that fills it:
@@ -1018,13 +981,13 @@ build the same way:
 
 > ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
 
-Nothing else is emitted. A site whose notes carry no `tags:` publishes no
-taxonomy pages — `[taxonomies]` and `[outputs]` go unwritten, and Hugo's
-defaults never apply because `taxonomy` and `term` are disabled kinds. A site
-with at least one tagged note publishes `/tags/` and a page per tag: Hugo's
-own default taxonomy pair also declares `category`, so `[taxonomies]` names
-only `tag`, and `[outputs]` restricts both to `HTML` so neither produces a
-feed. Every other key is `site.hugo`'s to add.
+Nothing else is emitted. `home` and `page` are the only kinds a site
+renders: the homepage is the mount's `_index.md`, every note is a page, and
+`section`, `taxonomy`, `term` and `RSS` are disabled on every site — so no
+`[taxonomies]` or `[outputs]` is written, Hugo's default taxonomy pair never
+applies, and a note's `tags:` reach the page's front matter and nothing
+else. A tag is a field a content table filters on, not a page of its own.
+Every other key is `site.hugo`'s to add.
 
 ### `pdf`
 
@@ -1332,9 +1295,8 @@ its content tree's addresses mount inside the package.
 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, no `site.sections` / `site.landing`
-output. `content` is the homepage plus every page the content tree
-publishes. `publishesContentPages(config)`, exported from
+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
@@ -1706,17 +1668,19 @@ the source directory:
 
 ## Every retired or forbidden key, in one place
 
-| Key                                                                                                                                                                                                                                                                                                         | Why                                                                                                                                                    |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `publish.address.landing`                                                                                                                                                                                                                                                                                   | Retired — named a whole-section landing, and there are no sections to address.                                                                         |
-| `packs[].folders`                                                                                                                                                                                                                                                                                           | Retired — a folder is a note (`type: folder`), materialised by the pack whose documents reference it.                                                  |
-| `rootDir`                                                                                                                                                                                                                                                                                                   | Forbidden in a YAML configuration — always the file's own directory.                                                                                   |
-| `foundryPackage`                                                                                                                                                                                                                                                                                            | Forbidden in a YAML configuration — always the adjacent `package.json` `name`.                                                                         |
-| `homepage`, `author`                                                                                                                                                                                                                                                                                        | Forbidden in a YAML configuration — always the adjacent `package.json`'s own `homepage` and `author`.                                                  |
-| `stats.systemId`                                                                                                                                                                                                                                                                                            | Forbidden in every configuration — derived from `packageKind`, `requiresSystem` or a lone declared system.                                             |
-| `stats.systemVersion`                                                                                                                                                                                                                                                                                       | Forbidden in every configuration — derived from `package.json` (a system) or `systems:` / `relationships.systems` (a module).                          |
-| `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs`                                                                                                                                                             | Forbidden — each is derived from `package.json` or the top level of `package-build.config.yaml`; see [`packageBuild.manifest`](#packagebuildmanifest). |
-| `site.out`                                                                                                                                                                                                                                                                                                  | Retired — the site build writes its content mount at `build/hugo/content`, beside the generated `hugo.toml`.                                           |
-| `site.hugo.baseURL`, `.title`, `.locale`, `.publishDir`, `.contentDir`, `.themesDir`, `.theme`, `.disableKinds`, `.taxonomies`, `.outputs`, `.params.description`, `.params.author`, `.params.cdnBaseURL`, `.params.brand`, `.params.list`, `.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`.                                                                                            |
-| `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. |
+| Key                                                                                                                                                                                                                                                                                         | Why                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `publish.address.landing`                                                                                                                                                                                                                                                                   | Retired — named a whole-section landing, and there are no sections to address.                                                                         |
+| `packs[].folders`                                                                                                                                                                                                                                                                           | Retired — a folder is a note (`type: folder`), materialised by the pack whose documents reference it.                                                  |
+| `rootDir`                                                                                                                                                                                                                                                                                   | Forbidden in a YAML configuration — always the file's own directory.                                                                                   |
+| `foundryPackage`                                                                                                                                                                                                                                                                            | Forbidden in a YAML configuration — always the adjacent `package.json` `name`.                                                                         |
+| `homepage`, `author`                                                                                                                                                                                                                                                                        | Forbidden in a YAML configuration — always the adjacent `package.json`'s own `homepage` and `author`.                                                  |
+| `stats.systemId`                                                                                                                                                                                                                                                                            | Forbidden in every configuration — derived from `packageKind`, `requiresSystem` or a lone declared system.                                             |
+| `stats.systemVersion`                                                                                                                                                                                                                                                                       | Forbidden in every configuration — derived from `package.json` (a system) or `systems:` / `relationships.systems` (a module).                          |
+| `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs`                                                                                                                                             | Forbidden — each is derived from `package.json` or the top level of `package-build.config.yaml`; see [`packageBuild.manifest`](#packagebuildmanifest). |
+| `site.out`                                                                                                                                                                                                                                                                                  | Retired — the site build writes its content mount at `build/hugo/content`, beside the generated `hugo.toml`.                                           |
+| `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`.                                                                                            |
+| `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. |

package/docs/content-format.md

@@ -2249,11 +2249,26 @@ A SoHL "being" document will be created, as will an "HM3" document.
 
 ### type: homepage
 
-A homepage for the module will be created.
-
-The contents will be available in a page at `https://www.heroiclands.org/<package>/`.
-
-It will also generate a single JournalEntry located at the top level of the "journals" compendium named "\_Introduction".
+The package's front page, published at `https://www.heroiclands.org/<package>/`.
+Exactly one note in a content tree declares this type, and it compiles into
+no Foundry document: it is a page and nothing else.
+
+It declares a `shortcode` — conventionally `root` — because that is what a
+link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
+resolves to `/<package>/`. The shortcode names the page in links; its address
+is the package root. `title` defaults to `packageBuild.manifest.title`; a
+`description` and a `banner` are read by the theme's hero; any other
+top-level key is passed through to the page as a theme parameter.
+
+The page is its body, published verbatim: no wikilink is resolved on it and
+no table expanded, so its links are markdown links, package-relative
+(`kb/rules/`) or external. An index of what the package publishes is not
+written here and is not generated anywhere — it is a `doc` note carrying a
+content table, linked from this page like any other.
+
+Two top-level keys are refused, because neither decides anything on a page:
+`id`, the Foundry document id a compendium UUID is built from, and `landing`,
+a card block — the homepage is a page with a body, rendered as one.
 
 ### type: vehicle
 
@@ -3137,21 +3152,16 @@ any other, and the audience is the section it sits in.
 Write `type: doc`, `subType: reference`, `shortcode: <type>` — so the
 affiliations introduction is `doc-affiliation`, addressed and linked like
 anything else, and typically carrying a generated table of what it introduces.
-It has no build path of its own; the package's own front page already works this
-way (`homepage-root`).
+It has no build path of its own, and it is the only kind of index there is: a
+site is its homepage and its pages, and nothing is generated between them.
 
-There is no landing page and no section. A `README.md` used to _be_ its
-section's landing, and a `subType: collection` note with a top-level `section:`
-key was a second way to say the same thing. All of it is retired, because a
-section appears in **no address**: a
+There is no landing page and no section. A section appears in **no address**: a
 page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
 section is what Hugo calls a content directory, and the note format does not
 carry one.
 
-So a `doc`'s `subType` is a **genre** and nothing else, closed to the three
-values above. It briefly had to accept a content type as well, because a
-landing's `subType` named the section it addressed; with no landings, one field
-has one reading again.
+So a `doc`'s `subType` is a **genre** and nothing else, closed to the values
+above.
 
 ### type: macro
 

package/docs/getting-started.md

@@ -780,10 +780,11 @@ values, and the content mount — for `hugo --source build/hugo` to render
 into `build/site/<contentPackage>/`. There is no Hugo configuration to
 write: the file is generated on every run, and what is genuinely the
 package's own — the wording of its "page not found" page — goes in the
-`site:` block as `site.notfound`. Set `publish.site: content` and name the
-sections under `site.sections`, and the same command publishes the content
-tree's every page beside the homepage. [`project-setup.md`](project-setup.md)
-gives the npm scripts.
+`site:` block as `site.notfound`. Set `publish.site: content`, and the same
+command publishes the content tree's every page beside the homepage — one
+page per note, and nothing generated between them; an index of what the
+package publishes is a `doc` note carrying a content table.
+[`project-setup.md`](project-setup.md) gives the npm scripts.
 
 **Another package's content.** Declare a dependency under `relationships`, and
 `content-build deps fetch` caches that release's published content index so

package/docs/project-setup.md

@@ -254,7 +254,7 @@ package carries this group:
 `build:site-content` writes the whole Hugo source tree under `build/hugo/` —
 the generated `hugo.toml` and the content mount — with `content-build site`;
 `build:site-html` runs Hugo over it, rendering into `build/site/<contentPackage>/`;
-`build:site-root` writes the deployment's `_headers` and `_redirects` beside
+`build:site-root` writes the deployment's `_headers` beside
 that; and `serve:site` does the first and then `hugo server` for a live
 preview. The repository carries no Hugo configuration of its own: `hugo.toml`
 is generated on every run from `package.json`, `package-build.config.yaml`,