@heroiclands/package-build 17.1.0 → 18.0.0

package/CONTENT.md

@@ -22,7 +22,7 @@ A consuming repository declares one `package-build.config.yaml` at its root:
 
 ```yaml
 # The package this repository's content is published as: the first segment of
-# every canonical address, the name of the link manifest it emits, and the
+# every canonical address, the name of the content index it emits, and the
 # package a cross-package wikilink writes to reach one of its notes.
 contentPackage: thalorna
 # Where Foundry installs it: "systems" or "modules". Also decides the served
@@ -186,11 +186,27 @@ something migrates on it.
 ### A note's package is the repository's, not the note's
 
 `contentPackage` is the **address namespace** every note in the tree is
-published under: the first segment of every canonical key (`sohl-skill-clmb`),
-the name of the link manifest this build emits (`sohl.json`), and the package a
-cross-package wikilink writes to reach one of these notes. It is the
-repository's identity in the address space — not a filter — and a note does not
-restate it.
+published under: the first segment of every canonical key, the name of the link
+manifest this build emits (`sohl.json`), and the package a cross-package
+wikilink writes to reach one of these notes. It is the repository's identity in
+the address space — not a filter — and a note does not restate it.
+
+A canonical key has four segments, read by position:
+
+```text
+<package>-<system>-<type>-<shortcode>
+```
+
+`<system>` is a game system this toolchain compiles for — `sohl` or `hm3` — or
+the literal `none` for a document no game system defines: a JournalEntry, a
+Macro, a Scene, and an item's documentation journal, which is `none` however
+many system blocks the item itself carries. The registry of permitted values is
+`engine/systems.mjs`, and `none` is a **word** on purpose: `any` would read as a
+wildcard, which is the opposite of what it says, and a YAML null (`null`, `~`,
+an empty value) parses to an absent value and drops the segment altogether. So
+`sohl-none-doc-gear`, `sohl-sohl-skill-clmb` — the package and the system are
+independent slots that may hold the same word, because Foundry requires a system
+package's id to _be_ its system id.
 
 Because it is a segment of an address, the value is **validated** rather than
 taken as written, and a violation fails the build naming the line it is on:
@@ -199,14 +215,20 @@ taken as written, and a violation fails the build naming the line it is on:
   hyphen-separated segments, so the hyphen has to be purely a separator — which
   is why `harn-adventures` is configured as `harnadventures`. This is the same
   rule `shortcode` is already held to, and the two are one constant.
-- **Not a note type.** The package and the type are adjacent segments, and the
-  two vocabularies are kept disjoint so a reader never has to decide which slot
-  a name is filling. `doc`, `being`, every map type, and every item type this
+- **Not a note type.** A written address is a _partial_ one — the shorter forms
+  drop segments from the left, so `skill-clmb` and `sohl-skill-clmb` are both
+  addresses — and position alone therefore no longer says which vocabulary a
+  leading segment is drawn from. The reader settles that by asking whether the
+  name is a known package, so a name belonging to both vocabularies makes one
+  target readable two ways with no defensible pick. The package and the type are
+  no longer _adjacent_ segments now that the system sits between them, and that
+  changes nothing: the hazard was never adjacency, it is that a short form omits
+  the slots in between. `doc`, `being`, every map type, and every item type this
   repository declares — with its `doc`-prefixed documentation form — are
   refused.
 
 ```text
-package-build.config.yaml:1:1: error: package-build config: `contentPackage` is `harn-adventures`, which is not alphanumeric. It is the first segment of every address this package publishes (`harn-adventures-<type>-<shortcode>`), and an address is read by counting hyphen-separated segments — so anything outside `[A-Za-z0-9]` here makes those addresses unreadable rather than merely ugly. `harn-adventures` became `harnadventures`.
+package-build.config.yaml:1:1: error: package-build config: `contentPackage` is `harn-adventures`, which is not alphanumeric. It is the first segment of every address this package publishes (`harn-adventures-<system>-<type>-<shortcode>`), and an address is read by counting hyphen-separated segments — so anything outside `[A-Za-z0-9]` here makes those addresses unreadable rather than merely ugly. `harn-adventures` became `harnadventures`.
 ```
 
 **`package:` in a note's frontmatter is retired, and declaring it fails the
@@ -220,7 +242,7 @@ assets/content/Gear/Axe.md:12:1: error: `package: sohl` is a retired frontmatter
 ```
 
 `content-build lint` reports every such note in one pass; `content-build
-package compile` and `content-build manifest` refuse the tree.
+package compile` and `content-build content-index` refuse the tree.
 
 A generated table that scopes itself with `WHERE … and package = "<pkg>"` keeps
 working: the package is **synthesised** into what the table search sees,
@@ -400,6 +422,41 @@ system)` take the system that is asking; asking without one, for a type more
 than one registry declares, **throws** rather than answering with whichever was
 declared first.
 
