@heroiclands/package-build 22.3.0 → 22.4.0

package/bin/content-build.mjs

@@ -80,7 +80,7 @@ import {
     formatUnaddressableFinding,
 } from "../engine/metadata-index.mjs";
 import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
-import { renderItemFieldReference } from "../engine/field-reference.mjs";
+import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
@@ -284,6 +284,14 @@ const argv = yargs(hideBin(process.argv))
  * second implementation of the comparison. Staleness is a property of the whole
  * generated file, so there is no line to name.
  *
+ * **A destination under the content tree gets a note envelope**, so the walk
+ * that collects every note by its `type:` picks this one up too, rather than
+ * silently dropping it — `type: doc`, `subType: reference`, a `shortcode`
+ * derived from the destination's basename, `name.full` from the title, and
+ * `pack: none`; `docs.itemFields.frontmatter` deep-merges over it. `--check`
+ * compares the whole file, envelope included. A destination outside the
+ * content tree gets the page body alone, as before.
+ *
  * `--out` and `--title` still override, for a one-off render.
  *
  * @returns {object} The yargs command module.
@@ -332,13 +340,27 @@ function docsCommand() {
                 const spec = config.docs?.itemFields ?? {};
                 const destination =
                     argv.out ?? (spec.out ? path.resolve(config.rootDir, spec.out) : null);
+                const pageTitle = title ?? spec.title ?? "Item Note Frontmatter";
 
-                const page = `${renderItemFieldReference({
-                    ...((title ?? spec.title) ? { title: title ?? spec.title } : {}),
+                const body = `${renderItemFieldReference({
+                    title: pageTitle,
                     ...(spec.preamble ? { preamble: spec.preamble } : {}),
                     generatedBy: "`content-build docs item-fields`",
                     config,
                 })}\n`;
+                // A page filed under the content tree is walked for its
+                // `type:` like any other note, so it needs the envelope; one
+                // filed anywhere else — a repository's own `docs/` — is not,
+                // and gets exactly the body it always did.
+                const page =
+                    destination ?
+                        renderItemFieldsPage(body, {
+                            title: pageTitle,
+                            destination,
+                            contentRoot: config.paths.content,
+                            frontmatter: spec.frontmatter,
+                        })
+                    :   body;
 
                 if (check) {
                     if (!destination) {
@@ -1484,18 +1506,17 @@ function pdfCommand() {
  * The sibling of `package compile`: the same tree, rendered as pages instead of
  * compiled into packs. Everything a consumer would otherwise write for itself —
  * the walk, the address derivation, the address index, table expansion,
- * wikilink resolution, code-fence protection, the foreign-manifest merge and
- * the section-landing backfill — happens here, from configuration. So does the
- * Hugo configuration: the whole source tree Hugo reads lands under
- * `build/hugo/`, and the consumer's script runs Hugo over it.
+ * wikilink resolution, code-fence protection and the foreign-manifest merge —
+ * happens here, from configuration. So does the Hugo configuration: the whole
+ * source tree Hugo reads lands under `build/hugo/`, and the consumer's script
+ * runs Hugo over it.
  *
  * **The Hugo configuration is generated before anything is written.** Its
  * sources — `package.json`'s `homepage`, the cached navigation, the installed
  * theme — are each a way the build can fail, and failing before the output
- * tree is cleared leaves the last good site in place to be looked at. It is
- * generated again once the site walk completes, because whether the site
- * emits taxonomy pages is read from the walk — whether any note carries
- * `tags:` — and that is not known until then.
+ * tree is cleared leaves the last good site in place to be looked at. Nothing
+ * the walk reads changes it: a site renders its homepage and its pages, and
+ * the kinds Hugo disables are the same on every site.
  *
  * **Each gate is reported and the run stops at the first that fires.** They are
  * ordered so the report names the cause rather than its symptoms: an unusable
@@ -1513,14 +1534,12 @@ function siteCommand() {
         handler: async () => {
             try {
                 const config = loadPackConfig();
-                // Generated once before the walk, purely to fail fast on a
-                // missing or mismatched source — `homepage`, the manifest
-                // title, the cached navigation, the installed theme — while
-                // the last good site is still in place to be looked at. Its
-                // `disableKinds`/`taxonomies`/`outputs` are provisional: only
-                // the site walk below knows whether any note carries `tags:`,
-                // so the value actually written is regenerated after it runs.
-                generateHugoConfig(config);
+                // Generated before the walk, to fail fast on a missing or
+                // mismatched source — `homepage`, the manifest title, the
+                // cached navigation, the installed theme — while the last
+                // good site is still in place to be looked at. Written only
+                // once the walk has succeeded.
+                const hugo = generateHugoConfig(config);
                 const result = buildSite({
                     config,
                     sqlTables: await prepareTreeSqlTables(config.paths.content, {
@@ -1631,11 +1650,9 @@ function siteCommand() {
                 const s = result.stats;
                 log.info(
                     `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)}`,
+                        `${s.content ?? 0} content page(s) to ` +
+                        `${path.relative(process.cwd(), s.out)}`,
                 );
-                const hugo = generateHugoConfig(config, { hasTags: result.hasTags });
                 const { file } = writeHugoConfig(config, hugo);
                 log.info(`wrote ${path.relative(process.cwd(), file)}`);
             } catch (err) {

package/bin/package-build.mjs

@@ -455,15 +455,16 @@ function manifestCommand() {
  * `package-build site-root` — the deployment's root files.
  *
  * Hugo owns everything under the `/<package>/` prefix; this owns what sits
- * beside it, which is the pair Cloudflare Pages reads from the uploaded
- * directory and nowhere else.
+ * beside it, which is what Cloudflare Pages reads from the uploaded directory
+ * and nowhere else: `_headers`, and no `_redirects`, since the prefix root is
+ * the homepage.
  *
  * @returns {object} The yargs command.
  */
 function siteRootCommand() {
     return {
         command: "site-root",
-        describe: "Write the deployment's _headers and _redirects",
+        describe: "Write the deployment's _headers",
         builder: (y) =>
             y.option("out", {
                 type: "string",

package/content-config.mjs

@@ -256,10 +256,9 @@ export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
  * and the default.
  *
  * - `homepage` — the authored homepage, and **no other page**. The content tree
- *   is not walked for pages, `site.sections` / `site.landing` emit nothing,
- *   and nothing serves a page for its addresses.
- * - `content` — the homepage *plus* every page the content tree publishes: the
- *   knowledgebase and the section landings.
+ *   is not walked for pages, and nothing serves a page for its addresses.
+ * - `content` — the homepage *plus* every page the content tree publishes, one
+ *   per note.
  *
  * **Homepage-only is a first-class mode, not an accommodation.**
  * `sohl-kethira-basic` (unofficial Hârn fan material under Keléstia Productions'
@@ -528,6 +527,11 @@ export function publishesContentPages(config) {
  *                                 Without it the page goes to stdout.
  * @property {string[]} [preamble] Lines between the generated banner and the
  *                                 first table. Markdown, emitted verbatim.
+ * @property {Record<string, unknown>} [frontmatter] Further note frontmatter,
+ *                                 deep-merged over the generated envelope
+ *                                 (`type: doc`, `subType: reference`,
+ *                                 `shortcode`, `name.full`, `pack: none`)
+ *                                 when `out` is under the content tree.
  */
 
 /**
@@ -761,23 +765,17 @@ const SITE_KEYS = [
     "assets",
     "description",
     "packages",
-    "sections",
-    "landing",
     "pass",
     "passOptions",
-    "backfillSections",
-    "list",
     "notfound",
     "hugo",
 ];
-const SITE_LIST_KEYS = ["shortcodes"];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
 const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "iconFonts", "binary"];
 const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
-const SECTION_META_KEYS = ["title", "banner", "description", "listType", "listSubType"];
-const DOC_PAGE_KEYS = ["title", "out", "preamble"];
+const DOC_PAGE_KEYS = ["title", "out", "preamble", "frontmatter"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
 const RELATIONSHIP_KEYS = [
     "id",
@@ -1435,6 +1433,12 @@ function normalizeDocPage(value, where) {
             }),
         );
     }
+    if (input.frontmatter !== undefined) {
+        if (!isPlainObject(input.frontmatter)) {
+            fail(`${where}.frontmatter`, "must be a mapping");
+        }
+        out.frontmatter = deepFreeze({ .../** @type {object} */ (input.frontmatter) });
+    }
     return Object.freeze(out);
 }
 
@@ -1454,102 +1458,6 @@ function normalizeDocs(value) {
     });
 }
 
-/**
- * One section's landing metadata — what a section says about itself on the
- * `_index.md` this build generates for it.
- *
- * A generated landing is the *only* place a section can speak, and it
- * is the only place a section **exists**: a content page is addressed
- * `(type, shortcode)` and written flat under the mount, so no page creates a
- * directory and nothing else makes `<prefix><section>/` answer. This is
- * therefore the whole vocabulary, and it is deliberately a **closed** one.
- *
- * The alternative — passing whatever a section declared straight through, as
- * `site.landing` does — was weighed and refused. `landing` is written once, for
- * the mount, and its keys are one landing template's own; a section entry is
- * written fourteen to twenty times per build against a contract every package
- * and every section shares. Unbounded there, a mistyped `descrption:` publishes
- * into front matter, is read by nobody, and says nothing to anyone — which is
- * the same failure, moved one step downstream where no build can
- * see it. So the keys are named here, and the writers emit what this produced
- * rather than transcribing a second list of their own.
- *
- * `banner` and `description` are optional — the hero images are external assets
- * and not every section has one, and a section may reasonably have nothing to
- * add to its title. Each is left off entirely rather than written as
- * `undefined`, which is not a value YAML can carry.
- *
- * **`listType` / `listSubType` say what the section lists.** A section's
- * directory holds nothing but the `_index.md` written here, so a layout
- * reading Hugo's `.Pages` finds
- * no members and renders an empty landing. The membership survives in this map
- * and nowhere a theme can reach it, so the landing states it and a layout
- * substitutes the equivalent `site.RegularPages` query — the same one `sohl`'s
- * catalog layouts already run, which is why `sohl`'s landings never broke.
- *
- * They are two keys of their own rather than `type` / `subType` because `type`
- * on an `_index.md` is **Hugo's own layout selector**: verified against Hugo
- * 0.165, a section landing carrying `type: doc` renders through
- * `layouts/doc/list.html` rather than the default list template, so spelling
- * the content type there would silently change which template serves the
- * landing. (This build already uses that behaviour deliberately, for the
- * mount's own landing.)
- *
- * Both are checked as **address segments**, which is the trap this came from:
- * a section is named for the URL a consumer chose and a subType is an address
- * segment, and the two need not agree — `/sohl/kb/user-guide/` is the section,
- * `userguide` the subType. Copying the section's name into the
- * declaration would select no page at all, and an empty landing reported by
- * nobody is the failure being fixed. A `listSubType` with no `listType` is
- * refused for the same reason: a subType is only distinguishing *within* a
- * type — `rules`, `userguide` and `reference` are all `doc` — so alone it names
- * no query.
- *
- * @param {unknown} value - The declared entry.
- * @param {string} where - Dotted path, for the error.
- * @returns {Readonly<{title: string, banner?: string, description?: string,
- *   listType?: string, listSubType?: string}>}
- */
-function normalizeSectionMeta(value, where) {
-    if (!isPlainObject(value)) fail(where, "must be a mapping");
-    const input = /** @type {Record<string, unknown>} */ (value);
-    rejectUnknownKeys(input, SECTION_META_KEYS, `${where}.`);
-    const out = { title: requireNonEmptyString(input.title, `${where}.title`) };
-    if (input.banner !== undefined) {
-        out.banner = requireNonEmptyString(input.banner, `${where}.banner`);
-    }
-    if (input.description !== undefined) {
-        out.description = requireNonEmptyString(input.description, `${where}.description`);
-    }
-    for (const key of ["listType", "listSubType"]) {
-        if (input[key] === undefined) continue;
-        const segment = requireNonEmptyString(input[key], `${where}.${key}`);
-        if (!isAddressSegment(segment)) {
-            fail(
-                `${where}.${key}`,
-                `is \`${segment}\`, which is not lowercase alphanumeric. It names a ` +
-                    "content type or subType, and those are address segments " +
-                    `(${ADDRESS_SEGMENT_PATTERN.source}) — not the section's ` +
-                    "own name, which is a URL this site chose and need not " +
-                    "match (`user-guide` is the section, `userguide` the " +
-                    "subType). A value no page carries selects nothing and " +
-                    "leaves the landing empty",
-            );
-        }
-        out[key] = segment;
-    }
-    if (out.listSubType !== undefined && out.listType === undefined) {
-        fail(
-            `${where}.listSubType`,
-            "is declared without a `listType`. A subType tells pages apart " +
-                "only within a type — `rules`, `userguide` and `reference` " +
-                "are all `doc` — so on its own it names no query for a layout " +
-                "to run",
-        );
-    }
-    return Object.freeze(out);
-}
-
 /**
  * The asset host the website resolves a pathname against.
  *
@@ -1609,23 +1517,6 @@ function normalizeSiteDescription(value) {
     return description;
 }
 
-/**
- * A map of section name → landing metadata.
- *
- * @param {unknown} value - The declared mapping.
- * @param {string} where - Dotted path, for the error.
- * @returns {Readonly<Record<string, object>>}
- */
-function normalizeSectionMap(value, where) {
-    if (value === undefined) return Object.freeze({});
-    if (!isPlainObject(value)) fail(where, "must be a mapping");
-    const out = {};
-    for (const [name, meta] of Object.entries(/** @type {Record<string, unknown>} */ (value))) {
-        out[name] = normalizeSectionMeta(meta, `${where}.${name}`);
-    }
-    return Object.freeze(out);
-}
-
 /**
  * Hugo keys a repository may **not** declare under `site.hugo`, because the
  * site build generates them and would only overwrite what was written.
@@ -1647,35 +1538,24 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     contentDir: "the fixed content mount, `build/hugo/content`",
     themesDir: "where `@heroiclands/hugo-theme` is installed",
     theme: "the installed `@heroiclands/hugo-theme`",
-    disableKinds: "whether any note in the tree carries `tags:`, which the site walk discovers",
-    taxonomies: "whether any note in the tree carries `tags:`, which the site walk discovers",
-    outputs: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    disableKinds:
+        "the toolchain, which renders a site as its homepage and its pages: " +
+        "`section`, `taxonomy`, `term` and `RSS` are disabled on every site",
+    taxonomies:
+        "the toolchain, which renders a site as its homepage and its pages: no " +
+        "taxonomy is declared, because `taxonomy` and `term` are disabled kinds",
+    outputs:
+        "the toolchain, which renders a site as its homepage and its pages: no " +
+        "output format is declared, because every listing kind is disabled",
     "params.description": "`site.description`",
     "params.author": "package.json `author`",
     "params.cdnBaseURL": "`site.assets`",
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
-    "params.list": "`site.list`",
     "params.notfound": "`site.notfound`",
     "markup.goldmark.renderer.unsafe": "the toolchain, whose pages carry raw HTML",
     menu: "the navigation `content-build deps fetch` caches from heroiclands.org",
 });
 
-/**
- * The `site.list` block — how a listing page renders.
- *
- * @param {unknown} value - The block, or `undefined`.
- * @returns {Readonly<{shortcodes: boolean}>} It, frozen, with every default filled.
- */
-function normalizeSiteList(value) {
-    if (value === undefined) return Object.freeze({ shortcodes: false });
-    if (!isPlainObject(value)) fail("site.list", "must be a mapping");
-    const input = /** @type {Record<string, unknown>} */ (value);
-    rejectUnknownKeys(input, SITE_LIST_KEYS, "site.list.");
-    return Object.freeze({
-        shortcodes: optionalBoolean(input.shortcodes, "site.list.shortcodes", false),
-    });
-}
-
 /**
  * The `site.notfound` block — the wording of the "page not found" page.
  *
@@ -1753,25 +1633,59 @@ function normalizeSiteHugo(value) {
     return Object.freeze(structuredClone(input));
 }
 
+/**
+ * The keys that asked the site build to write an index between the homepage
+ * and the pages, each refused with the one message.
+ *
+ * A site is its homepage and its pages. Each of these keys asks for a
+ * generated listing between them — `sections` (with `listType` and
+ * `listSubType` inside an entry) a type-wide alphabetical one per entry,
+ * `backfillSections` one for every other directory under the mount, `landing`
+ * the mount's own, `list` how such a listing renders. None of those is a page
+ * anyone chose the contents of, and every one of them is authored instead: a
+ * `doc` note, addressed by its shortcode, carrying a content table over the
+ * notes it introduces, with the columns it chooses.
+ *
+ * Refused rather than ignored, for the reason {@link RETIRED_ADDRESS_KEYS}
+ * gives: a key left ignored reads to its author as though it still works.
+ *
+ * @type {readonly string[]}
+ */
+const SITE_INDEX_KEYS = Object.freeze(["sections", "landing", "backfillSections", "list"]);
+
+/**
+ * The message every key in {@link SITE_INDEX_KEYS} is refused with.
+ *
+ * @type {string}
+ */
+const SITE_INDEX_MESSAGE =
+    "is retired — a site is its homepage and its pages, and any index between " +
+    "them is a `doc` note: write one with `type: doc`, a `shortcode` and " +
+    "`pack: none`, carrying a content table over the notes it lists, and link " +
+    "it from the homepage. Nothing is generated between the homepage and the " +
+    "pages, so delete the key";
+
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
- * Everything here is *framing*: what a section is called, which named pass
- * bundle supplies the repository's own body rewrites, and the residue of the
- * generated Hugo configuration that is genuinely this repository's own. Where
- * the Hugo tree is written is not a choice: `content-build site` writes it
- * under `build/hugo/`, and a `site.out` is refused by name. How a page gets
- * its **address** is deliberately not here either — that is
- * `publish.address`, shared with the link manifest so the two cannot disagree
- * about where a page is.
- *
- * **What the site publishes is the content tree, and nothing beside it.** A
- * page of documentation is a note — `type: doc`, addressed by its shortcode,
- * compiling into no document where it says `pack: none` — so there is no
- * second mechanism for mounting a directory of markdown, and a configuration
- * that names one (`site.trees`, and the `site.readmeSections` that titled
- * such a tree's landing) is refused with a message saying where the page
- * goes instead.
+ * Everything here is *framing*: which named pass bundle supplies the
+ * repository's own body rewrites, and the residue of the generated Hugo
+ * configuration that is genuinely this repository's own. Where the Hugo tree
+ * is written is not a choice: `content-build site` writes it under
+ * `build/hugo/`, and a `site.out` is refused by name. How a page gets its
+ * **address** is deliberately not here either — that is `publish.address`,
+ * shared with the link manifest so the two cannot disagree about where a
+ * page is.
+ *
+ * **What the site publishes is the homepage and the content tree, and nothing
+ * beside them.** A page of documentation is a note — `type: doc`, addressed
+ * by its shortcode, compiling into no document where it says `pack: none` —
+ * so there is no second mechanism for mounting a directory of markdown, and a
+ * configuration that names one (`site.trees`, and the `site.readmeSections`
+ * that titled such a tree's landing) is refused with a message saying where
+ * the page goes instead. An index between the homepage and the pages is a
+ * `doc` note too, so the keys that asked the build to generate one
+ * ({@link SITE_INDEX_KEYS}) are refused the same way.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
@@ -1782,12 +1696,8 @@ function normalizeSite(value) {
         assets: "",
         description: "",
         packages: Object.freeze([]),
-        sections: Object.freeze({}),
-        landing: null,
         pass: "",
         passOptions: Object.freeze({}),
-        backfillSections: false,
-        list: Object.freeze({ shortcodes: false }),
         notfound: null,
         hugo: Object.freeze({}),
     });
@@ -1813,10 +1723,16 @@ function normalizeSite(value) {
             `site.${key}`,
             "is retired — a page is a note in the content tree. Give each page " +
                 "`type: doc`, a `shortcode` and `pack: none`, file it under " +
-                "`assets/content/`, and declare the section that lists it under " +
-                "`site.sections`",
+                "`assets/content/`, and link it from the homepage or from a " +
+                "`doc` note that indexes it",
         );
     }
