@heroiclands/package-build 13.0.0 → 15.0.0

package/content-config.mjs

@@ -68,7 +68,7 @@ import path from "node:path";
 
 // Leaves with no local imports of their own, so naming them here cannot close
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
-import { isAddressSegment } from "./engine/address-charset.mjs";
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
 
 /**
@@ -116,44 +116,37 @@ export const PACK_DOCUMENT_TYPES = /** @type {const} */ ([
 ]);
 
 /**
- * The landing-page rules a repository may route by. **Inert since #204.**
- *
- * A *landing page* was a note that addressed a whole section rather than a page
- * within one, so it had no slug of its own. There are no sections in the note
- * format any more — a section is a Hugo content directory, and a page's address
- * names no directory — so there are no landings and this selects nothing.
- *
- * The key survives its own mechanism on purpose. Both publishing consumers
- * declare `landing: readme`, which stated something true when they wrote it;
- * refusing it now would break them over a correct statement, and silently
- * ignoring an unknown value would be worse. So `readme` stays accepted, the
- * retired `collection` stays refused by name (below), and the key is deleted
- * once no configuration writes it — `content-config.mjs` has no warning channel
- * with which to say "accepted, and does nothing" in between.
- *
- * @type {readonly string[]}
- */
-export const LANDING_RULES = Object.freeze(["readme"]);
-
-/**
- * What a configuration naming the retired `collection` landing rule is told.
- *
- * A retired *value* is refused the way a retired *field* is (see
- * `engine/retired-fields.mjs`): left merely unrecognized it would be reported
- * as a bad value, which names something to correct and leaves the author to
- * work out for themselves that the mechanism is gone. The message says the rule
- * is retired, what lands a section instead, and what to do with the key.
+ * Address-scheme keys a configuration may no longer declare.
+ *
+ * A retired key has exactly two possible fates, and only one of them is honest
+ * — the same reasoning `engine/retired-fields.mjs` applies to a retired
+ * frontmatter field. Left honoured, it keeps doing whatever it did, which is
+ * why it was retired. Left *ignored*, it reads to its author as though it still
+ * works: the configuration says one thing and the build does another, and
+ * nothing says so. This module has no third option, because it has no warning
+ * channel — every finding goes through `fail()`, which throws. So a retired
+ * key is **refused**, at the line it was written on, with a message that says
+ * the mechanism is gone rather than naming a value to correct.
+ *
+ * **What `landing` did (#204).** It named which note addressed a whole section
+ * rather than a page within one — a *landing page*, which therefore had no slug
+ * of its own. #203 retired the second of its two rules and #204 retired the
+ * concept both rules chose between: a section is a Hugo content directory that
+ * the note format does not carry, a page's address names no directory, and so
+ * no note lands anything. The key outlived its mechanism by one release only
+ * because both publishing consumers still declared the then-true
+ * `landing: readme`, and neither breaking them over a correct statement nor
+ * accepting the key in silence was acceptable. Neither declares it now.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const RETIRED_LANDING_RULES = Object.freeze({
-    collection:
-        "the `collection` landing rule is retired, and so is the mechanism it " +
-        "chose between: a section is a Hugo directory the note format does not " +
-        "carry, so no note lands one. Delete this key. A page that introduces " +
-        "the notes of a type is an ordinary note — `type: doc`, " +
-        "`subType: reference`, `shortcode: <type>` — addressed `doc-<type>`; " +
-        "the `section:` frontmatter key the rule read is retired with it",
+export const RETIRED_ADDRESS_KEYS = Object.freeze({
+    landing:
+        "is a retired option — delete it. It named which note addressed a " +
+        "whole section rather than a page within one, and there are no " +
+        "sections to address: a section is a Hugo content directory the note " +
+        "format does not carry, so no note lands one and every page is " +
+        "addressed `<type>-<shortcode>`. Nothing replaces it",
 });
 
 /**
@@ -166,11 +159,12 @@ export const RETIRED_LANDING_RULES = Object.freeze({
  * knowledge, held in `PACKAGE_BASE` (`engine/kb-manifest.mjs`) and prefixed at
  * resolve time, so it is never recorded here (#1465).
  *
- * `landing` is inert — see {@link LANDING_RULES}.
+ * It is the whole scheme: `landing`, the key that named which note addressed a
+ * whole section, is retired with the sections themselves — see
+ * {@link RETIRED_ADDRESS_KEYS}.
  */
 export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     prefix: "",