+**`hm3` is a real registry, and the rest of the pipeline follows the same
+field.** Since #139 this package ships two system halves, `sohl/` and `hm3/`,
+each with its own builders, its own default art and its own note-type →
+document-subtype map; they share the engine between them and import nothing from
+each other. A pack's `system:` is what selects among them — the Item and Actor
+compilers, the item catalogue a being resolves against, the published
+`schema.json` its emissions are checked against, and the `_stats` stamp all read
+that one field — so declaring one Item pack and one Actor pack per system is the
+whole of the configuration a dual-system tree needs:
+
+```yaml
+itemBuilders: [sohl, hm3]
+systems:
+  sohl: { compatibility: { verified: "0.9.0" } }
+  hm3: { compatibility: { verified: "1.6.3" } }
+packs:
+  - { name: items-sohl, type: Item, system: sohl, default: true }
+  - { name: items-hm3, type: Item, system: hm3 }
+  - { name: actors-sohl, type: Actor, system: sohl, default: true }
+  - { name: actors-hm3, type: Actor, system: hm3 }
+```
+
+A note carrying both a `sohl:` and an `hm3:` block then compiles **one document
+in each system**, each shaped by its own builders and stamped with its own
+system version. A note carrying only one block compiles only that system's
+document: the other system's pass passes over it, rather than failing it for a
+block it was never going to have.
+
+Four of HM3's rows are **one-to-many** — `mysticalability` becomes a `psionic`,
+a `spell` or an `invocation`; `trauma` an `injury` or a `trait`; `weapongear` a
+`weapongear` or a `missilegear`; `being` a `character` or a `creature` — and the
+note says which by writing `hm3.type`. Nothing is inferred from the note's own
+`subType`, and a note that says nothing is an error naming the note and listing
+the permitted values.
+
 **Configuration is the source, and the manifest is generated from it.** That
 arrow used to point the other way: `paths.packageManifest` said where a
 hand-authored `system.template.json` lived, and the package-id guard and the
@@ -584,16 +641,24 @@ toolchain vocabulary, and the _generators_ `items` and `attributes` expand into
 embedded documents rather than mapping anywhere, so neither has a `system` path
 to be written at.
 
