@heroiclands/package-build 13.0.0 → 15.0.0

package/CONTENT.md

@@ -138,7 +138,6 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
-    landing: readme
 
 # How this repository frames the website `content-build site` publishes.
 # Framing only: addresses come from `publish.address` above.
@@ -456,9 +455,9 @@ error: pack "characters" (Actor) reads the compiled output of the Item pack
 
 ### An item type's default art
 
-A note that carries no `img:` gets its type's **default art**, and a type
-declares that art in the same place it declares its builder. An `itemBuilders`
-entry may be written two ways:
+A note that names no art gets its type's **default art**, and a type declares
+that art in the same place it declares its builder. An `itemBuilders` entry may
+be written two ways:
 
 ```js
 itemBuilders: {
@@ -479,8 +478,60 @@ same `resolveImg` rule as a note's `img:`, so `icons/relic.svg` means _this_
 repository's asset root — `modules/sohl-relics/assets/icons/relic.svg` — and an
 already-served path (`systems/sohl/assets/icons/…`) passes through untouched.
 
-**A type with neither is a build error, deliberately.** When a note sets no
-`img:` and its type pairs none, the pack build aborts rather than shipping an
+#### "Names no art" and "wants no art" are different (#218)
+
+A note has two ways to leave `img:` empty, and they mean opposite things:
+
+| a note writes  | it means                             | it compiles with |
+| -------------- | ------------------------------------ | ---------------- |
+| nothing at all | _unset_ — name me no art             | the type default |
+| `img: null`    | the same thing, said out loud        | the type default |
+| `img: ""`      | _blank on purpose_ — I want no image | no image         |
+| `img: <path>`  | this art                             | that path        |
+
+`resolveImg` returns `null` for the first two and `""` for the third, and every
+caller pairs its default with **nullish** coalescing — `resolveImg(fm.img) ?? itemArt(type)`.
+Never `||`: that collapses a deliberate blank back into the default and takes the
+distinction away again, which is exactly what the function used to do.
+
+**`portrait` is the same field twice over.** A being carries `img` (its token
+art) and `portrait` (its sheet portrait) independently, and both resolve through
+`resolveImg`, so the rule above is the rule for both.
+
+This is the convention the project already holds for an optional "not specified"
+DataModel string — `nullable, initial: null`, so "unset" is one honest value
+rather than two.
+
+> **The rule is `img`'s, and does not extend to `title`.** `title` is not art
+> and never reaches `resolveImg`, so nothing here applies to it.
+>
+> The reason used to be sharper, and is no longer true: a note's top-level
+> `title` was _also_ the shared source for an `affiliation` item's `system.title`
+> (`sohl/item-fields.mjs`, "the style of address the office carries"), so one
+> authored key fed two unrelated destinations that disagreed about what empty
+> means — and `title: null` stringified into the compiled document as the literal
+> `"null"`. That collision is gone: the field declares `topLevelMeans`, and the
+> top-level key is no longer a source for it (#218).
+>
+> So `title: null` is now a note declining to state a heading, and the site
+> emitter's `fm.title ?? name` falls back to `name.full`. `title: ""` still
+> publishes a deliberately blank heading, and nothing warns about that yet.
+
+Because `""` used to mean "unset", a note still carrying that spelling has
+quietly changed meaning, and the frontmatter lint says so — for either art
+field:
+
+```
+Note.md:9:1: warning: `img: ""` means "ship no art at all" — it no longer falls
+back to this type's default. Write `img: null` for a note that simply names
+none; keep `""` only where the document is meant to have no image
+```
+
+A warning, not an error: the note still compiles, to a document that is merely
+iconless.
+
+**A type with neither is a build error, deliberately.** When a note names no
+art and its type pairs none, the pack build aborts rather than shipping an
 item with a mismatched icon:
 
 ```
@@ -571,6 +622,47 @@ system `S` is:
 `sohl:`", which is the degenerate case where source and destination happen to
 share a name.
 
