@heroiclands/package-build 3.4.0 → 5.0.0

package/content-config.mjs

@@ -33,7 +33,7 @@
  *     assets:
  *         - { from: assets/icons, to: assets/icons }
  * publish:
- *     site: true
+ *     site: content
  *     manifests: { publish: true, consume: true }
  * ```
  *
@@ -153,6 +153,62 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     landing: "readme",
 });
 
+/**
+ * How much of a package reaches the web.
+ *
+ * Every HeroicLands package publishes something: a top-level, human-authored
+ * homepage at `https://www.heroiclands.org/<contentPackage>/` saying what the
+ * module is, which system it needs and how to install it (#50). So there is no
+ * value here meaning *no web presence at all* — homepage-only is the **floor**,
+ * and the default.
+ *
+ * - `homepage` — the authored homepage, and **no other page**. The content tree
+ *   is not walked for pages, `site.sections` / `site.trees` / `site.landing`
+ *   emit nothing, and link-manifest entries carry no web `path`.
+ * - `content` — the homepage *plus* every page the content tree publishes: the
+ *   knowledgebase, the extra trees, the section landings.
+ *
+ * **Homepage-only is a first-class mode, not an accommodation.**
+ * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
+ * Fan Material Guidelines) and `harn-adventures` (HârnFanon under Lythia's
+ * terms) must each publish a homepage and nothing beneath it — two packages
+ * under two different fan-content licences. The boundary is **published
+ * content**: journal text, artwork, item descriptions, compiled notes. A
+ * human-authored page announcing the module discloses none of it. Because the
+ * failure mode is silent — a `site:` block added later ships licensed content
+ * with nobody noticing — the mode fences the content surfaces off rather than
+ * trusting a configuration to stay empty.
+ *
+ * This was a boolean until 5.0.0, and `false` read as "no web presence", which
+ * no longer describes any package. Both spellings are refused rather than
+ * mapped: a value silently reinterpreted reads to its author as though it still
+ * means what it said.
+ *
+ * @typedef {"homepage" | "content"} SiteMode
+ */
+
+/**
+ * The publishing modes {@link PublishSwitches.site} may name, floor first.
+ *
+ * @satisfies {readonly SiteMode[]}
+ */
+export const SITE_MODES = /** @type {const} */ (["homepage", "content"]);
+
+/**
+ * Whether this package publishes the pages its content tree compiles to.
+ *
+ * The one question every reader of the mode actually asks — the site build, to
+ * decide whether to walk the tree at all, and the link-manifest emitter, to
+ * decide whether an entry carries a web `path`. Written once here so the two
+ * cannot come to disagree about what a mode means.
+ *
+ * @param {{publish: {site: SiteMode}}} config - A resolved configuration.
+ * @returns {boolean} Whether content pages are published.
+ */
+export function publishesContentPages(config) {
+    return config.publish.site === "content";
+}
+
 /**
  * @typedef {"systems" | "modules"} PackageKind
  */
@@ -300,7 +356,8 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
 
 /**
  * @typedef {object} PublishSwitches
- * @property {boolean} site           Render this package's knowledgebase/site pages.
+ * @property {SiteMode} site          How much of this package reaches the web.
+ *                                    See {@link SITE_MODES}.
  * @property {ManifestSwitches} manifests
  */
 
