@heroiclands/package-build 18.2.0 → 20.0.0

package/engine/foundry-entries.mjs

@@ -71,6 +71,7 @@ import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { isHomepage } from "./homepage.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
+import { assertNoDeclaredFolder } from "./folder-notes.mjs";
 import {
     assertNoAliasesField,
     assertNoDraftField,
@@ -132,6 +133,12 @@ export function anchorsOf(entryUuid, entryId, body, name) {
  * @param {string} name - The note's display name.
  * @param {string} address - The note's package-relative address.
  * @param {string} body - The note's markdown body.
+ * **Each entry carries the `id` of the document it addresses**, not only its
+ * UUID. The two are one fact — a UUID ends in the id — but only the entry knows
+ * which derivation produced it: an item's is its note's `fm.id`, and its
+ * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
+ * what lets the content index publish an identity it did not re-derive (#310).
+ *
  * @param {object} ctx - Resolved identities: `{ contentPackage,
  *   foundryPackageId, packRouter }`.
  * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.
@@ -200,6 +207,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 fm,
                 name,
                 url,
+                id: fm.id,
                 uuid: uuidFor(fm.type, fm.id, fm),
                 doc: docKey,
             },
@@ -210,6 +218,12 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 // On the web the item note renders as one page which *is* its
                 // documentation, so both addresses resolve to the same URL.
                 url,
+                // The journal's **own** id, which is not the item's: the
+                // content index publishes it beside the UUID, so an entry the
+                // index gives an identity to states both halves of it rather
+                // than leaving a consumer to parse the id back out of the
+                // UUID's last segment (#310).
+                id: docEntryId,
                 uuid: docUuid,
                 anchors: docUuid ? anchorsOf(docUuid, docEntryId, body ?? "", name) : undefined,
             },
@@ -225,6 +239,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             fm,
             name,
             url,
+            id: fm.id,
             uuid: own,
             anchors: own && fm.type === "doc" ? anchorsOf(own, fm.id, body ?? "", name) : undefined,
         },
@@ -273,6 +288,7 @@ export function collectFoundryEntries(contentBase, ctx) {
             absPath,
             configured: ctx.contentPackage,
         });
+        assertNoDeclaredFolder(fm, { file: rel, absPath });
         assertNoDraftField(fm, { file: rel, absPath });
         assertNoAliasesField(fm, { file: rel, absPath });
         assertNoSectionField(fm, { file: rel, absPath });

package/engine/frontmatter-lint.mjs

