@heroiclands/package-build 15.0.0 → 16.0.0

package/CHANGELOG.md

@@ -1,5 +1,148 @@
 # @heroiclands/package-build
 
+## 16.0.0
+
+### Major Changes
+
+- d734ac9: **Two embedded items on one actor may no longer share `(type, shortcode)`.**
+  `content-build lint` reports each collision as an error, at the later entry.
+  
+  SoHL treats `(type, shortcode)` as a **logical identity** rather than a lookup
+  convenience: two documents of one type bearing one shortcode denote _the same
+  entity_, whatever their `_id`s or field values. It is unique within four scopes,
+  one of which is an actor's own embedded items — and the invariant exists to keep
+  that identity well-defined. Two colliding entries make "the same thing"
+  ambiguous, and every match that resolves by it — compendium↔world
+  reconciliation, archetype shadowing, `fvttFindItemByShortcode`, cohort
+  membership, expression and effect references — becomes unsound.
+  
+  Nothing caught it. The compiler resolves each entry independently and
+  distinguishes the two only when seeding `_id`, so a collision compiled to two
+  documents with distinct ids and shipped unremarked:
+  
+  ```yaml
+  items:
+    - { shortcode: swim, type: skill, system: { masteryLevelBase: 30 } }
+    - { shortcode: swim, type: skill, initSkillMult: 1 }
+  ```
+  
+  Neither entry overrides `system.shortcode`, so both inherit `swim` from the
+  template and compile to two `skill` items keyed `swim` on one actor.
+  
+  **The rule is decidable from frontmatter alone**, which is why it is a lint and
+  not a compile step. An entry's effective key is `system.shortcode ?? shortcode`:
+  a top-level `shortcode` merely selects the template the entry is written from
+  and never reaches the document, while a template's own `system.shortcode` is its
+  address by construction. Neither the catalogue nor a compile is needed to know
+  what an entry will carry.
+  
+  Two entries written from one template are still fine when the second says which
+  entity it is — `{ shortcode: Dgr, type: weapongear, name: "Dagger 2", system: { shortcode: Dgr2 } }`.
+  The key is the _pair_, so two different types may share a shortcode, and an
+  entry naming no key at all is left to the compiler, which already reports it.
+  
+  **Major**, because a tree carrying a collision goes red on adoption. Known at
+  the time of writing: `Song-of-Heroic-Lands-FoundryVTT` 1 actor,
+  `sohl-thalorna` 15, `sohl-kethira-basic` 0.
+- 2e0d32e: **A note's address has one name: `packageAddress`.** `engine/content-address.mjs`
+  exported it twice — as `contentAddress` and as `packageAddress` — and the two
+  bodies had become byte-identical:
+  
+  ```js
+  // before                              // after
+  contentAddress(fm); // "doc-gear/"     packageAddress(fm); // "doc-gear/"
+  packageAddress(fm); // "doc-gear/"
+  ```
+  
+  `contentAddress` is removed. Import `packageAddress` from
+  `@heroiclands/package-build/engine/content-address` instead; the two returned
+  the same string, so nothing else changes.
+  
+  The names once meant different things — a note's address _within the content
+  tree_, and its address _relative to the package_. They could differ while a
+  `README.md` addressed its section rather than itself and while a page's URL was
+  derived from `name.full`; the first went with the landing rules (#204, #208) and
+  the second when a page's URL became its address (#181). What was left was two
+  exported names for one notion, on a public subpath, with `contentAddress`'s
+  documentation still describing an address "below the knowledgebase mount" that
+  it no longer returned.
+  
+  `packageAddress` is the name that survives because it still says something true
+  and load-bearing: the string is measured **from the package**, so a caller
+  composing a URL or a manifest `path` prepends where the package is served. That
+  is the one qualification a reader of the call site needs, and it is exactly the
+  distinction the `url:` change in 15.0.0 turned on. Closes #226.
+
+### Minor Changes
+
+- e131f7b: Publish the note tree as a queryable index, instead of throwing every build's walk away.
+  
+  Every content build parses every note's frontmatter — the pack compilers, the site
+  build, and the content-table expander each do it — and every one of them discards
+  the result. Nothing outside a build could therefore ask a question about the
+  content: _which beings carry no `kbcat`_, _what does this table actually select_,
+  _did that type rename leave anything behind_ each needed a throwaway script that
+  re-walked the tree. Eight dead tables shipped for weeks behind exactly that gap.
+  
+  `content-build content-index` emits one JSON Lines record per note — the whole
+  frontmatter, plus a derived `file` (`path`, `folder`, `name`) and the configured
+  `package` — so a question is one line of `jq`, and so an editor, a CI check, or
+  another package's build can read the content without re-deriving it.
+  
+  **The record is the note, not a projection of it.** Nothing is selected, flattened,
+  or renamed; a reader addresses `sohl.body.weight.base` because that is what the note
+  says, which is also exactly what a `dataview` query writes. The refusal to impose a
+  schema is deliberate: `sohl`'s frontmatter spreads 242 distinct leaf paths unevenly
+  over 15 types, from 9 on a `macro` to 72 on a `being`, so a fixed column set would
+  turn ordinary authoring into a schema migration. `package` and `file` are the two
+  derived keys, and a note carrying either is an error rather than a silent overwrite.
+  
+  **Derived, disposable, byte-stable.** It writes to the new `paths.contentIndex`
+  (`build/content-index/<package>.jsonl`) — never `paths.stage`, which is mirrored
+  into a Foundry data root — so nothing may be authored against it and it need never
+  be committed. Regenerating costs a frontmatter parse rather than a build, which is
+  why it is a command of its own; and because rebuilding is the intended use, records
+  are ordered by content path with the note id breaking ties and every object's keys
+  are sorted at every depth, so a rebuild over an unchanged tree is a no-op. A tree
+  that yields no note is an error, not an empty index: a reader takes the file as
+  authoritative, and "this package has no content" is indistinguishable from a
+  mis-pointed tree.
+  
+  **Every note's address, and every anchor it defines.** A record states
+  `address.slug` (what goes inside `[[…]]` locally) and `address.canonical` (the
+  package-qualified key the manifest files it under), plus every `{#slug}` anchor the
+  body declares — each with its heading name, level, **line in the file**, and the
+  `slug#anchor` link that reaches it. Neither address is new information, since both
+  derive from `type` and `shortcode`; what the fields add is the rule, derived through
+  the same `addressSlug` and `canonicalKey` the manifest and site build use, so an
+  index cannot disagree with either about where a note lives. The payoff is that a
+  wikilink — anchor and all — becomes checkable by lookup rather than by re-parsing
+  the tree, and an editor can jump to a section instead of searching for it. What
+  counts as an anchor is kept identical to what `splitPages` matches, and a test
+  asserts the two agree.
+  
+  **A keyboard-typeable form of every name.** `nameAscii` states `name.full`
+  reduced to printable 7-bit ASCII — `Kûrbúl ¾-Helm` → `Kurbul 3/4-Helm`, `Kèthîra`
+  → `Kethira`, `Ærling` → `AErling`, `Þorn` → `Thorn`, `Straße` → `Strasse`. Names
+  carry the setting's orthography and nobody types them, so anything searching or
+  completing over the index needs a form a keyboard produces; stating one means
+  every consumer folds the same way instead of each inventing its own and two
+  searches over the same data disagreeing. It transliterates rather than strips,
+  through the same `unidecode` table `slugify` already runs — so an ASCII name and
+  a slug cannot disagree about a character, and `Kûrbúl` does not become `Krbl`.
+  Emitted even when it equals the name, so a consumer never branches on whether a
+  name happened to be ASCII; `null` only when the note has no name. `aliasesAscii`
+  does the same for `name.aliases` in the authored order — an alias is the name a
+  reader is at least as likely to reach for (`Killer Whale` for an orca), so a
+  search has to match it too — and is an empty array rather than null when a note
+  has none.
+  
+  `file.path` stays relative to the content root and is deliberately never absolute:
+  an absolute path is a fact about the machine that built the index, so it would break
+  byte-stability between checkouts and publish someone's home directory.
+  
+  Closes #224.
+
 ## 15.0.0
 
 ### Major Changes

package/CONTENT.md

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

package/bin/content-build.mjs

@@ -97,6 +97,7 @@ import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
+import { emitContentIndex } from "../engine/content-index.mjs";
 import {
     buildSite,
     gatesFailed,
@@ -228,6 +229,7 @@ const argv = yargs(hideBin(process.argv))
     .command(formatCommand())
     .command(markdownCommand())
     .command(manifestCommand())
+    .command(contentIndexCommand())
     .command(siteCommand())
     .command(reachabilityCommand())
     .command(addressesCommand())
@@ -1195,6 +1197,58 @@ function manifestCommand() {
     };
 }
 
+/**
+ * `content-build content-index` — emit this package's note index.
+ *
+ * Every build already walks the tree and parses every note's frontmatter, then
+ * throws the result away, so nothing outside a build can ask a question about
+ * the content (#224). This publishes that walk as JSON Lines: one record per
+ * note, carrying the whole frontmatter plus the note's place in the tree.
+ *
+ * It is a command of its own rather than only a build step because the point of
+ * the artifact is that anyone can regenerate it at will — it costs a
+ * frontmatter parse, not a build. That is also what lets it stay uncommitted:
+ * something reproducible in under a second does not need to be kept.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function contentIndexCommand() {
+    return {
+        command: "content-index [root]",
+        describe: "Emit this package's note index as JSON Lines",
+        builder: (yargs) => {
+            yargs.positional("root", {
+                describe: "Content tree to read. Defaults to the configured contentBase.",
+                type: "string",
+            });
+            yargs.option("out", {
+                describe:
+                    "Directory to write into. Defaults to the configured " +
+                    "`paths.contentIndex`.",
+                type: "string",
+            });
+        },
+        handler: (argv) => {
+            try {
+                const config = loadPackConfig();
+                const { file, notes, bytes } = emitContentIndex({
+                    config,
+                    ...(argv.root ? { contentBase: argv.root } : {}),
+                    ...(argv.out ? { outDir: argv.out } : {}),
+                });
+                log.info(
+                    `${config.contentPackage} → ${path.relative(process.cwd(), file)} ` +
+                        `(${notes} notes, ${Math.round(bytes / 1024)} KiB)`,
+                );
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `content-build site` — publish the content tree as a website.
  *

package/content-config.mjs

@@ -90,6 +90,11 @@ export const DEFAULT_PATHS = /** @type {const} */ ({
     content: "assets/content",
     manifests: "assets/manifests",
     manifestOut: "build/manifests",
+    // Where `content-index` writes this package's note index. Under `build/`
+    // because it is derived and disposable — regenerating it costs a
+    // frontmatter parse — and emphatically not under `stage`, which is mirrored
+    // into a Foundry data root (#224).
+    contentIndex: "build/content-index",
     packJson: "build/packs-json",
     stage: "build/stage/packs",
     unpack: "build/tmp/packs",
@@ -305,6 +310,10 @@ export function publishesContentPages(config) {
  *                                       build artifact — the published copy is
  *                                       the one a consumer vendors into its
  *                                       `manifests` directory.
+ * @property {string} [contentIndex]     Where `content-index` writes this
+ *                                       package's note index. Outbound, and a
+ *                                       derived artifact — never a source, and
+ *                                       never inside `stage`.
  * @property {string} [packJson]         Build-only per-entry JSON intermediate.
  * @property {string} [stage]            Compiled LevelDB packs.
  * @property {string} [unpack]           Where `unpack` extracts JSON back to.
@@ -317,6 +326,7 @@ export function publishesContentPages(config) {
  * @property {string} content
  * @property {string} manifests
  * @property {string} manifestOut
+ * @property {string} contentIndex
  * @property {string} packJson
  * @property {string} stage
  * @property {string} unpack

package/engine/content-address.mjs

@@ -79,47 +79,32 @@ export function addressSlug(fm) {
 }
 
 /**
- * A note's address below the knowledgebase mount, e.g. `affliction-aconite/`.
+ * A note's address: `<type>-<shortcode>/`, e.g. `affliction-aconite/`.
  *
- * Every note, without exception. A `README.md` used to be its section's landing
- * page and to address the section instead of itself; a section is a Hugo
- * directory concept the note format no longer carries (#204), so a file's name
- * decides nothing about where it publishes.
- *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string} The mount-relative address, with a trailing slash.
- * @throws {Error} When the note has no address.
- */
-export function contentAddress(fm) {
-    return `${addressSlug(fm)}/`;
-}
-
-/**
- * A note's address relative to its **package**, e.g. `affliction-aconite/`.
- *
- * This is the form the link manifest records and the site build emits pages at,
- * and it is one function because those two must agree — a manifest asserting an
+ * This is the one form a note is addressed by. It is what the link manifest
+ * records as an entry's `path` and what the site build emits the page at, and
+ * it is one function because those two must agree — a manifest asserting an
  * address the site does not publish resolves at build time and 404s for the
  * reader, which is the failure this module exists to prevent.
  *
- * **It is a pure function of the frontmatter.** Nothing about the file the note
- * was read from reaches it: the `README.md` convention that made one note
- * address a whole section is retired with the section itself (#204), so there
- * is one rule and no branch.
- *
- * **The prefix does not apply to a page's own address.** `prefix` says where the
- * content tree *mounts inside the package* — the Hugo directory its pages are
- * written under — and an address is `(type, shortcode)`, a package-wide identity
- * that takes no mount: `sohl` publishes `/sohl/affliction-aconite/` from a file
- * written under `kb/`. The `type-` half is what keeps that flat namespace clear
- * of the package's fixed mounts — `/<package>/` for the landing,
- * `/<package>/api/` for generated API docs, neither of which contains a hyphen
- * or names a type.
+ * **The address is relative to the package**, and to nothing finer. A consumer
+ * composing a URL prepends where the package is served (`/<package>/`); a
+ * consumer composing a manifest entry measures against that same base. Nothing
+ * else is prepended: `prefix` says where the content tree *mounts inside the
+ * package* — the Hugo directory its pages are written under — and an address is
+ * `(type, shortcode)`, a package-wide identity that takes no mount, so `sohl`
+ * publishes `/sohl/affliction-aconite/` from a file written under `kb/`. The
+ * `type-` half is what keeps that flat namespace clear of the package's fixed
+ * mounts — `/<package>/` for the landing, `/<package>/api/` for generated API
+ * docs, neither of which contains a hyphen or names a type.
  *
- * **It takes no address scheme.** It took one until #215, to validate the
- * `landing` rule it then discarded; with that key retired, `prefix` was the
- * only thing left in the scheme and the paragraph above is the reason it never
- * applied. A parameter read by nothing is the defect this deletion is about.
+ * **It is a pure function of the frontmatter**, and takes no options. Nothing
+ * about the file the note was read from reaches it: the `README.md` convention
+ * that made one note address a whole section is retired with the section itself
+ * (#204), so every note is addressed alike and there is one rule and no branch.
+ * It took an address scheme until #215, to validate a `landing` rule it then
+ * discarded; with that key retired, `prefix` was the only thing left in the
+ * scheme and the paragraph above is the reason it never applied.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The package-relative address, with a trailing slash and no