+    // And by name, for the same reason: an index between the homepage and
+    // the pages is a `doc` note, and the useful thing to say is that.
+    for (const key of SITE_INDEX_KEYS) {
+        if (input[key] === undefined) continue;
+        fail(`site.${key}`, SITE_INDEX_MESSAGE);
+    }
     rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     let packages = [];
@@ -1827,30 +1743,16 @@ function normalizeSite(value) {
         packages = input.packages.map((p, i) => requireNonEmptyString(p, `site.packages[${i}]`));
     }
 
-    let landing = null;
-    if (input.landing !== undefined) {
-        if (!isPlainObject(input.landing)) {
-            fail("site.landing", "must be a mapping");
-        }
-        // Passed through rather than validated field by field: it is Hugo
-        // frontmatter, whose vocabulary is the theme's and not this package's.
-        landing = Object.freeze({ ...input.landing });
-    }
-
     return Object.freeze({
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
         description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
-        sections: normalizeSectionMap(input.sections, "site.sections"),
-        landing,
         pass: input.pass === undefined ? "" : requireNonEmptyString(input.pass, "site.pass"),
         passOptions:
             input.passOptions === undefined ?
                 Object.freeze({})
             :   Object.freeze({ ...input.passOptions }),
-        backfillSections: optionalBoolean(input.backfillSections, "site.backfillSections", false),
-        list: normalizeSiteList(input.list),
         notfound: normalizeSiteNotfound(input.notfound),
         hugo: normalizeSiteHugo(input.hugo),
     });

