@heroiclands/package-build 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @heroiclands/package-build
 
+## 5.0.0
+
+### Major Changes
+
+- 4da0dbc: Every package publishes an authored homepage at `/<contentPackage>/`, and
+  `publish.site` becomes a mode rather than a boolean (#51, #55).
+  
+  **A `type: homepage` note (#51)**
+  
+  A new engine-level content type that compiles into a **page** rather than into a
+  compendium document. Its whole frontmatter envelope is `type` and an optional
+  `title`, defaulting to `packageBuild.manifest.title` so the package's name is not
+  written twice:
+  
+  ```markdown
+  ---
+  type: homepage
+  title: HârnMaster Kethira Basic
+  ---
+  
+  What the module is, which system it needs, how to install it.
+  ```
+  
+  It compiles into no document, appears in no pack and in no link manifest, and is
+  addressed by the **package** — `/<contentPackage>/` — rather than by a slug
+  derived from its name, so `name.full`, `shortcode` and `id` decide nothing on it.
+  It is written at the root of `site.out`, one level above the content mount.
+  
+  The page is _authored, not assembled_. Deriving it from the manifest, the release
+  address and `relationships` was the obvious shortcut and produces a page nobody
+  chose the contents of — it cannot express that Kethira requires buying the book
+  from Keléstia, or which of twenty sections a reader should start with.
+  
+  It is declared in `engine/note-schemas.mjs` rather than in the `sohl` item
+  registry: the `engine/` ÷ `sohl/` line is note-format knowledge against
+  game-system knowledge, and a homepage carries no `system` block and mirrors no
+  item builder. Reachability is the symptom that makes it obvious —
+  `HarnMaster-3-FoundryVTT` declares no `itemBuilders` at all, so a type living in
+  the SoHL registry would be unavailable to HM3 and every HM3 module, which is most
+  of the packages that need a homepage and nothing else.
+  
+  **`publish.site` is a mode (#55) — breaking**
+  
+  | Was           | Write                              |
+  | ------------- | ---------------------------------- |
+  | `site: true`  | `site: content`                    |
+  | `site: false` | `site: homepage`                   |
+  | absent        | absent — the default is `homepage` |
+  
+  `homepage` publishes the authored homepage and **no other page**; `content`
+  publishes it plus every page the content tree compiles to. There is no value
+  meaning "no web presence", because every package publishes its homepage.
+  
+  Both booleans are **refused rather than mapped** onto the nearest mode, naming
+  the mode to write. `false` read as _this package has no web presence_, which
+  describes no package now, and a value silently reinterpreted reads to its author
+  as though it still means what it said.
+  
+  **Homepage-only is a first-class mode, not an accommodation.**
+  `sohl-kethira-basic` (Keléstia Productions' Fan Material Guidelines) and
+  `harn-adventures` (HârnFanon under Lythia's terms) 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. Because the failure mode is silent — a `site:` block added later
+  ships licensed content with nobody noticing — the mode **fences the content
+  surfaces off**: in `homepage` mode the tree is never walked for pages, and
+  `sections`, `trees`, `landing` and `backfillSections` emit nothing even when they
+  are declared. Measured against the real `sohl-kethira-basic` tree — 363 notes,
+  and a `site:` block deliberately declaring sections and a landing — the build
+  emits exactly one file.
+  
+  `publish.manifests.publish` is a separate decision and stays `false` for both, for
+  an unrelated reason: a link manifest is the dependency edge that would stop a
+  module being withdrawable, and a homepage is one row in a routing table.
+  
+  **Nothing else moves.** `publish.address`, `publish.manifests` and the whole
+  `site:` block are unchanged, and every address `sohl` already publishes is
+  byte-identical across the upgrade. Verified against the real tree: 1,669 emitted
+  files before, 1,670 after, the one addition being `kb/content/_index.md`; the
+  link manifest's 2,989 entries and all 3,126 compiled pack documents are
+  byte-identical with and without the homepage note.
+
 ## 4.0.0
 
 ### Major Changes

package/CONTENT.md

@@ -128,9 +128,11 @@ packageBuild:
     - { from: assets/icons, to: assets/icons }
 
 # Three independent switches — every combination is real — plus the address
-# scheme both `manifest` and `site` derive addresses under.
+# scheme both `manifest` and `site` derive addresses under. `site` is a mode,
+# not a boolean: `homepage` (the default) publishes the authored homepage and
+# no other page; `content` publishes it plus every page the tree compiles to.
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/
@@ -147,8 +149,8 @@ site:
 
 The loader validates the document, resolves every path against the directory
 the file sits in, fills the optional halves with their defaults
-(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, every
-publishing switch off),
+(`skipDirectories: []`, `packageBuild: {}`, the conventional `paths`, both
+manifest switches off and `publish.site` at its `homepage` floor),
 derives `assetRoot`, `packDirectories`, `itemTypes` and `docEntryTypes`, and
 freezes the result. A malformed configuration throws a `TypeError` naming the
 offending field, so it fails at load rather than as an empty pack much later.
@@ -594,10 +596,11 @@ It reads its whole input from configuration and takes nothing else:
 | `publish.address`           | The address scheme those paths are derived under — see below. |
 
 **Both addresses are optional, independently.** A note that compiles into no
-document has no `uuid`, and a package that ships compendiums and publishes no
-site (`publish.site: false`) has no `path` on any entry. Neither is an error, and
-neither is guessed: inventing the missing one asserts a target that does not
-exist, which is the silent dead link the manifest exists to prevent.
+document has no `uuid`, and a package that ships compendiums and publishes only
+a homepage (`publish.site: homepage`) has no `path` on any entry — its notes are
+not pages. Neither is an error, and neither is guessed: inventing the missing one
+asserts a target that does not exist, which is the silent dead link the manifest
+exists to prevent.
 
 **`publish.manifests.publish` is a declaration, not a preference.** The file is
 vendored by other repositories and read as authoritative, so emitting one is a
@@ -615,7 +618,7 @@ time and 404s for the reader.
 
 ```yaml
 publish:
-  site: true
+  site: content
   manifests: { publish: true, consume: true }
   address:
     prefix: kb/ # default: "" — the package root
@@ -658,6 +661,64 @@ address derivation, the address index, table expansion, wikilink resolution,
 code-fence protection, the foreign-manifest merge, the page emission and the
 section-landing backfill.
 
+### The homepage, and how much else is published
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and what a reader finds there is a note in the content tree — one markdown file,
+written by a person:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+That is the whole envelope. A homepage **compiles into no compendium
+document**, appears in no pack and in no link manifest, and is addressed by the
+_package_ rather than by its own name — so `name.full`, `shortcode` and `id`
+decide nothing on it. It is dispatched on `type` like every other note, not on a
+filename: `README.md` is already a section landing under `landing: readme`, and
+in `sohl-thalorna` it is a developer explainer about the source tree.
+
+`type: homepage` is declared by the **engine**, not by the `sohl` item registry,
+so a package that configures no `itemBuilders` at all — `HarnMaster-3-FoundryVTT`
+and every HM3 module — can author one. The `engine/` ÷ `sohl/` line is
+note-format knowledge against game-system knowledge, and a homepage carries no
+`system` block.
+
+`publish.site` then says how much _else_ is published:
+
+| Mode       | What is published                                                               |
+| ---------- | ------------------------------------------------------------------------------- |
+| `homepage` | The authored homepage, and no other page. **The default, and the floor.**       |
+| `content`  | The homepage plus every page the content tree compiles to, and its extra trees. |
+
+There is no value meaning "no web presence": every package publishes its
+homepage. It was a boolean until 5.0.0, and both spellings are now refused
+naming the mode to write instead — see [MIGRATING.md](MIGRATING.md).
+
+**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. The boundary is _published
+content_ — journal text, artwork, item descriptions, compiled notes — and a page
+announcing the module discloses none of it. Because the failure mode is silent,
+the mode **fences the content surfaces off** rather than trusting a
+configuration to stay empty: in `homepage` mode the tree is never walked for
+pages, and `sections`, `trees`, `landing` and `backfillSections` emit nothing
+even when they are declared.
+
+That is separate from `publish.manifests.publish`, which stays off for both for
+an unrelated reason: a link manifest is the dependency edge that would stop the
+module being withdrawable, and a homepage is one row in a routing table.
+
+The homepage is written at the root of `site.out` — the package's own address —
+one level above the content mount, which is where `publish.address.prefix` puts
+everything else.
+
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the link manifest reads, so a page and its manifest entry cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
@@ -686,7 +747,7 @@ site:
 
 | Key                | What it decides                                                                                  |
 | ------------------ | ------------------------------------------------------------------------------------------------ |
-| `out`              | The Hugo content root. **Required**, and wiped on every run — see the safety note below.         |
+| `out`              | The Hugo content root. **Required** in both modes, and wiped on every run — see below.           |
 | `base`             | Where the package is served. Defaults to `/<contentPackage>/`.                                   |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                   |
 | `sections`         | Landing title and hero per section, so a landing matches the card that links to it.              |

package/MIGRATING.md

@@ -1,3 +1,76 @@
+# Migrating to `@heroiclands/package-build` 5.0.0
+
+**One configuration change: `publish.site` is a mode, not a boolean.** And one
+new authoring capability that needs no migration: a `type: homepage` note.
+
+## 1. Respell `publish.site`
+
+```yaml
+publish:
+  site: content # was `site: true`
+```
+
+```yaml
+publish:
+  site: homepage # was `site: false`, or absent
+```
+
+`homepage` is the default, so a repository that never set the key needs no edit.
+A repository that set it to either boolean gets a `TypeError` at load naming the
+mode to write:
+
+```text
+package-build config: `publish.site` is no longer a boolean — write `site: content`. 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.
+```
+
+Both spellings are **refused rather than mapped** onto the nearest mode. `false`
+read as _this package has no web presence_, which now describes no package at
+all, and a value silently reinterpreted reads to its author as though it still
+means what it said.
+
+Nothing else about publishing moved: `publish.address`, `publish.manifests` and
+the whole `site:` block are unchanged, and every address `sohl` and `thalorna`
+already publish is byte-identical across the upgrade.
+
+## 2. Author a homepage (optional here, required by #52)
+
+Every package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
+and the page there is a note in the content tree:
+
+```markdown
+---
+type: homepage
+title: HârnMaster Kethira Basic # optional; defaults to packageBuild.manifest.title
+---
+
+What the module is, which system it needs, how to install it.
+```
+
+It compiles into no compendium document, appears in no pack and in no link
+manifest, and is addressed by the package rather than by its own name. It is
+written to the root of `site.out`, one level above the content mount.
+
+A repository with no homepage note publishes none, and the site build says so in
+its count. Requiring exactly one is a separate change (#52).
+
+## 3. What homepage-only means
+
+`homepage` mode does not merely leave the content configuration unused — it
+**fences the content surfaces off**. The tree is never walked for pages, and
+`site.sections`, `site.trees`, `site.landing` and `site.backfillSections` emit
+nothing even when they are declared.
+
+That is deliberate, and it is a licensing requirement rather than a preference.
+`sohl-kethira-basic` (Keléstia Productions' Fan Material Guidelines) and
+`harn-adventures` (HârnFanon under Lythia's terms) publish a homepage and no
+other page; the failure mode is silent — a `site:` block added later ships
+licensed content with nobody noticing — so the property is asserted by the code
+path rather than left to configuration.
+
+`publish.manifests.publish` is a separate decision and stays `false` for both: a
+link manifest is the dependency edge that would stop a module being withdrawable,
+and a homepage is not.
+
 # Migrating to `@heroiclands/package-build` 4.0.0
 
 **One authoring change: delete `package:` from every content note.** A note's

package/bin/content-build.mjs

@@ -76,6 +76,9 @@ import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
 // set — an adventure module ships skills, beings and magic swords — so no
 // consumer gets a subset (#19, #20).
 import { NOTE_SCHEMAS } from "../sohl/note-schemas.mjs";
+// The engine's own types, merged under the registry's so the vocabulary stands
+// in a package that configures no `itemBuilders` at all (#51).
+import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { checkFormatting, lintMarkdown } from "../engine/prose-lint.mjs";
 import { emitLinkManifest } from "../engine/manifest-emit.mjs";
 import {
@@ -346,7 +349,7 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
                 const frontmatter = lintFrontmatter(index, {
-                    schemas: NOTE_SCHEMAS,
+                    schemas: { ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS },
                     references: argv.references,
                 });
 
@@ -823,7 +826,8 @@ function siteCommand() {
 
                 const s = result.stats;
                 log.info(
-                    `wrote ${s.content ?? 0} content page(s) + ` +
+                    `wrote ${s.homepages ?? 0} homepage(s) + ` +
+                        `${s.content ?? 0} content page(s) + ` +
                         `${s.tree ?? 0} tree page(s) + ${s.landings} ` +
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );

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/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;
+}

package/engine/index.mjs

@@ -60,6 +60,12 @@ export * as notePackage from "./note-package.mjs";
 /** Frontmatter fields a note may no longer declare, and the refusal of them. */
 export * as retiredFields from "./retired-fields.mjs";
 
+/** The package homepage: the note type that compiles to a page, not a document. */
+export * as homepage from "./homepage.mjs";
+
+/** The note types the engine itself declares, whatever a consumer registers. */
+export * as noteSchemas from "./note-schemas.mjs";
+
 /** The shipped Foundry manifest: locating it, reading it, guarding its id. */
 
 /** The URL a content note is published at — the one web-address rule. */

package/engine/manifest-emit.mjs

@@ -59,6 +59,7 @@ import { assertNoDraftField } from "./retired-fields.mjs";
 import { journalPageId, splitPages } from "./journals.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { publishesContentPages } from "../content-config.mjs";
 
 /**
  * The reserved anchor name for a journal's **first** page.
@@ -271,7 +272,7 @@ export function manifestContext(config = loadPackConfig()) {
         foundryPackageId: config.foundryPackage,
         packRouter: routerFor(config),
         scheme: config.publish.address,
-        web: config.publish.site,
+        web: publishesContentPages(config),
         // The walk's own configuration, threaded through rather than left to
         // its default, so a caller that passes a config drives every read.
         skipDirectories: config.skipDirectories,

package/engine/note-schemas.mjs

@@ -0,0 +1,44 @@
+/*
+ * 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 note types the **engine** declares — the ones whose vocabulary is a fact
+ * about the note format rather than about any game system (#51).
+ *
+ * `sohl/note-schemas.mjs` is the other half, and the line between them is the
+ * `engine/` ÷ `sohl/` line everywhere else in this package: note-format
+ * knowledge here, game-system knowledge there. It is not a permission boundary
+ * between consumers — every content project authors the full vocabulary — but it
+ * is a reachability one in exactly one direction. A package that declares no
+ * `itemBuilders` (`HarnMaster-3-FoundryVTT`, and every HM3 module) uses only the
+ * packaging half of the toolchain, so a type declared in the SoHL registry would
+ * be unavailable to it. These are the types every package has, whatever it
+ * ships.
+ *
+ * One entry today. A consumer merges it under its own registry —
+ * `{ ...ENGINE_NOTE_SCHEMAS, ...NOTE_SCHEMAS }` — so a game system may extend
+ * these but the engine's declaration stands wherever no registry is configured.
+ *
+ * @module
+ */
+
+import { HOMEPAGE_FIELDS, HOMEPAGE_TYPE } from "./homepage.mjs";
+
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS = Object.freeze({
+    [HOMEPAGE_TYPE]: HOMEPAGE_FIELDS,
+});

package/engine/site-build.mjs

@@ -63,6 +63,13 @@ import {
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
+import {
+    HOMEPAGE_DESTINATION,
+    homepageFrontmatter,
+    homepageTitle,
+    isHomepage,
+} from "./homepage.mjs";
+import { publishesContentPages } from "../content-config.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -137,6 +144,10 @@ export function collectContentPages(contentBase, ctx) {
         // (#56).
         const pkg = ctx.contentPackage;
         if (!ctx.packages.has(pkg) || !fm.type) continue;
+        // A homepage is addressed by the *package*, not by its own name, so it
+        // never takes a section and a slug (#51). {@link collectHomepages}
+        // gathers it instead.
+        if (isHomepage(fm)) continue;
 
         for (const hit of frontmatterWikilinks(fm)) {
             fmLinkFindings.push({ file, ...hit });
@@ -249,6 +260,62 @@ export function collectTreePages(tree, ctx) {
     return { pages, fmLinkFindings };
 }
 
+/**
+ * The package's homepage notes — the authored page at `/<contentPackage>/`.
+ *
+ * A separate walk from {@link collectContentPages} rather than a branch inside
+ * it, because in homepage-only mode it is the **whole** of the site build: the
+ * content tree is never read for pages at all, so the licensing constraint two
+ * packages ship under is a property of the code path rather than of a
+ * configuration that happens to be empty (#55).
+ *
+ * Returned as a list rather than as the one note there should be. Requiring
+ * exactly one is #52's, and it is a separate decision — this reports what it
+ * found so a count is visible either way.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ skipDirectories }`.
+ * @returns {{pages: object[]}} The homepage notes, in walk order.
+ */
+export function collectHomepages(contentBase, ctx) {
+    const pages = [];
+    for (const file of walkSiteTree(contentBase, ctx.skipDirectories)) {
+        const note = readNote(file);
+        if (!note || !isHomepage(note.fm)) continue;
+        pages.push({ kind: "homepage", file, fm: note.fm, body: note.body });
+    }
+    return { pages };
+}
+
+/**
+ * Writes each homepage at the package's own root.
+ *
+ * Its own writer, deliberately small. A homepage is authored markdown published
+ * verbatim — no table expansion, no section landing, and (until #54) no link
+ * resolution — so routing it through {@link renderPages} would buy it a pipeline
+ * it has no input for, and would make homepage-only mode depend on the index,
+ * the foreign manifests and the table universe that mode exists to not build.
+ *
+ * @param {string} outRoot - The package's site root — the configured `site.out`,
+ *   one level above the content mount.
+ * @param {readonly object[]} pages - From {@link collectHomepages}.
+ * @param {object} config - The resolved configuration, for the package name and
+ *   the default title.
+ * @returns {number} How many pages were written.
+ */
+export function writeHomepages(outRoot, pages, config) {
+    for (const page of pages) {
+        const data = homepageFrontmatter(page.fm, {
+            contentPackage: config.contentPackage,
+            title: homepageTitle(page.fm, config),
+        });
+        const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, matter.stringify(page.body, data));
+    }
+    return pages.length;
+}
+
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -318,6 +385,30 @@ export function siteGates(pages, findings, { manifestDir }) {
     return out;
 }
 
+/**
+ * The gate result of a build that ran none of them.
+ *
+ * Homepage-only publishes one authored page and resolves nothing, so every gate
+ * here is about a surface that mode does not have. The shape is returned all the
+ * same, because a caller reads the same fields whichever mode ran and a `null`
+ * would make each of them a special case.
+ *
+ * @returns {object} An all-clear gate result.
+ */
+export function emptyGates() {
+    return {
+        frontmatterLinks: [],
+        slugErrors: [],
+        collisions: [],
+        staleManifests: [],
+        unaddressable: [],
+        conflicts: [],
+        index: null,
+        foreign: null,
+        manifests: null,
+    };
+}
+
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates) {
     return Boolean(
@@ -706,6 +797,10 @@ export function buildSite({ config, outRoot } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
+    // Homepage-only or homepage-plus-content (#55). The floor is the homepage,
+    // so this decides whether the *content* surfaces are published, never
+    // whether anything is.
+    const publishesContent = publishesContentPages(resolved);
 
     // Where the package is served, and where its content mounts inside it. The
     // two are separate facts: `base` is the package's own address on the site
@@ -722,9 +817,16 @@ export function buildSite({ config, outRoot } = {}) {
     // directory it was launched from (#1508).
     const outBase = resolveOutputRoot(resolved.rootDir, site.out);
     const out =
-        outRoot ?
-            path.resolve(outRoot)
-        :   path.join(outBase, scheme.prefix.replace(/\/$/, ""));
+        outRoot ? path.resolve(outRoot)
+        : publishesContent ?
+            path.join(outBase, scheme.prefix.replace(/\/$/, ""))
+            // Homepage-only has no content mount, so the package's root *is*
+            // the output root and `--out` redirects the whole of it.
+        :   outBase;
+    // The homepage publishes at `/<contentPackage>/`, which is the package's
+    // own root — one level above the content mount, and the same directory in
+    // homepage-only mode.
+    const homeRoot = publishesContent ? outBase : out;
 
     const packages = new Set(
         site.packages.length ? site.packages : [resolved.contentPackage],
@@ -744,6 +846,25 @@ export function buildSite({ config, outRoot } = {}) {
     // note was deleted or renamed would otherwise linger and keep publishing.
     fs.rmSync(outBase, { recursive: true, force: true });
 
+    const homepages = collectHomepages(resolved.paths.content, ctx).pages;
+
+    // Homepage-only stops here, and stopping is the point: nothing below reads
+    // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
+    // cannot publish one whatever else their `site:` block declares (#55).
+    if (!publishesContent) {
+        return {
+            gates: emptyGates(),
+            manifests: null,
+            tableErrors: [],
+            wikiErrors: [],
+            stats: {
+                homepages: writeHomepages(homeRoot, homepages, resolved),
+                landings: 0,
+                out: homeRoot,
+            },
+        };
+    }
+
     const content = collectContentPages(resolved.paths.content, ctx);
     const pages = [...content.pages];
     const fmLinkFindings = [...content.fmLinkFindings];
@@ -804,12 +925,21 @@ export function buildSite({ config, outRoot } = {}) {
         sectionTitle: site.backfillSections ? pluralTitle : null,
     });
 
+    // 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);
+
     return {
         gates,
         manifests: gates.manifests,
         tableErrors: rendered.tableErrors,
         wikiErrors: rendered.wikiErrors,
-        stats: { ...rendered.byKind, landings, out },
+        stats: {
+            ...rendered.byKind,
+            homepages: homepagesWritten,
+            landings,
+            out,
+        },
     };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "4.0.0",
+    "version": "5.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/note-schemas.mjs

@@ -38,6 +38,7 @@
  */
 
 import { AS_AUTHORED, NUMBER, STRING } from "../engine/field-spec.mjs";
+import { ENGINE_NOTE_SCHEMAS } from "../engine/note-schemas.mjs";
 import { ITEM_FIELDS } from "./item-fields.mjs";
 
 /** A map-valued property, whose entries the compiler walks by key. */
@@ -302,9 +303,16 @@ const PRESENTATION_FIELDS = Object.freeze({
  * Every content type this package compiles, and what a note of that type may
  * write.
  *
+ * The engine's own types are merged in first, so a SoHL tree is checked against
+ * one vocabulary rather than two. They are declared there rather than here
+ * because they are note-format knowledge — a `homepage` carries no `system`
+ * block and would mean the same thing for a game system that is not SoHL — and
+ * because a package declaring no `itemBuilders` never reaches this file (#51).
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const NOTE_SCHEMAS = Object.freeze({
+    ...ENGINE_NOTE_SCHEMAS,
     ...Object.fromEntries(
         Object.entries(ITEM_FIELDS).map(([type, fields]) => [
             type,

package/types/content-config.d.mts

@@ -1,3 +1,19 @@
+/**
+ * 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: {
+    publish: {
+        site: SiteMode;
+    };
+}): boolean;
 /**
  * Validate and normalize a content configuration.
  *
@@ -76,6 +92,77 @@ export const DEFAULT_ADDRESS_SCHEME: Readonly<{
     prefix: "";
     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: readonly ["homepage", "content"];
+/**
+ * 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.
+ */
+export type SiteMode = "homepage" | "content";
 export type PackageKind = "systems" | "modules";
 export type PackDocumentType = "Actor" | "Adventure" | "Item" | "JournalEntry" | "Macro" | "Scene";
 /**
@@ -272,9 +359,10 @@ export type ManifestSwitches = {
 };
 export type PublishSwitches = {
     /**
-     * Render this package's knowledgebase/site pages.
+     * How much of this package reaches the web.
+     * See {@link SITE_MODES}.
      */
-    site: boolean;
+    site: SiteMode;
     manifests: ManifestSwitches;
 };
 export type ManifestSwitchesInput = {
@@ -394,8 +482,19 @@ export type DocsSpec = {
     itemFields?: DocPageSpec | undefined;
 };
 export type PublishSwitchesInput = {
-    site?: boolean | undefined;
+    site?: SiteMode | undefined;
     manifests?: ManifestSwitchesInput | undefined;
+    address?: AddressSchemeInput | undefined;
+};
+export type AddressSchemeInput = {
+    /**
+     * Where the content tree mounts inside the package.
+     */
+    prefix?: string | undefined;
+    /**
+     * Which note addresses a whole section.
+     */
+    landing?: string | undefined;
 };
 /**
  * One entry of a consumer's `itemBuilders` registry.
@@ -502,7 +601,9 @@ export type ContentBuildConfigInput = {
      */
     relationships?: Relationships | undefined;
     /**
-     * Publishing switches. Each defaults to off.
+     * Publishing switches. The manifest
+     * switches default to off; `site`
+     * defaults to `homepage`, the floor.
      */
     publish?: PublishSwitchesInput | undefined;
 };

package/types/engine/homepage.d.mts

@@ -0,0 +1,118 @@
+/**
+ * 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: object | null | undefined): boolean;
+/**
+ * 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: object | null | undefined, config: object): string;
+/**
+ * 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: object, { contentPackage, title }: {
+    contentPackage: string;
+    title: string;
+}): object;
+/**
+ * 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: string;
+/**
+ * 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: readonly import("./field-spec.mjs").FieldSpec[];
+/**
+ * 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: string;

package/types/engine/index.d.mts

@@ -7,6 +7,8 @@ export * as packRouter from "./pack-router.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
+export * as homepage from "./homepage.mjs";
+export * as noteSchemas from "./note-schemas.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";

package/types/engine/note-schemas.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Every engine-level content type, and what a note of that type may write.
+ *
+ * @type {Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>}
+ */
+export const ENGINE_NOTE_SCHEMAS: Readonly<Record<string, readonly import("./field-spec.mjs").FieldSpec[]>>;

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

@@ -41,6 +41,43 @@ export function collectTreePages(tree: object, ctx: object): {
     pages: object[];
     fmLinkFindings: object[];
 };
+/**
+ * The package's homepage notes — the authored page at `/<contentPackage>/`.
+ *
+ * A separate walk from {@link collectContentPages} rather than a branch inside
+ * it, because in homepage-only mode it is the **whole** of the site build: the
+ * content tree is never read for pages at all, so the licensing constraint two
+ * packages ship under is a property of the code path rather than of a
+ * configuration that happens to be empty (#55).
+ *
+ * Returned as a list rather than as the one note there should be. Requiring
+ * exactly one is #52's, and it is a separate decision — this reports what it
+ * found so a count is visible either way.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ skipDirectories }`.
+ * @returns {{pages: object[]}} The homepage notes, in walk order.
+ */
+export function collectHomepages(contentBase: string, ctx: object): {
+    pages: object[];
+};
+/**
+ * Writes each homepage at the package's own root.
+ *
+ * Its own writer, deliberately small. A homepage is authored markdown published
+ * verbatim — no table expansion, no section landing, and (until #54) no link
+ * resolution — so routing it through {@link renderPages} would buy it a pipeline
+ * it has no input for, and would make homepage-only mode depend on the index,
+ * the foreign manifests and the table universe that mode exists to not build.
+ *
+ * @param {string} outRoot - The package's site root — the configured `site.out`,
+ *   one level above the content mount.
+ * @param {readonly object[]} pages - From {@link collectHomepages}.
+ * @param {object} config - The resolved configuration, for the package name and
+ *   the default title.
+ * @returns {number} How many pages were written.
+ */
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -63,6 +100,17 @@ export function collectTreePages(tree: object, ctx: object): {
  * @returns {object} The gate results and, when they pass, the built index.
  */
 export function siteGates(pages: object[], findings: object, { manifestDir }: object): object;
+/**
+ * The gate result of a build that ran none of them.
+ *
+ * Homepage-only publishes one authored page and resolves nothing, so every gate
+ * here is about a surface that mode does not have. The shape is returned all the
+ * same, because a caller reads the same fields whichever mode ran and a `null`
+ * would make each of them a special case.
+ *
+ * @returns {object} An all-clear gate result.
+ */
+export function emptyGates(): object;
 /** Whether any gate produced a finding. */
 export function gatesFailed(gates: any): boolean;
 /**

package/types/sohl/note-schemas.d.mts

@@ -2,6 +2,12 @@
  * Every content type this package compiles, and what a note of that type may
  * write.
  *
+ * The engine's own types are merged in first, so a SoHL tree is checked against
+ * one vocabulary rather than two. They are declared there rather than here
+ * because they are note-format knowledge — a `homepage` carries no `system`
+ * block and would mean the same thing for a game system that is not SoHL — and
+ * because a package declaring no `itemBuilders` never reaches this file (#51).
+ *
  * @type {Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>}
  */
 export const NOTE_SCHEMAS: Readonly<Record<string, readonly import("../engine/field-spec.mjs").FieldSpec[]>>;