@heroiclands/package-build 22.17.0 → 22.17.2

package/docs/commands.md

@@ -1712,82 +1712,118 @@ $ package-build docs item-fields --out docs/item-fields.md --title "Demo Item Fi
 
 [Configuration](configuration.md).
 
-### `package-build prose lint [path]`
+### `package-build prose lint [path]` and `prose score [path]`
 
 **NAME**
 
-Analyze note prose for readability and simpler wording.
+Review sentence readability or score each note against a package's prose bands.
 
 **SYNOPSIS**
 
 ```text
-package-build prose lint [path] [--age <years>] [--threshold <count>] [--min-words <count>]
+package-build prose lint [path] [--age <years>] [--threshold <count>] [--min-words <count>] [--rules readability|simplify|all] [--fail-on-warning]
+package-build prose score [path] [--min-words <count>] [--fail-outside]
 ```
 
 **DESCRIPTION**
 
-Run this command from the package root to review the readable prose in one
-Markdown note or a content tree. Pass a note path while editing that note;
-omit it to review the configured `paths.content` tree. A directory path scans
-its Markdown files recursively and honors `skipDirectories`. A file path
-analyzes that file alone, even if it sits in an excluded directory. The command
-reads source files and writes nothing. It is an optional editorial check:
-`package-build lint` and the normal lint scripts do not run it.
+Run the `lint` or `score` action from the package root. Pass a Markdown note while editing;
+omit the path to read the configured `paths.content` tree. A directory path
+scans Markdown files recursively and honors `skipDirectories`. A file path
+analyzes that file alone, even in an excluded directory. Both actions read
+source files and write nothing. They are optional editorial checks and are
+outside `package-build lint` and the normal build.
 
 Set defaults in `package-build.config.yaml` under `packageBuild.proseLint`:
 
 ```yaml
 packageBuild:
-  proseLint: { age: 21, threshold: 5, minWords: 8 }
+  proseLint: { age: 21, threshold: 5, minWords: 8, rules: readability }
+  proseScore:
+    minWords: 80
+    bands:
+      flesch: { min: 45, max: 80 }
+      syllablesPerWord: { max: 1.65 }
 ```
 
-No configuration is required; the values above are the defaults. `age` is the
+No configuration is required. `proseLint` uses the defaults shown. The
+`proseScore` default is `minWords: 80` with no bands; the example bands express
+one package's editorial preference, not a toolchain standard. `age` is the
 intended reader's age in years. `threshold` is the number of seven readability
 algorithms that must classify a sentence as difficult before it is reported.
 For example, a threshold of 5 reports a sentence if five or more algorithms
-flag it; a threshold of 7 reports only unanimous findings. `minWords` excludes
-shorter sentences from readability analysis. Each setting is a positive integer,
-and `threshold` must be at most 7. CLI options override individual settings:
-`--min-words` overrides `minWords`, while `--age` and `--threshold` override
-their matching keys.
-
-The command analyzes Markdown prose with `retext-english`,
-`retext-readability`, and `retext-simplify`; `retext-stringify` completes the
-text pipeline. YAML frontmatter, code blocks, wikilink addresses, and inline
-expressions are excluded. Each suggestion is a warning with a file, line,
+flag it; a threshold of 7 reports only unanimous findings. Lint's `minWords`
+excludes shorter sentences. `rules: readability` reports difficult sentences;
+`simplify` reports wording suggestions; `all` reports both. The CLI options
+override individual settings. Lint numeric settings are positive integers;
+`threshold` is at most 7.
+
+Lint analyzes Markdown paragraphs, including those in blockquotes, with `retext-english` and the selected
+readability or simplify rules; `retext-stringify` completes the text pipeline.
+Frontmatter, headings, lists, GFM tables, code blocks and inline code, image
+embeds, wikilinks, and inline expressions are excluded. The body of an ordinary
+directive such as `:::info` remains prose; SQL directive bodies are excluded.
+Each suggestion is a warning with a file, line,
 column, rule ID, confidence, offending sentence, and `expected` replacement
 list. The source location marks the difficult sentence or the specific phrase
 that could be simplified. Readability confidence is the number of algorithms
 that found the sentence difficult, out of seven. Simplify suggestions have no
 numeric confidence score, so they say `unscored`. `expected` lists suggested
 replacements; `[]` means the rule offers no replacement and may recommend