package/docs/api.md

@@ -308,20 +308,19 @@ Schema fields a note may never author, because the document writes them during p
 
 The package homepage: a note that compiles to a page rather than a compendium document, hand-authored at the conventional shortcode `root`, checked for its address fields and for uniqueness across the tree.
 
-| Export                       | Signature                             | Returns                            | Use it when                                                                                |
-| ---------------------------- | ------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ |
-| `HOMEPAGE_TYPE`              | `const HOMEPAGE_TYPE`                 | —                                  | naming the note type that compiles to the package homepage                                 |
-| `HOMEPAGE_FIELDS`            | `const HOMEPAGE_FIELDS`               | —                                  | declaring what a homepage note may write under `sohl:` — nothing                           |
-| `HOMEPAGE_SHORTCODE`         | `const HOMEPAGE_SHORTCODE`            | —                                  | naming the shortcode a package landing conventionally takes                                |
-| `homepageDestination`        | `homepageDestination(fm)`             | `string` — e.g. `homepage-root.md` | naming the file a homepage is written to, relative to the site root                        |
-| `isHomepage`                 | `isHomepage(fm)`                      | `boolean`                          | checking whether a note's frontmatter declares the homepage type                           |
-| `HOMEPAGE_REFUSED_FIELDS`    | `const HOMEPAGE_REFUSED_FIELDS`       | —                                  | naming the top-level field a homepage refuses, and what it would decide                    |
-| `checkHomepageAddressFields` | `checkHomepageAddressFields(fm, ...)` | one finding per issue              | checking what the address rule says about one homepage note's top-level fields             |
-| `checkHomepageCount`         | `checkHomepageCount(found, ...)`      | one finding per offending note     | requiring exactly one homepage note in a content tree                                      |
-| `homepageTitle`              | `homepageTitle(fm, config)`           | `string`                           | resolving the title a homepage publishes under, defaulting to the package's manifest title |
-| `homepageFrontmatter`        | `homepageFrontmatter(fm, ...)`        | `object`                           | assembling the frontmatter a homepage publishes with, note plus derived values             |
-| `HOMEPAGE_ADDRESS_KEYS`      | `const HOMEPAGE_ADDRESS_KEYS`         | —                                  | naming the two frontmatter keys that hold an address, and what each means                  |
-| `homepageAddresses`          | `homepageAddresses(fm, body, ...)`    | `Array<{field, url, kind}>`        | finding every address a homepage carries, in frontmatter and body both                     |
+| Export                       | Signature                             | Returns                        | Use it when                                                                                |
+| ---------------------------- | ------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
+| `HOMEPAGE_TYPE`              | `const HOMEPAGE_TYPE`                 | —                              | naming the note type that compiles to the package homepage                                 |
+| `HOMEPAGE_FIELDS`            | `const HOMEPAGE_FIELDS`               | —                              | declaring what a homepage note may write under `sohl:` — nothing                           |
+| `HOMEPAGE_SHORTCODE`         | `const HOMEPAGE_SHORTCODE`            | —                              | naming the shortcode a package front page conventionally takes                             |
+| `HOMEPAGE_DESTINATION`       | `const HOMEPAGE_DESTINATION`          | —                              | naming the file a homepage is written to, `_index.md` at the site root                     |
+| `isHomepage`                 | `isHomepage(fm)`                      | `boolean`                      | checking whether a note's frontmatter declares the homepage type                           |
+| `HOMEPAGE_REFUSED_FIELDS`    | `const HOMEPAGE_REFUSED_FIELDS`       | —                              | naming the top-level fields a homepage refuses, and what each would decide                 |
+| `checkHomepageAddressFields` | `checkHomepageAddressFields(fm, ...)` | one finding per issue          | checking what the address rule says about one homepage note's top-level fields             |
+| `checkHomepageCount`         | `checkHomepageCount(found, ...)`      | one finding per offending note | requiring exactly one homepage note in a content tree                                      |
+| `homepageTitle`              | `homepageTitle(fm, config)`           | `string`                       | resolving the title a homepage publishes under, defaulting to the package's manifest title |
+| `homepageFrontmatter`        | `homepageFrontmatter(fm, ...)`        | `object`                       | assembling the frontmatter a homepage publishes with, note plus derived values             |
+| `homepageAddresses`          | `homepageAddresses(body)`             | `Array<{field, url, kind}>`    | finding every address a homepage carries — the markdown links in its body                  |
 
 ### `engine.noteSchemas`
 