@@ -387,8 +444,15 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
 
 /**
  * @typedef {object} PublishSwitchesInput
- * @property {boolean} [site]
+ * @property {SiteMode} [site]
  * @property {ManifestSwitchesInput} [manifests]
+ * @property {AddressSchemeInput} [address]
+ */
+
+/**
+ * @typedef {object} AddressSchemeInput
+ * @property {string} [prefix]   Where the content tree mounts inside the package.
+ * @property {string} [landing]  Which note addresses a whole section.
  */
 
 /**
@@ -454,7 +518,9 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
  *                                          which has none to invent.
  * @property {Relationships} [relationships]  What this package declares about
  *                                          others, in Foundry's own shape.
- * @property {PublishSwitchesInput} [publish]  Publishing switches. Each defaults to off.
+ * @property {PublishSwitchesInput} [publish]  Publishing switches. The manifest
+ *                                          switches default to off; `site`
+ *                                          defaults to `homepage`, the floor.
  */
 
 /**
@@ -1272,6 +1338,43 @@ function normalizeItemBuilders(value) {
     };
 }
 
+/**
+ * The publishing mode, refusing the boolean this setting used to be.
+ *
+ * A boolean is refused rather than mapped onto the nearest mode, because the
+ * reading `false` invited — *this package has no web presence* — is exactly the
+ * belief the change exists to correct, and a value quietly reinterpreted reads
+ * to its author as though it still means what it said. So the message names the
+ * mode to write instead of the value to fix.
+ *
+ * @param {unknown} value - The authored `publish.site`.
+ * @returns {SiteMode} The mode.
+ */
+function normalizeSiteMode(value) {
+    if (value === undefined) return "homepage";
+    if (typeof value === "boolean") {
+        fail(
+            "publish.site",
+            `is no longer a boolean — write \`site: ${value ? "content" : "homepage"}\`. ` +
+                `Every package publishes an authored homepage at ` +
+                `/<contentPackage>/, so no value means "no web presence": ` +
+                `\`homepage\` publishes that page and nothing else, and ` +
+                `\`content\` publishes it plus every page the content tree ` +
+                `compiles to`,
+        );
+    }
+    if (
+        typeof value !== "string" ||
+        !(/** @type {readonly string[]} */ (SITE_MODES).includes(value))
+    ) {
+        fail(
+            "publish.site",
+            `must be one of ${SITE_MODES.join(", ")} (got ${JSON.stringify(value)})`,
+        );
+    }
+    return /** @type {SiteMode} */ (value);
+}
+
 /**
  * @param {unknown} value
  * @returns {Readonly<PublishSwitches>}
@@ -1279,7 +1382,7 @@ function normalizeItemBuilders(value) {
 function normalizePublish(value) {
     if (value === undefined) {
         return Object.freeze({
-            site: false,
+            site: "homepage",
             manifests: Object.freeze({ publish: false, consume: false }),
             address: Object.freeze({ ...DEFAULT_ADDRESS_SCHEME }),
         });
@@ -1332,7 +1435,7 @@ function normalizePublish(value) {
     }
 
     return Object.freeze({
-        site: optionalBoolean(publish.site, "publish.site", false),
+        site: normalizeSiteMode(publish.site),
         address: Object.freeze({ prefix, landing }),
         manifests: Object.freeze({
             publish: optionalBoolean(

package/engine/base-compiler.mjs

@@ -14,9 +14,9 @@
 /**
  * `BasePackCompiler` — the one compile loop every pack pass runs.
  *
- * Walking the content tree, rejecting what this build does not own, skipping
- * drafts, expanding generated tables, converting wikilinks, writing the JSON
- * and counting what failed are the same in every pass. They were written out
+ * Walking the content tree, rejecting what this build does not own, expanding
+ * generated tables, converting wikilinks, writing the JSON and counting what
+ * failed are the same in every pass. They were written out
  * once per pass — three times when this was filed, five by the time it landed —
  * so a fix to any of them had to be made everywhere, and the passes drifted
  * apart in exactly the places nobody was comparing (#1509).
@@ -73,26 +73,25 @@ import {
     expandNoteTables,
 } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
-import { contentPackage } from "./content-package.mjs";
-import { assertNotePackage } from "./note-package.mjs";
+import { assertNoDeclaredPackage } from "./note-package.mjs";
+import { assertNoDraftField } from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
 
 /**
  * The tallies one pass accumulates while walking the tree.
  *
  * `declined` and `skippedOther` are deliberately separate numbers. A declined
- * note is one this build **refused** — it names a package this repository does
- * not compile — and it is an error; a skipped one legitimately belongs to
- * another pass, and there are thousands of those. Folding the first into the
- * second is what let a whole tree be filtered out in silence (#56).
+ * note is one this build **refused** — it declares a retired frontmatter field
+ * — and it is an error; a skipped one legitimately belongs to another pass, and
+ * there are thousands of those. Folding the first into the second is what let a
+ * whole tree be filtered out in silence (#56).
  *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
- * @property {number} skippedDraft - Notes marked `draft: true`.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare another
- *   package. Counted as errors, never as skips.
+ * @property {number} declined - Notes refused because they declare a retired
+ *   frontmatter field. Counted as errors, never as skips.
  */
 
 /**
@@ -336,9 +335,6 @@ export class BasePackCompiler {
         const { markdown: tabulated, lineMap } = expandNoteTables(body, {
             docs: this.contentDocs,
             name,
-            // The repository's package, not the note's: every note in the tree
-            // is this package's note, whether or not it says so (#56).
-            pkg: contentPackage(),
             fm,
             bodyLine,
         });
@@ -512,15 +508,13 @@ export class BasePackCompiler {
         if (stats.skippedNoId) {
             log.info(`Skipped ${stats.skippedNoId} note(s) missing id`);
         }
-        if (stats.skippedDraft) {
-            log.info(`Skipped ${stats.skippedDraft} draft(s)`);
-        }
         if (stats.declined) {
             // Its own line, at error level: these are not skips, and burying
             // them in the skipped tally is the defect (#56). Each one has
             // already been named individually as a diagnostic.
             log.error(
-                `Declined ${stats.declined} note(s) declaring another package`,
+                `Declined ${stats.declined} note(s) declaring a retired ` +
+                    `frontmatter field`,
             );
         }
         this.reportDetail(stats);
@@ -535,7 +529,6 @@ export class BasePackCompiler {
         /** @type {PassStats} */
         const stats = {
             compiled: 0,
-            skippedDraft: 0,
             skippedNoId: 0,
             skippedOther: 0,
             declined: 0,
@@ -560,18 +553,27 @@ export class BasePackCompiler {
                 stats.skippedOther++;
                 continue;
             }
-            // The package a note belongs to is this repository's configured
-            // one; `package:` is optional and merely has to agree (#56). A
-            // disagreement is reported and counted as an error — never skipped,
-            // which is how a tree naming a package nothing answers to used to
-            // compile zero notes and exit 0. The file comes from the diagnostic
-            // locator, so the message must not repeat it.
+            // The retired frontmatter fields, refused before `selects` so a
+            // note is answered whichever pass would have claimed it — and
+            // whatever the declared value says.
+            //
+            // - `package:` (#56): a note's package is the repository's
+            //   configured one, so declaring it restates a constant.
+            // - `draft:` (#69): it excluded the note from the packs, the
+            //   manifest and the site, and no checker reported the links that
+            //   left dangling.
+            //
+            // Both are reported and counted — never skipped, which is how a
+            // tree naming a package nothing answers to used to compile zero
+            // notes and exit 0. The file comes from the diagnostic locator, so
+            // neither message may repeat it.
             try {
-                assertNotePackage(fm);
+                assertNoDeclaredPackage(fm, { absPath });
+                assertNoDraftField(fm, { absPath });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;
-                this.noteError(err.message);
+                this.noteError(err.message, err.position);
                 continue;
             }
             // Checked before `selects`, and therefore for every note this
@@ -584,11 +586,6 @@ export class BasePackCompiler {
                 stats.skippedOther++;
                 continue;
             }
-            if (fm.draft === true) {
-                stats.skippedDraft++;
-                log.debug(`Skipping draft: ${absPath}`);
-                continue;
-            }
             if (!fm.id) {
                 if (this.constructor.requiresId) {
                     throw new Error(`${Label} missing id: ${absPath}`);
@@ -597,9 +594,9 @@ export class BasePackCompiler {
                 this.noteWarn(`${label} note has no id, skipping`);
                 continue;
             }
-            // Which pack of this type takes it. Applied after the draft and
-            // id checks — a draft is not compiled anywhere, so its declaration
-            // is nobody's business — and before `skipNote`, so a note this pack
+            // Which pack of this type takes it. Applied after the id check —
+            // a note with no id is nobody's document, so its routing is
+            // nobody's business — and before `skipNote`, so a note this pack
             // does not own never reaches this pass's own rejection rules.
             try {
                 if (!this.routesHere(fm)) {

package/engine/content-links.mjs

@@ -52,7 +52,8 @@ import { matchAllOutsideCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
-import { notePackage, searchableFrontmatter } from "./note-package.mjs";
+import { contentPackage } from "./content-package.mjs";
+import { searchableFrontmatter } from "./note-package.mjs";
 import {
     canonicalKey,
     loadForeignManifests,
@@ -130,12 +131,13 @@ export function buildLinkIndex(
     const byAlias = new Map();
     const aliasCollide = new Set();
 
+    // The one package every note in this tree belongs to. Taken from the
+    // configuration, never from a note: `package:` is retired, so there is no
+    // second source an address could disagree with (#56).
+    const pkg = contentPackage();
+
     for (const note of notes) {
         const { fm, type } = note;
-        // Derived, never read out of frontmatter: `package:` is optional, and a
-        // note that declares nothing addresses exactly as one that declares the
-        // configured package (#56).
-        const pkg = notePackage(fm);
         if (typeof fm.shortcode === "string" && fm.shortcode) {
             byKey.set(`${type}/${fm.shortcode}`.toLowerCase(), note);
             // The canonical, fully qualified address alongside the short one,
@@ -170,7 +172,7 @@ export function buildLinkIndex(
     // A foreign package may use a type this tree has never seen, so its types
     // join `types` — otherwise `readQualifier` reads the link as prose and it
     // is never checked at all.
-    const localPackages = new Set(notes.map((n) => notePackage(n.fm)));
+    const localPackages = new Set([pkg]);
     const foreign =
         manifestDir ?
             loadForeignManifests(manifestDir, localPackages)
@@ -178,15 +180,15 @@ export function buildLinkIndex(
     for (const v of foreign.index.values()) if (v.type) types.add(v.type);
 
     const packages = new Set([
-        ...[...byKey.values()].map((n) => notePackage(n.fm)),
+        ...(byKey.size ? [pkg] : []),
         ...foreign.packages,
     ]);
 
     /** The searchable universe a `dataview` table draws its rows from. */
     const tableDocs = notes.map((n) => ({
-        // Package present however the note spells it — see
-        // {@link searchableFrontmatter} (#56).
-        fm: searchableFrontmatter(n.fm),
+        // Package present for a `WHERE … package = "…"` clause, synthesised
+        // rather than authored — see {@link searchableFrontmatter} (#56).
+        fm: searchableFrontmatter(n.fm, pkg),
         path: n.rel,
         tld: n.rel.split("/")[0],
         folder: path.dirname(n.rel).split("/").pop(),
@@ -205,9 +207,9 @@ export function buildLinkIndex(
         let body = note.body;
         if (/^[ \t]*(?:`{3,}|~{3,})[ \t]*dataview\b/im.test(body)) {
             body = expandContentTables(body, {
-                docs: tableDocs.filter(
-                    (d) => notePackage(d.fm) === notePackage(note.fm),
-                ),
+                // Unfiltered: every note in the tree is this package's, so
+                // there is no other package's note to exclude (#56).
+                docs: tableDocs,
                 linkable: (d) => Boolean(d.fm.shortcode),
                 source: note.file,
             }).markdown;

package/engine/content-package.mjs

@@ -38,8 +38,9 @@ import { loadPackConfig } from "./pack-config.mjs";
  * `package:` frontmatter and the compilers kept the ones that matched. Every
  * content tree is single-package — each is single-sourced in the repository that
  * ships it — so the field restated this constant once per note while a value
- * that matched nothing filtered the whole tree out in silence. The field is
- * being retired; the value stays, here, where it is declared once.
+ * that matched nothing filtered the whole tree out in silence. That field is
+ * retired and declaring it now fails the build; this value stays, here, where
+ * it is declared once.
  *
  * Stable across compilation targets. If this content were ever compiled for a
  * second game system, it would still be published as `sohl` — only the Foundry

package/engine/field-reference.mjs

@@ -147,8 +147,8 @@ function workedExample(type, fields) {
         `type: ${type}`,
         "shortcode: xmpl",
         // No `package:`. A note's package is the repository's configured
-        // `contentPackage`, so the field is redundant and is being retired
-        // (#56) — and this example is the smallest note that compiles.
+        // `contentPackage`, and declaring the field is a build error (#56) —
+        // this example is the smallest note that compiles.
         "id: <16-character id>",
         "sohl:",
         "  archetype: null",

package/engine/frontmatter-lint.mjs

@@ -51,6 +51,7 @@
 import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
+import { draftRetiredMessage } from "./retired-fields.mjs";
 
 /**
  * `sohl:` keys every type accepts, whatever its schema says.
@@ -211,6 +212,31 @@ export function lintNote(note, { schemas, index }) {
     const at = (key, literal) =>
         positionInFrontmatter(raw(), key, literal ?? undefined);
 
+    // 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
+    // here as well as refused at compile because this is where an author meets
+    // every finding in the tree at once, rather than one note at a time (#56).
+    if (Object.hasOwn(fm, "package")) {
+        findings.push({
+            file: note.file,
+            ...at("package"),
+            severity: "error",
+            message:
+                "`package:` is a retired frontmatter field — delete it. A " +
+                "note's package is this repository's configured " +
+                "`contentPackage`, in package-build.config.yaml, and every " +
+                "note in the tree belongs to it",
+        });
+    }
+    if (Object.hasOwn(fm, "draft")) {
+        findings.push({
+            file: note.file,
+            ...at("draft"),
+            severity: "error",
+            message: draftRetiredMessage(),
+        });
+    }
+
     const replacement = RETIRED_TYPES[type];
     if (replacement) {
         findings.push({

package/engine/helpers.mjs

@@ -36,7 +36,7 @@ import log from "loglevel";
 import { loadPackConfig } from "./pack-config.mjs";
 import { packRouter } from "./pack-router.mjs";
 import { contentPackage, foundryPackageId } from "./content-package.mjs";
-import { notePackage, searchableFrontmatter } from "./note-package.mjs";
+import { searchableFrontmatter } from "./note-package.mjs";
 import { loadForeignManifests, PACKAGE_BASE } from "./kb-manifest.mjs";
 import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
 import { expandContentTables } from "./content-tables.mjs";
@@ -602,8 +602,9 @@ export function collectContentDocs(contentBase) {
         if (!fm) continue;
         const segments = path.relative(contentBase, absPath).split(path.sep);
         docs.push({
-            // With its package present whether the note declares one or not, so
-            // a `WHERE … package = "…"` query reads the same either way (#56).
+            // With its package supplied for a `WHERE … package = "…"` query —
+            // synthesised from the configuration, since no note declares it
+            // (#56).
             fm: searchableFrontmatter(fm),
             // POSIX-separated and relative to the content root — what a
             // `path:` search term globs, on every platform.
@@ -636,17 +637,15 @@ const packLinkable = (doc) =>
  * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
  * are resolved — so a generated cell may itself be a wikilink.
  *
- * A table searches only notes of the source note's own package, so a SoHL page
- * never tabulates setting-package content (and vice versa). Each candidate's
- * package is **derived** rather than read out of its frontmatter: `package:` is
- * optional, and comparing a declared value with an absent one would drop every
- * unswept — or every swept — note from the table (#56).
+ * A table searches the whole tree, which is one package's notes and nothing
+ * else — so there is no longer a package to scope on. It used to filter, back
+ * when a tree could hold several packages' notes and `package:` said which was
+ * which; that field is retired and the filter with it (#56).
  *
  * @param {string} body - The note's markdown body.
  * @param {object} ctx
  * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
  * @param {string} ctx.name - The note, for the error message.
- * @param {string} [ctx.pkg] - The source note's package.
  * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
  *   query's `this` reads. Its entry in `docs` supplies the path as well.
  * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
@@ -659,8 +658,7 @@ const packLinkable = (doc) =>
  *   compile rather than shipping a table-shaped hole. The error carries
  *   `position`, the directive's own line.
  */
-export function expandNoteTables(body, { docs, name, pkg, fm, bodyLine }) {
-    const scoped = pkg ? docs.filter((d) => notePackage(d.fm) === pkg) : docs;
+export function expandNoteTables(body, { docs, name, fm, bodyLine }) {
     const self =
         fm ?
             (docs.find((d) => d.fm?.id && d.fm.id === fm.id) ?? {
@@ -668,7 +666,7 @@ export function expandNoteTables(body, { docs, name, pkg, fm, bodyLine }) {
             })
         :   undefined;
     const { markdown, errors, lineMap } = expandContentTables(body ?? "", {
-        docs: scoped,
+        docs,
         linkable: packLinkable,
         source: name,
         self,

package/engine/homepage.mjs

@@ -0,0 +1,150 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The package homepage — a note that compiles to a **page** rather than to a
+ * compendium document (#51).
+ *
+ * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+ * and what a reader finds there is one markdown file in the content tree,
+ * written by a person: what the module is, which system it needs, how to install
+ * it, where its source lives. Nothing about it is derived.
+ *
+ * **Authored, not assembled.** An earlier sketch generated the page in tiers —
+ * identity and licence from the manifest, install URL from the release address,
+ * "requires" links from `relationships`, a card per configured section. It would
+ * have worked and needed almost no authoring, and it produces a page nobody
+ * chose the contents of. The things that matter most on these pages cannot be
+ * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
+ * setting *is*, which of twenty sections a reader should start with. So the only
+ * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
+ * the package's name is not written twice.
+ *
+ * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
+ * special-cased would be the anomaly: notes are routed by frontmatter, not by
+ * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
+ * map types. `homepage` is one more entry whose compile step emits a page. It is
+ * deliberately not `README.md`: `landing: readme` already means "a `README.md`
+ * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
+ * is a developer explainer about the source tree — adopting that name would make
+ * Thalorna's public front page its build documentation.
+ *
+ * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
+ * knowledge from *game-system* knowledge, and a homepage is note format: it
+ * carries no `system` block, mirrors no item builder, and would mean the same
+ * thing for a game system that is not SoHL. Reachability is the symptom that
+ * makes it obvious — `HarnMaster-3-FoundryVTT` declares no `itemBuilders`, so a
+ * type living in the SoHL registry would be unavailable to HM3 and to every HM3
+ * module, which is most of the packages that need a homepage and nothing else.
+ *
+ * **Its address is the package's, not the note's.** A homepage publishes at
+ * `/<contentPackage>/` because that is where the package is, so `name.full`,
+ * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
+ * module simply never reads them). It compiles into no document, so it carries
+ * no compendium UUID and appears in no pack and in no link-manifest entry.
+ *
+ * @module
+ */
+
+/**
+ * The note type that compiles to the package homepage.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_TYPE = "homepage";
+
+/**
+ * What a homepage note may write under `sohl:` — nothing.
+ *
+ * Empty on purpose, and declared rather than omitted: a type with no vocabulary
+ * and a type that is unknown are different findings, and only the second is an
+ * authoring error. The whole envelope is the two top-level keys `type` and an
+ * optional `title`; there is no game-system data on a page that compiles to no
+ * document.
+ *
+ * @type {readonly import("./field-spec.mjs").FieldSpec[]}
+ */
+export const HOMEPAGE_FIELDS = Object.freeze([]);
+
+/**
+ * Where a homepage is written, relative to the package's site root.
+ *
+ * Hugo's section landing, because the page *is* the package's landing: the
+ * package root is a section and this is its index.
+ *
+ * @type {string}
+ */
+export const HOMEPAGE_DESTINATION = "_index.md";
+
+/**
+ * Whether a note's frontmatter declares the homepage type.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether it is a homepage note.
+ */
+export function isHomepage(fm) {
+    return Boolean(fm) && fm.type === HOMEPAGE_TYPE;
+}
+
+/**
+ * The title a homepage publishes under.
+ *
+ * The one defaulted value on the page, and it defaults to the package's own
+ * `packageBuild.manifest.title` — the name Foundry already shows for the
+ * package — so a homepage that adds nothing to it need not restate it. An
+ * authored `title` wins, because a front page is allowed to greet a reader
+ * differently from a package browser.
+ *
+ * Falls back to `contentPackage` last, so a package that has no manifest of its
+ * own still yields a titled page rather than a blank heading.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {object} config - The resolved configuration.
+ * @returns {string} The title.
+ */
+export function homepageTitle(fm, config) {
+    const authored = fm?.title;
+    if (typeof authored === "string" && authored.trim()) return authored;
+    const manifest = /** @type {Record<string, unknown>|undefined} */ (
+        config?.packageBuild?.manifest
+    );
+    const title = manifest?.title;
+    return typeof title === "string" && title.trim() ?
+            title
+        :   config.contentPackage;
+}
+
+/**
+ * The frontmatter a homepage publishes with.
+ *
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
+ * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * `.Params.package`.
+ *
+ * An authored `aliases` is dropped for the same reason it is on every other
+ * page: Obsidian reads it as names a reader might call the note, Hugo reads it
+ * as URL redirects, and passing it through would publish a redirect stub at
+ * each one.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package this build publishes.
+ * @param {string} options.title - The resolved title.
+ * @returns {object} The frontmatter to write.
+ */
+export function homepageFrontmatter(fm, { contentPackage, title }) {
+    const data = { ...fm, package: contentPackage, title };
+    delete data.aliases;
+    return data;
+}