@heroiclands/package-build 19.0.0 → 20.2.0

package/CHANGELOG.md

@@ -1,5 +1,1105 @@
 # @heroiclands/package-build
 
+## 20.2.0
+
+### Minor Changes
+
+- 85fffd6: **The frontmatter lint checks the system blocks a package ships for, instead of
+  a block named `sohl`.**
+  
+  A system block is a closed region: a key the system's vocabulary does not
+  declare is an error, because the compiler's builders are an allow-list and drop
+  it without a word. That held for exactly one block, `sohl:`, and it held whatever
+  system the package shipped for — the linter takes the blocks its caller names,
+  and the only caller named none, so every tree fell back to the same constant.
+  
+  Both directions of that are wrong once a second system exists, and the second is
+  the costlier:
+  
+  |                               | before                                                    | now                                  |
+  | ----------------------------- | --------------------------------------------------------- | ------------------------------------ |
+  | a package shipping for `sohl` | `sohl:` checked                                           | unchanged                            |
+  | a package shipping for `hm3`  | `sohl:` checked — a block it does not carry               | `hm3:` checked                       |
+  | an `hm3:` block               | **never read**, every key discarded at compile in silence | checked against HM3's own vocabulary |
+  | a tree feeding both           | one of two blocks checked                                 | each block against its own system    |
+  
+  **Which systems a package ships for is already declared**, so this reads that
+  rather than asking for it again — in all three places it is written:
+  
+  - `systems:`, which declares them without requiring one;
+  - a **pack's** `system:`, which is the same statement per pack and the only one
+    some trees make. It is already authoritative at compile, where a note routed
+    to such a pack and carrying no such block fails the build, so a lint blind to
+    it would refuse a note for want of a block it never checked;
+  - `stats.systemId` where neither is written, which has already absorbed every
+    remaining spelling: a system package is its own system, and a module takes
+    `requiresSystem`, its lone `systems:` entry, or its lone system relationship.
+  
+  **Each block is held to its own system's vocabulary**, and that has two sources.
+  A system's `itemBuilders` registry covers its item types — `skill` is one name
+  over two data models, so a key SoHL's `skill` declares is not thereby a key
+  HM3's. The note schemas cover the rest, `being` above all, which is an actor type
+  sitting in no item registry; they are SoHL's, because that is the vocabulary
+  `content-build` is built with.
+  
+  A type neither source names is a type that system says nothing about, and its
+  block is left alone on such a note rather than reported wholesale. A package
+  naming no system anywhere is system-agnostic on purpose — its packs are core
+  document types carrying no system data — so it has no system block, and none is
+  invented for it.
+  
+  **A block whose vocabulary nothing states is said out loud.** A package
+  declaring a system other than SoHL and no `itemBuilders` registry for it has
+  nothing that can say what that block may carry, so the block goes unchecked and
+  `content-build lint` reports that once, naming the system and the registry to
+  declare. A check that quietly does nothing is indistinguishable from one that
+  passed, which is the whole subject here.
+  
+  For `harn-ensemble` — the tree this issue is about, declaring both systems
+  through its packs — that means its `sohl:` block is checked exactly as before,
+  its 2,512 `being` notes included, and its `hm3:` block waits on
+  `itemBuilders: [hm3, sohl]`, which the lint now asks for by name.
+  
+  **Nothing changes for a package shipping for SoHL**, which is every consumer
+  today: one system, one registry, and the derivation is the identity on it.
+- e084547: The e2e harness no longer reports a run that never started as green.
+  
+  Observed against a licensed container: a concurrent `npm ci` removed
+  `node_modules` out from under a run in progress, Cypress died with
+  `Cannot find package '.../cypress/index.js'`, and `package-build e2e run`
+  **exited 0**. The concurrency was an operator's mistake; the exit code was not.
+  A scripted caller, or anyone reading the tail of a log, would have recorded the
+  suite as passing when nothing was executed — and the suite is what moves
+  `compatibility.verified`, so an exit code that says green when nothing ran makes
+  that evidence unfalsifiable in the one direction that matters.
+  
+  The suite is now bracketed rather than trusted on its exit status:
+  
+  | When   | Check                              | What it catches                                                                          |
+  | ------ | ---------------------------------- | ---------------------------------------------------------------------------------------- |
+  | Before | Every executable the command names | The runner is not installed — an error naming it, before a container and a world.        |
+  | Before | The tool behind a package runner   | `npx cypress run` resolves **`cypress`**; `npx` is never missing, so it answers nothing. |
+  | After  | Those executables again            | The runner disappeared mid-run, which is the failure reported above.                     |
+  | After  | Results written since the spawn    | The suite started and produced nothing. Needs the new `results` key.                     |
+  
+  **New: `packageBuild.e2e.results`.** One path, or a list of them, relative to
+  the repository root, naming where the suite writes its results:
+  
+  ```yaml
+  e2e:
+    suite:
+      run: [npx, cypress, run]
+    results: [cypress/results]
+  ```
+  
+  Existence is not the test — a directory the _previous_ run left behind exists,
+  and reading that as evidence would make the check agree with exactly the thing
+  it was built to catch. What counts is a file modified since the suite was
+  spawned. Declaring nothing keeps the previous contract, in which the exit status
+  is taken at its word; declaring a path is what buys the distinction between _the
+  suite ran and passed_ and _the suite did not run_.
+  
+  **What a consumer may notice.** A `run`, `fast` or `sweep` whose suite is not
+  installed now fails immediately with a diagnostic naming the missing program,
+  where before it stood a container up and failed later — or, in the reported
+  case, did not fail at all. The check only ever makes a verdict _worse_: a suite
+  that failed keeps its own exit status, so there is no new way for the harness to
+  report a result that did not happen. `open` is untouched, because a person
+  decides what to execute there and a session that ran no specs is not a fault.
+  
+  Also exported from `@heroiclands/package-build/e2e`, for a repository that wants
+  the same rules elsewhere: `suiteExecutables`, `findExecutable`,
+  `missingExecutables`, `freshResults` and the pure `suiteVerdict`.
+- d72c4b2: A note can now name an interface icon instead of drawing one. `:icon-star:`
+  renders as the same Font Awesome element the system's own sheets emit, and an
+  undeclared name is reported rather than published as literal text.
+  
+  The user guide described Foundry's interface by pasting Unicode lookalikes of
+  icons the sheets actually draw — `☆` for the improve flag, `✎` for the formula
+  editor — so the note and the screen it described were drifting apart. Those
+  characters are also the worst in the corpus to typeset: of eight candidate book
+  faces, none carries them.
+  
+  A registry maps a writer's name to a style and a Font Awesome icon, because the
+  three surfaces need different artefacts from one name: the journals and the
+  website want an `<i class="fa-solid fa-star">`, and a PDF wants a font file and
+  a glyph. It also means an icon renamed between Font Awesome major versions costs
+  one line rather than a sweep of the corpus.
+  
+  Codepoints are deliberately absent: a renderer embedding the font has to read it
+  to subset it, and the font's own `cmap` is the only trustworthy source for which
+  glyph a name resolves to.
+  
+  Part of #378.
+- 15fb41f: **A pack's `system:` must resolve to the version its documents are stamped with,
+  and a configuration where it resolves to nothing is now refused.**
+  
+  Every document in a pack carries `_stats.systemId` and `_stats.systemVersion`,
+  and for a pack declaring `system:` those come from one of exactly two places:
+  the `systems:` entry for that system, which carries the verified version, or the
+  package-wide stats, which answer for a package whose packs are all for its own
+  system.
+  
+  A pack naming a system that resolves to **neither** used to fall through to the
+  package-wide value — and a module that declares no system does not have one, so
+  both fields were stamped `null`. That is the plausible lie #43 was about,
+  reached by the one path the guard did not cover:
+  
+  ```
+  _stats: { systemId: null, systemVersion: null, … }
+  ```
+  
+  on 2,513 compiled actors in a pack whose configuration says `system: sohl` on
+  the line above.
+  
+  **The check existed; it was skipped in exactly this case.** `packs.<n>.system`
+  was validated against `systems:` only when that block was non-empty — the guard
+  read `declaredSystems.size && …` — so an absent block meant no check at all. Its
+  sibling ten lines up refuses the same thing for `requiresSystem` and says "the
+  `systems:` block is empty or absent" in as many words, and the comment above
+  both already described this failure. The suite was green throughout because its
+  `harn-ensemble`-shaped fixture declares the `systems:` block the repository does
+  not: the fixture was more complete than the configuration it stood for.
+  
+  **What a consumer sees.** A configuration in this shape now fails with the pack
+  named and the entry to add:
+  
+  > `packs.actors-hm3.system` names `hm3`, which `systems:` does not declare — the
+  > `systems:` block is empty or absent, and this package has no package-wide
+  > system either. Every document in the pack is stamped `_stats.systemId` and
+  > `systemVersion` from one of those two, so with neither it would be stamped
+  > null. Add `systems:` naming `hm3` with a `compatibility.verified` version.
+  
+  **Nothing changes for a package whose packs name no system**, or whose packs name
+  its own system — the package-wide stats answer for those exactly as before,
+  which is every single-system tree. The package-wide derivation itself is now a
+  named function read by both the stamp and the check, so the value validated
+  against and the value stamped cannot come to disagree about the case that has no
+  answer.
+- c9e7a5a: **A pack default is resolved per system, so one note compiles into one pack per
+  system without declaring anything.**
+  
+  This is the routing half of #58, and until now it made the documented
+  two-system layout impossible to build. A default was computed per document
+  _type_: a type with exactly one pack is that type's default implicitly, and a
+  type with several designates one with `default: true`. A tree shipping one Actor
+  pack per system has two, so it had neither — and a note feeding both systems
+  declares no `pack:` by design, since a block's `pack:` exists to say where one
+  system's document goes only when that _differs_.
+  
+  So every note routed nowhere. On `harn-ensemble` that was all 2,519 of them, the
+  build failing on each in turn with a message saying the configuration was wrong
+  when it was the question being asked that was.
+  
+  |                                              | before                                                                                                    | now                                                             |
+  | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+  | one Actor pack per system, no flag           | every note routes nowhere; build fails                                                                    | each system's document routes to its own pack                   |
+  | a type-wide `default: true` on `actors-sohl` | returned to the HM3 pass too, which saw a name that was not its own and **skipped every note in silence** | the HM3 pass gets `actors-hm3`                                  |
+  | `hm3.pack:` naming a SoHL pack               | routed there, and the HM3 document was lost without a word                                                | refused, naming the note and the pack                           |
+  | a shared `pack:` naming a SoHL pack          | the HM3 document was lost without a word                                                                  | does not answer for HM3, which falls through to its own default |
+  
+  **A system is never answered with another system's pack.** That is the rule the
+  four rows share, and the second is the one worth stating twice: it failed
+  silently. The pack compiled zero entries, which a build reports only because a
+  pack that compiles nothing from a non-empty tree is itself an error.
+  
+  **Marking a default still means what it says** — it designates that _system's_
+  default where a system has several packs of one type — and every single-system
+  configuration is untouched, since a pack declaring no system belongs to all of
+  them and the type-wide default answers exactly as before.
+  
+  On `harn-ensemble` this takes `actors-sohl` from 0 compiled actors to 2,497, and
+  `actors-hm3` from routing nothing to claiming every note and reporting what each
+  still needs: `hm3.type`, which `being` requires because it is one-to-many into
+  `character` and `creature`.
+- 0418fa8: `content-build lint` now holds a content tree to a character allowlist, so a
+  book can choose its typeface without discovering at print time that no font
+  carries what the notes are written in.
+  
+  Typst does not warn when a glyph is missing — it falls back to whatever system
+  font has one and exits 0, so a rules table can set in three unrelated faces and
+  the build still reports success. The check moves that failure back to where the
+  character is written.
+  
+  The tiers are measured rather than chosen: eight candidate book faces were
+  probed over every non-ASCII character in the five content trees, and what is
+  admitted is what enough of them carry. Letters and typography are universal;
+  Latin Extended Additional is carried by seven of eight; IPA was considered and
+  refused at five of eight, because requiring it would cost font freedom rather
+  than buy it.
+  
+  Two rules ride along that an allowlist cannot express. Content must be NFC — a
+  decomposed letter is a different string to every byte comparison, including
+  DuckDB's `=`, so a filter typed one way silently misses a note stored the other.
+  And box-drawing, geometric and arrow characters are permitted inside a fenced
+  code block only, where the mono face sets them.
+  
+  Part of #377.
+- 571d5bc: **`content-build format` now says which shared Prettier conventions your
+  repository is not using.**
+  
+  A consumer's own Prettier config wins **wholesale** — that is Prettier's own
+  behaviour and it is not changing — so the conventions this package publishes held
+  by convention alone, and lapsed silently in two opposite directions (#133):
+  
+  | what a repository declares                                      | what it actually formatted to                                                           |
+  | --------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+  | `export { default } from "@heroiclands/package-build/prettier"` | the shared conventions                                                                  |
+  | `{ ...PRETTIER_BASE }`, without the `**/*.md` override          | markdown at `tabWidth: 4` — every note reindenting away from the form it was written in |
+  | a partial `.prettierrc`, e.g. `{"tabWidth": 2}`                 | Prettier's defaults for `printWidth`, `trailingComma`, `experimentalTernaries`, …       |
+  | nothing at all                                                  | the shared conventions here, Prettier's own in your editor and in `npx prettier`        |
+  
+  Every `format` run now reports each disagreement by name, before the per-file
+  report:
+  
+  ```text
+  prettier.config.mjs: warning: markdown `tabWidth` is 4 here; the shared configuration says 2
+  .prettierrc: warning: `printWidth` is not set here, so Prettier's own default applies; the shared configuration says 100
+  ```
+  
+  A repository with no Prettier config is warned too, with the one line that fixes
+  it — that case is the sharper one, because the shared conventions then reach this
+  command and nothing else, so a bare `npx prettier --check .` and the lint chain
+  take turns rewriting the same lines.
+  
+  **Nothing here fails a build.** Every finding is a `warning`, the exit code is
+  untouched, and a deliberate local override keeps working exactly as before — it
+  just stops being silent.
+  
+  New export: `checkPrettierConventions(root)` from
+  `@heroiclands/package-build/engine/prose-lint`, and the pure comparison behind it,
+  `sharedPrettierDivergence(resolved, file)` from
+  `@heroiclands/package-build/engine/prose-config`.
+- 9f638fa: **A note whose secondary document has no pack is now a finding, instead of
+  losing that document in silence.**
+  
+  A note produces more than one document as a matter of course: an item note an
+  Item and the JournalEntry its prose becomes, a map note a Scene and a
+  JournalEntry, an actor note an Actor and a JournalEntry since #337. Where the
+  configuration declares no pack for one of them, that document was dropped while
+  the rest of the note compiled into a pack that does exist. The build succeeded,
+  the compendium shipped, and the missing half was discoverable only by noticing
+  it was not there.
+  
+  #146 already reports a note **nothing** claims, and could not see this: it asks
+  one question of the whole configuration — does any pack claim this type — and a
+  note that compiles its Item into an Item pack answers yes.
+  
+  > a note of type "being" compiles into a JournalEntry as well as an Actor, and
+  > `packs:` declares no JournalEntry pack — so the JournalEntry is dropped with
+  > no error while the rest of the note compiles. Declare a JournalEntry pack in
+  > package-build.config.yaml, or accept the loss deliberately by not authoring
+  > what it would have carried.
+  
+  The message names the note, the class with no pack, and the class that did
+  compile — the last because it is what tells the two findings apart at a glance:
+  one is a `type:` to correct, this one a pack to declare.
+  
+  **Asked per note, not per type**, which is the difference between a useful
+  finding and a useless one. `Journals` declines a doc-carrying note whose body is
+  empty — an item with no prose gets no doc — so whether an item note produces a
+  JournalEntry is decided by the note. `sohl-kethira-basic` declares no
+  JournalEntry pack and ships 393 notes whose descriptions are _deliberately_
+  empty under the Fan Material Guidelines its configuration explains at length; a
+  type-level answer would report every one of them for losing a document none of
+  them produces. It reports none.
+  
+  **It names no system**, so a type one system maps and another does not stays
+  silent for the system that declines it, per #79. That holds by construction: the
+  `Item` and `Actor` rows fold the systems' maps together before this sees them,
+  so a type appears once or not at all and no system is ever named.
+  
+  **What it finds today.** `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna`
+  report nothing — every document their notes produce already has a pack.
+  `harn-ensemble` reports 2,512: it declares two Actor packs and no JournalEntry
+  pack, so every one of its beings has been losing the `{#appearance}` and
+  `{#dossier}` prose it carries. When the issue was filed no tree authored the
+  affected combination; one does now.
+
+### Patch Changes
+
+- 6499109: **A build now reads the configuration of the tree it was run in.**
+  
+  The configuration was located by walking up from the installed package's own
+  directory. That is the same file as the working directory's in every ordinary
+  install — and a different one in a git worktree nested under its parent checkout
+  with no `node_modules` of its own. Node's resolution walks parent directories,
+  so such a worktree resolves `@heroiclands/package-build` out of the _parent's_
+  `node_modules`; the walk started inside the parent and landed on the parent's
+  `package-build.config.yaml`. The build then compiled the parent's content tree
+  into the parent's `build/`, said so only in absolute paths that are easy to read
+  past, and exited 0.
+  
+  Resolution now starts at `process.cwd()` and falls back to the installed
+  package's directory only when that finds nothing.
+  
+  | running `content-build package compile` in   | before                  | after            |
+  | -------------------------------------------- | ----------------------- | ---------------- |
+  | a repository, or any directory below it      | that repository         | unchanged        |
+  | a nested worktree that has had `npm ci` run  | the worktree            | unchanged        |
+  | a nested worktree with **no `node_modules`** | _the parent checkout_   | **the worktree** |
+  | a directory outside any repository           | the installed package's | unchanged        |
+  | anywhere, with `PACKAGE_BUILD_CONFIG` set    | the file it names       | unchanged        |
+  
+  Nothing about "a build reads one tree however it was launched" changes: the walk
+  climbs, so every directory inside a repository still resolves that repository's
+  single configuration.
+  
+  When both walks find a configuration and they disagree, the working directory's
+  is read and the ignored one is named in a warning on stderr. The disagreement is
+  worth hearing on its own — it is the cheapest signal that this tree is building
+  on another checkout's `node_modules`, which is also a masked missing dependency.
+  `npm ci` in the worktree silences it properly.
+  
+  **Why this was worth a fix rather than a note.** A silent wrong-tree build does
+  not merely fail to prove what was wanted, it produces confident evidence for the
+  wrong tree — and on an output-preserving sweep there is no observation that
+  distinguishes success from it. The usual tell is a zero diff where a change was
+  expected; a sweep that expects zero differences has no tell at all.
+  
+  `resolveConfigFile()` is exported from
+  `@heroiclands/package-build/engine/pack-config`, reporting the chosen file and
+  each walk's own answer, so a caller can ask which tree it is about to compile
+  without re-deriving the resolution and risking disagreement with the loader.
+- c229f2b: Stop shipping a `node_modules` symlink, which had broken every release for a
+  day.
+  
+  A worktree's `node_modules` symlink — a 120000 blob holding one developer's
+  absolute path — was committed on 2026-09-11. `.gitignore` said
+  `/node_modules/`, and a trailing slash matches a directory rather than a
+  symlink, so nothing refused it.
+  
+  The release job installs, runs the tests, and then hands over to the changesets
+  action, which does `git reset --hard` before versioning. That reset restored the
+  symlink over the top of the install, pointing at a path no runner has, so every
+  module became unresolvable and the release died on `changeset: not found`. The
+  tests had already passed, because they run before the reset.
+  
+  The symlink is untracked, the ignore rule now matches a symlink at any depth,
+  and CI refuses a tracked `node_modules` path outright — the release is the only
+  thing this breaks, and no pull request check would otherwise notice.
+- 80f40b2: Unblock releasing. Every run of the release workflow had failed at
+  `changeset version` with `sh: 1: changeset: not found` since 2026-09-11, so
+  nothing reached the registry past 20.0.0 while `main` went on believing itself
+  released.
+  
+  The workflow installed `npm@latest` before publishing, to clear an OIDC floor of
+  11.5. That was written when Node 24.0–24.4 bundled npm 11.3–11.4; since 24.5 the
+  bundled npm has cleared the floor on its own, and the step became a no-op that
+  nobody removed. On 2026-09-11 `latest` became npm 12, which stopped putting
+  `node_modules/.bin` on the PATH of a run-script's shell, and a release path
+  nobody had touched broke.
+  
+  The install is gone rather than pinned: the npm that publishes is now the one
+  Node brings, so its version follows `node-version` instead of a number kept in
+  step by hand. A check in its place asserts the floor and fails loudly if a
+  future Node pin ever drops below it — an assertion cannot go quietly stale the
+  way the comment it replaces did. The version script also resolves its binary
+  through `npx`, as the publish script already did.
+- 12061da: Release again. Since 2026-09-11 every run of the release workflow had died at
+  `changeset version` with `sh: 1: changeset: not found`, so nothing reached the
+  registry past 20.0.0.
+  
+  The workflow set `version-script`, which replaces the action's own invocation of
+  the changesets CLI with a shell command run through its exec — and under that
+  exec a bare `changeset` does not resolve on a runner. Left unset, the action
+  resolves the installed package with `require.resolve` and runs it with `node`,
+  depending on no PATH at all. The override is removed.
+  
+  The fault was never in this repository's install. A diagnostic run confirmed
+  that after `npm ci` a runner has the package, has the bin linked, puts
+  `node_modules/.bin` first on a run-script's PATH, and resolves the bare name
+  through `npm run` — all in the same job that then failed.
+  
+  The one thing the override bought, refreshing `package-lock.json`'s root
+  `version`, is now #385 rather than a reason to keep a step that does not run.
+- 9572517: Finish unblocking the release. Removing the stale `npm install -g npm@latest`
+  fixed the npm-12 half, but the same change also swapped the version script's
+  bare `changeset` for `npx changeset`, and that turned the failure into `npm
+  error could not determine executable to run`.
+  
+  The npx form was belt-and-braces and it was wrong. `npm run` already puts
+  `node_modules/.bin` on the PATH — the same mechanism `npm test` uses to reach
+  `vitest` earlier in the same job — so the bare name resolves the pinned local
+  copy with no lookup. npx instead consults the registry, which this job
+  configures for OIDC publishing rather than for reads.
+  
+  The script is back to the bare binary, and the reasoning is recorded beside it
+  so the asymmetry with `publish-script` is not mistaken for an oversight again.
+
+## 20.1.0
+
+### Minor Changes
+
+- f6d2a8f: **A fetched item catalogue is read one system at a time** (#58).
+  
+  A pack declaring `system: hm3` already read only this repository's `hm3` and
+  system-neutral Item packs. The other half of the same lookup — the catalogue
+  fetched from a dependency that declares `itemCatalog: true` — was unscoped, and
+  both halves are merged into one address space keyed by `subType:shortcode`. So
+  an address that exists in both vocabularies resolved against whichever document
+  the dependency's other system happened to supply, and said nothing: `skill:awar`
+  is a real address under SoHL and under HM3 and means two different documents.
+  
+  `deps fetch` now records what each extracted pack is, from the dependency's own
+  manifest, and `foreignItemCatalogDirs(config, system)` reads only the packs that
+  system may see plus the ones declaring no system at all.
+  
+  **What a consumer sees**
+  
+  |                                      | Before                  | After                            |
+  | ------------------------------------ | ----------------------- | -------------------------------- |
+  | a pack with `system: hm3`            | reads every cached pack | reads the `hm3` and neutral ones |
+  | a single-system build                | reads every cached pack | unchanged                        |
+  | a cache filled by an earlier version | used as-is              | treated as incomplete            |
+  
+  **Refill the cache once.** A cache written before this holds the items but not
+  what they are, and neither way of proceeding without that is honest: reading
+  every pack is the wrong-document failure above, and reading none fails a build
+  that worked. So it is incomplete, and `content-build deps fetch` refills it —
+  the command the cold-cache error already names.
+
+### Patch Changes
+
+- 2b1157e: **The license header is on every shipped module, and CI refuses a `TODO`.**
+  
+  `engine/foreign-catalog.mjs` and `engine/schema-extract.mjs` shipped without the
+  GPL-3.0 header every other module carries — 109 of 111 had one, which is the
+  state a rule reaches when nothing checks it.
+  
+  The forbidden-marker check now runs here too, through the org-wide
+  `HeroicLands/.github/actions/todos` action the other repositories already call.
+  It scans the whole checkout rather than a named list of directories: this
+  package's modules sit at its root as well as under `bin/`, `ci/`, `engine/`,
+  `hm3/` and `sohl/`, so a list would name sixteen root files today and quietly
+  stop covering the seventeenth.
+  
+  Nothing a consumer imports changes.
+
+## 20.0.0
+
+### Major Changes
+
+- 1670506: **An omitted address segment now defaults from where the link is written** (#336),
+  instead of being wildcarded or searched for. Three resolvers each carried their
+  own reading of a partial address and disagreed; there is one rule now, in
+  `expandAddress` beside `canonicalKey`.
+  
+  - **package** omitted → the current package.
+  - **system** omitted → the **system block the link sits under**: anywhere under
+    `sohl:` is `sohl`, anywhere under `hm3:` is `hm3`, and anywhere else —
+    top-level frontmatter, `data:`, body prose — is `none`. The enclosing block
+    decides at any depth; the field has no say.
+  
+  Every short form therefore expands to exactly one canonical address before
+  lookup. Resolution is a `Map.get`, with no candidate set and no single-hit rule.
+  
+  **Under `none`, a system-bearing type addresses its documentation.** A note's
+  `none` address _is_ its `doc<type>` journal, so a prose `[[affiliation-x|…]]`
+  names the page — what a prose link almost always means. A prose link that means
+  the Item states the system: `[[sohl-affiliation-x|…]]`. A `macro` and the map
+  types are **not** redirected: their own documents are core ones already at
+  `none`, so `macro-x` still names the Macro.
+  
+  **Breaking, in three ways a consumer will notice**
+  
+  |                                     | before                                       | after                                             |
+  | ----------------------------------- | -------------------------------------------- | ------------------------------------------------- |
+  | a bare prose link to an item type   | the Item's UUID                              | the documentation journal's                       |
+  | a bare address naming no local note | fell through to any dependency publishing it | `unresolved`; qualify it to reach another package |
+  | `[[Skill-Climb\|…]]`                | resolved, case folded                        | `not-lowercase`                                   |
+  
+  The first rewrites every such link in every pack. The second is the point of the
+  issue: a link resolved into another package only because no local note claimed
+  the address, and would have retargeted silently the day one did.
+  
+  **Two defects go with it.** The index's system-blind `type/shortcode` key is
+  gone — it was set with a plain `Map.set`, so two notes in one package sharing a
+  `(type, shortcode)` across systems silently overwrote each other while both
+  canonical keys sat correctly beside it. And cross-package `ambiguous` is now
+  unreachable: one expanded address names one package, so a lookup returns one
+  entry or none. The finding is retained for older vendored manifests.
+  
+  **An address capitalises nothing but its shortcode.** Package, system and type
+  are closed vocabularies with one spelling each; a shortcode is case-sensitive and
+  routinely mixed (`Clb`, `LtShoe`), so it keeps its case. Neither tree carried a
+  violation — 10,538 authored targets checked. Requiring the shortcode to be
+  lowercase too is tracked as #340.
+- c906d54: **A shortcode must now match `^[a-z0-9]+$`** — lowercase letters and digits only
+  (#340). So must every other address segment; the charset is one rule with no
+  exceptions left in it.
+  
+  `Dgr` beside `dgr` is a distinction nobody can say out loud and can only see by
+  looking twice. It was also a silent identity collapse: `canonicalKey` lowercases
+  the address it builds, so a note declaring `Clb` published
+  `sohl-sohl-weapongear-clb` and derived its `_id` from that — and two notes
+  differing only in case shared one address, one `_id` and one URL with nothing to
+  report it, because the shortcode check compared shortcodes (genuinely distinct)
+  and the address check saw one address.
+  
+  It forced two exceptions elsewhere, and both go: #336 had to exempt the shortcode
+  from the lowercase rule it pinned on every other segment, and #346 had to fold
+  the shortcode's case in the item catalogue because an address is lowercased when
+  it is read.
+  
+  **A consumer with a capital in a shortcode will fail to build**, citing the
+  note's file, line and column. The sweep is mechanical: every violation in every
+  tree is a capital letter — no underscores, hyphens or other characters occur —
+  and **nothing collides when folded**, checked per `(type, shortcode)` in every
+  tree.
+  
+  | tree                              |  shortcodes to change |
+  | --------------------------------- | --------------------: |
+  | `Song-of-Heroic-Lands-FoundryVTT` |                   438 |
+  | `sohl-thalorna`                   |                    96 |
+  | every other tree                  | 0 — already compliant |
+  
+  **No document changes identity and no URL moves**, because an address and a
+  document `_id` already derive from the lowercased form. References need no edit
+  either: no authored wikilink target carries a capital (10,538 checked), and
+  `model:` addresses are already lowercase.
+  
+  **The emitted packs do change, in three narrow ways**, measured on `sohl`'s 438:
+  
+  | change                                                | count |
+  | ----------------------------------------------------- | ----: |
+  | `system.shortcode` on an Item document, `Clb` → `clb` |   438 |
+  | embedded item `_id` / `_key` on one being             |     6 |
+  | journal pages showing a shortcode in a content table  |     5 |
+  | **top-level document `_id`**                          | **0** |
+  | **addresses and published URLs**                      | **0** |
+  
+  The first is the point: the emitted field now matches the address built from it.
+  The six embedded ids move because an embedded id derives from the item's own
+  `system.shortcode`, which #346 deliberately does **not** case-fold — folding
+  there would re-identify documents rather than look them up.
+- 4890864: **A map note's `image:` is no longer read** (#149). Its art is `img:`, as every
+  other note type's is.
+  
+  This is the third and last step of the rename #142 began. Through the retirement
+  window both spellings were read, `img` won where a note carried both, and a note
+  still writing `image` got a located warning — it compiled to the byte-identical
+  document, so failing a build over it would have redded a tree that had done
+  nothing wrong. The trees have since been swept, so the alias has nothing left to
+  honour and is gone.
+  
+  **No shipped tree is affected.** Every content tree was checked — `sohl`,
+  `sohl-thalorna`, `sohl-kethira-basic`, `harn-ensemble` and `harn-adventures` —
+  and none writes the retired spelling. The window did its job; this only closes
+  it.
+  
+  **What an unswept note now sees.** Two errors rather than one warning, and it
+  stops compiling: `image` in a `sohl:` block is reported as a key the type does
+  not have, and the `img` the note therefore never declared is reported as
+  missing. The fix is the rename, and moving the key to the note's top level while
+  you are there — art is not system-specific, so it belongs beside every other
+  note's `img` rather than inside a system block.
+  
+  **A tile's `image:` is untouched.** `sohl.tiles.<key>.image` is a nested
+  placeable's texture, not the note's own artwork, and was never the retired field:
+  the check reads the `sohl:` block's own keys and never descends into one.
+  
+  **Nothing was added to refuse it.** The two findings above are the ordinary
+  unknown-key and required-field checks, which is the point of a rename's third
+  step — one that had to add a standing refusal would be one whose replacement
+  never arrived. No tombstone entry is kept: the absence of an alias is the record.
+- a1c21e8: **A being's items entry names the item it copies with `model:`, an address**
+  (#334). The top-level `shortcode:` it replaces is retired.
+  
+  ```yaml
+  sohl:
+    items:
+      - { model: skill-wpnc, system: { masteryLevelBase: 52 } } # this package
+      - { model: sohl-sohl-weapongear-dgr } # another one
+  ```
+  
+  The old key was doing two jobs badly. It **selected a template**, while the
+  `system.shortcode` beside it **was** the compiled item's identity — one word for
+  two things, which the compiler's own error messages had to keep explaining. And
+  it could not say **which package** the template came from: `loadItemsMap`
+  flattened every local Item pack and every dependency catalogue into one
+  `subType:shortcode` space where a local definition silently shadowed a foreign
+  one. In `sohl-thalorna`, 25,485 of 26,251 model references reach into `sohl` and
+  none of them said so; the day that repository ships its own `weapongear-dgr`,
+  every entry citing `dgr` would have retargeted with a green build and no
+  diagnostic.
+  
+  **What changes for an author**
+  
+  |                          | before                             | after                                          |
+  | ------------------------ | ---------------------------------- | ---------------------------------------------- |
+  | naming a template        | `{ shortcode: wpnc, type: skill }` | `{ model: skill-wpnc }`                        |
+  | reaching another package | impossible                         | `{ model: sohl-sohl-skill-wpnc }`              |
+  | `type:` beside it        | required                           | refused — the address names the type           |
+  | a custom item            | `name` + `type` + `system`         | unchanged, and `system.shortcode` now required |
+  
+  A `model` is read by the same grammar every wikilink is (#336), so it is written
+  at whatever length says what it means and the system segment defaults from the
+  block the entry sits in — which is why the short form names an **Item** here
+  while the same string in body prose names a page.
+  
+  **The catalogue is package-aware.** Every item is keyed under its own package as
+  well as unqualified, so a `model` that states a package resolves to that
+  package's item and nothing local can shadow it, while a `model` that states none
+  still resolves locally-first exactly as before. `foreignItemCatalogDirs` returns
+  `{ dir, package }` rather than a bare path.
+  
+  **Consumer sweeps**: HeroicLands/Song-of-Heroic-Lands-FoundryVTT#1875 (95 beings,
+  1,557 entries) and HeroicLands/sohl-thalorna#176 (645 beings, 26,251 entries plus
+  938 shortcodes derived for custom gear).
+
+### Minor Changes
+
+- ccf35a1: **An actor note now publishes documentation, like every other note that compiles
+  into a system-bearing document** (#337).
+  
+  A being used to produce its Actor and nothing else. That left it the one
+  system-bearing note with no address at `none` — its only address named the
+  Actor — so a prose link written `[[being-<shortcode>|Text]]` had no page to land
+  on. `sohl-thalorna` alone carries 772 such links.
+  
+  `docEntryTypes` is now `itemTypes` plus the actor types the shipped subtype maps
+  declare (derived from those maps, not listed again), plus `macro` and the map
+  types. Only `doc` stays outside it, for the reason that actually applies to it:
+  its single document _is_ the prose.
+  
+  **What a consumer sees**
+  
+  | Before                                | After                                                                |
+  | ------------------------------------- | -------------------------------------------------------------------- |
+  | `<pkg>-<system>-being-<shortcode>`    | that, **and** `<pkg>-none-docbeing-<shortcode>`                      |
+  | a being's prose reachable only inline | also a JournalEntry, and a page the site publishes                   |
+  | `[[docbeing-x\|Text]]` unresolved     | resolves, in the link checker, the pack compilers and the site build |
+  
+  Packs gain one JournalEntry per being **carrying prose**; a being with an empty
+  body compiles no entry, exactly as an item with an empty body does. No existing
+  document changes.
+  
+  **A being keeps its prose inline as well**, and the asymmetry with items is
+  deliberate. `system.appearance` and `system.dossier` stay as rendered text, where
+  an item's description is an `@UUID` pointer into its journal. One item is
+  embedded across hundreds of beings, so baking its description into every copy
+  bloats the compendium by the length of the prose times the number of carriers,
+  and the pointer buys that back. An actor is singular, so the same indirection
+  would cost a reader a click and save nothing.
+- afb3650: **An asset path's first segment says which package owns it, and the rule is now
+  stated and tested** (#331).
+  
+  `img:` and `portrait:` have always answered "which package holds this file?" in
+  their first segment, but nothing wrote the rule down and nothing asserted it —
+  the only way to confirm it was to compile a package and read `build/packs-json`.
+  
+  | Authored path starts with | Owner                 | Emitted              |
+  | ------------------------- | --------------------- | -------------------- |
+  | `systems/`                | a separate **system** | unchanged            |
+  | `modules/`                | a separate **module** | unchanged            |
+  | anything else             | **this package**      | `<assetRoot>/<path>` |
+  
+  **The third row is now true.** The translator prefixed `icons/…` and `images/…`
+  and passed everything else through — the same answer for every path any tree
+  authors today, and the wrong one for the next directory a package ships.
+  `sohl-kethira-basic` keeps art under `assets/artwork/`, so an authored
+  `artwork/deity.webp` would have shipped unprefixed: a 404 in Foundry, reported
+  by nothing. Ownership is the rule; the directory names inside a package's
+  `assets/` tree are that package's business.
+  
+  An address naming no package — an absolute URL, a `data:` URI, a `/`-rooted
+  path — passes through, on the same rule rather than as an exception. `worlds/`
+  is deliberately not exempt: a package may not ship art out of a world.
+  
+  **No compiled document changes.** Compiling `sohl-thalorna` and this system's
+  own tree before and after gives byte-identical `packs-json`; every path either
+  tree authors is `icons/`, `images/` or already `systems/`-rooted.
+  
+  **`banner:` is a path that does not follow this rule, and is documented as
+  deliberate rather than reconciled.** It reaches no compiled document: it is a
+  top-level key the Hugo theme reads, and the theme prefixes a relative value with
+  `images/` and joins it onto `params.cdnBaseURL`. The two address different
+  places — `img:` a file Foundry serves, `banner:` a file the CDN serves.
+- e3d300c: **An `img:` authored on a type that emits none is now reported instead of
+  dropped in silence** (#349).
+  
+  `img` is a shared top-level field — it maps onto `document.img`, so it is legal
+  on every note whatever the type — but not every document has one. `doc`, `place`,
+  `lore` and `scenario` compile into a JournalEntry, `folder` into a Foundry
+  `Folder`, and neither carries artwork; a `homepage` compiles into no compendium
+  document at all. On any of those the authored path went nowhere, the note
+  validated, the tree compiled clean, and nothing said so.
+  
+  The frontmatter lint now warns, naming the note, the key and what the type
+  compiles into. `portrait:` is checked the same way, so an item authoring one is
+  told it has nowhere to put a sheet portrait.
+  
+  **What it does not report.** `img: null` — that is the blessed way to say "this
+  note names no art", and on a type with no art it is a true and harmless thing to
+  say. A warning rather than an error, too: the note still compiles correctly, and
+  a note's top level is the generated page's front matter as well, so a site
+  template may read there what no document carries.
+  
+  **Which types those are is derived, not listed.** Each pass declares the art it
+  writes (`BasePackCompiler.emitsArt`), and `emittedArtFor` walks type → document →
+  pass to answer. A second table of iconless types would be free to drift from what
+  is actually emitted, which is the defect rather than the check.
+  
+  **What a consumer sees.** New advisory findings on notes already in this state;
+  warnings do not fail a build. `sohl-thalorna` has 57 — the `Lore/Totems/` and
+  `Lore/Deities/Kemetian/` clusters, which carried an `img:` from when they
+  compiled to affiliation items. The other shipped trees are clean.
+- bd5e6cb: **`lore` declares `gathering`, a genre for a scheduled public occasion** (#333).
+  
+  A tournament or martial games, a great market or fair, a religious festival, a
+  ceremony or rite: something that happens at a place and a time, on a cycle, and
+  that people travel to. The genre had no value, and neither neighbour fitted.
+  
+  | genre       | what it covers                                                   |
+  | ----------- | ---------------------------------------------------------------- |
+  | `calendar`  | the _reckoning_ — the cycle, the seasons, the dating system      |
+  | `culture`   | a social grouping of people                                      |
+  | `gathering` | the occasion itself — who attends, what is contested or observed |
+  
+  A festival's **date** is `calendar`; the festival is not. A tournament is not a
+  matter of time-reckoning at all, and a great market is not a grouping of people.
+  
+  **Why it matters beyond labelling.** `site.sections` narrows a section with
+  `listSubType`, so a subType is what makes a genre browsable. Without one, a
+  consumer declaring a Gatherings section would sweep in the castes, Marriage and
+  Personal Names alongside the games — the notes could not be listed as what they
+  are.
+  
+  **On the name.** `festival` is too narrow: a tournament is not a festival, a
+  great market is a fair, and a rite is not a celebration. `event` is avoided
+  because it already names something else in SoHL — the event queue and
+  `system.scheduledActions`, where an event is a timed thing that fires in play.
+  `gathering` covers the whole set, and matches how the other `lore` genres are
+  named: a single lowercase noun for a kind of thing.
+  
+  Nothing existing changes. A note already filed under `lore/culture` keeps
+  compiling until its author moves it; `subType` is not an address, so nothing
+  resolves through it.
+- 5630e7c: **A note can no longer author a field the document writes in play** (#330).
+  
+  A data model declares everything a document stores, and part of that is runtime
+  state — an affliction's `onsetDate` is the world time its onset fired at.
+  Writing `sohl.system.onsetDate` reached it as directly as any other field: the
+  block is a verbatim passthrough, no declared field claimed the path, and the
+  schema check's fatal direction is _undeclared_, which a field the schema really
+  does declare satisfies. So a compiled pack could ship one world's play state to
+  every world that installed it, with the build reporting success.
+  
+  A field declaration may now say `runtimeOnly`, whose value is the reason — what
+  the field holds — the way `topLevelMeans` already works. It states both halves
+  of one fact:
+  
+  | declaration   | authored    | absent          |
+  | ------------- | ----------- | --------------- |
+  | ordinary      | emitted     | default written |
+  | `runtimeOnly` | **refused** | key omitted     |
+  
+  The refusal names the note, the line, the whole key and the field's own reason,
+  and says that deleting it is the fix — there is no value that makes writing one
+  right. Omitting the key rather than emitting `null` is what leaves the data
+  model's own `initial` standing.
+  
+  It is a property of the declaration, not a list of names, so it holds for any
+  runtime-only field any system adds later. Such an entry declares a `to` and no
+  `name`, which keeps it out of the authored vocabulary — the generated field
+  reference lists it under **Never authored** with its reason instead of as a row
+  an author might fill in — while still claiming the path for the passthrough.
+  
+  **What a consumer sees**
+  
+  - SoHL's six timed-phase dates are declared: `contractDate`, `onsetDate`,
+    `treatmentDate` and `resolutionDate` on `affliction`; `contractDate` and
+    `treatmentDate` on `trauma`. No tree authors one today, so no compiled
+    document changes.
+  - The refusal covers both positions a note can reach them from: a note's own
+    `<system>.system` block, and an actor's `items:` entry `system:` overlay,
+    which merges verbatim and so passed no field declaration at all.
+  - A runtime-only path is no longer reported as a field the builder forgot to
+    emit — "every compiled document will carry the field's initial value" is what
+    the declaration is _for_, so the warning could never be cleared.
+  - Regenerate the item frontmatter reference to pick up the new section.
+- cf20488: **The specification's `subType` lists are compared to the declared vocabulary,
+  for every type** (#345).
+  
+  `tests/content-format-agreement.test.ts` made `docs/content-format.md`
+  executable for the `data` property tables only. The other half of the same
+  vocabulary entry — a type's genres, which an author picks from and which a
+  note's `subType` is closed against — was prose that nothing read, free to
+  disagree with `note-vocabulary.mjs` in either direction. That is the drift #231
+  and #232 were filed about, on the half they did not reach. `gathering` (#333)
+  guarded `lore` alone, deliberately scoped to the type it changed.
+  
+  **The five spellings converged on one first.** The document stated a type's
+  values as `subType`, `subType:`, `**subType**`, `**subType**:` and
+  `**subTypes**:`, and a reader that accepted every one of them would accept the
+  sixth by reading that section as declaring nothing — the exact failure the
+  comparison exists to catch. One shape is now stated in the specification and
+  enforced by the parser: `**subType**:` on its own line, then `- <value>` or
+  `- <value>: <definition>`, one bullet per value. A type with no `subType`, or
+  one whose values are not enumerated yet, writes no marker.
+  
+  | Written                                      | Read as                                                     |
+  | -------------------------------------------- | ----------------------------------------------------------- |
+  | `**subType**:` + a bullet per value          | that type's closed value list, in document order            |
+  | no marker                                    | the type enumerates none — the ordinary case for nine types |
+  | any other spelling, or a marker with no list | a build error naming the line                               |
+  
+  **What the comparison asks**, of every type rather than of `lore`: the values
+  the specification lists equal the values `NOTE_VOCABULARY` declares, in the same
+  order. `subTypes` stays three-valued — a list is closed, `null` is a `subType`
+  whose values are not enumerated, an absent key is a type with no `subType` at
+  all — and each reading is compared to what the document states. The `lore`-only
+  assertion is folded in.
+  
+  Nothing that compiles changes: the values were already equal everywhere, in both
+  shapes, so this is about keeping them that way. `parseContentFormat` gains a
+  `subTypes` array per type, and throws on a marker it does not recognise —
+  reachable only through `content-format --spec <a copy of the document>`.
+- 312379e: **Afflictions and traumas can declare their timed phases** (#329).
+  
+  SoHL stores each timed phase as `{…DurationFormula, …DurationBase, …Date}`, and
+  the two authored thirds were declared by nothing. They were reachable only
+  through the raw `system:` passthrough — undocumented, uncoerced, and absent from
+  the field list every author-facing surface is built from — so no note in any
+  tree wrote one. Every shipped affliction carried `null`, and
+  `AfflictionLogic.rollDuration()` opens `if (!formula) return 0`: the timed-phase
+  machinery existed, and the content that would drive it could not be written.
+  
+  They could not simply be declared either. `buildFromFields` wrote every declared
+  field unconditionally, so a declaration would have stamped `null` onto every
+  document — the same outcome, minus the ability to tell "unset" from "authored as
+  empty".
+  
+  **`omitWhenAbsent`** is the missing capability: a field declaring it is emitted
+  when the note carries one and has its **key left out entirely** when it does
+  not, so the DataModel's own `initial` stands. It completes the table
+  `runtimeOnly` (#330) opened:
+  
+  | declaration      | authored    | absent          |
+  | ---------------- | ----------- | --------------- |
+  | ordinary         | emitted     | default written |
+  | `omitWhenAbsent` | emitted     | key omitted     |
+  | `runtimeOnly`    | **refused** | key omitted     |
+  
+  The decision is made on the **position** a value came from, never on the value:
+  a declared `default: null` and an authored `null` are the same value and
+  opposite facts. `readFieldEntry` reports the source beside the value so the
+  position is resolved once rather than twice.
+  
+  **Twelve fields are now declared vocabulary** — `onset`, `healingCheck` and
+  `resolution` on `affliction`; `healingCheck`, `bloodLossAdvance` and `course` on
+  `trauma` — each as both a `…DurationFormula` and a `…DurationBase`, in the
+  `sohl:` block and in the closed `data:` container alike. Intervals are in
+  seconds, and a bare number is a valid formula.
+  
+  **What a consumer sees**
+  
+  - The twelve appear in the generated item-frontmatter reference, with `_omitted_`
+    in the Default column rather than a value. Regenerate the page.
+  - The `unemitted` warnings these raised against a pinned schema clear.
+  - No compiled document changes: no tree authors one yet, and a note that writes
+    nothing emits nothing where it previously emitted nothing.
+  - `omitWhenAbsent` may not be combined with `default` (contradictory), with
+    `required`, or with `runtimeOnly`; the shipped declarations are checked for all
+    three.
+
+### Patch Changes
+
+- b5004f0: **A `model:` now resolves an item whose shortcode carries a capital** (#346). The
+  catalogue was keyed on the compiled document's `system.shortcode` exactly, while
+  an address is lower-cased when it is read — so `model: weapongear-clb` looked for
+  `weapongear:clb` while the document sat under `weapongear:Clb`, and every being
+  referencing one of the six mixed-case gear shortcodes in `sohl` failed to
+  compile.
+  
+  The catalogue key folds the shortcode's case. The **id-bearing** address does
+  not: `itemAddress` seeds `embeddedItemId`, so folding there would change the
+  `_id` of every embedded item whose identity carries a capital — silently
+  re-identifying documents nothing about which had changed. A catalogue is a lookup
+  table; an id is a promise.
+  
+  Verified by compiling both swept trees: `sohl` emits actors, items, macros,
+  scenes and adventures byte-identical to its pre-sweep baseline, and
+  `sohl-thalorna` differs only by the 938 embedded ids its sweep predicts.
+- 4c57a5a: **A being's `data.portrait` reaches the actor** (#332). It never had: the
+  emitters read `blockProperty(fm, "portrait")`, which knows a system block and
+  the note's top level and never splits a dotted path, so the position the content
+  format names was invisible to them — and the `?? defaultImg` beside it turned
+  every miss into the subtype's icon rather than into a complaint. 646
+  `sohl-thalorna` beings authored a portrait, 341 of them pointing at art that
+  exists on disk, and every one compiled the generic person icon. Nothing warned.
+  
+  `portrait` now resolves through the same declaration `data.species` does, in
+  both the `sohl` and `hm3` actor passes.
+  
+  **A `data:` source has a retiring top-level spelling, and step 3b reads it.**
+  `data:` did not invent the facts it holds — it gathered them out of the note's
+  open top level, where `portrait:` sat beside `img:` — so the pre-`data:`
+  spelling of `data.<key>` is `<key>`, and until now nothing read it. That is why
+  this is a resolution-order fix and not a one-line emitter fix: `data.portrait`
+  had to start working _without_ breaking the top-level `portrait:` that `sohl`'s
+  own bestiary writes on every note.
+  
+  The spelling is **derived**, not declared — a second declaration would be a
+  second place for one fact to live — and only a `data.` source has one, so
+  `protection.blunt` and `impact.die` resolve exactly as they did.
+  
+  **Nothing is dropped in silence any more.** A field read from the retiring
+  top-level key emits a warning naming the line, the counterpart to the existing
+  in-block report; the note compiles to the identical document either way. The
+  frontmatter lint's `portrait: ""` check reads the `data:` position too, which it
+  could not see before.
+- 59469d7: **The dependency check read English prose in a comment as an import** (#355).
+  
+  `tests/dependencies-are-declared.test.ts` finds a shipped file's imports with a
+  regex over the raw file text. It already reasoned about one false positive — the
+  lookbehind stops `["from", "to"]` reading as an import of `", "` — but not about
+  comments, where `from` is an ordinary word and the quotes are ordinary quotes.
+  Any explanatory comment containing the word `from`, `import` or `require`
+  followed by a quoted phrase was reported as an undeclared dependency:
+  
+  ```text
+  FAIL sohl/item-fields.mjs imports only builtins, itself, or a declared dependency
+    + [ "sohl/item-fields.mjs:455 → this note does not set the phase" ]
+  ```
+  
+  The message names a real file and a real line and says a dependency is missing,
+  so the first reading is that one genuinely is. Nothing in it suggests the culprit
+  is a sentence, and the fix — reword the comment — is unrelated to anything the
+  message describes. It cost a debugging cycle in #329, and the workaround left the
+  trap armed for whoever wrote the next comment.
+  
+  **Comments are now blanked before the regex runs.** They are located by parsing
+  the file, not by a second regex, so `//` inside a string literal is still a string
+  literal. Each comment's characters are replaced one-for-one with spaces and its
+  newlines are left alone, so every offset survives and a finding still points at
+  the line a reader opens. The `sohl/item-fields.mjs` comment that provoked this
+  reads naturally again, and the suite carries it verbatim.
+- fec6c80: **The generated item-frontmatter examples no longer author an `id:`** (#314).
+  
+  `content-build docs item-fields` emitted `id: <16-character id>` in the worked
+  example for every item type — thirteen of them in the `sohl` tree. Since #270
+  and #277 a note's document `_id` derives from its canonical address, and the
+  authored field is the escape hatch for keeping a document's identity across a
+  shortcode rename, not part of the envelope every note carries.
+  
+  The example is the block an author copies as a template, and the page is the
+  per-type reference they read while writing the note, so the one place the field
+  survived a tree's sweep was the document teaching them to write it. It is now
+  omitted, as every other optional envelope field already was; the `type` and
+  `shortcode` the derivation reads are unchanged.
+  
+  Consumers should regenerate their item frontmatter reference to drop the line.
+- a48802f: **A folder note's published `id` is now the id its Foundry documents carry**
+  (#310).
+  
+  The content index derived every note's id under the `document` namespace. A
+  `Folder` is hashed under the `folder` namespace, so the index published one
+  value and the packs addressed another — `sohl-none-folder-cookware` was
+  `f5d3dc635b7e799c` in the index and `b92b28b7d06638ed` in every pack.
+  
+  `noteDocId` now asks the folder pass for a folder's id instead of deriving a
+  second one, so the two cannot disagree.
+  
+  **Why nothing caught it.** Every one of `sohl`'s 79 folder notes pins an `id`,
+  and a pin wins in both paths — so all 65 emitted folder documents agreed by
+  coincidence. It is also invisible from inside a build: no pass reads a folder's
+  id off the index. The published artifact was the only place the wrong value
+  surfaced, and a reader outside the build could neither recompute the right one
+  nor notice the wrong one.
+  
+  **The general rule this settles:** for every entry the content index gives an
+  identity to, it publishes both the `id` and the `uuid`, each computed once by
+  whatever owns that entry's derivation. A documentation journal's record
+  accordingly gains its own `id` — it carried the UUID that id ends in, but not
+  the id — so a consumer reads it rather than parsing it back out of the UUID's
+  last segment.
+  
+  _No emitted document changes; this corrects what the index says about them._
+- ebd3a80: **A note-level frontmatter check no longer answers from a system field that
+  merely shares the name** (#312).
+  
+  `topLevelMeans` exists because one spelling can name two unrelated quantities. An
+  `affiliation` item's `system.title` is the style of address an office carries —
+  "Ajaw", "Warden"; a note's top-level `title` is the heading its page publishes
+  under. The field declares the collision, and `resolveFieldValue` honours it by
+  refusing to read the top level for that field.
+  
+  The frontmatter lint did not. `authoredValue` resolved every check through the
+  `sohl:` block first, so the blank-heading check — whose emitter is `fm.title ??
+  name`, the note's top level and nothing else — read `sohl.title` and found the
+  office's style of address. An office with no style of address is ordinary, and
+  each one was reported as a page published with no heading, sorting to the front
+  of its section.
+  
+  **The statement is symmetric, and is now read that way.** If two positions hold
+  unrelated quantities then the in-block position is not the note-level field
+  either, so a note-level check reads past a block key the note's own type claims
+  for something else. The exemption is still the field's own declaration rather
+  than a name the linter knows: `collidingBlockKeys` asks the schemas the caller
+  supplies, so the linter and the resolver cannot disagree about which field
+  declares one.
+  
+  **The art fields are checked the same way.** `img` and `portrait` keep resolving
+  through the block, because that is what their emitter does — `blockProperty`
+  reads `sohl.img` first, so a `sohl.img: ""` really does ship a document with no
+  art and is still reported. What changes is that a future system field of either
+  name cannot quietly answer for the note's own art; a map's was `sohl.image`
+  until #142.
+  
+  **What a consumer sees.** Twenty-eight fewer warnings on an unswept
+  `sohl-kethira-basic` — every affiliation writing `sohl.title: ""`. All were false
+  positives; their pages took `name.full` throughout. A tree already swept onto
+  `sohl.system.title` was unaffected either way, which is why the findings
+  disappearing looked like a lint regression in that sweep rather than the
+  false positives going away.
+- f6a8a05: **The specification and four engine docblocks stated the retired folder model**
+  (#358).
+  
+  The folder epic replaced a model wholesale — `folder:` named a Foundry id
+  resolved against a per-pack `*-folders.yaml`, and `packFolder` named a path.
+  None of that exists: `folder:` is refused, the YAML is gone, and `packFolder`
+  is a folder note's address. Six passages still described the old shape as the
+  live one.
+  
+  **`docs/content-format.md` contradicted itself twice.** The shared-mappings
+  table — the one place eight rows common to all sixteen type tables are stated —
+  offered `` `packFolder` / `folder` ``, so a reader was told to write a value the
+  build rejects, 330 lines before the same document says it is retired. And the
+  argument for deriving a document id cited "`packFolder: <path>` above", where
+  above says address.
+  
+  **Four docblocks described the retired resolution path**, and they publish:
+  
+  | site                       | said                                                                                |
+  | -------------------------- | ----------------------------------------------------------------------------------- |
+  | `engine/generate.mjs`      | folder files "referenced from entry frontmatter via `sohl.folder: <id>`"            |
+  | `engine/journals.mjs`      | the target folder's id "from folders.yaml", resolved against a folders.yaml list    |
+  | `engine/base-compiler.mjs` | `folderResolver` "resolves a `sohl.folder` id against this pack's folder hierarchy" |
+  | `engine/frontmatter.mjs`   | `folderField` reads "two spellings", `packFolder` winning "where both are present"  |
+  
+  The last two were the sharpest. `folderField` reads `packFolder` and nothing
+  else, so its docstring described a resolution the function cannot perform and
+  deferred to an issue that had closed. `generate.mjs` disagreed with itself
+  across one file: the module header named `sohl.folder`, while its `resolver`
+  states the rule correctly — "There is one spelling."
+  
+  **Prose is the defect the epic was about.** Its argument against
+  `*-folders.yaml` was that a second, unchecked statement of one fact drifts from
+  the first, and nothing compares the two. These six passages were exactly that,
+  and nothing caught them: `lint:content-format` makes a claim only for a
+  `system.*` target, so a row mapping to core Foundry's `folder` yields none, and
+  the source side of a shared row is checked by nothing at all.
+  
+  Two assertions now hold the specification to it — the shared-mappings sources
+  name no retired field, and the document never presents `packFolder` as holding
+  a path. The docblocks are held to review instead: a sentence describing
+  `folder:` as _retired_ is correct and must survive, and no assertion separates
+  that from one describing it as live without reading the prose.
+  
+  No behaviour changes; the fix is what the documents say.
+
 ## 19.0.0
 
 ### Major Changes