-deleting a word or rewriting a sentence. Suggestions are advisory, are never
-applied automatically, and do not make the command fail. Unreadable paths and
-invalid options do.
+deleting a word or rewriting a sentence. Suggestions are advisory and are
+never applied automatically. `--fail-on-warning` makes a selected rule's
+suggestions an explicit exit-code gate.
+
+Score uses the same paragraph selection. It reports Flesch reading ease,
+syllables per word, mean and longest sentence length, unfamiliar-word percentage
+against the Dale–Chall list, and nominalizations per thousand words. A
+nominalization is counted by its word ending (`-tion`, `-sion`, `-ment`,
+`-ness`, `-ity`, `-ance`, `-ence`, or `-ism`); this is a mechanical count, not a
+grammar judgment. Coverage is the percentage of readable body words included
+in the score: headings and lists count toward the body but are not scored.
+Review low-coverage notes in context. A note with fewer than score's `minWords`
+is reported as insufficient and is not compared with bands.
+
+Under `packageBuild.proseScore.bands`, any of `flesch`, `syllablesPerWord`,
+`meanSentenceWords`, `longestSentenceWords`, `unfamiliarWordPercent`, and
+`nominalizationsPer1000Words` may set `min`, `max`, or both. Limits are finite
+numbers and a minimum cannot exceed a maximum. Violations are warnings. The
+directory summary pools sentence, word, and syllable counts across sufficiently
+long notes before computing Flesch; it is not an average of note scores.
+`--fail-outside` makes band violations an explicit gate. No band is enforced
+until the package declares it.
 
 **OPTIONS**
 
-| Input         | Default                    | Meaning                                  |
-| ------------- | -------------------------- | ---------------------------------------- |
-| `path`        | configured `paths.content` | Markdown file or content tree            |
-| `--age`       | 21                         | Reader age in years                      |
-| `--threshold` | 5                          | Number of readability algorithms (1–7)   |
-| `--min-words` | 8                          | Minimum words for readability assessment |
+| Input               | Default                    | Meaning                                      |
+| ------------------- | -------------------------- | -------------------------------------------- |
+| `path`              | configured `paths.content` | Markdown file or content tree                |
+| `--age`             | 21                         | Lint reader age in years                     |
+| `--threshold`       | 5                          | Lint readability algorithms required (1–7)   |
+| `--rules`           | `readability`              | Lint rules: `readability`, `simplify`, `all` |
+| `--min-words`       | 8 lint; 80 score           | Minimum words per sentence or note           |
+| `--fail-on-warning` | false                      | Fail lint on selected rule findings          |
+| `--fail-outside`    | false                      | Fail score when a note crosses a band        |
 
 **EXIT STATUS**
 
-0 after reporting suggestions; 1 for invalid options or unreadable paths.
+0 after an advisory report; 1 for invalid options, unreadable paths, or an
+explicit failure condition.
 
 **EXAMPLES**
 
 ```bash
 package-build prose lint assets/content/Lore/Harbor.md
+package-build prose lint assets/content/Lore/Harbor.md --rules simplify
+package-build prose lint assets/content/Lore/Harbor.md --fail-on-warning
 package-build prose lint
 package-build prose lint assets/content --age 18 --threshold 6 --min-words 10
+package-build prose score assets/content/Lore/Harbor.md
+package-build prose score assets/content/Lore --fail-outside
 ```
 