@@ -114,7 +114,7 @@ import {
  * @type {ReadonlySet<string>}
  */
 export const UNIVERSAL_KEYS = Object.freeze(
-    new Set(["folder", "packFolder", "pack", "archetype", "templatePriority", "kbcat"]),
+    new Set(["packFolder", "pack", "archetype", "templatePriority", "kbcat"]),
 );
 
 /**
@@ -591,30 +591,93 @@ function checkTags(note, { type }) {
  * 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[]}
+ * **Each carries where it is authored**, because the two no longer agree. The
+ * specification puts an actor's portrait under `data:` and leaves its token art
+ * at the note's top level, so `portrait` has a third position to read and `img`
+ * does not — and a check that read only the two they share would pass a
+ * `data.portrait: ""` it could not see (#332).
+ *
+ * @type {readonly {key: string, inData: boolean}[]}
+ */
+const ART_FIELDS = Object.freeze([
+    Object.freeze({ key: "img", inData: false }),
+    Object.freeze({ key: "portrait", inData: true }),
+]);
+
+/**
+ * The in-block keys a type's own declarations claim for a *different* quantity.
+ *
+ * {@link module:engine/field-spec.FieldSpec.topLevelMeans} read from the other
+ * side. That property says the note's top-level key of a field's name means
+ * something else, and `resolveFieldValue` honours it by refusing to read the
+ * shared position *for that field*. The statement is symmetric: if the two
+ * positions hold unrelated quantities, then the **block** position is not the
+ * note-level field either, and a check about the note-level field must not read
+ * it.
+ *
+ * `affiliation`'s `title` is the case that named this. A note's top-level
+ * `title` is its page heading, which the site emitter publishes as
+ * `fm.title ?? name`; `sohl.title` is the style of address an office carries —
+ * "Ajaw", "Warden". Twenty-eight `sohl-kethira-basic` affiliations author
+ * `sohl.title: ""` — an office with no style of address, which is ordinary —
+ * and every one of them was reported as publishing a page with no heading. None
+ * of them does; their pages take `name.full` exactly as intended (#312).
+ *
+ * Keyed on the **in-block** key — `legacyKey` where a field declares one, and
+ * its first segment where that is dotted — because that is the position a note
+ * authors, and so the position a note-level check would otherwise read.
+ *
+ * @param {readonly object[]|null|undefined} schema - The type's declarations.
+ * @returns {Set<string>} The in-block keys that are not the note-level field of
+ *   the same name.
  */
-const ART_FIELDS = Object.freeze(["img", "portrait"]);
+function collidingBlockKeys(schema) {
+    const keys = new Set();
+    if (!Array.isArray(schema)) return keys;
+    for (const field of authoredFields(schema)) {
+        if (field.topLevelMeans === undefined) continue;
+        keys.add(String(legacyKeyOf(field)).split(".")[0]);
+    }
+    return keys;
+}
 
 /**
- * Read a shared top-level field the way the compiler reads one: the `sohl:`
- * block first, then the note's top level.
+ * Read a shared field the way the compiler reads one: the `sohl:` block first,
+ * then `data:` where the field lives there, 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).
+ * The same order {@link module:engine/system-block.resolveFieldValue} uses,
+ * restated here rather than imported so this module stays a leaf the linter can
+ * load without a resolved build configuration. Unlike that resolver 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).
+ *
+ * **`blockCollides` drops the first position**, where the note's type declares
+ * a system field of that name meaning something else — the resolver's
+ * `topLevelMeans` exemption, applied from the note-level side (#312). See
+ * {@link collidingBlockKeys}. The caller decides per key rather than this
+ * function deciding for itself, because this module knows no type's vocabulary:
+ * the declarations arrive from the caller, as `schemas` and `vocabulary` do.
  *
  * @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.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Whether the field's shared source
+ *   is `data.<key>` rather than the top-level key.
+ * @param {boolean} [options.blockCollides=false] - Whether `sohl.<key>` is a
+ *   system field that merely shares this name, and so answers for nothing here.
+ * @returns {any} The authored value, or `undefined` where no position declares
+ *   one.
  */
-function authoredValue(fm, key) {
-    const block = fm?.sohl;
+function authoredValue(fm, key, { inData = false, blockCollides = false } = {}) {
+    const block = blockCollides ? undefined : fm?.sohl;
     if (block && typeof block === "object" && !Array.isArray(block) && Object.hasOwn(block, key)) {
         return block[key];
     }
+    const data = inData ? fm?.data : undefined;
+    if (data && typeof data === "object" && !Array.isArray(data) && Object.hasOwn(data, key)) {
+        return data[key];
+    }
     return fm && Object.hasOwn(fm, key) ? fm[key] : undefined;
 }
 
@@ -709,6 +772,12 @@ function checkEmbeddedShortcodes(note, blockName) {
  *   note against whatever its type declares and knows no type names of its
  *   own. Its absence skips the `data:` and `subType` checks rather than
  *   reporting every key as unknown.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a note of one type reaches its document through — the passes' own
+ *   declaration, asked through `engine/generate.mjs`'s `emittedArtFor`.
+ *   Supplied by the caller like `schemas`, so this module states no list of
+ *   iconless types of its own; absent it, an inert `img:` goes unreported
+ *   rather than every note's being (#349).
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
@@ -720,13 +789,21 @@ function checkEmbeddedShortcodes(note, blockName) {
  */
 export function lintNote(
     note,
-    { schemas, index, vocabulary, packs, systems = DEFAULT_SYSTEM_BLOCKS },
+    { schemas, index, vocabulary, packs, emittedArt, systems = DEFAULT_SYSTEM_BLOCKS },
 ) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+    /**
+     * The in-block keys this note's own type claims for something other than
+     * the note-level field of that name, which every note-level check below
+     * reads past (#312). Resolved once: the type is fixed for the note, and
+     * each check would otherwise ask the same question of the same
+     * declarations.
+     */
+    const blockCollisions = collidingBlockKeys(schemas?.[currentType(type)]);
 
     // The retired top-level fields, checked before the type: a note may carry
     // one whatever its type is, and each finding stands on its own. Reported
@@ -744,6 +821,34 @@ export function lintNote(
                 "note in the tree belongs to it",
         });
     }
+    // `folder:` named a compendium folder by the raw Foundry id declared in a
+    // per-pack `*-folders.yaml`. Both halves are retired together (#260): the
+    // id spelling has nothing left to resolve against once the YAML is gone.
+    //
+    // Checked here as well as refused at compile because this is where an
+    // author meets every one of them in the tree at once — which is what a
+    // tree still to sweep needs, the whole corpus rather than the first note
+    // the compile happens to reach.
+    //
+    // **Both positions**, because notes wrote it both ways: top-level, and
+    // inside the `sohl:` block. The block spelling is no longer a universal
+    // key, so it would otherwise be reported as merely unrecognized, which
+    // says nothing about what to write instead.
+    const sohlBlock = fm.sohl;
+    const folderInBlock =
+        !!sohlBlock && typeof sohlBlock === "object" && Object.hasOwn(sohlBlock, "folder");
+    if (Object.hasOwn(fm, "folder") || folderInBlock) {
+        findings.push({
+            file: note.file,
+            ...at("folder"),
+            severity: "error",
+            message:
+                "`folder:` is a retired frontmatter field — write `packFolder` " +
+                "instead. A folder is a note (`type: folder`) now, and " +
+                "`packFolder` names it by its address, not by the Foundry id a " +
+                "retired `*-folders.yaml` used to declare",
+        });
+    }
     // `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
@@ -769,15 +874,23 @@ export function lintNote(
     // 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.
+    // It once had a sharper reason: 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. The field declares
+    // `topLevelMeans` now, so the top-level key is no longer a source for it and
+    // `title: null` is harmless. `title: ""` is warned about on its own account
+    // below, as the *page's* heading rather than as an art path.
+    //
+    // **The collision itself did not go away, and this was where that was
+    // misread.** `topLevelMeans` settles which position the *emitted field*
+    // reads; it says nothing about which position a *check* reads, and
+    // `authoredValue` went on resolving through the block regardless — so an
+    // office with no style of address answered for its note's heading, in
+    // twenty-eight `sohl-kethira-basic` affiliations (#312). Hence
+    // `blockCollisions`: a note-level check reads past a block key its type
+    // claims for something else.
+
     // The template priority is a *shared source* — the specification states it
     // once for every type, as it does `pack` — so its retirement is reported
     // here rather than by the per-type loop below, which only reaches a field
@@ -801,8 +914,70 @@ export function lintNote(
         });
     }
 
-    for (const key of ART_FIELDS) {
-        if (authoredValue(fm, key) !== "") continue;
+    // An art field a note's own type never emits (#349). `img` is a *shared
+    // top-level* field — `BLOCK_DOCUMENT_PROPERTIES` maps it onto
+    // `document.img`, so it is legal on every note whatever the type — and a
+    // note whose document has no such property authors it, validates, compiles,
+    // and loses the value with nothing said. `Parrot` in `sohl-thalorna` had
+    // declared `img: images/mystery/parrot.webp` since long before the art rule
+    // was written and compiled `img: null`, exactly as a note declaring nothing
+    // does. The author's only evidence was the absence of an icon somewhere
+    // they were probably not looking.
+    //
+    // **Which types those are is not stated here.** It is asked of the passes,
+    // through the `emittedArt` the caller supplies — a note's type routes to a
+    // document, a document to the pass that compiles it, and the pass declares
+    // its own art. A list of iconless types kept in the linter would be a list
+    // free to drift from what is actually emitted, which is the defect rather
+    // than the check. Absent the option no claim is made, on the pattern
+    // `index` and `vocabulary` set.
+    //
+    // **Only an authored value, never `null`.** `null` is the blessed spelling
+    // for "this note names no art" (#218), and on a type with no art that is a
+    // true and harmless thing to say — it compiles identically to writing
+    // nothing. Twenty-six `sohl-thalorna` place notes are in exactly that
+    // state, and telling each of them to delete a key that already means
+    // nothing would bury the fifty-seven that name a path they believe ships.
+    //
+    // A **warning**, as the `package:` and retired-alias sweeps are: the note
+    // compiles correctly and the value is merely inert. Nor is it certainly
+    // unwanted — a note's top level is the generated page's front matter as
+    // well, so a template may read there what no document carries, which is a
+    // judgement only the tree's author can make.
+    const emitted = emittedArt ? emittedArt(currentType(type)) : null;
+    /** The art fields this note's type reaches nothing through. */
+    const inertArt = new Set(
+        emitted ? ART_FIELDS.filter(({ key }) => !emitted.art.includes(key)).map((f) => f.key) : [],
+    );
+    for (const { key, inData } of ART_FIELDS) {
+        if (!inertArt.has(key)) continue;
+        const authored = authoredValue(fm, key, {
+            inData,
+            blockCollides: blockCollisions.has(key),
+        });
+        if (typeof authored !== "string") continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message:
+                `\`${key}:\` reaches no document from a \`${type}\` note — ` +
+                (emitted?.document ?
+                    `it compiles into a ${emitted.document}, which carries no artwork`
+                :   "it compiles into a page rather than a compendium document") +
+                ", so the path is dropped. Delete the key, or move the art onto " +
+                "the note whose document is meant to show it; keep it only where " +
+                "a page template reads it as a parameter",
+        });
+    }
+
+    for (const { key, inData } of ART_FIELDS) {
+        // Reported above, and the distinction this draws does not exist there:
+        // where nothing is emitted, `""` and `null` are equally inert and the
+        // note has no default art to lose.
+        if (inertArt.has(key)) continue;
+        if (authoredValue(fm, key, { inData, blockCollides: blockCollisions.has(key) }) !== "")
+            continue;
         findings.push({
             file: note.file,
             ...at(key),
@@ -824,7 +999,13 @@ export function lintNote(
     //
     // A warning rather than an error: the value is legal under the rule, and a
     // note that genuinely wants no heading may keep it — it just has to mean it.
-    if (authoredValue(fm, "title") === "") {
+    //
+    // **The emitter reads `fm.title`, so this reads the note level.** On an
+    // `affiliation` `sohl.title` is the office's style of address, which the
+    // heading has nothing to do with — and `blockCollisions` is what keeps the
+    // two apart (#312). On every other type nothing claims the block key, so the
+    // resolution is the unchanged one.
+    if (authoredValue(fm, "title", { blockCollides: blockCollisions.has("title") }) === "") {
         findings.push({
             file: note.file,
             ...at("title"),
@@ -1170,10 +1351,15 @@ export function lintNote(
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a type reaches its document through; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, vocabulary, packs, references = true, systems }) {
+export function lintFrontmatter(
+    index,
+    { schemas, vocabulary, packs, emittedArt, references = true, systems },
+) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -1186,6 +1372,7 @@ export function lintFrontmatter(index, { schemas, vocabulary, packs, references
                 schemas,
                 vocabulary,
                 packs,
+                emittedArt,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
             }),

package/engine/frontmatter.mjs

@@ -301,13 +301,15 @@ export function parseValueDesc(raw) {
 }
 
 /**
- * The compendium folder a note names, and how it named it.
+ * The compendium folder a note names.
  *
- * Two spellings, deliberately not merged into one value: `packFolder:` is a
- * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
- * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
- * the string — both are alphanumeric — so the field it was written in is what
- * says, and that answer is carried rather than re-derived (#251).
+ * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * (`folder-poisonsandtoxins`), resolved through the address index the whole
+ * build shares. The `folder:` Foundry-id spelling this function once read
+ * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
+ * are retired together (#260) — a note declaring `folder:` is refused by
+ * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
+ * reaching here, so there is no second source for a value to come from.
  *
  * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
  * and is an address now (#255). A path encoded the hierarchy *in the value*, so
@@ -318,16 +320,14 @@ export function parseValueDesc(raw) {
  * authors to migrate, which is the whole reason the change was cheap enough to
  * make.
  *
- * `packFolder` wins where both are present. Nothing about `folder` changes: a
- * note that names one is read, resolved and emitted exactly as before, until
- * #260 retires it.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @returns {{value: string|null, isAddress: boolean}} The authored value, and
- *   whether it is a folder note's address.
+ *   whether it is a folder note's address. `isAddress` is always `true` and is
+ *   kept so a caller reads the same shape it always did; it distinguished the
+ *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
     const asAddress = sohlField(fm, "packFolder", null);
     if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
-    return { value: sohlField(fm, "folder", null), isAddress: false };
+    return { value: null, isAddress: true };
 }

package/engine/generate.mjs

@@ -23,10 +23,12 @@
  * Each `*` compiler walks the whole content tree and selects its own entries by
  * the note's `type` — every note in the tree belongs to this repository's
  * `contentPackage` (#56) — so routing is directory-agnostic: a file lands in a
- * pack because of its `type`, not its location. Which packs exist and which
- * folder hierarchy each one loads are declared in
- * `package-build.config.yaml`; folder files live under the content root and are
- * referenced from entry frontmatter via `sohl.folder: <id>`.
+ * pack because of its `type`, not its location. Which packs exist is declared
+ * in `package-build.config.yaml`; the **folder hierarchy is not declared
+ * anywhere**. A folder is a note like any other (#256), named by `packFolder`
+ * — its address — and it materialises in every pack that holds a document
+ * naming it, its ancestors with it (#257). So no pack loads a folder list, and
+ * two packs can no longer disagree about a folder they both hold.
  *
  * **The order the passes run in is derived, not declared** — see
  * {@link orderPassesByDependency}. The declared list is the manifest's `packs`
@@ -51,14 +53,7 @@ import { Hm3Actors } from "../hm3/actors.mjs";
 import { Macros } from "./macros.mjs";
 import { Scenes } from "./scenes.mjs";
 import { Bundles } from "./bundles.mjs";
-import {
-    statsForPack,
-    loadFolders,
-    buildFolderResolver,
-    writeFolderDocs,
-    parseMarkdownFile,
-    folderFilename,
-} from "./helpers.mjs";
+import { statsForPack, parseMarkdownFile, folderFilename } from "./helpers.mjs";
 import {
     buildFolderNoteIndex,
     collectFolderNotes,
@@ -73,7 +68,10 @@ import { buildCompileCorpus } from "./compile-corpus.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
-import { unclaimedNoteFindings } from "./note-claims.mjs";
+import { NEVER_PACKED_TYPES, unclaimedNoteFindings } from "./note-claims.mjs";
+// Which document a content type compiles into, so the art declaration below is
+// answered from the same routing the compile uses (#349).
+import { RETIRED_TYPES, currentType, packForType } from "./ids.mjs";
 import { contentPackage } from "./content-package.mjs";
 
 /**
@@ -138,6 +136,56 @@ export function compilerFor(docType, system = null) {
     return (system && SYSTEM_COMPILERS[system]?.[docType]) || COMPILERS[docType];
 }
 
+/**
+ * The art fields a note of one content type reaches its document through, and
+ * the document it reaches (#349).
+ *
+ * **Derived, never listed.** A note's type routes to a document type
+ * ({@link packForType}), a document type routes to the pass that compiles it
+ * ({@link compilerFor}), and the pass declares which art it emits
+ * ({@link BasePackCompiler.emitsArt}). So the answer is assembled from the same
+ * three statements the compile itself follows, and a pass that starts or stops
+ * emitting art changes this by changing its own declaration. A second table of
+ * "types with no image" would be a table free to drift from what is emitted,
+ * which is the defect this exists to report rather than to reproduce.
+ *
+ * **The union across systems**, because a note is compiled by whichever pack
+ * claims it: a tree feeding both SoHL and HM3 has two Actor passes, and a field
+ * either of them emits is live for the note. Only a field *no* pass emits is
+ * inert, and that is the finding this supports.
+ *
+ * @param {string} type - The note's content type.
+ * @returns {{document: string|null, art: readonly string[]}|null} What the type
+ *   compiles into and the art it carries there, or `null` where no claim can be
+ *   made — a retired type, which is reported as retired instead.
+ */
+export function emittedArtFor(type) {
+    const name = String(type ?? "");
+    if (!name || Object.hasOwn(RETIRED_TYPES, name)) return null;
+
+    // A homepage compiles into a *page*, not a compendium document, so nothing
+    // it authors reaches one. It is the one type whose absence from every pack
+    // is the intended state (`NEVER_PACKED_TYPES`).
+    if (NEVER_PACKED_TYPES.has(currentType(name))) return { document: null, art: [] };
+
+    // A folder reaches a pack by a route of its own — it materialises in every
+    // pack holding a document that references it — so `packForType` has no
+    // answer for it and no compiler class writes it. `folderDocument` does, and
+    // a Foundry `Folder` has no artwork at all.
+    if (currentType(name) === FOLDER_TYPE) return { document: "Folder", art: [] };
+
+    const { docType } = packForType(name);
+    const passes = [
+        COMPILERS[docType],
+        ...Object.values(SYSTEM_COMPILERS).map((bySystem) => bySystem[docType]),
+    ].filter(Boolean);
+    if (!passes.length) return null;
+
+    const art = new Set();
+    for (const pass of passes) for (const field of pass.emitsArt ?? []) art.add(field);
+    return { document: docType, art: Object.freeze([...art]) };
+}
+
 /**
  * Root of the build-only JSON tree for one pack.
  *
@@ -359,7 +407,7 @@ export function unsatisfiedPassDependencies(running, config) {
  *     count (0 on success) and the number of entries it wrote.
  */
 async function generatePack(
-    { name, type, folders, companions, system },
+    { name, type, companions, system },
     config,
     router,
     routingReporter,
@@ -380,41 +428,27 @@ async function generatePack(
 
     log.info(`Pack ${name}: ${contentBase} → ${dest}`);
 
-    let folderList;
-    let yamlResolver;
-    try {
-        folderList = folders ? loadFolders(path.join(contentBase, folders)) : [];
-        ({ resolver: yamlResolver } = buildFolderResolver(folderList));
-    } catch (err) {
-        log.error(`${name} ${folders} validation failed: ${err.message}`);
-        return { errors: 1, compiled: 0 };
-    }
-
     // Which folder notes this pack turned out to hold something for. A folder
     // materialises in every pack holding a document that references it, so the
-    // set is not knowable until the pass has compiled — which is why these
-    // documents are written after `compile()` and the YAML ones before it
-    // (#257).
+    // set is not knowable until the pass has compiled, which is why these
+    // documents are written after `compile()` (#257).
     /** @type {Set<import("./folder-notes.mjs").FolderNote>} */
     const referencedFolders = new Set();
 
     /**
-     * The Foundry folder id a note names, by address or by id.
+     * The Foundry folder id a note names, by its folder note's address.
      *
-     * The two spellings resolve against two different sources and always did:
-     * `packFolder` names a folder **note**, resolved through the address index
-     * shared by the whole build, and `folder` names a Foundry **id** declared
-     * in this pack's own YAML. Which one applies is the field the value was
-     * written in, never the string (#251).
+     * There is one spelling. `packFolder` names a folder **note**, resolved
+     * through the address index shared by the whole build; the `folder:`
+     * Foundry-id spelling and the per-pack `*-folders.yaml` it resolved
+     * against are retired together (#260), so there is no second source left
+     * for a value to come from.
      *
      * @param {string|null|undefined} value - As authored.
-     * @param {object} [opts]
-     * @param {boolean} [opts.isAddress] - Whether `value` is a folder address.
      * @returns {string|null} The folder id, or `null` for an absent value.
      */
-    const resolver = (value, { isAddress = false } = {}) => {
+    const resolver = (value) => {
         if (value == null || value === "") return null;
-        if (!isAddress) return yamlResolver(value);
         const folder = folderNotes.resolve(value);
         // Its ancestors with it: a `Folder` whose parent is absent from the
         // pack is an orphan Foundry renders at the root, so materialising a
@@ -444,10 +478,6 @@ async function generatePack(
         companionDests[companion.name] = companionDest;
     }
 
-    // A folder document belongs to the pack it is written into, so it carries
-    // that pack's system rather than the package-wide one (#48).
-    writeFolderDocs(folderList, statsForPack(system, config), dest, type);
-
     const pack = new packClass({
         contentBase,
         dest,
@@ -681,11 +711,13 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                 // which wins over the id it derives under the folder namespace.
                 // A record's `id` is not that: the index fills it in for every
                 // addressable note (#270), so handing records straight over
-                // would make every folder look pinned and file each one under a
-                // different id than the packs address it by. The index cannot
-                // tell a pin from a derivation, so the note is read — and only
-                // folder notes are, 79 of `sohl`'s 1,685 rather than all of
-                // them.
+                // would make every folder look pinned. Since #310 the *value*
+                // would be right either way — the index derives a folder's id
+                // under the folder namespace, so the two agree — but `derivedId`
+                // would not, and it is what tells an author whether a duplicate
+                // id was two pins or two addresses. The index cannot tell a pin
+                // from a derivation, so the note is read — and only folder notes
+                // are, 79 of `sohl`'s 1,685 rather than all of them.
                 corpus.records
                     .filter(
                         (record) =>