@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/wikilinks.mjs

@@ -22,7 +22,7 @@
  *   `[[#slug|Text]]`            a section of the source note itself
  *   `[[doctype-shortcode|T]]`   an item's *documentation* (see below)
  *
- * **Every link is an address, and every address carries a label** (#180). A
+ * **Every link is an address, and every address carries a label**. A
  * link written without one addresses nothing and is reported — see
  * {@link unlabelledLinkMessage}, which states the rule for both builds. The
  * bare `[[Alias]]` form and the index it was looked up in are retired.
@@ -36,8 +36,7 @@
  * Nothing narrower than `(type, shortcode)` is consulted — a note's directory
  * and its `category` play no part in resolution — and nothing wider: a note's
  * *name* is not an address, so two notes of a type may share a display name
- * ("Gear" as a rules page and as a user guide page) with nothing to disambiguate
- * (#179, #180).
+ * ("Gear" as a rules page and as a user guide page) with nothing to disambiguate.
  *
  * At compile time each becomes a Foundry UUID enricher, routed to the pack that
  * the target's type compiles into (see {@link packForType}):
@@ -47,7 +46,7 @@
  *
  * **Every address is computed once, when the target is indexed** — see
  * {@link buildWikilinkIndex} — and a link is resolved by looking that value up.
- * Nothing here concatenates a prefix at the point of use (#1498).
+ * Nothing here concatenates a prefix at the point of use.
  *
  * Section links address a **JournalEntryPage**, because Foundry UUIDs cannot
  * target a position inside a page. A heading carrying `{#slug}` therefore starts
@@ -63,15 +62,15 @@
  * **A document and its documentation are two documents.** An item note
  * compiles into an item — and, separately, its prose compiles into a
  * JournalEntry in the journals pack (see
- * {@link sohl.utils.packs.itemDocEntryId}); a macro note works the same way
- * (#1514). `skill/wpnc` addresses the skill; the **virtual qualifier**
+ * {@link sohl.utils.packs.itemDocEntryId}); a macro note works the same way.
+ * `skill/wpnc` addresses the skill; the **virtual qualifier**
  * `docskill/wpnc` addresses that skill's documentation, and
  * `docskill/wpnc#crafting` a page within it. `docmacro/autoattack#script`
  * reaches a macro's source. Every doc-carrying type has a `doc<type>`
  * counterpart, formed by prefix and never enumerated; see
  * {@link resolveItemDocType}. Without it a section link to an item note
  * produced a UUID against the *items* pack, which cannot hold a
- * JournalEntryPage, and dead-ended (#1362).
+ * JournalEntryPage, and dead-ended.
  *
  * **The two builds read the qualifier differently, by design.** In Foundry the
  * item and its documentation are separate documents in separate packs, so the
@@ -117,15 +116,15 @@ const norm = (s) => String(s).toLowerCase().trim();
  * not one.
  *
  * A document and its documentation are two documents in two packs, so they
- * need two addresses (#1362). `skill/wpnc` is the item; `docskill/wpnc` is the
+ * need two addresses. `skill/wpnc` is the item; `docskill/wpnc` is the
  * JournalEntry its prose compiled into, and `docmacro/autoattack` is the same
- * arrangement for a macro (#1514).
+ * arrangement for a macro.
  *
  * The virtual form exists for a type that carries separate documentation
  * ({@link sohl.utils.packs.docEntryTypes} — the set the journals compiler and
  * the link manifest read too), **or** for one that routes to the items pack.
  * The second clause is the older rule and stays: types that compile into items
- * are the open, unenumerated set (#1276), and a foreign package may publish an
+ * are the open, unenumerated set, and a foreign package may publish an
  * item type this build has never heard of. Dropping it would silently unlink
  * every `doc<type>` address into such a package.
  *
@@ -153,8 +152,8 @@ export function resolveItemDocType(qualifier, types) {
  * Two separators are accepted, and they are **not** interchangeable in how
  * confidently they mark a target as qualified:
  *
- * - **`type-shortcode`** and its qualified forms — the canonical spelling
- *   (#1398). Obsidian reads `/` inside a wikilink as a *path* and resolves it
+ * - **`type-shortcode`** and its qualified forms — the canonical spelling.
+ * Obsidian reads `/` inside a wikilink as a *path* and resolves it
  *   against the vault's folders, so a slash-qualified link is a broken link in
  *   the editor where the content is now authored.
  * - **`type/shortcode`** — the legacy form, still resolved so that a link
@@ -163,7 +162,7 @@ export function resolveItemDocType(qualifier, types) {
  *   before it is reported rather than guessed at. The split is at the **last**
  *   slash, as it always was.
  *
- * **The grammar is strict, and omission runs left to right** (#59):
+ * **The grammar is strict, and omission runs left to right**:
  *
  * ```text
  * [[[[<package>-]<system>-]<type>-]<shortcode>]
@@ -178,12 +177,13 @@ export function resolveItemDocType(qualifier, types) {
  * **Parsing is plain positional counting**, the same rule
  * {@link readCanonicalKey} follows, and it is sound for the same reason: every
  * segment is `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced on
- * shortcodes by `content-lint.mjs` since #1397), so the hyphen is purely a
+ * shortcodes by `content-lint.mjs`), so the hyphen is purely a
  * separator and the count alone determines every field. Verified across the
  * four content trees: 138,204 authored shortcodes, none carrying a separator.
  *
  * That replaced a first-hyphen split which let a shortcode contain a hyphen
- * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates #1397 and
+ * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates the
+ * charset rule and
  * outlived it; no tree has used it, and keeping it would make a three-segment
  * target ambiguous between a system and a hyphenated shortcode.
  *
@@ -287,7 +287,7 @@ function readQualifierCased(target, types, packages) {
             return read && { ...read, system, package: pkg };
         }
 
-        // One segment is a bare name, which is not an address (#180); five or
+        // One segment is a bare name, which is not an address; five or
         // more is not a hyphenated shortcode but a name that happens to carry
         // separators, since no segment may contain one.
         default:
@@ -347,7 +347,7 @@ export function anchorPageId(noteId, anchorSlug) {
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
  *   one-pack-per-type names stand in. `draft` says the note carries the `draft`
- *   tag, which marks links *into* it and changes nothing else (#183).
+ *   tag, which marks links *into* it and changes nothing else.
  * @param {string} packageId - The Foundry package shipping the packs; the first
  *   segment of every emitted UUID.
  * @param {Map<string, object>} [foreign] - Canonically keyed entries from
@@ -363,7 +363,7 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
         throw new Error(
             "buildWikilinkIndex: packageId is required — it is the first " +
                 "segment of every emitted UUID, and defaulting it is how links " +
-                "came to address the wrong package (#1498).",
+                "came to address the wrong package.",
         );
     }
 
@@ -382,7 +382,7 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
         uuidByDoc.set(d, {
             // `d.pack` is where this note's document actually landed, resolved
             // by the pack router when the index was collected. A repository may
-            // ship several packs of one type (#1566) and a UUID carries the
+            // ship several packs of one type and a UUID carries the
             // pack name, so the address cannot be derived from the type alone.
             uuid: compendiumUuid(packageId, d.type, d.id, d.pack),
             // An item's prose compiles into a separate JournalEntry, addressed
@@ -398,7 +398,7 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
     // foreign address resolves exactly like a local one and there is no
     // precedence rule to get wrong. A foreign package's types are added to
     // `types` too — without that, its addresses read as prose and silently lose
-    // their link (#1499).
+    // their link.
     const foreignByKey = new Map(foreign ?? []);
     const foreignTypes = [];
     for (const v of foreignByKey.values()) {
@@ -448,7 +448,7 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
  * The foreign manifest entry an address names, or `null`.
  *
  * A target is a **partial** address, matched on the segments it supplies with
- * the rest wildcarded (#59) — so a package-qualified one is a scan rather than
+ * the rest wildcarded — so a package-qualified one is a scan rather than
  * a single lookup, and may still match one entry per system. An unqualified one
  * names no package either, so it resolves against whichever foreign package
  * publishes it — and, in both readings, only when exactly one entry matches.
@@ -470,7 +470,7 @@ function findForeign(index, read) {
  * Every foreign manifest entry an address names.
  *
  * The count is what separates *nothing publishes this* from *two packages do*,
- * and those are different findings with different fixes (#184), so the caller
+ * and those are different findings with different fixes, so the caller
  * gets the list rather than a single answer that has already collapsed the
  * distinction.
  *
@@ -484,7 +484,7 @@ function foreignHits(index, read) {
     const wanted = norm(read.itemDoc ? `doc${read.type}` : read.type);
     const shortcode = norm(read.shortcode);
 
-    // **An omitted package means this package** (#336), so a short form
+    // **An omitted package means this package**, so a short form
     // addresses nothing foreign and never reaches a dependency's index. A link
     // that resolved into another package only because no local note claimed the
     // address was resolving by accident, and would have retargeted silently the
@@ -534,7 +534,7 @@ function unresolvedLink(text, target) {
 }
 
 /**
- * How a link to a **draft** note renders (#183).
+ * How a link to a **draft** note renders.
  *
  * A note tagged `draft` exists so a link into it is not dead, and nothing more.
  * Unmarked, a reader follows a promising link into an empty page and an author
@@ -552,7 +552,7 @@ function unresolvedLink(text, target) {
  * **Byte-identical with the site build's copy** in `web-wikilinks.mjs`, down to
  * the class name and the `title` wording — one authored link renders on two
  * surfaces, and the two builds have drifted before over exactly this kind of
- * detail (#1409). The argument is already-built markup and is deliberately not
+ * detail. The argument is already-built markup and is deliberately not
  * escaped; the *authored* text inside it was escaped, or made into a link, by
  * whichever resolver called this.
  *
@@ -574,7 +574,7 @@ function draftLink(inner) {
  *
  * **Code is verbatim.** A `[[…]]` inside a fenced or indented code block, or
  * inside an inline code span, is source text an author wrote to be read as
- * written, so it is left alone and not reported (#1505). Without that, a
+ * written, so it is left alone and not reported. Without that, a
  * script sample containing `grid[[0]]` became a link — and only for some
  * array shapes, `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross,
  * so the corruption looked arbitrary. It reaches the reader through the
@@ -595,23 +595,23 @@ function draftLink(inner) {
  * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
  *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
  *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
- *   three resolvers share (#184) — `ambiguous` carries the claiming `packages`
+ *   three resolvers share — `ambiguous` carries the claiming `packages`
  *   and `unknown-anchor` the section it named. `offset` is the link's 0-based
  *   position in `markdown`, which is what lets a caller report the line and
- *   column it sits on (#17).
+ *   column it sits on.
  */
 export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
     const unresolved = [];
 
     // `offset` is the third replacer argument because the pattern has exactly
     // one capture group. It is what makes two identical unresolved links on
-    // one note tellable apart, and a position reportable at all (#17).
+    // one note tellable apart, and a position reportable at all.
     const out = replaceOutsideCode(markdown, WIKILINK, (all, rawInner, offset) => {
         const parsed = parseWikilink(rawInner);
         const target = parsed.target;
         const slug = parsed.anchor || null;
 
-        // **Every link carries a label** (#180). Without one there is nothing
+        // **Every link carries a label**. Without one there is nothing
         // to resolve against: the alias namespace a bare `[[Text]]` was looked
         // up in is retired, and a shortcode is an address rather than prose, so
         // the link has neither a target this build can find nor text to show.
@@ -631,7 +631,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
 
         // An *empty* label is not a label — `[[x|]]` means "show the target's
         // name" — and that reading comes from {@link authoredLabel} so the web
-        // resolver cannot draw the line somewhere else (#113).
+        // resolver cannot draw the line somewhere else.
         let text = authoredLabel(parsed) ?? "";
 
         // Resolve the document: the source note itself for an empty target, or
@@ -648,7 +648,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
             const qualified = readQualifier(target, index.types, index.packages);
             qualifiedRead = qualified;
             // A target that does not parse as an address is a defect: there is
-            // no second namespace left to fall through to (#180).
+            // no second namespace left to fall through to.
             if (!qualified || qualified.reason) {
                 unresolved.push({
                     link: all,
@@ -659,7 +659,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
                 });
                 return unresolvedLink(text || target, target);
             }
-            // An omitted system defaults from where the link is written (#336),
+            // An omitted system defaults from where the link is written,
             // and a body is under no system block, so it is `none`. Under
             // `none` a system-bearing type addresses its *documentation* — a
             // note's `none` address IS its `doc<type>` entry — which is what a
@@ -686,7 +686,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
             if (hits.length > 1) {
                 // Two packages publish the short address, so it names neither.
                 // Its own class: the fix is the package-qualified form, not a
-                // corrected shortcode (#184).
+                // corrected shortcode.
                 unresolved.push({
                     link: all,
                     target,
@@ -729,7 +729,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // An address with an *empty* label — `[[skill-clmb|]]` — has no prose
         // to show, a shortcode being an address rather than display text, so
         // the document's **current** name stands in and a rename shows at every
-        // citation with no link edited (#1409). The knowledgebase build reads
+        // citation with no link edited. The knowledgebase build reads
         // the same authored link the same way.
         if (!text) text = doc.name ?? target;
 
@@ -751,13 +751,13 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // page an anchor names. An Item or Actor link opens that document's
         // *sheet*, which has no sections, so the anchor has nothing to address
         // and is dropped. Forging a JournalEntryPage id onto a document that
-        // can never hold one is what made such links dead-end (#1362); an
+        // can never hold one is what made such links dead-end; an
         // item's pages are addressed through its `doc<type>` counterpart.
         // A `#section` the target declares no heading for. Checked here, and
         // not only by `content-build links`, because this is the build that
         // *emits* the link: `anchorPageId` will hash any slug into a page id,
         // so an undeclared one compiles to a `@UUID` that dead-ends for the
-        // reader (#193). A foreign anchor has always been checked this way —
+        // reader. A foreign anchor has always been checked this way —
         // the manifest carries the map — and a local one now is too, from the
         // anchor set the index carries.
         if (slug && isJournal && doc.anchors && !doc.anchors.has(slug)) {
@@ -774,8 +774,8 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         const uuid =
             slug && isJournal ? pageUuid(entryUuid, anchorPageId(entryId, slug)) : entryUuid;
         const link = `@UUID[${uuid}]{${text}}`;
-        // A link into a note that exists but is not written renders marked
-        // (#183). Presentation only — the UUID above is unchanged, and a
+        // A link into a note that exists but is not written renders marked.
+        // Presentation only — the UUID above is unchanged, and a
         // `[[#slug]]` self-link is not marked because the reader is already in
         // the note it would be telling them about.
         return doc.draft ? draftLink(link) : link;

package/hm3/actors.mjs

@@ -16,7 +16,7 @@
  *
  * The machinery is {@link module:engine/actor-compiler}'s and is shared with
  * the SoHL pass: the predefined-item catalogue, the note-vocabulary →
- * document-subtype translation each embedded reference goes through (#140), the
+ * document-subtype translation each embedded reference goes through, the
  * merge and the stable embedded ids. This module states HM3's data model and
  * nothing else.
  *
@@ -24,7 +24,7 @@
  * splits what a note calls a `being` into a `character` and a `creature`, and
  * nothing in the note's own vocabulary partitions cleanly onto that split — so
  * the note says which, by writing `hm3.type`. An absent one is an error naming
- * the note, never a default (#139).
+ * the note, never a default.
  *
  * **What is emitted, and what is deliberately not.** Four rows of the content
  * format's `being` mapping table give HM3 a destination — `data.portrait` →
@@ -32,8 +32,8 @@
  * `data.templatePriority` → `flags.hm3.templatePriority` — and every one of
  * them is *declared as that source* rather than as the bare key the corpus
  * writes, so the specification's mapping is executable rather than
- * aspirational. Three were declared by #305; `data.portrait` was still read by
- * hand until #332, and so was the one row that did not work. Plus the two anchored prose sections: `{#appearance}` is HM3's `description` and `{#dossier}` its
+ * aspirational. Plus the two anchored prose sections: `{#appearance}` is HM3's
+ * `description` and `{#dossier}` its
  * `biography`. Everything else an HM3 actor carries — the thirteen abilities,
  * the sunsign, `move`, `fatigue`, `shockIndex`, a creature's `loadRating` — has
  * no shared source stated anywhere, so it is authored at its own path under
@@ -57,7 +57,7 @@ import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
 // The retirement window's reports, shared with the frontmatter lint so the
-// two cannot say different things about the same key (#305, #332).
+// two cannot say different things about the same key.
 import {
     legacyKeyMessage,
     locateFrontmatterKey,
@@ -65,7 +65,7 @@ import {
 } from "../engine/retired-fields.mjs";
 // The note-level `hm3:` block: `hm3.system` onto the document's `system`
 // verbatim, and `hm3.img` / `hm3.items` / `hm3.effects` / `hm3.flags`
-// overriding their shared top-level forms for this system alone (#58).
+// overriding their shared top-level forms for this system alone.
 import { blockField, blockProperty, mergeSystemData } from "../engine/system-block.mjs";
 
 /**
@@ -73,13 +73,13 @@ import { blockField, blockProperty, mergeSystemData } from "../engine/system-blo
  *
  * Declared rather than read by hand, so a value resolves by the same order
  * every other declared field does — `hm3.system.<to>` first, then the in-block
- * position, then the shared source, then the default (#58) — and so the
+ * position, then the shared source, then the default — and so the
  * author-facing reference can be generated from the same statement the compiler
- * obeys (#22).
+ * obeys.
  *
- * **Both positions, named separately (#305).** The specification maps
+ * **Both positions, named separately.** The specification maps
  * `data.species` onto `system.species`, and every HM3 note in the corpus writes
- * `hm3.species`. Until #126 sweeps them those are two live positions for one
+ * `hm3.species`. Until the sweep those are two live positions for one
  * field, so the declaration names both: `name` is the shared source, `legacyKey`
  * the key the block still carries, and the block wins while it is there. Naming
  * only one of them is what made the row unreadable — a plain `species` could
@@ -107,12 +107,12 @@ const ACTOR_FIELDS = Object.freeze([
  * `data.species` was: read with `blockProperty(fm, block, "portrait")` it saw
  * the block and the note's top level and nothing else, so the `data.portrait`
  * the specification names never reached the document and the `?? defaultImg`
- * beside it dressed the miss up as "this note names no art" (#332).
+ * beside it dressed the miss up as "this note names no art".
  *
  * It is **not** in `ACTOR_FIELDS`, because `buildFromFields` has no seam for
  * the subtype default that has to follow it — the `?? defaultImg` is the whole
- * of what distinguishes an unnamed portrait from a deliberately blank one
- * (#218), and it needs a subtype the coercion is not handed.
+ * of what distinguishes an unnamed portrait from a deliberately blank one,
+ * and it needs a subtype the coercion is not handed.
  *
  * @type {import("../engine/field-spec.mjs").FieldSpec}
  */
@@ -270,7 +270,7 @@ export class Hm3Actors extends SystemActorCompiler {
         const id = fm.id;
         const ctx = `actor "${name}"`;
         // The document's own subtype, and the art that goes with it. Both are
-        // looked up from the note's `type` rather than spelled here (#79); for
+        // looked up from the note's `type` rather than spelled here; for
         // HM3 the row is one-to-many, so the note's `hm3.type` decides.
         const subType = /** @type {string} */ (
             documentSubtype(this.documentSubtypes, fm.type, fm, {
@@ -283,7 +283,7 @@ export class Hm3Actors extends SystemActorCompiler {
 
         // The sweep's progress signal, reported where an author meets it
         // soonest — every consumer runs the compile, and not every one runs the
-        // lint (#142). A warning: the note compiles to the correct document
+        // lint. A warning: the note compiles to the correct document
         // either way, and refusing the position comes once no tree writes it.
         const onLegacyKey = (field) =>
             this.noteWarn(
@@ -292,7 +292,7 @@ export class Hm3Actors extends SystemActorCompiler {
             );
 
         // The shared level's own retiring position — the top-level key `data:`
-        // gathered the field off (#332). Same signal, same severity, separate
+        // gathered the field off. Same signal, same severity, separate
         // callback: a note may have moved one position and not the other.
         // Anchored at column 1, because the two spellings coincide — `portrait`
         // names a block key and a top-level one — and a locator that took the
@@ -312,16 +312,16 @@ export class Hm3Actors extends SystemActorCompiler {
         // One spelling, as everywhere else: `packFolder` names a folder note
         // by its address. This pass once read only the Foundry id, so an HM3
         // tree could not file an actor by address at all — which its own sweep
-        // needs; the id spelling is retired outright (#251, #255, #260).
+        // needs; the id spelling is retired outright.
         const folder = this.folderResolver(blockField(fm, block, "packFolder", null), {
             isAddress: true,
         });
 
         const system = {
-            // Nullish, not `||` (#218): a note that names no portrait gets the
+            // Nullish, not `||`: a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
             // Resolved through the declaration so `data.portrait` is reached at
-            // all — see {@link BIO_IMAGE_FIELD} (#332).
+            // all — see {@link BIO_IMAGE_FIELD}.
             bioImage: readField(BIO_IMAGE_FIELD, fm, reports) ?? defaultImg,
             description: renderSection(body || "", "appearance"),
             biography: renderSection(body || "", "dossier"),
@@ -332,13 +332,13 @@ export class Hm3Actors extends SystemActorCompiler {
         };
 
         // Whatever the note authors under `hm3.system`, at the DataModel's own
-        // paths (#58). This pass has no field declaration, so it claims
+        // paths. This pass has no field declaration, so it claims
         // nothing: every authored path is the author's, and the fields above
         // are what a note that authors none still gets.
         mergeSystemData(system, fm, { block });
         this.reportUndeclaredSystemData(fm, block, "Actor", subType);
         // And what this pass wrote itself — there is no field declaration for a
-        // being at all, so every key above is a compiler emission (#155).
+        // being at all, so every key above is a compiler emission.
         this.reportEmittedSystemData(system, {
             fm,
             block,
@@ -385,7 +385,7 @@ export class Hm3Actors extends SystemActorCompiler {
      * template priority.
      *
      * The rule itself is {@link module:hm3/template-priority.templateFlags},
-     * because the Item pass writes the same flag from the same statement (#283)
+     * because the Item pass writes the same flag from the same statement
      * and two copies of it were one copy too many — this pass had the only one,
      * and the Item pass had none.
      *

package/hm3/document-subtypes.mjs

@@ -14,18 +14,18 @@
 /**
  * **HM3's note-type → document-subtype map** — which Foundry document, and
  * which subtype of it, a note of each content type compiles into for HârnMaster
- * 3 (#139).
+ * 3.
  *
  * The mechanism is `engine/document-subtypes.mjs`, the same one SoHL's
  * declaration uses; the two halves share it and share nothing else. That is the
- * `engine/` ÷ system line this package draws everywhere (#36), and this file is
+ * `engine/` ÷ system line this package draws everywhere, and this file is
  * the first evidence that the line holds: a second system declared its map
  * without a line of the mechanism changing.
  *
  * **Where this map differs from SoHL's, and why that matters.**
  *
- * SoHL's map was the identity in every row until #78 renamed three of them,
- * which was a fact about SoHL rather than a rule (#79) — and while it stayed
+ * SoHL's map would be the identity in every row but for three renames,
+ * which was a fact about SoHL rather than a rule — and while it stayed
  * true nothing proved the map was doing any work. HM3's was never close. Four
  * of its rows are one-to-many, one renames outright (`projectile` →
  * `missilegear`), and five of its type names are SoHL's own with a *different
@@ -82,7 +82,7 @@ export const HM3_TYPE_KEY = "type";
  * map does not name — `affiliation`, `affliction`, `attribute`,
  * `concoction`, `mystery`, and every core type — compile into no HM3
  * document at all, silently and correctly: HM3 has no form of them, and a
- * finding on every such note would be the noise #79's rule exists to prevent.
+ * finding on every such note would be the noise the rule exists to prevent.
  *
  * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
  */

package/hm3/index.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The HM3-specific half of the toolchain: the knowledge of the HârnMaster 3
- * data model that a generic content module must never receive (#139).
+ * data model that a generic content module must never receive.
  *
  * The second half, and the first evidence that `engine/` ÷ system is a real
  * line rather than an aspiration: HM3's item-type registry and its builders,
@@ -39,7 +39,7 @@ export * as itemBuilders from "./item-builders.mjs";
 /** The `hm3:` frontmatter vocabulary of every HM3 item type. */
 export * as itemFields from "./item-fields.mjs";
 
-/** This system's note-type → document-subtype map, one-to-many rows and all (#139). */
+/** This system's note-type → document-subtype map, one-to-many rows and all. */
 export * as documentSubtypes from "./document-subtypes.mjs";
 
 /** The Item compiler. */

package/hm3/item-builders.mjs

@@ -19,7 +19,7 @@
  * both systems names both: `itemBuilders: [sohl, hm3]`. The engine keeps them
  * apart from there on — `itemBuilder(type, system)` takes the system that is
  * asking, and a type both registries declare **throws** rather than resolving
- * when nobody says which (#58). That guard existed before there was a second
+ * when nobody says which. That guard existed before there was a second
  * registry to trip it; this is the registry it was written for.
  *
  * **The builders are generated, not written**, from the field declarations in

package/hm3/item-fields.mjs

@@ -33,16 +33,16 @@
  * **One shared source, two destinations.** `name` is the shared property a
  * field draws from and `to` is where it lands, so a single authored `weight`
  * feeds `sohl.system.weightBase` *and* `hm3.system.weight` — one authored fact,
- * two documents (#58). That is the whole reason the two are declared
+ * two documents. That is the whole reason the two are declared
  * separately.
  *
  * The specification writes those sources as `data.weight`, and the sources here
- * are written bare, exactly as SoHL's are: the `data:` region is #128's
+ * are written bare, exactly as SoHL's are: the `data:` region is the sweep's
  * migration and neither half has moved to it. Spelling HM3's differently would
  * make a note feeding both systems author the same fact twice for no gain, and
  * would take these rows out of reach of `content-build content-format fields`,
  * which pairs a `data.<key>` claim with a bare declared `<key>`. Both halves
- * move together when #128 lands.
+ * move together when the sweep lands.
  *
  * **What a note authors under `hm3.system` is not declared here.** HM3 fields
  * that no shared `data:` property feeds — a skill's `type`, an armour's

package/hm3/items.mjs

@@ -13,13 +13,13 @@
 
 /**
  * **HM3's Item pass** — the two things about compiling a note into an HM3 Item
- * that are facts about HM3 rather than about the note format (#139).
+ * that are facts about HM3 rather than about the note format.
  *
  * Everything else is {@link module:engine/item-compiler}'s, and is the same
  * code the SoHL pass runs: which notes are claimed, which subtype each becomes,
  * which registry builds it, the authored `hm3.system` passthrough, the schema
  * check, and the compendium envelope. A second system is a map and a handful of
- * emitted keys, which is the arrangement #79 and #58 were building towards.
+ * emitted keys, which is the arrangement the mapping tables build towards.
  *
  * **What HM3's compiler writes on every item: one key, and only when there is
  * something to write.** The content format gives an item's `{#appearance}`
@@ -35,9 +35,9 @@
  * priority is a shared statement — a note declaring `data.templatePriority` says
  * the same thing to both systems — but HM3 declares no `system` field for it, so
  * it lands under this system's own flag scope as `flags.hm3.templatePriority`,
- * exactly as the Actor pass writes it. This pass wrote no such flag until #283:
- * an item note declaring the priority compiled into a SoHL item that knew it was
- * a template and an HM3 item that did not.
+ * exactly as the Actor pass writes it. Without it, an item note declaring the
+ * priority compiles into a SoHL item that knows it is a template and an HM3
+ * item that does not.
  *
  * **There is no HM3 equivalent of `docHtml`.** SoHL points an item at the
  * JournalEntry its prose compiled into, and HM3's data model has nowhere to put
@@ -57,13 +57,25 @@ import { templateFlags } from "./template-priority.mjs";
 export class Hm3Items extends SystemItemCompiler {
     /**
      * HM3's note-type → document-subtype map — the one declaration that says
-     * which block this pass reads, which notes it claims, and what each becomes
-     * (#58/#79).
+     * which block this pass reads, which notes it claims, and what each becomes.
      *
      * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
      */
     static documentSubtypes = HM3_DOCUMENT_SUBTYPES;
 
+    /**
+     * The `system` keys this pass derives from the note.
+     *
+     * `description` is the note's `{#appearance}` section, rendered. A note
+     * authoring it writes into a key the compiler overwrites from prose that
+     * may say something else.
+     *
+     * @type {readonly {key: string, from: string}[]}
+     */
+    static derivedSystemKeys = Object.freeze([
+        { key: "description", from: "the note's `{#appearance}` section" },
+    ]);
+
     /**
      * The `system.*` field HM3 writes on an item from the note's prose.
      *
@@ -85,7 +97,7 @@ export class Hm3Items extends SystemItemCompiler {
      * The same statement the Actor pass records, through the same
      * {@link module:hm3/template-priority.templateFlags} — see that module for
      * why the priority lives in flags at all, and for what its absence here
-     * cost (#283).
+     * cost.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {object} The flags to emit.

package/hm3/template-priority.mjs

@@ -13,7 +13,7 @@
 
 /**
  * **Where HM3 records the template priority** — one statement, read by both of
- * this system's passes (#283).
+ * this system's passes.
  *
  * `data.templatePriority` is the shared fact that a note is a *starting
  * template*, and the specification states it as a row every type maps:
@@ -48,7 +48,7 @@ import { blockProperty } from "../engine/system-block.mjs";
  * A note that is not a template — or states nothing — writes nothing, rather
  * than a `null` nothing reads.
  *
- * **Read through the shared resolver, not a field declaration** (#266). A
+ * **Read through the shared resolver, not a field declaration**. A
  * `FieldSpec`'s shared source is a single position, and this value has five:
  * `data:`, this block, the top level, and the retiring `archetype` spelling in
  * the latter two. The resolver is the single implementation of what a note said,

package/lang.mjs

@@ -29,13 +29,13 @@
  *   `expandObject` **throws**: it cannot create a `Note` property on the string
  *   `"The Pall"`. Foundry catches that throw and discards the **entire** file,
  *   so one colliding pair drops every translation in it and each string renders
- *   as its raw key (#636). A key must be a leaf **or** a branch, never both.
+ *   as its raw key. A key must be a leaf **or** a branch, never both.
  * - **A Handlebars placeholder.** Foundry interpolates with `format()` and
  *   SINGLE braces, so a `{{…}}` value renders literally unless some call site
- *   happens to hand it to a Handlebars pass (#1353).
+ *   happens to hand it to a Handlebars pass.
  * - **Data baked into a key segment.** A segment carrying anything but
  *   `[A-Za-z0-9_-]` is a path or a UUID in a key, and a dotted payload is how
- *   the collision above gets in (#636, #1351).
+ *   the collision above gets in.
  *
  * Every function here is pure — it takes source text and returns findings, and
  * touches no filesystem and emits nothing. The caller owns discovery and