-For a note whose fifth line says `The utilization is very high.`, the command
-can report:
+For a note whose fifth line says `The utilization is very high.`, lint with
+`--rules simplify` can report:
 
 ```text
 assets/content/Lore/Harbor.md:5:5: warning: retext-simplify/utilization: confidence=unscored; sentence="The utilization is very high."; expected=["use"]; Unexpected `utilization`, use `use` instead
@@ -1823,8 +1859,11 @@ checks frontmatter against the declared vocabulary and each system's `sohl:`
 it), that an icon a note writes is one the registry declares, and that
 markup inside a note's body does not smuggle in a character the charset
 check cannot see. `--no-references` turns off the check that a frontmatter
-shortcode reference lands, for a tree whose cross-package references it
-cannot see. Reads the content tree named by `root`, defaulting to
+shortcode reference lands, including references in schema-declared system
+fields, for a tree whose cross-package references it cannot see. Address
+references in system fields resolve against this package and its declared
+dependencies; exact Item UUID validation remains part of compilation. Reads
+the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
 **OPTIONS**
@@ -2037,7 +2076,9 @@ retired — every link is an address), a wikilink authored in frontmatter
 (which is data and is never resolved), and a package homepage's markdown
 links and `landing:` addresses, which are published verbatim and use no
 wikilink at all. Also reports a vendored foreign-package content index that
-has drifted out of reach, naming `package-build deps fetch` as the fix.
+has drifted out of reach, naming `package-build deps fetch` as the fix. Resolves
+address-valued SoHL system fields declared by the installed schema against this
+package and its declared dependencies.
 Reads the content tree named by `root`, defaulting to `paths.content`, and
 the cached content indexes of any declared dependency; writes nothing.
 
@@ -2647,19 +2688,15 @@ package-build addresses diff --from <zip|dir> [--strict]
 **DESCRIPTION**
 
 Reports every published `(type, shortcode)` address this build no longer
-publishes, against a released artifact — the signal that a shortcode
-rename or a withdrawn note used to cost nothing and now does, emitted in
-the repository doing the renaming while the change is still in front of
-its author. Its own command rather than a step of `package compile`,
-because it reads a _second_ artifact the compile knows nothing about and
-asks a question about a release, not about a build — a repository between
-releases has nothing to compare against. `--from` names the baseline
-explicitly — a release's `.zip`, or the directory built from one — never
-derived and never downloaded, for the same reason `deps fetch --from` is
-explicit: a command that reaches the network on its own is not
-reproducible. A finding is placed against the tree, at the note that made
-the rename, not against the compiled output it was read from. Reads the
-baseline artifact and the current content tree; writes nothing.
+publishes, against a released artifact. A departed address is identified as
+renamed when the same document id appears under another address; otherwise it
+is reported as withdrawn. An id derived from the canonical address changes
+with its shortcode. The old address is reported as withdrawn; the new address
+appears in the current package and produces no finding. Pair those addresses
+by hand. A pinned id lets the command identify the same document at its new
+address. `--from` names the baseline explicitly: a release's `.zip`, or the
+directory built from one. The command reads the baseline artifact and current
+content tree and writes diagnostics only.
 
 **OPTIONS**
 
@@ -2674,8 +2711,8 @@ baseline artifact and the current content tree; writes nothing.
 
 **EXIT STATUS**
 
-1 if `diff` is named with no `--from`. Without `--strict`, a renamed or
-withdrawn address is reported as a warning and does not fail the run. With
+1 if `diff` is named with no `--from`. Without `--strict`, a departed address
+is reported as a warning and does not fail the run. With
 `--strict`, 1 if any address is no longer published. 1 on any other thrown
 error (the baseline declaring an Item pack this build does not have, or
 this repository declaring no Item pack at all to diff). Otherwise 0.

package/docs/configuration.md

@@ -1457,38 +1457,65 @@ packageBuild:
     envPrefix: SOHL
 ```
 