-    landing: "readme",
 });
 
 /**
@@ -471,10 +465,7 @@ export function publishesContentPages(config) {
 
 /**
  * @typedef {object} AddressSchemeInput
- * @property {string} [prefix]   Where the content tree mounts inside the package.
- * @property {string} [landing]  Which note addressed a whole section. Inert
- *   since #204 retired sections from the note format — see
- *   {@link LANDING_RULES}.
+ * @property {string} [prefix]  Where the content tree mounts inside the package.
  */
 
 /**
@@ -658,7 +649,7 @@ const SITE_KEYS = [
     "backfillSections",
 ];
 const SITE_TREE_KEYS = ["from", "section"];
-const SECTION_META_KEYS = ["title", "banner", "description"];
+const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
 const DOC_PAGE_KEYS = ["title", "out", "preamble"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
 const RELATIONSHIP_KEYS = ["id", "type", "manifest", "compatibility", "itemCatalog"];
@@ -695,7 +686,7 @@ const STATS_KEYS = ["lastModifiedBy"];
 export const DERIVED_SYSTEM_VERSION = Symbol.for("package-build.derivedSystemVersion");
 const PUBLISH_KEYS = ["site", "manifests", "address"];
 const MANIFEST_KEYS = ["publish", "consume"];
-const ADDRESS_KEYS = ["prefix", "landing"];
+const ADDRESS_KEYS = ["prefix"];
 
 /** @param {unknown} value */
 function isPlainObject(value) {
@@ -1134,9 +1125,36 @@ function normalizeDocs(value) {
  * add to its title. Each is left off entirely rather than written as
  * `undefined`, which is not a value YAML can carry.
  *
+ * **`listType` / `listSubType` say what the section lists**
+ * (heroiclands-hugo-theme#50). Since #204 a section's directory holds nothing
+ * but the `_index.md` written here, so a layout reading Hugo's `.Pages` finds
+ * no members and renders an empty landing. The membership survives in this map
+ * and nowhere a theme can reach it, so the landing states it and a layout
+ * substitutes the equivalent `site.RegularPages` query — the same one `sohl`'s
+ * catalog layouts already run, which is why `sohl`'s landings never broke.
+ *
+ * They are two keys of their own rather than `type` / `subType` because `type`
+ * on an `_index.md` is **Hugo's own layout selector**: verified against Hugo
+ * 0.165, a section landing carrying `type: doc` renders through
+ * `layouts/doc/list.html` rather than the default list template, so spelling
+ * the content type there would silently change which template serves the
+ * landing. (This build already uses that behaviour deliberately, for the
+ * mount's own landing.)
+ *
+ * Both are checked as **address segments**, which is the trap this came from:
+ * a section is named for the URL a consumer chose and a subType is an address
+ * segment, and the two need not agree — `/sohl/kb/user-guide/` is the section,
+ * `userguide` the subType (#207). Copying the section's name into the
+ * declaration would select no page at all, and an empty landing reported by
+ * nobody is the failure being fixed. A `listSubType` with no `listType` is
+ * refused for the same reason: a subType is only distinguishing *within* a
+ * type — `rules`, `userguide` and `reference` are all `doc` — so alone it names
+ * no query.
+ *
  * @param {unknown} value - The declared entry.
  * @param {string} where - Dotted path, for the error.
- * @returns {Readonly<{title: string, banner?: string, description?: string}>}
+ * @returns {Readonly<{title: string, banner?: string, description?: string,
+ *   listType?: string, listSubType?: string}>}
  */
 function normalizeSectionMeta(value, where) {
     if (!isPlainObject(value)) fail(where, "must be a mapping");
@@ -1149,6 +1167,32 @@ function normalizeSectionMeta(value, where) {
     if (input.description !== undefined) {
         out.description = requireNonEmptyString(input.description, `${where}.description`);
     }
+    for (const key of ["listType", "listSubType"]) {
+        if (input[key] === undefined) continue;
+        const segment = requireNonEmptyString(input[key], `${where}.${key}`);
+        if (!isAddressSegment(segment)) {
+            fail(
+                `${where}.${key}`,
+                `is \`${segment}\`, which is not alphanumeric. It names a ` +
+                    "content type or subType, and those are address segments " +
+                    `(${ADDRESS_SEGMENT_PATTERN.source}) — not the section's ` +
+                    "own name, which is a URL this site chose and need not " +
+                    "match (`user-guide` is the section, `userguide` the " +
+                    "subType). A value no page carries selects nothing and " +
+                    "leaves the landing empty",
+            );
+        }
+        out[key] = segment;
+    }
+    if (out.listSubType !== undefined && out.listType === undefined) {
+        fail(
+            `${where}.listSubType`,
+            "is declared without a `listType`. A subType tells pages apart " +
+                "only within a type — `rules`, `userguide` and `reference` " +
+                "are all `doc` — so on its own it names no query for a layout " +
+                "to run",
+        );
+    }
     return Object.freeze(out);
 }
 
@@ -1731,6 +1775,15 @@ function normalizePublish(value) {
         fail("publish.address", "must be an object");
     }
     const address = /** @type {Record<string, unknown>} */ (addressInput ?? {});
+    // A retired key is refused by name, ahead of the vocabulary check: reported
+    // as merely unrecognized it would read as a misspelling of the one key that
+    // survives, and the author would correct the spelling rather than learn
+    // that the mechanism is gone (#215).
+    for (const key of Object.keys(address)) {
+        if (Object.hasOwn(RETIRED_ADDRESS_KEYS, key)) {
+            fail(`publish.address.${key}`, RETIRED_ADDRESS_KEYS[key]);
+        }
+    }
     rejectUnknownKeys(address, ADDRESS_KEYS, "publish.address.");
 
     const prefix =
@@ -1749,24 +1802,9 @@ function normalizePublish(value) {
         fail("publish.address.prefix", "must not begin with a slash");
     }
 
-    const landing =
-        address.landing === undefined ?
-            DEFAULT_ADDRESS_SCHEME.landing
-        :   optionalString(address.landing, "publish.address.landing");
-    // A retired rule is refused by name, before the vocabulary check: reported
-    // as merely unrecognized it would read as a misspelling of the one that
-    // survives, and the author would correct the value rather than learn that
-    // the mechanism is gone (#202).
-    if (Object.hasOwn(RETIRED_LANDING_RULES, landing)) {
-        fail("publish.address.landing", RETIRED_LANDING_RULES[landing]);
-    }
-    if (!LANDING_RULES.includes(landing)) {
-        fail("publish.address.landing", `must be one of ${LANDING_RULES.join(", ")}`);
-    }
-
     return Object.freeze({
         site: normalizeSiteMode(publish.site),
-        address: Object.freeze({ prefix, landing }),
+        address: Object.freeze({ prefix }),
         manifests: Object.freeze({
             publish: optionalBoolean(manifests.publish, "publish.manifests.publish", false),
             consume: optionalBoolean(manifests.consume, "publish.manifests.consume", false),

package/docs/content-format.md

@@ -138,6 +138,17 @@ it _there_, and a system that disagrees is not in error. A weapon weighs what
 This is the same rule as `hm3.type` overriding a derived document type, applied
 to fields: derive from the shared source, and let the system state the exception.
 
+**A field whose spelling means something else at the note level has no shared
+source.** The fallback assumes the two vocabularies agree about what a name
+means, and they do not always: a note's top-level `title` is the heading its page
+publishes under, while an `affiliation` item's `system.title` is the style of
+address an office carries. Where they diverge, the field declares what the
+top-level key means instead, and the top level stops being read for it — leaving
+`<system>.system.<field>` and the legacy in-block position, which describe the
+document rather than the note. `title` is the one field this applies to; `subType`
+is the other declared item field spelled like a note-level key, and there the two
+levels mean the same thing by design.
+
 **A `WikiLink` becomes a shortcode where the target field expects one.** SoHL
 stores cross-references as shortcode strings, which is what the `Code` suffix
 marks: `data.assocSkill` is a link to a skill note, and `system.assocSkillCode`
@@ -249,17 +260,16 @@ against the same constant a shortcode is checked against, and a note carrying a
 hyphenated value is reported where it wrote it:
 
 ```text
-Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not an address segment — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a shortcode is held to. The hyphen separates the segments of an address, so a value containing one is read back as two segments and resolves to nothing
+Trauma/Blood_Loss.md:3:1: error: `subType` "blood-loss" is not a well-formed subType — a subType is letters and digits only (^[A-Za-z0-9]+$), the same charset a type, a shortcode and a contentPackage are held to. It is a vocabulary term the whole toolchain keys on, and one closed set away from being an address segment again, so a charset that held for every term but this one would be a rule nobody could state in a sentence
 ```
 
 One declared value broke the rule and has been renamed: a `doc`'s `user-guide`
-is now **`userguide`**. The old spelling is accepted for one transitional
-release and reported as a **warning** naming the replacement, so a tree that has
-not yet swept still builds:
-
-```text
-User_Guide/Actions.md:3:1: warning: `subType` "user-guide" is a retired spelling of "userguide" on a doc; write "userguide". …
-```
+is now **`userguide`**. The old spelling was accepted for one transitional
+release, as a warning naming the replacement, so the 43 `sohl` notes authoring
+it were not invalidated by the release that renamed them. Every consumer tree
+has swept, so the acceptance is gone (#210) and `user-guide` is refused by the
+charset check — it contains a hyphen, which is the reason that always applied.
+No retirement-specific code outlived the sweep.
 
 That is a guarantee rather than an observation, and it holds: of **4,456 distinct
 shortcodes** across the four content trees, not one contains a character outside
@@ -786,6 +796,16 @@ mapping for a field no schema declares is the drift these tables exist to catch.
 likewise absent here: they are filled on an embedded membership, never from a
 catalogue note's `data:`.
 
+**`system.title` is not the note's `title`.** The two are unrelated quantities
+that share a spelling. A note's top-level `title` is _the title of the note_ —
+the heading its page is published under; an affiliation's `system.title` is _the
+style of address the office carries_, Ajaw or Warden, which a being holds by
+virtue of its rank. So the top-level key is **not** a shared source for this
+field, and a note that writes one is stating its own heading and nothing else
+(#218). Author the style of address on the membership — the `system.title` of the
+entry in a being's `sohl.items` — or, on a catalogue note that genuinely carries
+one, at `sohl.system.title`.
+
 ### type: affliction
 
 Represents an affliction.

package/engine/content-address.mjs

@@ -32,12 +32,12 @@
 // The scheme vocabulary is part of the configuration contract — a
 // repository names its scheme in `package-build.config.yaml` — so it is
 // declared beside the rest of that vocabulary rather than here, and this
-// module reads it. `config.mjs` is the leaf entry point and imports nothing
-// but `node:path` and `engine/ids.mjs`, so the direction cannot close a
-// cycle (see `engine/pack-config.mjs`).
-import { DEFAULT_ADDRESS_SCHEME, LANDING_RULES } from "../content-config.mjs";
+// module re-exports it beside the addresses it derives. `config.mjs` is the
+// leaf entry point and imports nothing but `node:path` and `engine/ids.mjs`,
+// so the direction cannot close a cycle (see `engine/pack-config.mjs`).
+import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
 
-export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };
+export { DEFAULT_ADDRESS_SCHEME };
 
 /** The knowledgebase's mount within this package's site (#1470). */
 export const KB_PREFIX = "kb/";
@@ -116,26 +116,18 @@ export function contentAddress(fm) {
  * `/<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.
+ *
  * @param {object} fm - Parsed frontmatter.
- * @param {object} [options] - Options.
- * @param {{prefix?: string, landing?: string}} [options.scheme] - The
- *   repository's address scheme; defaults to {@link DEFAULT_ADDRESS_SCHEME}.
- *   `landing` is validated against {@link LANDING_RULES} and selects nothing —
- *   it is accepted so a configuration declaring the still-true `landing: readme`
- *   keeps loading, and is removed once none does.
  * @returns {string} The package-relative address, with a trailing slash and no
  *   leading one.
  * @throws {Error} When the note has no type or no shortcode to be addressed by.
  *   Such a note is not published, and inventing an address for one would put a
  *   dead entry in the manifest.
  */
-export function packageAddress(fm, { scheme } = {}) {
-    const { landing } = { ...DEFAULT_ADDRESS_SCHEME, ...scheme };
-    if (!LANDING_RULES.includes(landing)) {
-        throw new Error(
-            `unknown landing rule ${JSON.stringify(landing)} — expected one ` +
-                `of ${LANDING_RULES.join(", ")}`,
-        );
-    }
+export function packageAddress(fm) {
     return `${addressSlug(fm)}/`;
 }

package/engine/field-reference.mjs

@@ -111,6 +111,34 @@ function fieldTable(fields) {
     return padTable(rows);
 }
 
+/**
+ * The fields of one type that are **not** filled from the note's top level.
+ *
+ * A field ordinarily falls back to the top-level property spelled like its
+ * name, so an author who writes `weight: 3` at the top of a note reasonably
+ * expects it to reach the document. Where that spelling means something else at
+ * the note level the fallback is off, and an author has no way to tell from the
+ * table — the field is there, the value is written, and the document ships the
+ * default. So the reason each such field declares is rendered beside its table
+ * rather than left in the source (#218).
+ *
+ * Below the table, not inside it: the reason is a sentence or two, and
+ * {@link padTable} pads every column to its widest cell, so a cell holding it
+ * would stretch the whole type's table past legibility.
+ *
+ * @param {readonly object[]} fields - The type's declaration.
+ * @returns {string[]} Markdown lines, empty when the type exempts nothing.
+ */
+function sharedExemptions(fields) {
+    const exempt = authoredFields(fields).filter((field) => field.topLevelMeans);
+    if (!exempt.length) return [];
+    return exempt.flatMap((field) => [
+        `**\`${field.name}\` is not read from the note's top level.** There it means ` +
+            `${field.topLevelMeans}`,
+        "",
+    ]);
+}
+
 /**
  * A minimal note for one type: the frontmatter envelope every note carries,
  * plus exactly the `sohl:` fields the type requires.
@@ -204,6 +232,7 @@ export function renderItemFieldReference({
             "",
             ...fieldTable(declared[type]),
             "",
+            ...sharedExemptions(declared[type]),
             ...workedExample(type, declared[type]),
             "",
         );

package/engine/field-spec.mjs

@@ -65,6 +65,31 @@ export { setPath };
  *   still read, second, until #126 moves the corpus off it.
  *
  *   Absent means the value is not authored at all — see `value`.
+ * @property {string} [topLevelMeans] - **What the note's top-level key of this
+ *   name means instead** — declared only where it means something else, and
+ *   stating it removes the shared top-level position from this field's
+ *   resolution order (#218).
+ *
+ *   A field's `name` doubles as its identity and as the shared property it
+ *   draws from, which is right wherever the two levels state the same quantity
+ *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
+ *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   `system.title` is the style of address an office carries; a note's
+ *   top-level `title` is the note's own heading. Nothing relates them, and
+ *   before this key one silently fed the other, stringifying an authored
+ *   `title: null` into fifteen documents.
+ *
+ *   **The value is the reason**, not a flag with a comment beside it. A boolean
+ *   would record the decision and lose the case for it, and the next person
+ *   adding a field needs to know the question exists — this package's own rule
+ *   that the declaration *is* the statement, never a description of one. The
+ *   author-facing reference renders it, so an author reading the field table
+ *   learns that the top-level key will not fill this field, and why.
+ *
+ *   The exempted field is still authorable, at both of the positions that
+ *   describe the *document* rather than the note: `<system>.system.<to>` and
+ *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+ *   the top level is read, as the third step.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -

package/engine/frontmatter-lint.mjs

@@ -61,13 +61,7 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
-import {
-    declaredTags,
-    retiredSubType,
-    retiredSubTypeMessage,
-    subTypeCharsetMessage,
-    typeCharsetMessage,
-} from "./note-vocabulary.mjs";
+import { declaredTags, subTypeCharsetMessage, typeCharsetMessage } from "./note-vocabulary.mjs";
 import {
     RETIRED_FIELD_ALIASES,
     declaresRetiredAlias,
@@ -342,11 +336,18 @@ function checkDataContainer(note, { type, fields }) {
  * called, and `rules`, `userguide`, `reference` mean three genres and nothing
  * else.
  *
- * **Three checks, in this order** — retired spelling, then charset, then the
- * closed set (#206, #204). Each is ahead of the next because it is the more
- * specific statement about the same value: a retired spelling has a named
- * replacement, a hyphenated value is unaddressable whatever the type declares,
- * and only then is the type's own list the reason.
+ * **Two checks, in this order** — the charset, then the closed set (#206,
+ * #204). The charset is first because it is the more general statement about
+ * the same value: a value outside `^[A-Za-z0-9]+$` is refused whatever the type
+ * declares, and only once it is a well-formed term is the type's own list the
+ * reason to refuse it.
+ *
+ * There were three. #206 ran a retired-spelling check ahead of both, accepting
+ * `user-guide` as a warning naming `userguide`, so the 43 `sohl` notes
+ * authoring it were not invalidated by the release that renamed it. Every
+ * consumer tree has swept, so the acceptance guarded nothing and is gone: the
+ * old spelling now falls through to the charset check, which refuses it for the
+ * reason that always applied — it contains a hyphen (#210).
  *
  * @param {object} note - The note.
  * @param {object} opts
@@ -374,26 +375,7 @@ function checkSubType(note, { type, entry }) {
         ];
     }
 
-    // A retired spelling is **accepted**, and said out loud (#206). Checked
-    // before the charset, because the note is not wrong about the charset in
-    // some general way — it is wrong about one value, and naming the
-    // replacement is the whole of what the author needs. A warning rather than
-    // an error for the same reason the retired field aliases below are: the
-    // note compiles to the correct page, and erroring would red every tree the
-    // moment it took this release, ahead of any chance to sweep.
-    const replacement = retiredSubType(type, value);
-    if (replacement) {
-        return [
-            {
-                file: note.file,
-                ...at,
-                severity: "warning",
-                message: retiredSubTypeMessage(type, value, replacement),
-            },
-        ];
-    }
-
-    // The charset, before the closed set: a hyphenated value is unaddressable
+    // The charset, before the closed set: a value outside it is refused
     // whatever the type declares, and the type's list is not the reason it is
     // refused. Reported here rather than only for an enumerated type, so a
     // `subTypes: null` type — whose values nothing may yet check — is still
@@ -479,6 +461,44 @@ function checkTags(note, { type }) {
     return findings;
 }
 
+/**
+ * The frontmatter fields that name artwork, and so resolve through
+ * {@link module:engine/helpers.resolveImg}.
+ *
+ * Both, always: a being carries `img` and `portrait` independently — the token
+ * art and the sheet portrait — and a rule about how the translator reads an
+ * empty value belongs to the translator, not to whichever key happens to be
+ * more common. Eleven `sohl-kethira-basic` beings write `portrait: ""` and no
+ * note in any tree writes `img: ""` on a being; a check keyed on `img` alone
+ * would have called that tree clean (#218).
+ *
+ * @type {readonly string[]}
+ */
+const ART_FIELDS = Object.freeze(["img", "portrait"]);
+
+/**
+ * Read a shared top-level field the way the compiler reads one: the `sohl:`
+ * block first, then the note's top level.
+ *
+ * The same order {@link module:engine/helpers.sohlField} uses, restated here
+ * rather than imported so this module stays a leaf the linter can load without
+ * a resolved build configuration. Unlike `sohlField` it distinguishes the two
+ * empties — an authored `""` comes back as `""` and an authored `null` as
+ * `null` — which is the whole point of the caller below (#218).
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - The field name.
+ * @returns {any} The authored value, or `undefined` where neither position
+ *   declares one.
+ */
+function authoredValue(fm, key) {
+    const block = fm?.sohl;
+    if (block && typeof block === "object" && !Array.isArray(block) && Object.hasOwn(block, key)) {
+        return block[key];
+    }
+    return fm && Object.hasOwn(fm, key) ? fm[key] : undefined;
+}
+
 /**
  * Check one note against its type's schema.
  *
@@ -521,6 +541,53 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
                 "note in the tree belongs to it",
         });
     }
+    // `img: ""` was how a note said "I name no art" while `resolveImg`
+    // conflated the two empties and every caller defaulted with `||`. It now
+    // says the opposite — "ship no art, and do not default me" (#218) — so a
+    // note carrying the old spelling has quietly changed meaning. Forty-five
+    // `sohl-thalorna` notes were written under the old reading and would have
+    // lost their default art with no error and no warning; this is the guard
+    // that would have caught them.
+    //
+    // **Both art fields, because both go through `resolveImg`.** `portrait` is
+    // not a variant spelling of `img` — a being carries the two independently —
+    // and checking only the more common one is how the sweep that prompted this
+    // guard missed eleven `sohl-kethira-basic` beings that write
+    // `portrait: ""`. Whatever the rule is, it belongs to the function, not to
+    // one of the keys that reaches it.
+    //
+    // A **warning**, on the pattern the `package:` and retired-alias sweeps
+    // set: the note still compiles, to a document that is merely iconless, so
+    // reddening a tree over it would refuse before the sweep rather than after
+    // it. It is transitional in the same sense — `""` is a legal thing to mean,
+    // and the message says so, but nothing in any tree means it yet.
+    //
+    // **These two only, never `title`.** The rule reads as a general one about
+    // optional strings, and it is not — it belongs to `resolveImg`, and `title`
+    // never goes through it.
+    //
+    // It once had a sharper reason, recorded here because it was load-bearing
+    // and is now false: a note's top-level `title` was simultaneously the shared
+    // source for an `affiliation` item's `system.title`, so asking an author for
+    // `title: null` would have compiled the literal string `"null"` into the
+    // document. That collision is gone — the field declares `topLevelMeans` and
+    // the top-level key is no longer a source for it — so `title: null` is now
+    // harmless. Whether `title: ""` deserves a warning of its own is a separate
+    // question about the *page's* heading, still open on #218, and not settled
+    // by extending an art-path check to it.
+    for (const key of ART_FIELDS) {
+        if (authoredValue(fm, key) !== "") continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message:
+                `\`${key}: ""\` means "ship no art at all" — it no longer falls ` +
+                `back to this type's default. Write \`${key}: null\` for a note ` +
+                'that simply names none; keep `""` only where the document is ' +
+                "meant to have no image",
+        });
+    }
     if (Object.hasOwn(fm, "draft")) {
         findings.push({
             file: note.file,