@heroiclands/package-build 14.0.0 → 16.0.0

package/CONTENT.md

@@ -73,6 +73,9 @@ paths:
   manifests: assets/manifests
   # Where `manifest` writes this package's own. Outbound, and a build artifact.
   manifestOut: build/manifests
+  # Where `content-index` writes this package's note index. Derived and
+  # disposable — never a source, and never inside `stage`.
+  contentIndex: build/content-index
   packJson: build/packs-json
   stage: build/stage/packs
   unpack: build/tmp/packs
@@ -455,9 +458,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 +481,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 +625,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**,
@@ -620,6 +716,7 @@ npx content-build links [root] [--manifests <dir>]
 npx content-build format [paths..] [--write]
 npx content-build markdown [paths..] [--fix]
 npx content-build manifest [root] [--out <dir>]
+npx content-build content-index [root] [--out <dir>]
 npx content-build site [--out <dir>]
 npx content-build reachability <dir> [file] [--index <shortcode>]
 npx content-build addresses diff --from <zip|dir> [--strict]
@@ -635,6 +732,7 @@ npx content-build addresses diff --from <zip|dir> [--strict]
 | `format`         | Prettier, with the shared configuration. See [Prose: formatting and markdown](#prose-formatting-and-markdown).                                                          |
 | `markdown`       | markdownlint, with the shared rule set — the structure Prettier is indifferent to.                                                                                      |
 | `manifest`       | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).                                                         |