@@ -345,7 +344,6 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
 | `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
-| `hasAnyTag`               | `hasAnyTag(fm)`                              | `boolean`                                | checking whether a note carries any `tags:` at all, for the site build's taxonomy decision   |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
@@ -608,23 +606,20 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 Publishing a content tree as a website. Compiling a content tree into compendium packs is `content-build package compile`. Publishing the _same tree_ as a website was a script each consumer wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of them identical — and the copies drifted in ways neither repository could see. `sohl-thalorna` reimplemented four things this package already exported, not because it needed different behaviour but because its script predates the extraction. That is the failure a command removes: a consumer cannot accidentally reimplement one.
 
-| Export                 | Signature                                         | Returns                                                                                                                                | Use it when                                                                |
-| ---------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `collectContentPages`  | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                 |
-| `collectHomepages`     | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.  |
-| `writeHomepages`       | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage at its address, below the package's own root.         |
-| `siteGates`            | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.           |
-| `emptyGates`           | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                          |
-| `gatesFailed`          | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                       |
-| `tableUniverse`        | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.               |
-| `sectionFrontmatter`   | `function sectionFrontmatter(meta)`               | {object} Its front matter, `title` first.                                                                                              | The front matter a section's landing states about itself.                  |
-| `pageFrontmatter`      | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                     |
-| `pageDestination`      | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                      |
-| `renderPages`          | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                             |
-| `writeSectionLandings` | `function writeSectionLandings(outRoot,`          | {number} How many landings were written.                                                                                               | Writes the Hugo sections a published tree declares.                        |
-| `pluralTitle`          | `function pluralTitle(name)`                      | {string} The display title.                                                                                                            | A section landing's title, from its directory name — `macro` → `Macros`.   |
-| `resolveSitePass`      | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                        |
-| `buildSite`            | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found. |
+| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                 |
+| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.  |
+| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                    |
+| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.           |
+| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                          |
+| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                       |
+| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.               |
+| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                     |
+| `pageDestination`     | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                      |
+| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                             |
+| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                        |
+| `buildSite`           | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found. |
 
 ### `engine.contentLint`