@heroiclands/package-build 14.0.0 → 15.0.0

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

@@ -461,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.
  *
@@ -503,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,

package/engine/helpers.mjs

@@ -234,25 +234,51 @@ export function makeFilename(name, id) {
  * asset roots — `icons/...` and `images/...` — are served from the package
  * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
  * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged, and an
- * empty path yields `""`.
- *
- * This is translation only: the per-type default for an empty result is
- * domain-specific (actors default differently from items, and gear differently
- * again), so each compiler owns its own default and applies it to the result —
- * `resolveImg(fm.img) || <default>`. For items that default is the art paired
- * with the type's builder, reached through `itemArt()`, which runs the path
- * back through this function so a registry entry and a note's `img:` are
- * spelled the same way (#7).
+ * path (already package-rooted, an absolute URL) is returned unchanged.
+ *
+ * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * key, which reaches here as `undefined` — means _unset_: the note names no art
+ * and the caller's default applies. `""` means _blank on purpose_: the note
+ * names no art **and wants none**, so no default may replace it. Both come back
+ * distinguishable, `null` and `""` respectively, and neither is invented from
+ * the other.
+ *
+ * This used to open `if (!raw) return ""`, which made the two one case: every
+ * caller then applied its default with `||`, so a deliberate blank was
+ * unspellable and an unset key and an empty string compiled identically. That
+ * is the convention the project already rejects for an optional "not specified"
+ * DataModel string, where `nullable, initial: null` keeps "unset" a single
+ * honest value rather than two.
+ *
+ * **`title` does not follow this rule**, and must not be made to. On a
+ * `type: affiliation` note `title` is *also* a declared item field whose default
+ * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
+ * key the site emitter reads as the page title — so `title: null` stringifies
+ * into the compiled document as the literal `"null"`. One key, two destinations
+ * that disagree about what empty means; see #218.
+ *
+ * This is translation only: the default for an unset path is domain-specific
+ * (actors default differently from items, and gear differently again), so each
+ * compiler owns its own default and applies it to the result with **nullish**
+ * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
+ * a deliberate blank back into the default and undo the distinction. For items
+ * that default is the art paired with the type's builder, reached through
+ * `itemArt()`, which runs the path back through this function so a registry
+ * entry and a note's `img:` are spelled the same way (#7).
  *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
  * @param {{assetRoot: string}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ * @returns {string | null} the Foundry-relative path; `""` for a deliberate
+ *   blank, and `null` when the note names no art at all.
  */
 export function resolveImg(raw, config = loadPackConfig()) {
-    if (!raw) return "";
+    // Unset — the caller's default applies. An absent key arrives as
+    // `undefined`, an authored one as `null`; they say the same thing.
+    if (raw == null) return null;
     const s = String(raw);
+    // Blank on purpose — the caller's default must not apply.
+    if (s === "") return "";
     if (s.startsWith("icons/") || s.startsWith("images/")) {
         return `${config.assetRoot}/${s}`;
     }

package/engine/homepage.mjs

@@ -371,6 +371,13 @@ export function homepageTitle(fm, config) {
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
+ * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * `pageFrontmatter` states a content page's: Hugo resolves a `url`
+ * against `baseURL`, whose path is already where the package is served, so a
+ * stated base was written twice and published the landing at
+ * `/<package>/<package>/homepage-root/`. Where the package is served is what
+ * every *href* is composed from and it reaches this page's address not at all.
+ *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
  * redirect stub at each one. The field is retired (#180) and refused before a
@@ -380,14 +387,12 @@ export function homepageTitle(fm, config) {
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
- * @param {string} options.base - Where the package is served, with both
- *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
  * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm, { contentPackage, title, base }) {
+export function homepageFrontmatter(fm, { contentPackage, title }) {
     const slug = addressSlug(fm);
-    const data = { ...fm, package: contentPackage, title, slug, url: `${base}${slug}/` };
+    const data = { ...fm, package: contentPackage, title, slug, url: `/${slug}/` };
     delete data.aliases;
     return data;
 }

package/engine/item-registry.mjs

@@ -188,5 +188,8 @@ export function itemArt(type, system) {
                 `note an \`img:\` of its own.`,
         );
     }
-    return resolveImg(art);
+    // `art` is non-empty by the guard above, so the translation never returns
+    // the `null` a note's unset `img:` would (#218); the coalesce states that
+    // rather than leaving the declared `string` return a half-truth.
+    return resolveImg(art) ?? "";
 }

package/engine/macros.mjs

@@ -261,7 +261,9 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         // into chat instead of running.
         type: resolveMacroType(fm, name),
         author: null,
-        img: resolveImg(fm.img) || DEFAULT_MACRO_IMG,
+        // Nullish, not `||` (#218): a macro note that names no art gets the
+        // shared default, one that writes `img: ""` ships blank on purpose.
+        img: resolveImg(fm.img) ?? DEFAULT_MACRO_IMG,
         scope: resolveMacroScope(fm, name),
         command,
         folder,

package/engine/site-build.mjs

@@ -343,18 +343,13 @@ export function collectHomepages(contentBase, ctx) {
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
- * @param {object} [options] - Options.
- * @param {string} [options.base] - Where the package is served; defaults to the
- *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot, pages, config, { base } = {}) {
-    const at = base || config.site?.base || `/${config.contentPackage}/`;
+export function writeHomepages(outRoot, pages, config) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
-            base: at,
         });
         const dest = path.join(outRoot, homepageDestination(page.fm));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -544,6 +539,16 @@ export function sectionFrontmatter(meta) {
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
+ * **It is stated relative to the site root, and so carries no package base**
+ * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * the package is served — a consumer's Hugo site *is* its package — so writing
+ * `page.url`, which carries the base for every href this build renders, wrote
+ * that base a second time and published every content page a segment too deep
+ * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
+ * states `/<slug>/`, and everything that points *at* the page — the address
+ * index a wikilink resolves through, and the link manifest — composes
+ * `<base><slug>/`.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
@@ -571,13 +576,14 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
             // Spread after the note's own frontmatter. Guarded because
             // `package: undefined` is not a value YAML can carry.
             ...(page.pkg ? { package: page.pkg } : {}),
-            // The address, stated. `slug` is written beside it because it is
-            // the last segment of that address and Hugo's own key for one; it
-            // decides nothing while `url` is present, but a page that carried
-            // only `url` would report a slug Hugo had inferred from the
-            // filename.
+            // The address, stated — site-root relative, because Hugo prefixes
+            // the site's own base to it (#217). `slug` is written beside it
+            // because it is the last segment of that address and Hugo's own key
+            // for one; it decides nothing while `url` is present, but a page
+            // that carried only `url` would report a slug Hugo had inferred
+            // from the filename.
             slug,
-            url: page.url,
+            url: `/${slug}/`,
             title: fm.title ?? name,
             kbfolder: page.folder,
         };
@@ -993,7 +999,7 @@ export function buildSite({ config, outRoot } = {}) {
             tableErrors: [],
             wikiErrors: [],
             stats: {
-                homepages: writeHomepages(homeRoot, homepages, resolved, { base }),
+                homepages: writeHomepages(homeRoot, homepages, resolved),
                 landings: 0,
                 out: homeRoot,
             },
@@ -1078,7 +1084,7 @@ export function buildSite({ config, outRoot } = {}) {
 
     // Last, and outside the mount: the package's front page is not part of the
     // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, { base });
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
 
     return {
         gates,

package/engine/system-block.mjs

@@ -52,6 +52,28 @@
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
  * 4. the field's own default.
  *
+ * ## A name that collides across the two vocabularies skips step 3
+ *
+ * A field's `name` is both its identity and the shared property it draws from,
+ * and those coincide only while the two vocabularies agree about what the
+ * spelling means. They do not always. An `affiliation` item's `system.title` is
+ * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
+ * `title` is the note's own heading, which the site emitter publishes. Two
+ * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ *
+ * It was not a harmless coincidence either, because step 3 answers **without**
+ * applying `field.default` — only step 2 does — so an authored `title: null`
+ * reached the field's coercion unguarded and shipped as the literal string
+ * `"null"` in fifteen documents (#218).
+ *
+ * So a field may declare `topLevelMeans`: what the top-level key of that name
+ * means *instead*. Declaring it removes step 3 for that field, leaving the two
+ * positions that describe the document rather than the note. It is deliberately
+ * a per-field opt-out rather than a change to the order — step 3 is right
+ * wherever the two levels state the same quantity, which is nearly everywhere —
+ * and its value is the reason rather than a bare flag, so the collision is
+ * legible where the field is declared. See {@link module:engine/field-spec.FieldSpec}.
+ *
  * `sohlField()` — read `fm.sohl[key]`, fall back to `fm[key]` — is the
  * degenerate case where source and destination happen to share a name. It stops
  * being the general rule; {@link blockField} is what remains of it.
@@ -347,9 +369,13 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
         if (nested !== undefined) return { value: nested, from: "block" };
     }
 
-    // 3. The shared property this field declares as its source.
-    const shared = getFrontmatter(fm, field.name, undefined);
-    if (shared !== undefined) return { value: shared, from: "shared" };
+    // 3. The shared property this field declares as its source — unless the
+    //    field declares that the top-level key of that name means something
+    //    else, in which case there is no shared position to read (#218).
+    if (field.topLevelMeans === undefined) {
+        const shared = getFrontmatter(fm, field.name, undefined);
+        if (shared !== undefined) return { value: shared, from: "shared" };
+    }
 
     // 4. The field's own default.
     return { value: field.default, from: "default" };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "14.0.0",
+    "version": "15.0.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/actors.mjs

@@ -763,7 +763,9 @@ export class Actors extends BasePackCompiler {
             // Required nullable number: a priority, or `null` for a being that
             // is not an archetype (#126 / archetype contract #604).
             archetype: systemArchetype(fm, ctx),
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) || defaultImg,
+            // Nullish, not `||` (#218): a note that names no portrait gets the
+            // subtype's default, one that writes `""` ships blank on purpose.
+            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
@@ -815,7 +817,8 @@ export class Actors extends BasePackCompiler {
         return {
             name,
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg,
+            // Nullish, not `||` — see the portrait above (#218).
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
             _id: id,
             system,
             items,
@@ -823,7 +826,7 @@ export class Actors extends BasePackCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg },
+                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },

package/sohl/item-fields.mjs

@@ -265,6 +265,12 @@ export const ITEM_FIELDS = Object.freeze({
             to: "title",
             ...STRING,
             default: "",
+            topLevelMeans:
+                "the note's own title — the heading its page is published under, " +
+                "which has nothing to do with the style of address an office " +
+                "carries. Author this on the membership instead: `sohl.system.title` " +
+                "on the item, or the `system.title` of the entry in a being's " +
+                "`sohl.items`.",
             describe: "The style of address the office carries.",
         },
         {

package/sohl/items.mjs

@@ -255,7 +255,10 @@ export class Items extends BasePackCompiler {
             // both registries are keyed by content type — while the document's
             // own subtype comes from the system's map (#79).
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || itemArt(type, SYSTEM),
+            // Nullish, not `||` (#218): `resolveImg` returns `null` for a note
+            // that names no art and `""` for one that wants none, and only the
+            // first may be replaced by the type's default.
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? itemArt(type, SYSTEM),
             _id: id,
             system,
             effects: Array.isArray(effects) ? [...effects] : [],

package/types/engine/field-spec.d.mts

@@ -63,6 +63,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] -
@@ -170,6 +195,34 @@ export type FieldSpec = {
      * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
+    /**
+     * - **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.
+     */
+    topLevelMeans?: string | undefined;
     /**
      * - Human-readable shape, for documentation. Comes
      * paired with `read` from one of the coercion constants below.

package/types/engine/helpers.d.mts

@@ -117,25 +117,47 @@ export function makeFilename(name: any, id: any): string;
  * asset roots — `icons/...` and `images/...` — are served from the package
  * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
  * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged, and an
- * empty path yields `""`.
- *
- * This is translation only: the per-type default for an empty result is
- * domain-specific (actors default differently from items, and gear differently
- * again), so each compiler owns its own default and applies it to the result —
- * `resolveImg(fm.img) || <default>`. For items that default is the art paired
- * with the type's builder, reached through `itemArt()`, which runs the path
- * back through this function so a registry entry and a note's `img:` are
- * spelled the same way (#7).
+ * path (already package-rooted, an absolute URL) is returned unchanged.
+ *
+ * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * key, which reaches here as `undefined` — means _unset_: the note names no art
+ * and the caller's default applies. `""` means _blank on purpose_: the note
+ * names no art **and wants none**, so no default may replace it. Both come back
+ * distinguishable, `null` and `""` respectively, and neither is invented from
+ * the other.
+ *
+ * This used to open `if (!raw) return ""`, which made the two one case: every
+ * caller then applied its default with `||`, so a deliberate blank was
+ * unspellable and an unset key and an empty string compiled identically. That
+ * is the convention the project already rejects for an optional "not specified"
+ * DataModel string, where `nullable, initial: null` keeps "unset" a single
+ * honest value rather than two.
+ *
+ * **`title` does not follow this rule**, and must not be made to. On a
+ * `type: affiliation` note `title` is *also* a declared item field whose default
+ * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
+ * key the site emitter reads as the page title — so `title: null` stringifies
+ * into the compiled document as the literal `"null"`. One key, two destinations
+ * that disagree about what empty means; see #218.
+ *
+ * This is translation only: the default for an unset path is domain-specific
+ * (actors default differently from items, and gear differently again), so each
+ * compiler owns its own default and applies it to the result with **nullish**
+ * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
+ * a deliberate blank back into the default and undo the distinction. For items
+ * that default is the art paired with the type's builder, reached through
+ * `itemArt()`, which runs the path back through this function so a registry
+ * entry and a note's `img:` are spelled the same way (#7).
  *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
  * @param {{assetRoot: string}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ * @returns {string | null} the Foundry-relative path; `""` for a deliberate
+ *   blank, and `null` when the note names no art at all.
  */
 export function resolveImg(raw: string | null | undefined, config?: {
     assetRoot: string;
-}): string;
+}): string | null;
 /**
  * Resolves the display name from frontmatter, preferring `name.full`,
  * falling back to `name` (if string), then `defaultValue`.

package/types/engine/homepage.d.mts

@@ -149,6 +149,13 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
+ * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * `pageFrontmatter` states a content page's: Hugo resolves a `url`
+ * against `baseURL`, whose path is already where the package is served, so a
+ * stated base was written twice and published the landing at
+ * `/<package>/<package>/homepage-root/`. Where the package is served is what
+ * every *href* is composed from and it reaches this page's address not at all.
+ *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
  * redirect stub at each one. The field is retired (#180) and refused before a
@@ -158,15 +165,12 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
- * @param {string} options.base - Where the package is served, with both
- *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
  * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title, base }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title }: {
     contentPackage: string;
     title: string;
-    base: string;
 }): object;
 /**
  * Every address a homepage carries, wherever it is written.

package/types/engine/site-build.d.mts

@@ -102,14 +102,9 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
- * @param {object} [options] - Options.
- * @param {string} [options.base] - Where the package is served; defaults to the
- *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { base }?: {
-    base?: string | undefined;
-}): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -201,6 +196,16 @@ export function sectionFrontmatter(meta: object): object;
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
+ * **It is stated relative to the site root, and so carries no package base**
+ * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * the package is served — a consumer's Hugo site *is* its package — so writing
+ * `page.url`, which carries the base for every href this build renders, wrote
+ * that base a second time and published every content page a segment too deep
+ * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
+ * states `/<slug>/`, and everything that points *at* the page — the address
+ * index a wikilink resolves through, and the link manifest — composes
+ * `<base><slug>/`.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The