+**A spelling that means two different things skips step 3.** Because a field's
+`name` doubles as its identity and as the shared property it draws from, the two
+coincide only while the note vocabulary and the system vocabulary agree about
+what a spelling means. `title` is where they do not. A note's top-level `title`
+is _the title of the note_ — the heading its page publishes under, which the
+site emitter reads. An `affiliation` item's `system.title` is _the style of
+address the office carries_ — Ajaw, Warden, a person's style within the body.
+They are unrelated quantities, and step 3 used to feed the second from the first
+(#218).
+
+That was not merely untidy, because **step 3 answers without applying
+`field.default`** — only step 2 does — so an authored `title: null` reached the
+field's `String()` coercion unguarded and shipped as the literal string `"null"`.
+
+So a field may declare `topLevelMeans`: what the top-level key of that name means
+_instead_. Declaring it removes step 3 for that field, and the value is the
+reason rather than a bare flag, so the collision is legible where the field is
+declared and the generated field reference can print it. It is a per-field
+opt-out, not a change to the order — step 3 is right wherever the two levels
+state the same quantity, which is nearly everywhere: `subType` is the other
+declared item field spelled like a note-level key, and there the two agree by
+design.
+
+**An exempted field is still authorable**, at the two positions that describe the
+document rather than the note:
+
+```yaml
+title: The Order of the Silver Hand # the note's own heading — reaches the page
+type: affiliation
+subType: order
+sohl:
+  system:
+    title: Warden # → document.system.title, the style of address
+```
+
+`sohl.title`, the legacy in-block position, works the same way. A membership — a
+`title` a particular being holds — is authored on the entry in that being's
+`sohl.items`, whose `system` is overlaid on the catalogue document directly.
+`data.title` is neither position: `title` is not a `data:` property any note type
+declares, so the frontmatter lint refuses it.
+
 **`<system>.system` is written through verbatim**, at the DataModel's own paths,
 with no renaming layer. A key the system's published `schema.json` does not
 declare for the subtype the note compiles into is an **error naming the note**,
@@ -806,15 +898,15 @@ 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. …
+assets/content/Beings/Folk.md:3:1: error: `subType` "common-folk" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. …
 ```
 
 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 old spelling was accepted for one transitional release, as a warning naming
+the replacement, because an error would have redded every tree that took the
+release before it had a chance to sweep. Every tree has swept, so the acceptance
+is gone (#210): `user-guide` is refused by the charset check like any other
+hyphenated value, and nothing retirement-specific was left to remove.
 
 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
@@ -1235,6 +1327,21 @@ 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.
 
+**A page states its address without the package base; everything pointing _at_
+it composes one** (#217). They read as one quantity and are two:
+
+| Written                                     | Form                        | Because                                                                                 |
+| ------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
+| A page's own `url:` front matter            | `/<type>-<shortcode>/`      | Hugo resolves it against `baseURL`, whose path already _is_ where the package is served |
+| Every `href` this build renders into a body | `<base><type>-<shortcode>/` | A browser resolves it against nothing                                                   |
+| A link-manifest `path`                      | `<type>-<shortcode>/`       | Measured against `site.base` and stripped; a consumer prefixes its own                  |
+
+`site.base` is the second and third of those and reaches the first not at all.
+It used to be written into the `url:` as well, so every consumer's Hugo prefixed
+its own base to a value that already carried one and published every content
+page a segment too deep — `/sohl/sohl/doc-rulesintro/`, 404 at the address the
+manifest, the sitemap and every inbound link named.
+
 **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
@@ -1247,9 +1354,8 @@ per section, and that is now the _only_ thing that makes one exist — see
 
 ### The address scheme
 
-Where the content tree mounts _inside the package_, and which note addresses a
-whole section rather than a page within one, differ between repositories and are
-both load-bearing. They are one setting, read by this command **and** by the page
+Where the content tree mounts _inside the package_ differs between repositories
+and is load-bearing. It is one setting, read by this command **and** by the page
 emitter, so the address a manifest publishes is the address a page is emitted at
 — stating it twice is how a manifest comes to assert a URL that resolves at build
 time and 404s for the reader.
@@ -1260,7 +1366,6 @@ publish:
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
-    landing: readme # inert since #204; still accepted
 ```
 
 - **`prefix`** — the content tree's mount within the package: the Hugo directory
@@ -1270,14 +1375,9 @@ publish:
   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.
+
+`prefix` is the whole scheme. The `collection` subtype and the top-level
+`section:` key are refused by name (#202).
 
 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
@@ -1371,7 +1471,8 @@ 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 front matter's `url`
-decides where it publishes.
+decides where it publishes, and states it relative to the site root — `site.base`
+does not reach it (#217).
 
 **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
@@ -1382,7 +1483,7 @@ published beside the content:
 ```yaml
 site:
   out: kb/content # required; wiped on every run
-  base: /sohl/ # default: /<contentPackage>/
+  base: /sohl/ # default: /<contentPackage>/ — hrefs only, never a page's `url:`
   packages: [sohl, thalorna] # default: just contentPackage
   backfillSections: true
   landing: { title: Knowledgebase, type: knowledgebase }
@@ -1402,18 +1503,18 @@ site:
     dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
 ```
 
-| Key                | What it decides                                                                                  |
-| ------------------ | ------------------------------------------------------------------------------------------------ |
-| `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`         | 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 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.                                                                           |
+| Key                | What it decides                                                                                                                                                                                                                                       |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.                                                                                                                                                                |
+| `base`             | Where the package is served: the prefix on every rendered `href`, and what a manifest `path` is measured against. It reaches no page's own `url:` — see [A page's URL is its address](#a-pages-url-is-its-address). Defaults to `/<contentPackage>/`. |
+| `packages`         | Which content packages this site renders. Defaults to its own.                                                                                                                                                                                        |
+| `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 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
 
@@ -1431,7 +1532,8 @@ Two consequences follow, and neither is optional:
   `_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.
+  file happened to be written. A section that wants that query run for it says
+  so with `listType` — see below.
 
 Whatever the entry may carry is the whole of what the section can say.
 
@@ -1440,18 +1542,63 @@ Whatever the entry may carry is the whole of what the section can say.
 | `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
 | `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. |
+| `listType`    | no       | The content **type** whose pages this section lists.                      |
+| `listSubType` | no       | Narrows that to one **subType**. Only with a `listType`.                  |
 
-`readmeSections` takes the same three, for a **`trees`** entry: those pages keep
+`readmeSections` takes the same keys, 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.
 
+#### Saying what a section lists
+
+A generic list layout has nothing to render, because the membership a section
+landing used to get free from Hugo's page tree no longer exists anywhere the
+theme can read: not on the page, not on the landing, not in any URL — only here.
+So a section states its own query, and a layout substitutes it when `.Pages` is
+empty:
+
+```yaml
+sections:
+  being: { title: Beings, listType: being }
+  rules: { title: Rules, listType: doc, listSubType: rules }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
+
+emits, for the last of those, `user-guide/_index.md`:
+
+```yaml
+---
+title: User Guide
+listType: doc
+listSubType: userguide
+---
+```
+
+Three things about the spelling, each of them load-bearing:
+
+- **Not `type`.** On an `_index.md` that is Hugo's own layout selector — a
+  landing carrying `type: doc` is rendered by `layouts/doc/list.html` rather
+  than the default list template — so writing the content type there would
+  silently change which template serves the landing. This build already relies
+  on that behaviour for the mount's own `landing`.
+- **Not inferred from the section's name.** A section is named for a URL the
+  site chose; a type and a subType are addresses. They need not agree, and on
+  `sohl` they do not: the section is `user-guide`, because that is a published
+  URL, while the subType is `userguide` because an address segment is
+  alphanumeric (#207). Both values are checked against that charset here, so
+  copying the section's name in is refused rather than quietly matching nothing.
+- **`listSubType` needs a `listType`.** A subType only tells pages apart within
+  a type — `rules`, `userguide` and `reference` are all `doc` — so alone it
+  names no query.
+
 **The vocabulary is closed, and a key outside it is refused by name:**
 
 ```text
 package-build config: `site.sections.affliction.descrption` is not a
-recognized option (expected one of: title, banner, description).
+recognized option (expected one of: title, banner, description, listType,
+listSubType).
 ```
 
 That refusal is the point. `landing` is passed through unvalidated because it is
@@ -1460,7 +1607,10 @@ entry is written fourteen to twenty times per build against a contract every
 package and every section shares, so an unbounded one would let a mistyped
 `descrption:` publish into front matter, be read by nobody, and say nothing to
 anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
-buys a build that cannot quietly emit a key no theme reads.
+buys a build that cannot quietly emit a key no theme reads. `listType` and
+`listSubType` are that growth: two named keys, checked, rather than an open
+passthrough in which `listTpye:` would publish and no landing would list
+anything.
 
 The **writers** name no keys: a section's `_index.md` is whatever the entry
 resolved to, `title` first. So extending the vocabulary is a change to the
@@ -1624,7 +1774,7 @@ path now rides on the error, and the loader that read the file resolves it
 against the YAML, so all of them come out located:
 
 ```text
-package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner).
+package-build.config.yaml:382:64: error: package-build config: `site.sections.being.descrption` is not a recognized option (expected one of: title, banner, description, listType, listSubType).
 ```
 
 The same two rules apply. A key the file never declares — a required one that is

package/MIGRATING.md

@@ -1,3 +1,188 @@
+# Migrating to `@heroiclands/package-build` 15.0.0
+
+**Three unrelated changes ship in this major, and they ask different
+repositories for different things.** A page's `url:` front matter is now stated
+relative to the **site root** (#217), which a site-publishing repository answers
+by deleting one line; an empty art path now means the opposite of an absent one
+(#218), which a content tree answers by sweeping `img: ""` and `portrait: ""` to
+`null`; and a note's own `title` no longer reaches an `affiliation` item's
+`system.title` (#218), which asks nothing of any repository that exists today.
+
+Route yourself by what you have. A repository that publishes no site skips
+§1–§2. One that authors no empty art path skips §3–§4. One with no
+`type: affiliation` notes skips §6 — and §5, which is only the seam between the
+two halves of #218.
+
+## 1. Drop the `site.base: "/"` stopgap (#217)
+
+If your repository set it to stop every page publishing at
+`/<package>/<package>/<address>/`, delete the line — the default,
+`/<contentPackage>/`, is now right for both halves:
+
+```yaml
+site:
+  out: kb/content
+  # base: "/"   ← delete this
+```
+
+Keeping it is no longer harmless: the addresses stay correct either way, but
+every same-package link this build renders into a page body stays short
+(`/doc-skills/` rather than `/sohl/doc-skills/`) and 404s.
+
+A repository that is genuinely served somewhere other than
+`/<contentPackage>/` still says so here, and that value still reaches every
+`href`.
+
+## 2. What the `url:` change does _not_ touch
+
+- No note edits, and no configuration key added or removed.
+- Every link-manifest entry, including each entry's `path`, is byte-identical.
+- Every compiled compendium document is unchanged.
+- `trees` pages and section landings state no `url:` and do not move.
+
+The published address of every content page **does** move — from
+`/<package>/<package>/<address>/`, where nothing linked, to
+`/<package>/<address>/`, which is what the link manifest, the sitemap and every
+inbound link already named.
+
+## 3. Sweep `img: ""` and `portrait: ""` to `null` (#218)
+
+`resolveImg` opened with `if (!raw) return ""`, and every caller applied its own
+default to the result with `||`. So `""`, `null` and an absent key were one
+case: all three compiled to the type's default art, and a note had no way to say
+"ship no image" at all.
+
+They are now three values with two meanings:
+
+| a note writes  | it means                             | it compiles with |
+| -------------- | ------------------------------------ | ---------------- |
+| nothing at all | _unset_ — name me no art             | the type default |
+| `img: null`    | the same thing, said out loud        | the type default |
+| `img: ""`      | _blank on purpose_ — I want no image | no image         |
+
+So a note still carrying `img: ""` **loses its default art**. The same holds for
+`portrait:`, which a being carries independently of `img` and which resolves
+through the same function. Find them both:
+
+```bash
+grep -rnE '^[[:space:]]*(img|portrait):[[:space:]]*""[[:space:]]*$' assets/content --include='*.md'
+```
+
+and write `null` in each — unless the document really is meant to have no image,
+which is what `""` now says. Before this release `sohl-thalorna` swept forty-five
+`img: ""` notes and `sohl-kethira-basic` eleven `portrait: ""` beings; `sohl`
+authors neither.
+
+The frontmatter lint reports every one that is left, as a warning:
+
+```
+Note.md:9:1: warning: `img: ""` means "ship no art at all" — it no longer falls
+back to this type's default. Write `img: null` for a note that simply names
+none; keep `""` only where the document is meant to have no image
+```
+
+## 4. Custom callers pair their default with `??`, not `||`
+
+`resolveImg` returns `string | null` now: `null` for an unset path, `""` for a
+deliberate blank. A consumer that calls it directly — a custom item builder, a
+compiler of its own — must switch:
+
+```diff
+-img: resolveImg(fm.img) || MY_DEFAULT,
++img: resolveImg(fm.img) ?? MY_DEFAULT,
+```
+
+`||` still compiles and still looks right; it silently reinstates the old
+conflation, because `""` is falsy. Every caller in this package moved:
+`sohl/items.mjs`, three in `sohl/actors.mjs` (`img`, `portrait`, and the
+prototype token's `texture.src`), and `engine/macros.mjs`.
+
+`itemArt()` is unaffected — a registry entry with no art throws before the
+translation, so its result is never the unset case.
+
+## 5. `title` is **not** on the art rule
+
+`resolveImg`'s rule reads as a general one about optional strings, and it is
+not — it belongs to the function, and `title` never goes through it. So do not
+extend §3's sweep to `title`, and do not read the table in §3 as saying anything
+about it.
+
+**The reason has changed since this section was first written, and the earlier
+one is no longer true.** It used to be that a note's top-level `title` was
+_simultaneously_ the page's heading and the shared source for an `affiliation`
+item's `system.title`, so `title: null` did not fall back — it stringified, and
+the compiled document shipped the literal string `"null"`. That collision is what
+§6 removes: the top-level key is no longer a source for the item field at all.
+
+So `title: null` is now simply a note declining to state a heading, and the site
+emitter's `fm.title ?? name` falls back to `name.full` as it always did. It
+reaches no document field and stringifies nothing.
+
+`title: ""` still publishes a **deliberately blank heading** — which is what cost
+fifteen `sohl-thalorna` notes their names (HeroicLands/sohl-thalorna#129) — and
+nothing warns about it yet. Whether the frontmatter lint should is #218's, still
+open, and deliberately not settled by the art-field warning in §3.
+
+## 6. A note's own `title` no longer fills `system.title` (#218)
+
+**No note edit, no URL change, and no compiled document moves.** An
+`affiliation` item's `system.title` stops falling back to the note's own
+top-level `title`. The two were never the same quantity — a note's `title` is
+the heading its page publishes under, while `system.title` is the style of
+address an office carries, Ajaw or Warden — and no note in any content tree
+relied on the fallback, so `content-build package compile` emits byte-identical
+`build/packs-json` for every consumer.
+
+Only a `type: affiliation` note is affected, and only if it carries a top-level
+`title` it meant as the item's field rather than as the page's heading:
+
+```bash
+grep -rl '^type: affiliation' assets/content --include='*.md' \
+  | xargs grep -l '^title:'
+```
+
+Anything that turns up wanted one of the two positions that describe the
+_document_ rather than the note — `sohl.system.title`, or `sohl.title`, the
+legacy in-block key most trees already write. A membership's title belongs on
+the entry in the being's `sohl.items`, as `system.title`.
+
+`data: { title: ... }` is not a position and never was: `title` is not a `data:`
+property any note type declares, so `content-build lint` refuses it.
+
+### Regenerate the item field reference
+
+The generated page now prints, under each affected type's table, what the
+top-level key of a non-shared field means instead — so an author reading the
+table learns that writing `title:` at the top of a note will not fill this
+field. Re-run the generator and commit the result, or a repository that checks
+the page for staleness reports it stale:
+
+```bash
+npx content-build docs item-fields --out <the path your repo uses>
+```
+
+### Declaring your own non-shared field
+
+A field in an `itemBuilders` `fields:` declaration may now carry
+`topLevelMeans`, whose value is _what the note's top-level key of that name
+means instead_. Declaring it removes the shared top-level position from that
+field's resolution order:
+
+```js
+{
+    name: "title",
+    to: "title",
+    ...STRING,
+    default: "",
+    topLevelMeans: "the note's own title — the heading its page is published under",
+    describe: "The style of address the office carries.",
+}
+```
+
+The value is the reason rather than a bare flag on purpose: the next person
+adding a field needs to know the question exists, and a boolean with a comment
+beside it is two statements of one rule.
+
 # Migrating to `@heroiclands/package-build` 12.0.0
 
 **No note edit, no URL change, and one thing to check in the Hugo layer.** A
@@ -49,12 +234,18 @@ That is the shape a content catalog wants regardless — it groups by what a pag
 _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
+A site rendering through a **shared theme** has no layout of its own to edit. As
+of 13.1.0 the section declares its query instead, and the theme runs it:
+
+```yaml
+sections:
+  weapongear: { title: Weapons, listType: weapongear }
+  user-guide: { title: User Guide, listType: doc, listSubType: userguide }
+```
 
-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).
+`listType` is the content type, not the section's name — the two need not agree,
+and `listSubType` narrows a type whose genres share it. See
+[What a section may declare](CONTENT.md#what-a-section-may-declare).
 
 ## What did not change