-| Key                                                                                        | Type                                        | Required | Default                                |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | -------------------------------------- |
-| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                          |
-| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                   |
-| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                 |
-| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                   |
-| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                 |
-| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                   |
-| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                          |
-| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                              |
-| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`                  |
-| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`       |
-| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}`      |
-| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                              |
-| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                              |
-| [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8}` |
-
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint).``
+| Key                                                                                        | Type                                        | Required | Default                                                    |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------- | -------- | ---------------------------------------------------------- |
+| [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
+| [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
+| [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
+| [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                                       |
+| [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                                              |
+| [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                                                  |
+| [`packageBuild.deploy`](#packagebuilddeploy)                                               | object                                      | no       | `{envPrefix: "SOHL"}`                                      |
+| [`packageBuild.release`](#packagebuildrelease)                                             | object                                      | no       | `{artifact: <from packageKind>}`                           |
+| [`packageBuild.bundle`](#packagebuildbundle)                                               | object                                      | no       | `{entry: "<foundryPackage>.mjs"}`                          |
+| [`packageBuild.container`](#packagebuildcontainer)                                         | object                                      | no       | see below                                                  |
+| [`packageBuild.e2e`](#packagebuilde2e)                                                     | object                                      | no       | see below                                                  |
+| [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
+| [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
+
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
-Optional defaults for [`package-build prose lint`](commands.md#package-build-prose-lint-path).
+Optional defaults for [`package-build prose lint`](commands.md#package-build-prose-lint-path-and-prose-score-path).
 `age` is the reader age, `threshold` is the number of readability algorithms
 required to flag a sentence (1–7), and `minWords` is the minimum sentence
-length. Each setting is a positive integer; command-line options can override
-them for one analysis.
+length. `rules` is `readability`, `simplify`, or `all`. Each numeric setting is
+a positive integer; command-line options can override them for one analysis.
 
 ```yaml
 packageBuild:
-  proseLint: { age: 21, threshold: 5, minWords: 8 }
+  proseLint: { age: 21, threshold: 5, minWords: 8, rules: readability }
 ```
 
+### `packageBuild.proseScore`
+
+Optional defaults for [`package-build prose score`](commands.md#package-build-prose-lint-path-and-prose-score-path).
+`minWords` is the minimum number of analyzed words for a note to receive a
+score. `bands` states the package's acceptable range for any reported metric;
+there are no default bands. Each band has `min`, `max`, or both, as finite
+numbers. An omitted bound is open. The score report stays advisory unless
+`--fail-outside` is requested.
+
+```yaml
+packageBuild:
+  proseScore:
+    minWords: 80
+    bands:
+      flesch: { min: 45, max: 80 }
+      syllablesPerWord: { max: 1.65 }
+      meanSentenceWords: { max: 28 }
+      longestSentenceWords: { max: 55 }
+      unfamiliarWordPercent: { max: 35 }
+      nominalizationsPer1000Words: { max: 30 }
+```
+
+Flesch is a reading-ease score, so a value below its minimum is harder prose
+and one above its maximum is simpler prose. These sample bounds are editorial
+choices for illustration. `--min-words` overrides `minWords` for one score run.
+
 ### `packageBuild.stageDir` and `packageBuild.assets`
 
 `stageDir` is where the package is assembled before it is zipped or

package/docs/reference/format-details.md

@@ -303,10 +303,16 @@ has three regions:
 | **Top level**        | The note's identity, name, description, and publication | An error     |
 | **`data:`**          | The subject itself, shared by systems                   | An error     |
 | **`hm3:` / `sohl:`** | The subject as one system's documents                   | An error     |
+| **`dnd5e:`**         | A declared system block with no document field schema   | Unchecked    |
 
 The complete top-level allowlist, in its required order, is `shortcode`, `name`,
-`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Omit fields that
-do not apply. The first fields of a typical note look like this:
+`type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`, `dnd5e`. The
+address vocabulary recognizes three systems: `sohl`, `hm3`, and `dnd5e`. Omit
+fields that do not apply. The first fields of a typical note look like this:
+
+The `dnd5e` system id is accepted in configuration and addresses. No
+dnd5e-specific document types are declared, so the block has no field
+vocabulary for lint or a compiler to check.
 
 ```yaml
 ---
@@ -410,7 +416,6 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **place character** | `place`                | `fortified`, `temple`, `market`, `trading`, `merchant`, `mining`, `fishing`, `naval`, `military`, `imperial`, `provincial`, `coastal`, `river`, `lakeside`, `hill`, `mountain`, `valley`, `forest`, `woodland`, `inland`, `island`, `frontier`, `border`, `craft`, `caravan`, `pilgrimage`, `holy`, `sacred`, `free`, `ford`, `portage`, `pass`, `well` |
 | **place scale**     | `place` / `region`     | `continent`                                                                                                                                                                                                                                                                                                                                             |
 | **being station**   | `being`                | `tradesfolk`, `common-folk`, `soldiery`, `administration`, `clergy`, `mages`, `underworld`, `dependents`, `guilded`, `unguilded`                                                                                                                                                                                                                        |
-| **being kind**      | `being`                | `character`, `creature`                                                                                                                                                                                                                                                                                                                                 |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                                                                 |
 | **audience**        | any                    | `gm`                                                                                                                                                                                                                                                                                                                                                    |
 
@@ -484,48 +489,25 @@ first because a person may be several at once and because nothing ranks
 **A continent is a region carrying a tag, not a subtype**, because structurally it
 is a region: the same fields, the same parent chain, everything but scale.
 
-#### A being's kind is the one tag group that is a slot
-
-A person and a beast carry very different amounts of data, and a being note says
-which it is with a tag rather than leaving it to be guessed from how much the
-note holds.
-
-| `beingKind` value | the subject is                                                                                                                                |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `character`       | a person — someone with a name, a station, a history, and the attributes, skills and carried gear that go with living a life                  |
-| `creature`        | a beast, a monster or a made thing — statted for what it does rather than for who it is, and usually carrying no equipment and no affiliation |
-
-**The slot is filled once, or not at all.** The two are alternative answers to
-one question, so a note carrying both has answered it twice and every reader of
-the tag gets to pick; that is refused as an error naming the note. A being
-carrying **neither** is not a finding. The kind is authored deliberately, and
-nothing can tell a being nobody has classified from one whose author means to
-leave it unclassified — a tree part-way through tagging is a tree with untagged
-beings in it, and failing its build would be a rule about the schedule rather
-than about the content.
-
-**Nothing else fills the slot, and nothing else is refused for failing to.** A
-being tagged `undead` or `beast-of-burden` is describing the subject in the
-author's own words, in a region that is open, and this build has no standing to
-take that back. What is refused is a near miss of one of the two — `charcter`
-drops the note out of every query for characters while the list still renders —
-and the two of them together. Those are the only two refusals a closed tag
-vocabulary can make here, and both are errors, so a build carrying one fails.
-
-**The same two words name two other things, and neither is this.** `hm3.type`
-takes `character` or `creature` as the HM3 _document_ a being compiles to, in a
-system block rather than in `tags:`. The note itself uses `type: being`; `type: character` is refused.
-Three namespaces, one pair of words; the tag is the system-agnostic one, and it
-is the only one that describes the subject rather than a document.
-
-**Neither the book nor the website branches on the kind.** One flow serves both
-— the authored image, then the infobox, then the prose — and a creature's box is
-simply shorter, because it has less in it. A section with nothing to put in it is
-not emitted at all, so a creature with no equipment has no `EQUIPMENT` heading
-rather than an empty one, exactly as rule 4 of [the infobox](#the-infobox) drops
-a row with no value. The tag classifies the subject, which is what makes a list
-of the creatures in a setting a thing a query can ask for; it is not an
-instruction to a renderer.
+#### A being's subtype describes the subject
+
+`being` accepts the optional top-level values `npc`, `character`, and `creature`.
+The subtype classifies the note's subject; it does not select a Foundry Actor
+document type.
+
+| `subType`   | the subject is                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `npc`       | A character meant to be encountered. It may describe a reusable template and need not be a singular individual. |
+| `character` | A detailed, playable, singular individual.                                                                      |
+| `creature`  | Any being that is neither a character nor an NPC.                                                               |
+
+`hm3.type` remains the HM3 document selector and must be `character` or
+`creature` when an HM3 being block is present. SoHL continues to compile beings
+as `Actor.being`. The note subtype and each system's document type answer
+different questions.
+
+Tags remain open descriptive terms. A being may carry tags such as `undead`,
+`soldiery`, or `draft`; those tags do not replace the `subType` classification.
 
 The mapping tables below describe the **document** destinations. A key that
 appears in no table still reaches the web page; it simply reaches no Foundry

package/docs/reference/note-types.md

@@ -28,7 +28,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 ### being
 
-**Subtypes:** Open vocabulary.
+**Subtypes:** `npc`, `character`, `creature`.
 
 | Field                            | Shape                     | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | -------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/engine/actor-compiler.mjs

@@ -448,11 +448,11 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The actor's two pieces of art, resolved, with the being default beneath
      * them.
      *
-     * **The default is chosen from the note's tags**, which only a compiler can
-     * read: a `character` falls back to one file and a `creature` to another,
-     * and both are addresses in the package that ships them. A tree whose index
-     * cannot answer that address — a dependency not yet fetched — falls through
-     * to the subtype's own default, so the document is never left with no art.
+     * **The default follows the note's `subType`**, with tags as a compatibility
+     * fallback for content trees that have not migrated. Both addresses belong
+     * to the package that ships them. A tree whose index cannot answer an
+     * address — a dependency not yet fetched — falls through to the document
+     * subtype's own default, so the document is never left with no art.
      *
      * `tokenIcon` unset follows `icon`, and the fallback is applied after
      * resolution rather than before: a note naming an icon and no token icon