@heroiclands/package-build 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,189 @@
 # @heroiclands/package-build
 
+## 6.1.0
+
+### Minor Changes
+
+- dc424d7: **`content-build addresses diff` reports every published address a build has
+  stopped publishing, and tells a rename from a removal** (#66).
+  
+  A package's `(type, shortcode)` addresses are a published interface — every
+  satellite declaring `itemCatalog: true` assembles its beings out of them — but
+  nothing compared one release's addresses against the next, so renaming a
+  shortcode cost nothing and produced no signal. The check that got made instead
+  was a repository-local grep, which cannot see the other repositories and reports
+  the reassuring answer. `sohl` renamed `weapongear:Tabri` to `weapongear:Taburi`
+  two days after the `v0.8.2` tag both satellites pin, stating that nothing
+  referenced the old value; five lookups across two repositories do, and they fail
+  the moment either pin moves.
+  
+  ```bash
+  gh release download v0.8.2 -p system.zip -D build/baseline
+  npx content-build addresses diff --from build/baseline/system.zip
+  ```
+  
+  Run against `sohl` today that reports 20 findings — 8 renames and 12
+  withdrawals — including the `Tabri` one, at the line of the note that made it:
+  
+  ```text
+  assets/content/Weapons/Melee/Taburi.md:12:1: warning: since sohl@0.8.2, weapongear:Tabri is no longer published; the same document (s5D6QJbw7ZbETxdN) is now published as weapongear:Taburi. Every package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
+  ```
+  
+  **A rename is told from a removal by the document id, which is an identity match
+  rather than an inference.** A note authors its `_id` in frontmatter and it is not
+  derived from the shortcode, so it survives a rename. Where the id is published
+  under no address at all, the finding says only that — _withdrawn_, naming no
+  successor. A split, a deletion and a merge are indistinguishable at that point,
+  and a "did you mean" guessed from string similarity would send the reader to the
+  wrong fix.
+  
+  Both findings are warnings and neither fails a build: retiring content is
+  legitimate, and so is renaming — the shortcode charset rule forces some. What a
+  rename must not do is happen in silence. `--strict` reports both as errors and
+  exits non-zero, for a release workflow that wants a gate.
+  
+  Additive: nothing runs unless the command is invoked, and no existing behaviour
+  changed.
+- f28f653: A section can now describe itself: `site.sections` and `site.readmeSections`
+  take a `description`, and it reaches the generated `_index.md` (#91).
+  
+  A generated section landing is the only place a section can speak — a content
+  package authors no `_index.md` for `weapongear` or `affliction`, so the file the
+  theme reads is the one this build writes. Its vocabulary was two keys, and
+  `partials/hero-banner.html` has always rendered `description` as the hero
+  standfirst, so every generated landing rendered a heading with no standfirst and
+  could not be given one by any consumer, at any level.
+  
+  **The pair was the defect, not a passthrough.** The vocabulary lived in two
+  places that had to be kept in step by hand: the schema that admits a key, and
+  the two writers that each transcribed `title` and `banner` by name. A key added
+  to the schema alone validated cleanly and then reached no page. So the writers
+  stop naming keys and emit what the section resolved to, `title` first, and the
+  schema is now the single place a section's vocabulary is decided.
+  
+  **The bound stays.** An unrecognised key under a section is refused at config
+  load, by name, exactly as before — `site.sections.affliction.descrption is not a
+  recognized option (expected one of: title, banner, description)`. Passing
+  sections through unvalidated the way `site.landing` is was weighed and refused:
+  `landing` is written once, for the mount, in one landing template's vocabulary,
+  where a section entry is written fourteen to twenty times per build against a
+  contract every package shares. Unbounded, a mistyped `descrption:` would publish
+  into front matter, be read by nobody, and say nothing to anyone — which is the
+  failure this issue was filed about, one step downstream where no build can see
+  it.
+  
+  Additive. `description` is optional and no consuming package declares one — none
+  could, since the loader has always refused it — so every generated landing is
+  byte-identical, verified across all six consuming packages.
+- 43a9de4: Refuse `name`, `shortcode` and `id` on a `type: homepage` note (#53).
+  
+  A note's URL derives from `name.full` and its identity from `(type, shortcode)`.
+  The homepage is the one page for which neither holds — it publishes at
+  `/<package>/`, fixed by the package id — so an author fluent in the conventions
+  writes them there expecting exactly what they do everywhere else, and gets none
+  of it. Until now `content-build lint` ignored all three: a homepage carrying
+  `shortcode`, `id` and `name.full` passed at exit 0.
+  
+  **They were never inert, which is why ignoring them was the wrong answer.** A
+  `shortcode` puts the note in the address index and in the `dataview` link
+  universe, so `[[homepage-<shortcode>]]` resolves _green_ — to `homepage/<slug>/`,
+  an address derived from `name.full` and published by nothing, because a homepage
+  is written to `_index.md` at the package root. A build that reports a live link
+  to a 404 is worse than one that says nothing.
+  
+  **The inflated address tally is the same defect, not a second one.** The same
+  note was counted as an address it does not publish, so the lint and the link
+  manifest disagreed about what the package ships: SoHL's tree reports
+  `1607 address(es) across 1607 note(s)` with a `shortcode` on its landing and
+  `1606 address(es) across 1607 note(s)` without one. The tally is only ever
+  printed on a clean run, so refusing the field is what makes the count honest —
+  `lintContentTree` needed no change, and got none.
+  
+  **A named class, not an allow-list, and that boundary is the decision.** An
+  unknown top-level key is deliberately still accepted. A homepage's frontmatter is
+  emitted into the published page, so an unrecognised key is a Hugo or theme
+  parameter this build has never heard of and has no standing to reject, and a
+  closed list would make every new theme parameter wait on a package-build release.
+  What is refused is the class that makes a false claim about _where this page is_.
+  `aliases` is not in it either — it is already dropped from every emitted page, so
+  authoring one here is the same no-op it is anywhere else. This departs from the
+  issue's third acceptance criterion, deliberately: over-strictness here breaks
+  authoring on a page whose whole frontmatter is pass-through.
+  
+  **Where it fires: `content-build lint` only.** This is a frontmatter-schema rule,
+  and `content-build site` runs none of them; wiring one type's field rule in there
+  would have the site build refuse `shortcode` on a homepage while accepting
+  `weight: heavy` on a weapon. The gap that leaves is `HarnMaster-3-FoundryVTT`,
+  which runs no `content-build lint` at all and so receives no frontmatter finding
+  of any kind — a missing script in that repository rather than a rule to duplicate
+  one at a time.
+  
+  Each finding is located at the offending key and says what the field would have
+  decided:
+  
+  ```text
+  assets/content/homepage.md:26:1: error: `shortcode` decides nothing on a `type: homepage` note: this page's address is the package's own, `/<package>/`, fixed by the package id. It is not ignored either — it puts the note in the address index, so `[[homepage-<shortcode>]]` resolves to a page the site build never writes. Delete it
+  ```
+  
+  **Minor rather than major, measured rather than assumed.** A new hard error is
+  breaking only if it fails a previously-passing consumer. All six HeroicLands
+  content packages were linted at their default branch, before and after — `sohl`,
+  `hm3`, `thalorna`, `kethira`, `harnensemble` and `harnadventures` — and every one
+  produces byte-identical findings and the same exit code with the rule as without
+  it. None of the six authors any of the three fields on its homepage.
+- d1166d0: Require exactly one `type: homepage` note per package (#52).
+  
+  Every package is reachable at `/<package>/` and what a reader finds there is one
+  authored note in its content tree — but nothing required a package to have one,
+  so the failure mode of the whole arrangement was a package that builds green and
+  serves nothing at its own address.
+  
+  **Zero and two are the same defect, at the same severity.** Neither is a warning,
+  because a build that proceeds past either publishes the wrong front page while
+  reporting success — which is exactly what a warning tolerates.
+  
+  | Count    | What ships                                                                                                                                                                       |
+  | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | **Zero** | Nothing at `/<package>/`, silently: the site build reports `wrote 0 homepage(s)` and exits 0.                                                                                    |
+  | **Two**  | A page nobody chose. Both are written to the same `_index.md`, so the last one walked wins — the front page decided by _filename_, on a type whose point is frontmatter routing. |
+  
+  **It fires in `content-build lint` and in `content-build site`, because neither
+  one reaches every package.** `HarnMaster-3-FoundryVTT` runs `site` and no `lint`;
+  `sohl-thalorna` runs `lint` and its own site builder. A rule in one of them is a
+  rule two of the six packages do not have. Both call the same function, so this is
+  one rule with two call sites rather than two rules that can drift. In the site
+  build it runs _before the output tree is cleared_, so a failing gate cannot
+  destroy a good site to report a bad tree.
+  
+  **It does not vary by `publish.site`.** That setting chooses whether the
+  _content_ surfaces are published; the homepage is the floor beneath both modes.
+  The lint call site reads no `site:` block at all, so it could not vary by mode
+  even if the rule wanted to.
+  
+  **Zero has no file to name, and none is invented.** The locator is the content
+  root — a real path, and the directory the note has to be added to — with no line
+  and no column, as the diagnostic rules require. Two is reported once per note,
+  located at its own `type:` value and naming the other, because each note is a
+  place an author has to open and edit:
+  
+  ```text
+  assets/content: error: holds no `type: homepage` note, so package "sohl" publishes nothing at its own address /sohl/ — a package's front page is one authored note in this tree, routed by `type:` rather than by filename
+  assets/content/homepage.md:3:7: error: duplicate `type: homepage` note, also declared by assets/content/Landing.md; a package has one front page, at /sohl/, and every homepage is written to the same `_index.md` — so the one the walk reaches last silently overwrites the rest
+  ```
+  
+  **Minor rather than major, measured rather than assumed.** A new hard error is
+  breaking only if it fails a previously-passing consumer. All six HeroicLands
+  content packages were run at their default branch, before and after: `sohl`,
+  `hm3`, `thalorna`, `kethira`, `harnensemble` and `harnadventures` each carry
+  exactly one homepage note, and every one produces byte-identical findings and the
+  same exit code with the check as without it.
+  
+  The issue's sequencing — ship it inert, flip it to an error later — was written
+  when the count was ~45 repositories and two homepages existed only in unmerged
+  pull requests. Both have since merged, the real count is six, and every one
+  passes today, so the warning window would protect nobody and the flip would be a
+  second pull request for no reason.
+
 ## 6.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -474,6 +474,7 @@ npx content-build markdown [paths..] [--fix]
 npx content-build manifest [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]
 ```
 
 | Command        | What it does                                                                                                                                                            |
@@ -487,6 +488,7 @@ npx content-build reachability <dir> [file] [--index <shortcode>]
 | `manifest`     | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).                                                         |
 | `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).                                 |
 
 Every path, pack name and root it needs comes from the consuming repository's
 `package-build.config.yaml`, so the usual invocation takes no arguments beyond
@@ -505,7 +507,7 @@ npx content-build lint            # the configured `paths.content`
 npx content-build lint some/tree  # or a tree named outright
 ```
 
-Checks the two rules every note's **identity** is authored against, and reports
+Checks the three rules every note's **identity** is authored against, and reports
 each finding in the located form below:
 
 - **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the identity
@@ -514,6 +516,8 @@ each finding in the located form below:
 - **Uniqueness** — `(type, shortcode)` names one note. A document is addressed
   across _every_ pack of its document type, so routing two same-address notes to
   different packs with `pack:` does not separate them.
+- **The package's own address** — exactly one note claims `/<package>/`. See
+  [Exactly one homepage](#exactly-one-homepage) below.
 
 It compiles nothing, opens no LevelDB and needs no Foundry manifest, so it runs
 in about a second and can gate a commit. An empty or untyped tree **fails**
@@ -527,6 +531,48 @@ addressed by the package rather than by a slug — so a package in
 permanently unkeyed. That tree passes; a tree holding no notes at all still
 fails.
 
+### Exactly one homepage
+
+A content tree declares **exactly one** `type: homepage` note (#52). Zero is an
+error and two is an error, at the same severity, because they are one defect: a
+package whose front page is not the page a person chose.
+
+- _Zero_ and the package serves nothing at `/<package>/` — the failure the
+  authored homepage exists to prevent, and a silent one: the site build reports
+  `wrote 0 homepage(s)` and exits 0.
+- _Two_ and it serves a page nobody chose. Every homepage is written to the same
+  `_index.md`, so the second overwrites the first and the front page is decided
+  by the order the walk reached the files in — by _filename_, on a type whose
+  whole point is that it is routed by frontmatter. There is no "first wins"
+  convention to fall back on, so nothing can pick the right one.
+
+Neither has a safe default, so neither is a warning: a build that proceeded past
+either would publish the wrong front page while reporting success, which is
+exactly what a warning tolerates.
+
+**Where it fires: `lint` _and_ `site`.** No single command reaches every
+package — `HarnMaster-3-FoundryVTT` runs `content-build site` and no
+`content-build lint`; `sohl-thalorna` runs `content-build lint` and its own site
+builder — so a rule in one of them is a rule two of the six packages do not
+have. Both call the same function, so there is one rule and two call sites
+rather than two rules. In the site build it runs **before the output tree is
+cleared**, so a failing gate cannot destroy a good site to report a bad tree.
+
+**It does not vary by `publish.site`.** That setting chooses whether the
+_content_ surfaces are published; the homepage is the floor beneath both modes.
+The lint call site reads no `site:` block at all, and so could not vary by mode
+even if the rule wanted to.
+
+Zero has no file to name, so the locator is the **content root** — a real path,
+and the directory the note has to be added to. No line or column is invented for
+it. Two is reported once per offending note, located at its own `type:` value and
+naming the other, because each note is a place an author has to open and edit:
+
+```text
+assets/content: error: holds no `type: homepage` note, so package "sohl" publishes nothing at its own address /sohl/ — a package's front page is one authored note in this tree, routed by `type:` rather than by filename
+assets/content/homepage.md:3:7: error: duplicate `type: homepage` note, also declared by assets/content/Landing.md; a package has one front page, at /sohl/, and every homepage is written to the same `_index.md` — so the one the walk reaches last silently overwrites the rest
+```
+
 ### Frontmatter, against the schema its type declares
 
 The same command also checks that each note's `sohl:` block is what its **type**
@@ -570,6 +616,55 @@ does not exist. Removing it was verified output-neutral first: across 1,735
 stripped notes, `package compile` produced byte-identical `build/packs-json` and
 the site build byte-identical `site/content`.
 
+### The homepage carries no address of its own
+
+A note's URL derives from `name.full` and its identity from
+`(type, shortcode)`. The homepage is the one page for which neither holds: it
+publishes at `/<package>/`, fixed by the package id. So `content-build lint`
+**refuses** `name`, `shortcode` and `id` on a `type: homepage` note (#53) rather
+than ignoring them — an author fluent in the conventions writes them here
+expecting exactly what they do everywhere else, and gets none of it.
+
+They were never inert, which is why ignoring them was the wrong answer. A
+`shortcode` puts the note in the address index and in the `dataview` link
+universe, so `[[homepage-<shortcode>]]` resolves _green_ — to `homepage/<slug>/`,
+an address derived from `name.full` that the site build never writes, because a
+homepage goes to `_index.md` at the package root. A build reporting a live link
+to a 404 is worse than one saying nothing. It also inflates this command's own
+address tally, so the lint and the link manifest disagree about what the package
+publishes: SoHL's tree reports `1607 address(es) across 1607 note(s)` with a
+`shortcode` on its landing and `1606 address(es) across 1607 note(s)` without
+one. That is one defect, not two — the tally is only ever printed on a clean run,
+so refusing the field is what makes the count honest.
+
+Each finding is located at the offending key and says what the field would have
+decided, not merely that it does not belong:
+
+```text
+assets/content/homepage.md:26:1: error: `shortcode` decides nothing on a `type: homepage` note: this page's address is the package's own, `/<package>/`, fixed by the package id. It is not ignored either — it puts the note in the address index, so `[[homepage-<shortcode>]]` resolves to a page the site build never writes. Delete it
+assets/content/homepage.md:28:1: error: `name` decides nothing on a `type: homepage` note: a page's slug derives from `name.full`, and a homepage's destination is fixed — it is written to `_index.md` at the package's own address, `/<package>/`. Write `title:` for what the page is called, and delete `name`
+```
+
+**A named class, not an allow-list.** The documented envelope is `type` plus an
+optional `title`, with `landing`, `description` and `banner` legitimate beside
+them — but an unknown top-level key is **not** refused, and that boundary is the
+decision rather than an omission. A homepage's frontmatter is emitted into the
+published page, so an unrecognised key is a Hugo or theme parameter this build
+has never heard of and has no standing to reject; a closed list would make every
+new theme parameter wait on a package-build release. What is refused is the
+specific class that makes a false claim about _where this page is_. `aliases` is
+not in that class either: it is already dropped from every emitted page, so
+authoring one here is the same no-op it is anywhere else.
+
+**Where it fires: `content-build lint` only.** Unlike a rule about the shape of
+the _tree_, which the site build has its own reason to gate on, this is a
+_frontmatter-schema_ rule and `content-build site` runs none of them — wiring in one type's field
+rule would have the site build refuse `shortcode` on a homepage while accepting
+`weight: heavy` on a weapon. The gap that leaves is `HarnMaster-3-FoundryVTT`,
+which runs no `content-build lint` at all and so receives no frontmatter finding
+of any kind; that is a missing script in that repository, not a rule to duplicate
+one at a time.
+
 ### The homepage's own links
 
 The homepage is the page a reader arrives at, and until #54 it was the one page
@@ -789,6 +884,10 @@ title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.t
 What the module is, which system it needs, how to install it.
 ```
 
+A package declares **exactly one** of these, and both `content-build lint` and
+`content-build site` require it — see
+[Exactly one homepage](#exactly-one-homepage).
+
 That is the whole envelope. A homepage **compiles into no compendium
 document**, appears in no pack and in no link manifest, and is addressed by the
 _package_ rather than by its own name — so `name.full`, `shortcode` and `id`
@@ -853,7 +952,10 @@ site:
   trees:
     - { from: kb/dev-docs, section: dev-docs }
   sections:
-    being: { title: Beings, banner: banners/creature.webp }
+    being:
+      title: Beings
+      banner: banners/creature.webp
+      description: Folk, animals and the things that walk the world.
   readmeSections:
     dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
 ```
@@ -863,7 +965,7 @@ site:
 | `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
-| `sections`         | Landing title and hero per section, so a landing matches the card that links to it.              |
+| `sections`         | What each section says about itself on its landing — see below.                                  |
 | `readmeSections`   | The same, for a section whose landing comes from a `README`.                                     |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.     |
 | `backfillSections` | Write a bare `_index.md` for any other section directly under the mount.                         |
@@ -871,6 +973,42 @@ site:
 | `pass`             | A named bundle of this repository's own body rewrites.                                           |
 | `passOptions`      | That bundle's options.                                                                           |
 
+### What a section may declare
+
+A generated section landing is the **only** place a section can describe itself.
+A content package authors no `_index.md` for `weapongear` or `affliction`, so
+the file the theme reads is the one this build writes from `sections` — and
+whatever that entry may carry is the whole of what the section can say.
+
+| Key           | Required | What it does                                                              |
+| ------------- | -------- | ------------------------------------------------------------------------- |
+| `title`       | yes      | The landing's heading, so it matches the card that links to it.           |
+| `banner`      | no       | The hero image, resolved as a CDN asset like any other `banner:`.         |
+| `description` | no       | The hero standfirst under the heading, and the blurb a landing card uses. |
+
+`readmeSections` takes the same three, for a section whose landing comes from a
+`README` rather than from nothing. What the section declares wins over what the
+`README` happens to carry — the landing has to match the card that links to it.
+
+**The vocabulary is closed, and a key outside it is refused by name:**
+
+```text
+package-build config: `site.sections.affliction.descrption` is not a
+recognized option (expected one of: title, banner, description).
+```
+
+That refusal is the point. `landing` is passed through unvalidated because it is
+written once, for the mount, in one landing template's own vocabulary. A section
+entry is written fourteen to twenty times per build against a contract every
+package and every section shares, so an unbounded one would let a mistyped
+`descrption:` publish into front matter, be read by nobody, and say nothing to
+anyone. Refusing it costs one line here when the vocabulary genuinely grows, and
+buys a build that cannot quietly emit a key no theme reads.
+
+The **writers** name no keys: a section's `_index.md` is whatever the entry
+resolved to, `title` first. So extending the vocabulary is a change to the
+schema alone, and the two can no longer drift apart.
+
 ### Why `out` is required
 
 The output tree is a build artifact and is **deleted on every run**, so that a
@@ -931,6 +1069,72 @@ None of them exits the process from inside the library; the command decides. Tha
 is what makes them testable, which the consumer scripts' inline `process.exit`
 calls were not.
 
+## Diffing published addresses
+
+```bash
+gh release download v0.8.2 -p system.zip -D build/baseline
+npx content-build addresses diff --from build/baseline/system.zip
+npx content-build addresses diff --from build/baseline/system.zip --strict
+```
+
+A package's `(type, shortcode)` addresses are a **published interface**. Every
+satellite declaring `itemCatalog: true` assembles its beings out of them —
+`attribute:str`, `skill:awar`, `weapongear:Tabri` — resolving each against the
+Item packs of the release its `compatibility.verified` pins. Renaming a
+shortcode is therefore a breaking change to something other repositories
+consume, and it used to cost nothing and produce no signal: the check that got
+made was a repository-local grep, which cannot see the other repositories and
+reports the reassuring answer.
+
+`sohl` renamed one weapon's shortcode from `Tabri` to `Taburi` two days after
+the `v0.8.2` tag, on the stated ground that "nothing referenced the old value".
+True of that repository. Both satellites pin `v0.8.2` and address
+`weapongear:Tabri` on their copy of the same character — five lookups that
+resolve today and fail the moment either pin moves, reporting a missing item.
+
+**A rename is told from a removal by the document id, and that is an identity
+match rather than an inference.** A note authors its `_id` in frontmatter; it is
+not derived from the shortcode, so it survives a rename. An address that
+disappeared while its document is still published elsewhere _is_ a rename:
+
+```text
+assets/content/Weapons/Melee/Taburi.md:12:1: warning: since sohl@0.8.2, weapongear:Tabri is no longer published; the same document (s5D6QJbw7ZbETxdN) is now published as weapongear:Taburi. Every package that resolves weapongear:Tabri breaks when it moves past sohl@0.8.2
+```
+
+Where the id is published under no address at all, that is all it says —
+**withdrawn**, with no successor named. A split, a deletion and a merge are
+indistinguishable at that point, and a "did you mean" guessed from string
+similarity would be worse than silence, because a wrong one sends the reader to
+the wrong fix.
+
+| Finding     | What it means                                            | Severity                                |
+| ----------- | -------------------------------------------------------- | --------------------------------------- |
+| `renamed`   | Address gone; the same document publishes under another. | `warning` — legitimate, but not silent  |
+| `withdrawn` | Address gone; its document publishes under none.         | `warning` — retiring content is allowed |
+
+Neither fails a build. Retiring content is legitimate, and so is renaming — the
+shortcode charset rule forces some. What a rename must not do is happen without
+anyone noticing. `--strict` reports both as errors and exits non-zero, for a
+release workflow that wants a gate.
+
+**A finding is placed against the note, not the pack it was read from.** The
+address space is read from compiled output because that is what actually ships;
+the content tree is read only to find the note carrying the id, so the reader
+lands on the `shortcode:` line they just edited. A withdrawal has no such note,
+so it degrades to the baseline document — and where neither is readable the
+position is dropped rather than guessed.
+
+**The baseline is named, never derived, and never downloaded.** `--from` takes
+the artifact for the same reason `deps fetch --from` does: a command that
+reaches the network on its own is not reproducible and fails strangely offline.
+A baseline that yields **no** addressable item is refused rather than read as
+"nothing changed" — it would report a clean result for every possible input,
+which is the one failure a check like this can never catch.
+
+Item packs only, because that is the address space consumers resolve against: a
+being's embedded items are the only cross-package resolution by
+`(type, shortcode)`.
+
 ## Diagnostics
 
 Every warning or error a build reports **about a content note** is emitted in the