+| `content-index`  | Emit this package's note index as JSON Lines. See [Publishing a content index](#publishing-a-content-index).                                                            |
 | `site`           | Publish the content tree as a website. See [Publishing a website](#publishing-a-website).                                                                               |
 | `reachability`   | Walk outward from an index note and report what no path reaches, for a tree meant to be navigable from one entry point.                                                 |
 | `addresses`      | Report every published item address this build has stopped publishing. See [Diffing published addresses](#diffing-published-addresses).                                 |
@@ -1234,6 +1332,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
@@ -1282,6 +1395,204 @@ 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 content index
+
+Every content build walks the whole note tree and parses every note's
+frontmatter — the pack compilers, the site build, and the content-table expander
+each do it — and every one of them throws the result away. So nothing outside a
+build can ask a question about the content. "Which beings carry no `kbcat`?",
+"what does this table actually select?", "did that type rename leave anything
+behind?" have no answer short of writing a throwaway script that re-walks the
+tree, which is how eight dead Bestiary tables came to ship for weeks unnoticed.
+
+`content-index` publishes the walk:
+
+```bash
+npx content-build content-index
+# sohl → build/content-index/sohl.jsonl (1606 notes, 1578 KiB)
+```
+
+One line of [JSON Lines](https://jsonlines.org/) per note, holding the note's
+whole frontmatter plus where it sits in the tree:
+
+```json
+{
+  "type": "being",
+  "shortcode": "aurochs",
+  "package": "sohl",
+  "file": { "path": "Bestiary/Animal/Aurochs.md", "folder": "Bestiary/Animal", "name": "Aurochs" },
+  "sohl": { "kbcat": "animal", "body": { "weight": { "base": 1500 } } }
+}
+```
+
+so a question is one line of `jq`:
+
+```bash
+jq -r 'select(.type == "being" and .sohl.kbcat == "animal") | .shortcode' \
+  build/content-index/sohl.jsonl
+```
+
+### The record is the note, not a projection of it
+
+Nothing is selected, flattened, or renamed. A reader addresses
+`sohl.body.weight.base` because that is what the note says — which is also,
+not by accident, exactly what a `dataview` content-table query writes.
+
+That is a deliberate refusal to impose a schema, and the tree is why. In `sohl`,
+frontmatter spreads **242 distinct leaf paths** unevenly over **15 types**, from
+9 on a `macro` to 72 on a `being`, and adding a field to one type is ordinary
+authoring. A format with a fixed column set would turn that authoring into a
+schema migration; a document format has no such problem.
+
+Two keys are **derived** rather than authored, and a note carrying either is an
+error rather than a silent overwrite:
+
+| Key       | What it holds                                                                                      |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| `package` | The configured `contentPackage`. A note may not declare its own, and the expander reads the same.  |
+| `file`    | `path`, `folder` and `name` below the content root — the same `file.*` a content-table query uses. |
+
+The location is namespaced under `file` precisely because `folder` is real
+frontmatter on most notes; a record states both, and they mean different things.
+
+### Every note's address, and every anchor it defines
+
+A record states the address a wikilink writes to reach the note, and every
+`{#slug}` anchor its body declares:
+
+```json
+{
+  "address": { "slug": "being-aurochs", "canonical": "sohl-being-aurochs" },
+  "file": { "path": "Bestiary/Animal/Aurochs.md", "folder": "Bestiary/Animal", "name": "Aurochs" },
+  "anchors": [
+    {
+      "slug": "appearance",
+      "name": "Appearance",
+      "level": 1,
+      "line": 348,
+      "link": "being-aurochs#appearance"
+    },
+    {
+      "slug": "dossier",
+      "name": "Dossier",
+      "level": 1,
+      "line": 352,
+      "link": "being-aurochs#dossier"
+    }
+  ]
+}
+```
+
+A record also states `nameAscii`, the note's `name.full` reduced to printable
+7-bit ASCII:
+
+| `name.full`     | `nameAscii`       |
+| --------------- | ----------------- |
+| `Kûrbúl ¾-Helm` | `Kurbul 3/4-Helm` |
+| `Kèthîra`       | `Kethira`         |
+| `Ærling`        | `AErling`         |
+| `Þorn`          | `Thorn`           |
+| `Ðunhold`       | `Dunhold`         |
+| `Straße`        | `Strasse`         |
+
+Names carry the setting's orthography and nobody types them, so anything
+searching or completing over the index needs a form a keyboard produces. Stating
+one means every consumer matches the same way, rather than each inventing a
+slightly different fold and two searches over the same data disagreeing.
+
+It **transliterates rather than strips**, through the same `unidecode` table
+`slugify` already runs — so an ASCII name and a slug can never disagree about a
+character. Diacritics fold, ligatures expand, the runic letters spell out, and a
+vulgar fraction becomes readable. Deleting the marks instead would reduce
+`Kûrbúl` to `Krbl`, which is worse than the original for anyone trying to
+recognise it. Whatever is still outside printable ASCII afterwards becomes a
+space and runs of whitespace collapse — a space rather than nothing, so a
+character that transliterates away cannot weld two words together.
+
+The value is emitted even when it equals the name, so a consumer matching on it
+never has to branch on whether the name happened to be ASCII already; it is
+`null` only when the note has no name at all. On the `sohl` tree, 25 of 1,606
+notes differ from their `name.full`.
+
+`aliasesAscii` does the same for `name.aliases`, in the authored order. An alias
+is the name a reader is at least as likely to reach for as the canonical one —
+`Killer Whale` for an orca, `Ice Bear` for a polar bear, `Ix'balam` for a
+jaguar — so anything searching the index has to match them too. It is an **empty
+array**, never null, when a note has no aliases: an empty set of names is a fact
+rather than a missing value, and a consumer iterating it should not have to check
+first. An entry that is not a non-empty string is dropped rather than left as a
+hole, since the array is a set of names to match and a null is not one.
+
+`address.slug` is what goes inside `[[…]]` within the package; `address.canonical`
+is the package-qualified key the link manifest files the note under. Both are
+`null` for a note with no type or no shortcode, which has no address at all — the
+record says so rather than leaving each reader to rediscover the rule.
+
+**Neither is new information** — both derive from `type` and `shortcode`, which
+every record already carries. What the fields add is the _rule_: the lowercasing
+and the hyphen join live in one place, derived by the same `addressSlug` and
+`canonicalKey` the manifest and the site build use, so an index cannot disagree
+with either about where a note lives. A consumer that reimplements the join
+slightly differently gets a lookup matching nothing and no explanation — which is
+exactly how a resolver keyed on a bare `type/shortcode` silently misses every
+canonical `pkg-type-shortcode` entry.
+
+**Anchors make a link checkable without a build.** Because the index states every
+anchor a note defines, `[[being-aurochs#dossier]]` can be confirmed — or shown
+dead — by a lookup, rather than by re-parsing the tree. Each anchor also carries
+its **line in the file**, so an editor jumps straight to the heading instead of
+searching for it, and a diagnostic about a section can name a real position.
+
+Only headings carrying an explicit `{#slug}` are listed. A bare `#` heading also
+starts a journal page, but declares no slug, so nothing can address it with `#…`
+and listing it would offer a link that cannot be written. What counts as an anchor
+is kept identical to what `splitPages` matches — that pass decides which sections
+become addressable journal pages — and a test asserts the two agree, so drift
+fails the suite rather than advertising a link that resolves nowhere.
+
+**The path stays relative.** `file.path` is below the content root and is
+deliberately never absolute: an absolute path is a fact about the machine that
+built the index rather than about the content, so it would differ between two
+checkouts of the same tree — costing the byte-stability the artifact depends on —
+and a published copy would carry someone's home directory and be wrong for every
+reader. Anyone holding the index knows the root it was built from, and
+`root + file.path` is the absolute form whenever it is wanted.
+
+### Why JSON Lines, and not a database
+
+The artifact has to survive the build that made it and be usable by anything — a
+person with `jq`, an editor, a CI check, another package's build. A
+line-per-note text file needs no server, no driver, and no schema; it is
+readable by every language without an install; and it **diffs**, so a migration
+that quietly empties a category shows up as a reviewable change rather than as a
+silently different binary.
+
+Choosing it forfeits no SQL: DuckDB reads JSON Lines directly, with nested
+access, so `FROM read_json_auto('build/content-index/sohl.jsonl')` is a query
+away. A stored schema would forfeit the open shape, which is the asymmetry that
+decides it.
+
+### It is derived, disposable, and byte-stable
+
+The index is written under `build/`, gitignored with the rest of it, and
+**nothing may be authored against it**. It is deliberately not in `paths.stage`:
+that tree is mirrored destructively into a Foundry data root, so anything left
+there ships inside the installed system to every player.
+
+Regenerating costs a frontmatter parse rather than a build, so the intended way
+to use it is to rebuild it whenever it looks stale — which is why it is a
+command of its own and not only a build step, and why it need never be
+committed.
+
+That only holds if a rebuild is a no-op when nothing changed, so the output is
+**byte-stable**: records are ordered by content path with the note id breaking
+any tie, and every object's keys are sorted at every depth. A walk order is a
+directory-read order, and directory-read order is not a fact about the content.
+
+An empty tree is an **error**, not an empty index. A reader takes the file as
+authoritative, and an index stating that a package has no content is
+indistinguishable from one built against a mis-pointed tree.
+
 ## Publishing a website
 
 ```bash
@@ -1363,7 +1674,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 +1686,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 +1706,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