-`archetype` is authored there too, and is the one such key that _is_ a field:
-the builder writes it to `system.archetype` — a number is an archetype at that
-priority, `null` is not an archetype — exactly as `portrait` reaches
-`sohl.system.portrait` from a shared top-level property. Its authored position
-is unchanged (#126).
+`templatePriority` is the one key of this shape that _is_ a field, and it is
+**shared rather than per-system**: its home is `data.templatePriority`, and it
+reaches `sohl.system.templatePriority` and `hm3.flags.hm3.templatePriority` —
+exactly as `portrait` reaches two differently-named fields from one shared
+property. A number is a template at that priority, `null` is not a template, and
+absent is an authoring error (#126, #266). The legacy in-block and top-level
+positions are still read, in that order after `data:`, so a tree sweeps on its
+own schedule; `archetype` is the retiring spelling of the same field, still read
+last but **refused by the frontmatter linter** — a priority and the `archetypes`
+a being fits are different things, and one letter is not enough to tell them
+apart.
 
 ```yaml
 type: being # the content type — system-agnostic
 pack: actors # shared: unless a block says otherwise
 portrait: kaldor.webp # shared: reaches both systems' fields, differently named
+data:
+  templatePriority: 1 # shared: → sohl `system.`, hm3 `flags.hm3.`
 hm3:
   type: character # this system's document subtype
   pack: actors-hm3 # overrides the shared one, for HM3 only
@@ -605,7 +670,6 @@ sohl:
   type: being
   system:
     currentMoveMedium: walk
-  archetype: 1
 ```
 
 **The shared fallback is declared, not name-matched.** `sohl.system.portrait`
@@ -676,7 +740,7 @@ value goes through one coercion rather than two.
 
 **What the compiler writes on its own is checked too.** A compiled document
 carries keys no field declaration and no note ever names — `shortcode`,
-`archetype`, `actionDefs`, `notes`, `docHtml` — because the pass writes them
+`templatePriority`, `actionDefs`, `notes`, `docHtml` — because the pass writes them
 itself, and they were compared against nothing: the declaration-derived check
 reads `itemBuilders`, the note-side check reads `<system>.system`, and these are
 in neither. A compile now reads the `system` block each pass **assembled** and
@@ -715,7 +779,6 @@ npx content-build content-format notes [root] [--strict]
 npx content-build links [root] [--manifests <dir>]
 npx content-build format [paths..] [--write]
 npx content-build markdown [paths..] [--fix]
-npx content-build manifest [root] [--out <dir>]
 npx content-build content-index [root] [--out <dir>]
 npx content-build site [--out <dir>]
 npx content-build reachability <dir> [file] [--index <shortcode>]
@@ -731,7 +794,6 @@ npx content-build addresses diff --from <zip|dir> [--strict]
 | `links`          | Check that every link in the tree lands: dead anchors, dead qualified addresses, wikilinks in frontmatter, drifted manifests, and the package homepage's own addresses. |
 | `format`         | Prettier, with the shared configuration. See [Prose: formatting and markdown](#prose-formatting-and-markdown).                                                          |
 | `markdown`       | markdownlint, with the shared rule set — the structure Prettier is indifferent to.                                                                                      |
-| `manifest`       | Emit this package's cross-package link manifest. See [Publishing a link manifest](#publishing-a-link-manifest).                                                         |
 | `content-index`  | Emit this package's note index as JSON Lines. See [Publishing a content index](#publishing-a-content-index).                                                            |
 | `site`           | Publish the content tree as a website. See [Publishing a website](#publishing-a-website).                                                                               |
 | `reachability`   | Walk outward from an index note and report what no path reaches, for a tree meant to be navigable from one entry point.                                                 |
@@ -894,10 +956,11 @@ mode rather than by kind — so `subType` on one is a finding; a `skill` declare
 ten, so `subType: crafte` is a finding naming `craft`.
 
 **A `type` and a `subType` are both held to `^[A-Za-z0-9]+$`** (#206) — the same
-constant a `shortcode` is held to, read rather than restated. A type is the
-first segment of every address, so a hyphen in one is read back as a segment
-boundary nobody wrote. A `subType` reaches no address since #204 retired
-sections, and keeps the rule anyway: it is a vocabulary term the toolchain keys
+constant a `shortcode` is held to, read rather than restated. A type is a
+segment of every address — the first of the short form an author writes, the
+third of the canonical `package-system-type-shortcode` — so a hyphen in one is
+read back as a segment boundary nobody wrote. A `subType` reaches no address
+since #204 retired sections, and keeps the rule anyway: it is a vocabulary term the toolchain keys
 on, and one charset that holds for every term is a rule an author can state. The
 rule is checked ahead of the closed-set check, which is what makes it reach a
 type whose values are declared but not yet enumerated:
@@ -935,6 +998,43 @@ folded in every note's `name.full` and so decided what a note could be named
 `[[type-shortcode|Text]]`, and declaring `aliases:` is refused naming the file
 and the line.
 
+### Writing a link: the address grammar
+
+Every wikilink is an address, and omission runs **strictly left to right**:
+
+```text
+[[[[<package>-]<system>-]<type>-]<shortcode>]
+```
+
+So the written forms are exactly the suffixes of the canonical address:
+
+| Form                            | Example                              | Means                             |
+| ------------------------------- | ------------------------------------ | --------------------------------- |
+| `type-shortcode`                | `[[skill-clmb\|Climbing]]`           | This package, any system.         |
+| `system-type-shortcode`         | `[[sohl-skill-clmb\|Climbing]]`      | This package, the `sohl` system.  |
+| `package-system-type-shortcode` | `[[thalorna-sohl-being-grod\|Grod]]` | Another package, fully qualified. |
+
+**There is no `package-type-shortcode`.** Naming a package means naming the
+system before the type, because the segments are positional rather than tagged.
+A link into another package must therefore be fully qualified — which is the
+price of a grammar that needs no vocabulary to parse.
+
+**An omitted system is a wildcard; an omitted package is a default.** Most links
+target items, which belong to a system, so a target naming none matches a note
+under any of them and exactly one hit is required — two claimants is an
+_ambiguity_, a different finding with a different fix from resolving nowhere. A
+target naming no package means the citing note's own, so an unqualified link
+resolves locally and only locally.
+
+**`sohl` is both a package and a system**, and positional counting is what makes
+that harmless: three segments name a _system_ whatever the first segment could
+also have meant, and four is the full form.
+
+**Parsing is plain segment counting**, the same rule the canonical key follows,
+and it is sound because every segment is `^[A-Za-z0-9]+$` — so a hyphen is
+purely a separator. A target with five segments is not a hyphenated shortcode;
+it is a name, and not an address.
+
 **`name.aliases` is kept, and is read by nothing.** It fed the same index and
 lost the same reader, but unlike the top-level list it is **reserved** — held
 for a use that does not exist yet. So it is the one field in the format that is
@@ -988,10 +1088,10 @@ the Foundry document id a compendium UUID is built from, and a homepage compiles
 into **no document**.
 
 ```text
-assets/content/homepage.md:4:1: error: `id` decides nothing on a `type: homepage` note: it is the Foundry document id a compendium UUID is built from, and a homepage compiles into no document — it appears in no pack and in no link manifest. Delete it
+assets/content/homepage.md:4:1: error: `id` decides nothing on a `type: homepage` note: it is the Foundry document id a compendium UUID is built from, and a homepage compiles into no document — it appears in no pack and states no Foundry address. Delete it
 ```
 
-That is also why a homepage stays **out of the link manifest**, now that a
+That is also why a homepage states **no Foundry address**, now that a
 shortcode alone would put it in. A manifest entry is how another package
 resolves a _document_; a cross-package link to a package's front page is its
 bare `/<package>/` address, which needs no index.
@@ -1128,7 +1228,7 @@ attempted:
   documentation, hand-authored Hugo sections — so this build does not hold the
   set of published pages and would report a working link as dead. A bare
   `https://www.heroiclands.org/<package>/` is left alone for the same reason it
-  cannot be improved: a package homepage is in no link manifest, so there is no
+  cannot be improved: a package homepage compiles into no document, so there is no
   better form to write.
 
 ## The content format specification
@@ -1260,44 +1360,145 @@ import shared from "@heroiclands/package-build/markdownlint";
 export default { ...shared, config: { ...shared.config, MD013: true } };
 ```
 
-## Publishing a link manifest
+## YAML: frontmatter, and every YAML file
+
+```bash
+npx package-build yaml                     # every YAML file git would consider
+npx package-build yaml assets/content      # or just these paths
+```
+
+Frontmatter carries a note's type, its shortcode, its address and the system
+blocks a document is compiled from — and until this command existed nothing
+checked it _as YAML_.
+
+**Worse than unchecked: a parse failure unmade the note.** `parseMarkdownFile`
+caught the error, logged it at `warn`, and returned `{frontmatter: null}` — which
+is not a note with bad frontmatter but, to every pass downstream, _a file with no
+frontmatter_. It was skipped by the compiler, the linter, the link checker and
+the index, and the build reported success. A duplicate key did not fail anything;
+it removed a note from the corpus. The parser had detected it all along.
+
+**Frontmatter is linted through an ESLint processor** — the mechanism
+`eslint-plugin-markdown` uses for fenced code blocks. Frontmatter is its easy
+case: the block is always at the top of the file, so a finding maps back to the
+line it came from with a constant `+1` for the opening `---`, and nothing after
+the closing `---` is read as YAML.
+
+The rule set is **deliberately narrow**, for the same reason `markdown`'s is.
+Prettier already owns YAML's whitespace, quoting and line breaks — including
+inside a frontmatter fence — so a rule about any of those would duplicate the
+formatter or fight it. What is left is the class a formatter cannot see: text
+that parses to something other than what it looks like.
+
+| Reported                              | Why it is not a matter of taste                                |
+| ------------------------------------- | -------------------------------------------------------------- |
+| a parse error                         | A duplicate key, a tab indent, mis-aligned mapping items.      |
+| `yml/no-empty-mapping-value`          | `folder:` and `folder: null` are one value and two statements. |
+| `yml/no-irregular-whitespace`         | A non-breaking space is invisible and part of the value.       |
+| `yml/no-empty-key`, `-empty-document` | A fence or a file that parses to nothing at all.               |
+
+`folder:` and `folder: null` read as opposites — a decision, or a key somebody
+began and did not finish — so the distinction is drawn where the text still
+exists. **A key with a block under it is not empty**: `name:` followed by an
+indented mapping, or by a sequence at its own indent, is an ordinary container.
+
+**GitHub workflows are exempt from the empty-value rule.** `on:`, `push:` and
+`workflow_dispatch:` carry their meaning by being present, and writing
+`push: null` to satisfy a linter would be worse YAML, not better. A real error in
+a workflow is still reported.
+
+**The files are the ones git would consider** — `--cached --others
+--exclude-standard`, tracked plus untracked-and-not-ignored, the same set
+`gitignore: true` gives the markdown linter. Untracked is included so a note is
+linted while it is being written rather than only once it has been staged.
+
+**A consumer needs no ESLint.** This ships as a command, not as a configuration
+to adopt: there is no `eslint` dependency to add, no `eslint.config.js` and no
+rules to declare. A repository that _has_ an ESLint of its own keeps it untouched
+and unconsulted — the run sets `overrideConfigFile: true`, so no config file is
+looked for at all.
+
+## Publishing the content index
+
+Every package emits one file naming every note it publishes:
 
 ```bash
-npx content-build manifest              # the configured tree and output directory
-npx content-build manifest --out tmp/   # or somewhere else
+npx content-build content-index         # the configured tree and output directory
 ```
 
-Writes `<contentPackage>.json` naming every note this package publishes, keyed by
-the canonical `package-type-shortcode` address and valued with every address that
-note has: a `path` on the web, a `uuid` in Foundry, the `anchors` its named
-sections compiled to, and a `doc` pointer where an item's prose compiles into a
-JournalEntry of its own. A consuming build vendors the file into its own
-`paths.manifests` and resolves cross-package links through it — the counterpart
-of `links`, which consumes what this emits.
-
-It reads its whole input from configuration and takes nothing else:
-
-| Setting                     | What it decides                                               |
-| --------------------------- | ------------------------------------------------------------- |
-| `contentPackage`            | The package emitted, which every note belongs to.             |
-| `foundryPackage`            | The package every emitted `uuid` names.                       |
-| `paths.content`             | The tree walked.                                              |
-| `paths.manifestOut`         | Where the file lands (`build/manifests` by default).          |
-| `publish.manifests.publish` | Whether this repository publishes one at all.                 |
-| `publish.site`              | Whether entries carry a `path` — see below.                   |
-| `publish.address`           | The address scheme those paths are derived under — see below. |
+`<contentPackage>-metadata.jsonl` holds one JSON record per line, keyed by the
+canonical `package-system-type-shortcode` address and carrying every address
+that note has: its `address.slug` on the web, a `foundry.<system>.uuid` in
+Foundry, the `anchors` its named sections compiled to, and a `documentation`
+pointer where an item's prose compiles into a JournalEntry of its own.
+
+**This is the artifact other packages resolve your addresses through.** It is
+advertised in the emitted `system.json` / `module.json` as
+`flags.metadataUrl` — derived, version-pinned, and not something you write down
+— and published as a release asset beside the manifest and the `.zip`.
+
+| Setting              | What it decides                               |
+| -------------------- | --------------------------------------------- |
+| `contentPackage`     | The package emitted, and the file's name.     |
+| `foundryPackage`     | The package every emitted `uuid` names.       |
+| `paths.content`      | The tree walked.                              |
+| `paths.contentIndex` | Where the file lands (`build/content-index`). |
 
 **Both addresses are optional, independently.** A note that compiles into no
-document has no `uuid`, and a package that ships compendiums and publishes only
-a homepage (`publish.site: homepage`) has no `path` on any entry — its notes are
-not pages. Neither is an error, and neither is guessed: inventing the missing one
-asserts a target that does not exist, which is the silent dead link the manifest
-exists to prevent.
+document states no `foundry` block, and a package that ships compendiums and
+publishes only a homepage serves no page at its addresses. Neither is an error,
+and neither is guessed: inventing the missing one asserts a target that does not
+exist, which is the silent dead link this whole mechanism exists to prevent.
+
+## Resolving another package's addresses
+
+Declare what you depend on, and fetch it:
+
+```bash
+npx content-build deps fetch                    # every declared dependency
+npx content-build deps fetch --from ../sohl     # from a local build, unreleased
+```
 
-**`publish.manifests.publish` is a declaration, not a preference.** The file is
-vendored by other repositories and read as authoritative, so emitting one is a
-statement about this package. With the switch off the command fails rather than
-writing.
+```yaml
+relationships:
+  systems:
+    - id: sohl
+      type: system
+      manifest: https://github.com/HeroicLands/Song-of-Heroic-Lands-FoundryVTT/releases/latest/download/system.json
+      compatibility: { minimum: "0.8.0", verified: "0.8.2" }
+```
+
+`deps fetch` reads that manifest, takes the `flags.metadataUrl` it advertises,
+and pulls the index into `build/cache/metadata`. The whole chain is declared, so
+nothing here holds an address of its own and a dependency that moves its release
+assets does not break its consumers.
+
+**You may cite what you depend on, and nothing else.** The set is every entry in
+`relationships.systems` and `relationships.requires`; `recommends` and
+`conflicts` are declarations _about_ other packages rather than dependencies on
+them, so a link into one is a defect in the citing note. An address into a
+package you have not declared resolves nowhere and fails the build.
+
+**A build never reaches the network.** A declared dependency whose index has not
+been fetched is an error naming `deps fetch`, rather than a download nobody
+asked for — a build that downloads silently is not reproducible and fails
+strangely offline. The cache is keyed by version, so changing the pinned version
+is a miss rather than a silent overwrite.
+
+**`--from` is for two packages changing together.** It fills the cache from a
+locally built artifact — a package zip or the directory it was built from — so a
+consumer can be built against a dependency that has not shipped. Without it,
+testing a dependency change against its consumers would cost a release
+round-trip.
+
+> **This replaced a vendored link manifest**, which every repository committed a
+> copy of every other repository's file into. A copy went stale silently and one
+> did — 2,101 entries in `Song-of-Heroic-Lands-FoundryVTT` pointed at URLs the
+> `thalorna` site had stopped publishing, at the current format version, so the
+> version gate saw nothing. Mutual vendoring also deadlocked: each package had to
+> read the other's file before it could publish its own. A fetched artifact
+> cannot drift from its producer, and a consumer reads one the producer has
+> already shipped.
 
 ### A page's URL is its address
 
@@ -1310,6 +1511,14 @@ writing.
 is no collision check behind it, there never can be one to fail, and renaming a
 note changes nothing: no part of the address comes from a display string.
 
+**A URL carries no `<system>` segment**, though the canonical address does. That
+is deliberate rather than an omission: a note publishes one page however many
+systems' documents it compiles into, so the segment would have nothing to
+distinguish and would only split one page's URL in two. The canonical address
+names a _document_; a URL names a _page_. So a consumer deriving a page address
+from a manifest key drops the package **and** the system, not the package
+alone.
+
 It used to come from `name.full`. That made a display name load-bearing three
 ways at once — a rename silently 404'd every inbound link, two notes in one
 section could derive the same URL so a uniqueness gate had to run, and long names
@@ -1462,7 +1671,7 @@ A record states the address a wikilink writes to reach the note, and every
 
 ```json
 {
-  "address": { "slug": "being-aurochs", "canonical": "sohl-being-aurochs" },
+  "address": { "slug": "being-aurochs", "canonical": "sohl-sohl-being-aurochs" },
   "file": { "path": "Bestiary/Animal/Aurochs.md", "folder": "Bestiary/Animal", "name": "Aurochs" },
   "anchors": [
     {
@@ -1524,18 +1733,22 @@ first. An entry that is not a non-empty string is dropped rather than left as a
 hole, since the array is a set of names to match and a null is not one.
 
 `address.slug` is what goes inside `[[…]]` within the package; `address.canonical`
-is the package-qualified key the link manifest files the note under. Both are
-`null` for a note with no type or no shortcode, which has no address at all — the
-record says so rather than leaving each reader to rediscover the rule.
-
-**Neither is new information** — both derive from `type` and `shortcode`, which
-every record already carries. What the fields add is the _rule_: the lowercasing
+is the fully qualified key the content index files the note under, carrying the
+package and the system as well. The slug is the canonical key's **last two
+segments**, not its whole tail: a page has no system to name, so the two forms
+diverge by that segment rather than one trailing the other. Both are `null` for a
+note with no type or no shortcode, which has no address at all — the record says
+so rather than leaving each reader to rediscover the rule.
+
+**Neither is new information** — the slug derives from `type` and `shortcode`,
+which every record already carries, and the canonical key adds only the system
+those two already imply. What the fields add is the _rule_: the lowercasing
 and the hyphen join live in one place, derived by the same `addressSlug` and
 `canonicalKey` the manifest and the site build use, so an index cannot disagree
 with either about where a note lives. A consumer that reimplements the join
 slightly differently gets a lookup matching nothing and no explanation — which is
 exactly how a resolver keyed on a bare `type/shortcode` silently misses every
-canonical `pkg-type-shortcode` entry.
+canonical `pkg-system-type-shortcode` entry.
 
 **Anchors make a link checkable without a build.** Because the index states every
 anchor a note defines, `[[being-aurochs#dossier]]` can be confirmed — or shown
@@ -1666,9 +1879,12 @@ configuration to stay empty: in `homepage` mode the tree is never walked for
 pages, and `sections`, `trees`, `landing` and `backfillSections` emit nothing
 even when they are declared.
 
-That is separate from `publish.manifests.publish`, which stays off for both for
-an unrelated reason: a link manifest is the dependency edge that would stop the
-module being withdrawable, and a homepage is one row in a routing table.
+That is separate from the **dependency** edge, which such a module also
+declines: being cited by another package is what would stop it being
+withdrawable, and a homepage is one row in a routing table rather than an
+address anyone links to. A package publishes its content index regardless — the
+licensing constraint is against publishing _pages_, not against the artifact
+existing — but nothing may declare it as a dependency.
 
 The homepage's file is written at the root of `site.out` — the package's own
 site root, one level above the content mount, which is where
@@ -1678,7 +1894,7 @@ decides where it publishes, and states it relative to the site root — `site.ba
 does not reach it (#217).
 
 **What it does not do is decide addresses.** Those come from `publish.address`,
-the same setting the link manifest reads, so a page and its manifest entry cannot
+the same setting the content index reads, so a page and its index record cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
 where the tree is written, what a section is called, which extra trees are
 published beside the content:
@@ -1951,7 +2167,7 @@ form every C-family compiler, `tsc` and ESLint already use, so an editor, a CI
 annotator or a `grep` parses it with no knowledge of this build:
 
 ```text
-assets/content/Regions/Capital_Nome.md:43:635: error: address [[place-kenbetpat]] resolves to no note — no package publishes it. Fix the shortcode, or vendor the link manifest of the package that does — in "The Capital Nome".
+assets/content/Regions/Capital_Nome.md:43:635: error: address [[place-kenbetpat]] resolves to no note — no package publishes it. Fix the shortcode, or declare the package that does as a dependency and run `content-build deps fetch` — in "The Capital Nome".
 ```
 
 `file:line:column: severity: message`. The path is relative to the working
@@ -2000,7 +2216,7 @@ authored character to point at.
 ## Layout
 
 - **`@heroiclands/package-build/engine`** — package-agnostic machinery: the
-  content walk, frontmatter, tables, wikilinks, ids, folders, the link manifest
+  content walk, frontmatter, tables, wikilinks, ids, folders, the content index
   and the web-address rule, `BasePackCompiler`, and the generic Foundry document
   compilers.
 - **`@heroiclands/package-build/sohl`** — Song of Heroic Lands data-model

package/README.md

@@ -7,7 +7,7 @@ It has two halves, split by **input**:
 
 | Half          | Reads                                                        | Produces                                                       |
 | ------------- | ------------------------------------------------------------ | -------------------------------------------------------------- |
-| **content**   | `assets/content/**`                                          | compendium packs, site content, link manifest                  |
+| **content**   | `assets/content/**`                                          | compendium packs, site content, content index                  |
 | **packaging** | `lang/`, `styles/`, `src/`, `assets/`, the manifest template | `system.json` / `module.json`, styles, bundle, release archive |
 
 The content half is documented separately in **[CONTENT.md](CONTENT.md)** — the