@heroiclands/package-build 11.0.0 → 13.0.0

package/CHANGELOG.md

@@ -1,5 +1,284 @@
 # @heroiclands/package-build
 
+## 13.0.0
+
+### Major Changes
+
+- 0c2def0: A section is a Hugo directory concept, and the note format no longer carries one
+  (#204). Content pages emit **flat** under the mount, named by their address; the
+  `README.md` landing convention, `sectionOf`, the `<section>/` output routing, and
+  the "no section, so nowhere to file the page" refusal are all gone.
+  
+  **Why it goes.** Since #181 a page's URL _is_ its address,
+  `/<package>/<type>-<shortcode>/`, so a section appears in **no address at all**.
+  Its only remaining job was choosing the directory a page was written into, and
+  the only reason that mattered was Hugo's rule about what counts as a section —
+  `writeSectionLandings`'s own docstring said both of its jobs "exist because of
+  how Hugo decides what a section is". So the note format carried a filename
+  convention, a landing rule, a routing function and a refusal in order to satisfy
+  a rendering engine's directory semantics. #197 was the bill for that: `subType`
+  did double duty — a genre for an ordinary `doc`, a URL section for a `README` —
+  the two vocabularies collided, and it took #198, #200, #201 and a release to
+  settle by widening one of them rather than by removing the overload.
+  
+  **A page that introduces the notes of a type is now an ordinary note**, named by
+  convention and with no build path of its own: `type: doc`, `subType: reference`,
+  `shortcode: <type>`, addressed `doc-<type>`. The package's own front page already
+  worked this way (`homepage-root`, #182).
+  
+  | Surface                                | Before                                        | After                                             |
+  | -------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
+  | A content page's file                  | `<mount>/<section>/<type>-<shortcode>.md`     | `<mount>/<type>-<shortcode>.md`                   |
+  | A content page's `url:`                | `/<package>/<type>-<shortcode>/`              | **unchanged**                                     |
+  | A `README.md` in the content tree      | its section's landing, addressed `<section>/` | an ordinary page, addressed `<type>-<shortcode>/` |
+  | A `doc` with no `subType`              | refused — "no section"                        | published, at `doc-<shortcode>/`                  |
+  | A `doc`'s `subType`                    | a genre, or a section address on a `README`   | a genre, closed to what the type declares         |
+  | `packageAddress(fm, { isReadme })`     | branched on the filename                      | a pure function of the frontmatter                |
+  | `sectionOf`                            | exported                                      | removed                                           |
+  | `declaredSections`                     | exported, fed the lint                        | removed — it had no other reader                  |
+  | `lintNote` / `lintFrontmatter` options | `landing`, `types`, `sections`                | removed                                           |
+  
+  **The closed-set check becomes meaningful again.** #206, released alongside this,
+  put a retired-spelling warning and an address-charset error ahead of it in
+  `checkSubType`; removing the section branch from underneath leaves three checks
+  in one order — retired spelling, then charset, then the genres the type declares
+  — with nothing widening the last of them. A `doc` note whose `subType` names a
+  content type is refused again, `README` or not.
+  
+  **`site.sections` is not retired — it is now the whole of what a section is.**
+  With no page filed into `<section>/`, nothing else makes
+  `/<package>/<prefix><section>/` exist at all, so `writeSectionLandings` stays and
+  its role changes from backfilling directories that pages created to _declaring_
+  the Hugo sections a site wants. Two consequences follow for a consuming site:
+  
+  - **Declare every section the site links to.** A card, menu entry or breadcrumb
+    pointing at an undeclared section is a 404.
+  - **A section landing lists no child pages.** Its directory holds only its own
+    `_index.md`, so a layout reading `.Pages` finds nothing; one that queries
+    `site.RegularPages` by `Params.type` is unaffected, and that is the shape a
+    content catalog wants anyway — it groups by what a page _is_, not by where its
+    file happened to be written.
+  
+  **`publish.address.landing` is inert, and still accepted.** Both publishing
+  consumers declare `landing: readme`, which stated something true when they wrote
+  it; refusing it now would break them over a correct statement, and silently
+  ignoring it would be worse. It selects nothing and is deleted once no
+  configuration writes it — the third step, and a separate change. The retired
+  `collection` value stays refused by name (#202).
+  
+  **Migration.** No note edit is required, and **no published URL moves** — an
+  address never contained a section. What a consuming site must check is its
+  layouts and its `site.sections`, per the two consequences above. Verified against
+  `sohl`, `sohl-thalorna` and `sohl-kethira-basic` at `origin/main`: `lint`,
+  `links`, `manifest` and `package compile` are byte-identical for all three (both
+  link manifests and every compiled pack document), and `sohl`'s emitted site is
+  byte-identical page for page, keyed by URL — all 1,606 addresses unchanged, 1,670
+  of 1,671 files identical. The one difference is a backfilled `kb/macro/_index.md`
+  that no longer exists, `macro` being the one section `sohl` did not declare;
+  nothing in its site or the shared theme links it.
+
+## 12.0.0
+
+### Major Changes
+
+- ab34b1c: Retire the `collection` landing rule, the `section:` frontmatter key it read,
+  and the `collection` doc subtype that selected it (#202). A section is landed by
+  the `README.md` in its directory, and that is now the only rule.
+  
+  **Why it goes.** Every publishing tree had already migrated: no note in `sohl`,
+  `sohl-thalorna` or `sohl-kethira-basic` declares `section:` or writes
+  `subType: collection`, and both publishing consumers configure `landing: readme`.
+  What was left was not merely unused but **unimplemented on one of the two sides
+  that must agree**. `engine/content-address.mjs` branched on the configured rule;
+  `engine/site-build.mjs` never read it — it derives `isReadme` from the basename
+  and treats a `README.md` as a landing whatever the configuration says. So under
+  `landing: collection` the link manifest and the emitted site would have disagreed
+  about where a page is, which is the single failure the shared address function
+  exists to prevent. With one rule they agree by construction.
+  
+  **`landing: collection` is refused, not merely unrecognized.** Reported as a bad
+  value it would read as a misspelling of the rule that survives, and an author
+  would correct the value rather than learn that the mechanism is gone. The
+  diagnostic names the key, says the rule is retired, says a section is landed by
+  its `README.md`, and says the `section:` key went with it — located to the line
+  and column in `package-build.config.yaml`, as every configuration finding is.
+  
+  **`section:` is refused the way `draft:`, `package:` and `aliases:` are.** It had
+  exactly one reader — the retired branch — and no schema or vocabulary declared
+  it, so nothing checked it: left in place it would be _ignored_, which reads to
+  its author as though it still works. It is now reported by `content-build lint`
+  and refused at compile, with the file, line and column.
+  
+  | Surface                          | Before                                | After                                  |
+  | -------------------------------- | ------------------------------------- | -------------------------------------- |
+  | `publish.address.landing`        | `readme` \| `collection`              | `readme` — the value is still accepted |
+  | `section:` in a note             | read under `collection`, else ignored | refused, at lint and at compile        |
+  | `subType: collection` on a `doc` | selected the rule                     | not a subtype the format declares      |
+  | `LANDING_RULES`                  | `["readme", "collection"]`            | `["readme"]`                           |
+  
+  **Migration.** Delete `landing: collection` from `publish.address` — or write
+  `landing: readme` — and make each section's landing the `README.md` in its
+  directory. Delete any `section:` a note still carries. A repository that already
+  configures `landing: readme` and writes no `section:` needs no change: `lint`,
+  `links` and `site` were verified byte-identical against `sohl`, `sohl-thalorna`
+  and `sohl-kethira-basic` at `origin/main`, including all 1,657 pages `sohl`
+  emits.
+  
+  **`publish.address.landing` itself survives, for now.** It is the key both
+  publishing consumers declare, and refusing a correct `landing: readme` would
+  break them over a statement that is still true. With one rule it selects nothing,
+  so it is a candidate for deletion once no configuration writes it — the third
+  step `package:` took (#56), and a separate change.
+
+### Minor Changes
+
+- ed06be0: Hold `type` and `subType` to the address charset, and rename a `doc`'s
+  `user-guide` subtype to `userguide` (#206).
+  
+  **The rule.** An address is `package-type-shortcode`, read back by counting
+  hyphen-separated segments, and that is sound for exactly one reason: no segment
+  may contain a hyphen. `ADDRESS_SEGMENT_PATTERN` (`^[A-Za-z0-9]+$`) stated it and
+  `SHORTCODE_PATTERN` aliased it, but only a **shortcode** was checked against it.
+  The other two values that reach an address were not: a `type` is the first
+  segment of every address, and a `doc`'s `subType` is the section it routes to —
+  a path segment of its own, and, under #204, a shortcode. Both are now held to
+  the same constant, read rather than restated; a third spelling of one rule is how
+  the disagreements found in #202 and #203 happened.
+  
+  **The diagnostic** is located where the value was written, in the standard form:
+  
+  ```text
+  assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. …
+  ```
+  
+  The charset is checked **ahead of** the closed-set check, which is what makes it
+  reach a type whose `subTypes` are declared but not yet enumerated (`being`) —
+  values nothing may otherwise claim to check.
+  
+  **`user-guide` became `userguide`**, the one declared value that broke the rule
+  and the only hyphenated `type` or `subType` in the vocabulary. A hyphenated
+  declaration can no longer be imported at all: the registry is checked against the
+  charset as `engine/note-vocabulary.mjs` loads.
+  
+  **The old spelling is accepted for one release, and says so.** A `doc` written
+  `subType: user-guide` is reported as a **warning** naming the note, the retired
+  value and its replacement, and the note still compiles:
+  
+  ```text
+  User_Guide/Actions.md:3:1: warning: `subType` "user-guide" is a retired spelling of "userguide" on a doc; write "userguide". …
+  ```
+  
+  _The ordering is the reverse of the usual, deliberately._ For a retired field the
+  sweep goes first; here it must go last. 43 `sohl` notes author `user-guide`
+  today, and declaring only the new spelling would invalidate all 43 with a release
+  they had no chance to sweep ahead of. So the acceptance ships first, consumers
+  rename, and a later change removes the acceptance — at which point the old
+  spelling falls through to the ordinary undeclared-value error with no code left
+  to remove. That later change is the breaking one; this one breaks nothing, which
+  is why it is a minor.
+  
+  **`type` gets no transitional path**, deliberately: no note in `sohl`,
+  `sohl-thalorna` or `sohl-kethira-basic` authors a hyphenated type, so an
+  acceptance would be dead code guarding a case that does not exist. Measured
+  against a pristine `origin/main` extraction of each tree, the only hyphenated
+  value of either key anywhere is the 43 `user-guide` notes.
+
+## 11.1.0
+
+### Minor Changes
+
+- 8906d7a: **A `README` landing's `subType` is checked against the sections the repository declares, not the genre list.**
+  
+  Two vocabularies were spelled with one key. For every note, `subType` is a
+  sub-kind of its type, checked against a closed list. For a `README` under
+  `publish.address.landing: readme` it is additionally the **URL section** —
+  `sectionOf` reads a `doc`'s `subType` as the segment the landing addresses — and
+  that is an open set the consuming repository names in `site.sections` /
+  `site.readmeSections`. `engine/frontmatter-lint.mjs` applied the closed reading
+  while `engine/content-address.mjs` applied the open one, so the two halves of the
+  toolchain disagreed about the same note: `content-build site` addressed and
+  published `Weapons/README.md` at `weapongear/`, and `content-build lint` refused
+  it because `doc` declares only `rules`, `user-guide` and `reference`. An item
+  section's landing was not expressible.
+  
+  The check now widens **for a landing only**, and only under `landing: readme`: a
+  `README` whose `subType` is its section may name any section the repository
+  declares, as well as any of its type's own genres — a genre is a section a `doc`
+  tree publishes under whether or not the repository describes it, so narrowing to
+  the configured set alone would refuse a correct `README`. An ordinary note's
+  `subType` stays closed to its type's genres, unchanged.
+  
+  **The guard survives**, checked against the set that actually decides where the
+  page goes:
+  
+  ```text
+  Weapons/README.md:4:1: error: `subType` "weapongeer" is the section this README
+  lands at, and nothing declares it: it is neither a section this repository
+  configures under `site.sections` / `site.readmeSections` (rules, user-guide,
+  weapongear, …) nor one of the subtypes doc declares (rules, user-guide,
+  reference). Did you mean "weapongear"?
+  ```
+  
+  Whether the value is an address is asked of `sectionOf` rather than by naming a
+  type, so the linter still knows no type names of its own; the section list is
+  read from the resolved configuration the site build renders those landings from,
+  through a new `declaredSections(config)`, so neither can name a section the other
+  does not.
+  
+  _Minor rather than patch_: `lintNote` and `lintFrontmatter` take two new
+  options (`landing`, `sections`) and `content-config.mjs` exports
+  `declaredSections`. Both options default to today's behaviour, so a caller that
+  passes neither — and a repository that declares no sections — is unaffected.
+  
+  Closes #197
+
+### Patch Changes
+
+- 68910b6: **A `README` landing may name any section that exists, not only a configured one.**
+  
+  #197 widened a landing's `subType` check by one term and it was the wrong one:
+  the sections the repository configures in `site.sections` /
+  `site.readmeSections`. That keys on configuration a consumer may legitimately not
+  have. `sohl-thalorna` has **no `site:` block at all** — it renders its site
+  through a local fork of the emitter — so `declaredSections` answered `[]`, the
+  accepted set collapsed back to the three `doc` genres, and five of its landings
+  were still refused for naming their own content type:
+  
+  ```text
+  assets/content/Characters/README.md:7:1: error: `subType` "being" is not one of the subtypes doc declares (rules, user-guide, reference)
+  ```
+  
+  A landing's `subType` is an **address**, so it is now checked against the
+  addresses that exist — the range of `sectionOf` over every note the format
+  permits, plus whatever the repository names:
+  
+  1. **Every content type the specification declares.** `sectionOf` returns
+     `fm.type` for a non-`doc` note, so `being`, `lore`, `scenario` and
+     `weapongear` are sections _by construction_, configured or not.
+  2. **The type's own subtypes** — `rules`, `user-guide`, `reference`.
+  3. **The configured sections**, which may name one that is neither: `sohl` has
+     `credits` and `dev-docs`.
+  
+  **The guard survives.** A misspelling is in none of the three, so it still fails,
+  and the near miss is drawn from the whole union. What is deliberately no longer
+  caught is a landing for a section that exists but is currently empty — which is
+  legitimate, and is why the set is the types the format _declares_ rather than
+  those _present in the tree_: `sohl` ships two such landings above tables that
+  stay empty until the first note of each type does.
+  
+  **The type list is the specification's, not the schema map's.** `NOTE_SCHEMAS`
+  declares 18 types and `docs/content-format.md` declares 23; `lore`, `place`,
+  `scenario`, `vehicle` and `armorlocation` are in the second only. Checking an
+  address against the schema map would refuse `Lore/README.md` for a reason that
+  is not about addresses, and would report one gap twice in two vocabularies.
+  Whether a note's fields can be checked is a different question, answered
+  elsewhere and reported on the notes themselves.
+  
+  `lintNote` / `lintFrontmatter` take a `types` option beside `sections`; both
+  default to empty, so a caller that passes neither is unaffected.
+  
+  Closes #200
+
 ## 11.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -796,6 +796,26 @@ 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]+$`** (#206) — the same
+constant a `shortcode` is held to, read rather than restated. A type is the
+first segment of every address, so a hyphen in one is read back as a segment
+boundary nobody wrote. A `subType` reaches no address since #204 retired
+sections, and keeps the rule anyway: it is a vocabulary term the toolchain keys
+on, and one charset that holds for every term is a rule an author can state. The
+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 an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. …
+```
+
+One declared value broke that rule: a `doc`'s `user-guide`, now **`userguide`**.
+The old spelling is accepted for one transitional release and reported as a
+**warning** naming the replacement — an error would red every tree that took the
+release before it had a chance to sweep, and the note still compiles to the
+correct page. A later release removes the acceptance, and the old spelling then
+falls through to the ordinary undeclared-value error.
+
 The vocabulary lives in `engine/note-vocabulary.mjs`, one entry per note type,
 taken from the content-format specification. It is note-format knowledge rather
 than any system's: `data:` holds what is true of the thing, and what a system
@@ -1206,15 +1226,24 @@ package's fixed mounts (`/<package>/` for the landing page, `/<package>/api/` fo
 generated API docs), neither of which contains a hyphen or names a type. So the
 namespace is provably disjoint rather than conventionally so.
 
-**Sections stay, as directories.** Hugo derives a page's section from where the
-file is written, not from its URL, and that section is what gives a landing page,
-`.CurrentSection` and the per-section layout lookup. So a page is still written
-into `<section>/`, and carries a front-matter `url:` publishing it at its
-address. The two are free to differ, and do.
-
-**A landing page is the one exception**, because it is not addressed by
-`(type, shortcode)` at all: it _is_ its section, so it addresses the section —
-under the content mount, where the section directories live (`kb/rules/`).
+**A page is written flat, named by its address** (#204). It used to be filed
+into `<section>/`, because Hugo derives a page's section from where the file is
+written and a section gave it a landing page, `.CurrentSection` and a per-section
+layout lookup. But a section appears in no address, so the note format was
+carrying a key, a filename convention, a landing rule and a synthesis pass in
+order to satisfy a rendering engine's directory semantics. The file is now
+`<mount>/<type>-<shortcode>.md` and the front-matter `url:` still publishes it at
+the package root, one level above.
+
+**There is no landing page.** A `README.md` was its section's landing and
+addressed the section itself; that is retired with the section. A page that
+introduces the notes of a type is an ordinary note addressed `doc-<type>`, with
+no build path of its own — exactly as the package's own front page is
+`homepage-root` (#182).
+
+**Sections stay, as configuration.** `site.sections` still writes an `_index.md`
+per section, and that is now the _only_ thing that makes one exist — see
+[What a section may declare](#what-a-section-may-declare).
 
 ### The address scheme
 
@@ -1231,33 +1260,35 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
-    landing: readme # default: readme
+    landing: readme # inert since #204; still accepted
 ```
 
-- **`prefix`** — the content tree's mount within the package: where its section
-  directories and their landing pages live. `sohl` publishes a knowledgebase
-  alongside generated API docs, so its sections sit under `kb/` (`kb/affliction/`)
-  while its pages address the package root (`affliction-aconite/`); `thalorna`'s
-  site is nothing but its content, so it has no prefix. It must end in a slash and
-  must not begin with one — where the _package_ is mounted is the consuming
-  build's knowledge and is never recorded here.
-- **`landing`** — which note is a section's landing page, and so is addressed by
-  the section rather than by `(type, shortcode)`:
-  - `readme` — a `README.md` addresses its section. A `doc` note then routes by
-    its `category` like any other, so a `category: collection` note publishes
-    under a literal `collection/` section.
-  - `collection` — a `doc` note whose `category` is `collection` addresses the
-    section it introduces, named by its authored `section`.
-
-  The two are alternatives rather than a pair that could both apply: each live
-  content tree holds notes the other rule would move.
-
-A note the scheme yields no address for — one carrying no `shortcode`, a `doc`
-with no subtype (so no section to be filed under), a collection note naming no
-section — is **reported and omitted**, never guessed. The command
-prints one located diagnostic per note and still writes the file, because a note
-with no address is ordinary while a manifest entry pointing at a page that does
-not exist is not.
+- **`prefix`** — the content tree's mount within the package: the Hugo directory
+  its pages are written under. `sohl` publishes a knowledgebase alongside
+  generated API docs, so its tree sits under `kb/` while its pages address the
+  package root (`affliction-aconite/`); `thalorna`'s site is nothing but its
+  content, so it has no prefix. It must end in a slash and must not begin with
+  one — where the _package_ is mounted is the consuming build's knowledge and is
+  never recorded here.
+- **`landing`** — **inert, and accepted only so it keeps loading.** It named
+  which note addressed a whole section rather than a page within one. There are
+  no sections in the note format (#204) and so no landings, so it selects
+  nothing; it is still accepted because both publishing consumers declare
+  `landing: readme` and refusing a correct statement would break them. It is
+  removed once no configuration writes it. The retired second rule, `collection`,
+  is still refused by name (#202), along with the `collection` subtype and the
+  top-level `section:` key.
+
+A note's `subType` is checked against the values its type declares, and only
+those. It briefly had a second reading — a `README` landing's `subType` was the
+_address_ it landed at, so the closed genre list could not answer for it (#197,
+#198, #200, #201) — and #204 removed the cause rather than widening the
+vocabulary again.
+
+The only note the scheme yields no address for is one carrying no `shortcode`.
+It is **reported and omitted**, never guessed: the command prints one located
+diagnostic per note and still writes the file, because a note with no address is
+ordinary while a manifest entry pointing at a page that does not exist is not.
 
 ## Publishing a website
 
@@ -1270,7 +1301,7 @@ The sibling of `package compile`: the same content tree, rendered as pages
 instead of compiled into packs. It does the walk, the frontmatter read, the
 address derivation, the address index, table expansion, wikilink resolution,
 code-fence protection, the foreign-manifest merge, the page emission and the
-section-landing backfill.
+section-landing synthesis.
 
 ### The homepage, and how much else is published
 
@@ -1300,8 +1331,9 @@ still refuses `id`. Everything else about its address is ordinary: it declares a
 [The homepage is addressed like every other note](#the-homepage-is-addressed-like-every-other-note)).
 `/<contentPackage>/` itself is a redirect the package authors, not a page this
 build writes. 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.
+filename — nothing in this format is decided by a file's name, which is why
+`sohl-thalorna` can keep a `README.md` in its content tree as 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`
@@ -1338,8 +1370,8 @@ module being withdrawable, and a homepage is one row in a routing table.
 The homepage's file is written at the root of `site.out` — the package's own
 site root, one level above the content mount, which is where
 `publish.address.prefix` puts everything else — under the name its address gives
-it, `homepage-root.md`. As with every other page, the file's location decides
-the Hugo section and the front matter's `url` decides where it publishes.
+it, `homepage-root.md`. As with every other page, the front matter's `url`
+decides where it publishes.
 
 **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
@@ -1375,20 +1407,33 @@ site:
 | `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`         | What each section says about itself on its landing — see below.                                  |
-| `readmeSections`   | The same, for a section whose landing comes from a `README`.                                     |
+| `sections`         | The Hugo sections this site declares, and what each says about itself — see below.               |
+| `readmeSections`   | The same, for a `trees` entry, whose landing comes from its own `README`.                        |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.     |
-| `backfillSections` | Write a bare `_index.md` for any other section directly under the mount.                         |
+| `backfillSections` | Write a bare `_index.md` for any other directory directly under the mount.                       |
 | `trees`            | Extra source trees published beside the content, preserving their source layout below a section. |
 | `pass`             | A named bundle of this repository's own body rewrites.                                           |
 | `passOptions`      | That bundle's options.                                                                           |
 
 ### What a section may declare
 
-A generated section landing is the **only** place a section can describe itself.
-A content package authors no `_index.md` for `weapongear` or `affliction`, so
-the file the theme reads is the one this build writes from `sections` — and
-whatever that entry may carry is the whole of what the section can say.
+**`sections` is what a section _is_ now** (#204). A content page is addressed
+`(type, shortcode)` and written flat under the mount, so no page creates a
+directory and nothing else makes `/<package>/<prefix><section>/` answer at all.
+A site that wants that address says so here, and this build writes the
+`_index.md` that makes Hugo agree it is a section.
+
+Two consequences follow, and neither is optional:
+
+- **Declare every section the site links to.** A card, a menu entry or a
+  breadcrumb pointing at a section nobody declared is a 404.
+- **A section landing lists no child pages.** Its directory holds only its own
+  `_index.md`, so a layout reading `.Pages` finds nothing. A layout that queries
+  `site.RegularPages` by `Params.type` is unaffected, and that is the shape a
+  content catalog wants anyway — it groups by what a page _is_, not by where its
+  file happened to be written.
+
+Whatever the entry may carry is the whole of what the section can say.
 
 | Key           | Required | What it does                                                              |
 | ------------- | -------- | ------------------------------------------------------------------------- |
@@ -1396,9 +1441,11 @@ whatever that entry may carry is the whole of what the section can say.
 | `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
 | `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
 
-`readmeSections` takes the same three, for a section whose landing comes from a
-`README` rather than from nothing. What the section declares wins over what the
-`README` happens to carry — the landing has to match the card that links to it.
+`readmeSections` takes the same three, for a **`trees`** entry: those pages keep
+their source layout below a named section, so the tree's own `README.md` is that
+section's landing. What the section declares wins over what the `README` happens
+to carry — the landing has to match the card that links to it. No content note
+reaches this map any more.
 
 **The vocabulary is closed, and a key outside it is refused by name:**
 

package/MIGRATING.md

@@ -1,3 +1,68 @@
+# Migrating to `@heroiclands/package-build` 12.0.0
+
+**No note edit, no URL change, and one thing to check in the Hugo layer.** A
+section is a Hugo directory concept that the note format no longer carries
+(#204): content pages are written **flat** under the content mount, named by
+their address, instead of into a `<section>/` directory.
+
+## 1. Nothing in the content tree changes
+
+A page's address never contained a section, so **no published URL moves**. A
+`README.md` in the content tree stops being its section's landing and becomes an
+ordinary page addressed `<type>-<shortcode>/` like every other note; if a tree
+still has one that was serving as a landing, it now publishes at its own address.
+No tree in this project had one.
+
+A `doc` with no `subType` used to be refused ("no section, so there is nowhere to
+file the page") and now publishes. Its `subType` is a **genre** again — closed to
+`rules`, `userguide`, `reference` — because it no longer doubles as a section
+address on a `README`. That closed check runs after the two #206 added ahead of
+it: a retired spelling is a warning naming its replacement, a hyphenated value
+is an error, and only then is the type's own list the reason.
+
+## 2. Declare every section your site links to
+
+`site.sections` is now the whole of what a section is. No page is filed into a
+section directory any more, so nothing else makes `/<package>/<prefix><section>/`
+exist:
+
+```yaml
+site:
+  sections:
+    being: { title: Beings, banner: banners/creature.webp }
+    weapongear: { title: Weapons, banner: banners/weapons.webp }
+```
+
+A card, menu entry or breadcrumb pointing at a section nobody declares is a 404.
+
+## 3. Check how a section landing lists its members
+
+A declared section's directory holds only its own `_index.md`, so a layout
+reading `.Pages` renders an empty listing. Query the site instead, on the page's
+own `type`:
+
+```go-html-template
+{{- $pages := where site.RegularPages "Type" "weapongear" -}}
+```
+
+That is the shape a content catalog wants regardless — it groups by what a page
+_is_ rather than by where its file happened to be written — and it is what
+`sohl`'s catalog layouts already do.
+
+## 4. `publish.address.landing` is inert, and still accepted
+
+It named which note addressed a whole section. There are no landings, so it
+selects nothing; `landing: readme` keeps loading because it stated something true
+when it was written, and the key is removed once no configuration declares it.
+`landing: collection` is still refused by name (#202).
+
+## What did not change
+
+- Every content page's `url:`, and so every published address.
+- Every link-manifest entry, including each entry's `path`.
+- Every compiled compendium document.
+- `site.sections` / `site.readmeSections` and what an entry may declare.
+
 # Migrating to `@heroiclands/package-build` 11.0.0
 
 **Two edits, and the second is one line per repository.** Every published page