@heroiclands/package-build 14.0.0 → 15.0.0

package/CHANGELOG.md

@@ -1,5 +1,189 @@
 # @heroiclands/package-build
 
+## 15.0.0
+
+### Major Changes
+
+- 5c16c02: Let a note's art path say "unset" and "blank on purpose" with two different values.
+  
+  `resolveImg` opened with `if (!raw) return ""`, and every caller then applied its
+  own default to the result with `||` — `resolveImg(fm.img) || itemArt(type)`. 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, 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):
+  
+  | 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         |
+  
+  **`resolveImg` returns `string | null`.** `null` for an unset path, `""` for a
+  deliberate blank, the translation half unchanged. Every caller pairs its default
+  with **nullish** coalescing: `sohl/items.mjs`, three in `sohl/actors.mjs` (`img`,
+  `portrait`, and the prototype token's `texture.src`), and `engine/macros.mjs`.
+  Not `||` — that collapses a deliberate blank back into the default and takes the
+  distinction away again, and it does so silently, because `""` is falsy.
+  `itemArt()` is unaffected: a registry entry with no art throws before the
+  translation, so its result is never the unset case.
+  
+  **The default-art seam is a documented extension point, so this is the substance
+  of the change, not a detail.** A consuming repository that pairs art with its own
+  `itemBuilders` entry, or calls `resolveImg` from a builder of its own, gets the
+  new reading of `""` whether or not it asked for it — which is why the sweeps have
+  to come first. `sohl-thalorna` swept forty-five `img: ""` notes ahead of this
+  release (HeroicLands/sohl-thalorna#134) and `sohl-kethira-basic` eleven
+  `portrait: ""` beings (HeroicLands/sohl-kethira-basic#81); `sohl` authors neither,
+  and its 3,125 compiled documents are byte-identical across the change.
+  
+  **Both art fields, because both go through `resolveImg`.** A being carries `img`
+  (its token art) and `portrait` (its sheet portrait) independently; `portrait` is
+  not a variant spelling of `img`, and the rule belongs to the translator rather
+  than to one of the keys reaching it. This is not theoretical: `sohl-kethira-basic`
+  writes `portrait: ""` on eleven beings and `img: ""` on none, so a change — or a
+  guard — keyed on `img` alone would have called that tree clean and dropped every
+  one of those portraits.
+  
+  **A warning for the old spelling.** The frontmatter lint reports `img: ""` and
+  `portrait: ""` — in either authoring position — as the meaning-change they are, on
+  the pattern the `package:` and retired-alias sweeps set: a warning, because the
+  note still compiles, to a document that is merely iconless.
+  
+  **`title` is deliberately not on this rule.** It reads as a general rule about
+  optional strings and it is not: on a `type: affiliation` note `title` is
+  _simultaneously_ a declared item field whose default is `""`
+  (`sohl/item-fields.mjs`), resolved from the very same shared top-level key the
+  site emitter reads as the page title. `title: null` therefore does not fall back —
+  it stringifies, and the compiled document ships the literal `"null"`. A `title` a
+  note does not want is written by omitting the key; the emitter's `fm.title ?? name`
+  is already correct and is untouched. The lint guard is `img`'s alone for the same
+  reason.
+  
+  Delivers the `img` half of #218. The `title` half — the collision above — stays
+  open.
+- 63dfcae: **A note's own `title` no longer fills an affiliation's `system.title`** (#218).
+  
+  The two were never the same quantity. A note's top-level `title` is _the title
+  of the note_ — the heading its page is published 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 collided only in
+  spelling, and field resolution's third step, the shared top-level property, fed
+  the second from the first.
+  
+  That step also answers **without** applying the field's default — only the
+  in-block step does — so an authored `title: null` reached the `String()` coercion
+  unguarded and compiled to the literal string `"null"`. Fifteen `sohl-thalorna`
+  notes shipped `"system": { "title": "null" }` that way.
+  
+  **Nothing in any content tree relied on the fallback.** Across all three
+  consumers — 295 `affiliation` notes in `sohl-thalorna`, 28 in
+  `sohl-kethira-basic`, none in `sohl` — not one carries a non-empty top-level
+  `title`, and `content-build package compile` emits byte-identical
+  `build/packs-json` for all three. It is a major because the rule that decides a
+  consumer's compiled documents changed with no configuration to restore it, and
+  because the generated item-field reference moves (below).
+  
+  **The field is still authorable**, at the two positions that describe the
+  document rather than the note: `sohl.system.title`, and the legacy in-block
+  `sohl.title` that most trees already write. A membership's title belongs on the
+  entry in a being's `sohl.items`, as its `system.title`. `data.title` is neither —
+  `title` is not a `data:` property any note type declares, so `content-build lint`
+  refuses it.
+  
+  **Declaring the exemption:** 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, and the generated item-field reference prints the
+  reason beneath the type's table, so an author reading it learns that the
+  top-level key will not fill the field. A repository that commits that page should
+  regenerate it.
+  
+  The value is the reason rather than a bare flag deliberately: a boolean would
+  record the decision and lose the case for it, and the next person adding a field
+  needs to know the question exists.
+- a41b066: **A page states its address relative to the site root.** `site.base` is no
+  longer written into a page's Hugo `url:` front matter — only into the `href`s
+  this build renders and the base a link-manifest `path` is measured against:
+  
+  ```yaml
+  # emitted page
+  url: /doc-rulesintro/ # was: /sohl/doc-rulesintro/
+  ```
+  
+  `site.base` was two quantities wearing one name. It is correctly _where the
+  package is served_ — the prefix on every rendered `href`, and the base a
+  manifest `path` is stripped against — and `/<contentPackage>/` is the right
+  default for that. It was also written verbatim into each page's `url:`, and that
+  is a different quantity: Hugo resolves `url` against `baseURL`, whose path for
+  every consumer that exists **already is** the package base. So the prefix was
+  written twice, and every content page — plus the homepage — published one
+  package segment too deep:
+  
+  ```text
+  /sohl/doc-rulesintro/                404      /sohl/sohl/doc-rulesintro/               200
+  /thalorna/being-afzndhprnzr/         404      /thalorna/thalorna/being-afzndhprnzr/    200
+  ```
+  
+  Not one address a link manifest advertised resolved: **0 of `sohl`'s 2,988
+  entries**, and 0 of `thalorna`'s 2,585.
+  
+  **One value fed two readers that need opposite framings**, which is why no
+  setting could fix it from a consumer: `site.base: "/"` bought the addresses and
+  short-changed the hrefs, and the default did the reverse. They are now separate,
+  and each reader gets the form it needs:
+  
+  | Reader                                              | Gets                        | Because                                                             |
+  | --------------------------------------------------- | --------------------------- | ------------------------------------------------------------------- |
+  | A page's own `url:` front matter                    | `/<type>-<shortcode>/`      | Hugo prefixes the site's `baseURL` path to it                       |
+  | The address index a `[[wikilink]]` resolves through | `<base><type>-<shortcode>/` | A browser resolves the rendered `href` against nothing              |
+  | A link-manifest `path`                              | `<type>-<shortcode>/`       | Measured against `site.base` and stripped; unchanged, byte for byte |
+  
+  The homepage moves with them: `homepageFrontmatter` states `/homepage-root/`,
+  and no longer takes a `base` (nor does `writeHomepages`' fourth argument, which
+  existed only to supply it). `trees` pages and section landings never stated a
+  `url:` and are untouched — they take their address from their path.
+  
+  **Take this release and drop your `site.base`.** Both publishing consumers set
+  `site.base: "/"` as a stopgap
+  (HeroicLands/Song-of-Heroic-Lands-FoundryVTT#1813, HeroicLands/sohl-thalorna#131),
+  which bought the correct addresses at the cost of same-package body links
+  rendering `/doc-x/` rather than `/sohl/doc-x/` — dead either way, so nothing
+  regressed. With this release the stopgap is no longer needed and no longer
+  harmless: keeping it leaves those hrefs short. Delete the `base:` line and the
+  default is right for both halves.
+  
+  **Verified against pristine `git archive origin/main` extractions of all three
+  consumers**, in both configurations, through `content-build site` **and** Hugo
+  0.165:
+  
+  | Consumer   | `site.base` | Page `url:`           | Rendered path                  | Manifest entries resolving |
+  | ---------- | ----------- | --------------------- | ------------------------------ | -------------------------- |
+  | `sohl`     | unset       | `/doc-rulesintro/`    | `/sohl/doc-rulesintro/`        | 2,988 of 2,988 (was 0)     |
+  | `sohl`     | `"/"`       | `/doc-rulesintro/`    | `/sohl/doc-rulesintro/`        | 2,988 of 2,988             |
+  | `thalorna` | unset       | `/being-afzndhprnzr/` | `/thalorna/being-afzndhprnzr/` | 2,585 of 2,585 (was 0)     |
+  | `thalorna` | `"/"`       | `/being-afzndhprnzr/` | `/thalorna/being-afzndhprnzr/` | 2,585 of 2,585             |
+  
+  No `/sohl/sohl/` or `/thalorna/thalorna/` path exists in either built tree, the
+  section landings, the content mount and the `dev-docs` tree pages all still
+  resolve, and with the stopgap dropped a same-package body link renders
+  `<a href=/sohl/doc-skills/>` again. `lint` and `links` are identical line for
+  line in every combination — `sohl` green, `sohl-thalorna` exactly as red as its
+  own content gap leaves it (1,983 lint findings, 122 link findings).
+  
+  **Exactly one line per page changes, and nothing else does.** Of `sohl`'s 1,671
+  emitted files, 1,606 differ — the 1,605 content pages and the homepage — each by
+  its `url:` alone; the 46 tree pages and 19 landings are byte-identical, and
+  `build/manifests/sohl.json` is byte-identical. `sohl-kethira-basic` publishes a
+  homepage and nothing else (`publish.site: homepage`) and declares no
+  `site.base`: its console output is identical, its one emitted page moves from
+  `/kethira/kethira/homepage-root/` to `/kethira/homepage-root/`, and its landing
+  at `/kethira/` is unaffected.
+  
+  Closes #217
+
 ## 14.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -455,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: {
@@ -478,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:
 
 ```
@@ -570,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**,
@@ -1234,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
@@ -1363,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
@@ -1374,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 }
@@ -1394,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
 

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

package/docs/content-format.md

@@ -138,6 +138,17 @@ it _there_, and a system that disagrees is not in error. A weapon weighs what
 This is the same rule as `hm3.type` overriding a derived document type, applied
 to fields: derive from the shared source, and let the system state the exception.
 
+**A field whose spelling means something else at the note level has no shared
+source.** The fallback assumes the two vocabularies agree about what a name
+means, and they do not always: a note's top-level `title` is the heading its page
+publishes under, while an `affiliation` item's `system.title` is the style of
+address an office carries. Where they diverge, the field declares what the
+top-level key means instead, and the top level stops being read for it — leaving
+`<system>.system.<field>` and the legacy in-block position, which describe the
+document rather than the note. `title` is the one field this applies to; `subType`
+is the other declared item field spelled like a note-level key, and there the two
+levels mean the same thing by design.
+
 **A `WikiLink` becomes a shortcode where the target field expects one.** SoHL
 stores cross-references as shortcode strings, which is what the `Code` suffix
 marks: `data.assocSkill` is a link to a skill note, and `system.assocSkillCode`
@@ -785,6 +796,16 @@ mapping for a field no schema declares is the drift these tables exist to catch.
 likewise absent here: they are filled on an embedded membership, never from a
 catalogue note's `data:`.
 
+**`system.title` is not the note's `title`.** The two are unrelated quantities
+that share a spelling. A note's top-level `title` is _the title of the note_ —
+the heading its page is published under; an affiliation's `system.title` is _the
+style of address the office carries_, Ajaw or Warden, which a being holds by
+virtue of its rank. So the top-level key is **not** a shared source for this
+field, and a note that writes one is stating its own heading and nothing else
+(#218). Author the style of address on the membership — the `system.title` of the
+entry in a being's `sohl.items` — or, on a catalogue note that genuinely carries
+one, at `sohl.system.title`.
+
 ### type: affliction
 
 Represents an affliction.

package/engine/field-reference.mjs

@@ -111,6 +111,34 @@ function fieldTable(fields) {
     return padTable(rows);
 }
 
+/**
+ * The fields of one type that are **not** filled from the note's top level.
+ *
+ * A field ordinarily falls back to the top-level property spelled like its
+ * name, so an author who writes `weight: 3` at the top of a note reasonably
+ * expects it to reach the document. Where that spelling means something else at
+ * the note level the fallback is off, and an author has no way to tell from the
+ * table — the field is there, the value is written, and the document ships the
+ * default. So the reason each such field declares is rendered beside its table
+ * rather than left in the source (#218).
+ *
+ * Below the table, not inside it: the reason is a sentence or two, and
+ * {@link padTable} pads every column to its widest cell, so a cell holding it
+ * would stretch the whole type's table past legibility.
+ *
+ * @param {readonly object[]} fields - The type's declaration.
+ * @returns {string[]} Markdown lines, empty when the type exempts nothing.
+ */
+function sharedExemptions(fields) {
+    const exempt = authoredFields(fields).filter((field) => field.topLevelMeans);
+    if (!exempt.length) return [];
+    return exempt.flatMap((field) => [
+        `**\`${field.name}\` is not read from the note's top level.** There it means ` +
+            `${field.topLevelMeans}`,
+        "",
+    ]);
+}
+
 /**
  * A minimal note for one type: the frontmatter envelope every note carries,
  * plus exactly the `sohl:` fields the type requires.
@@ -204,6 +232,7 @@ export function renderItemFieldReference({
             "",
             ...fieldTable(declared[type]),
             "",
+            ...sharedExemptions(declared[type]),
             ...workedExample(type, declared[type]),
             "",
         );