@heroiclands/package-build 22.2.0 → 22.3.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @heroiclands/package-build
 
+## 22.3.1
+
+### Patch Changes
+
+- b2bb2b2: **`content-build docs item-fields`.** A destination under the content tree
+  (`assets/content/`) now writes a complete note — `type: doc`,
+  `subType: reference`, a derived `shortcode`, `name.full` and `pack: none` —
+  rather than a typeless page the content walk silently drops. A consumer
+  declares further note frontmatter under `docs.itemFields.frontmatter`,
+  deep-merged over the generated envelope; `--check` compares the whole file.
+  A destination outside the content tree is unaffected.
+
+## 22.3.0
+
+### Minor Changes
+
+- a79b33a: **A note may declare `pack: none`.** The universal `pack` key accepts one more value: `none` says the note publishes to the site and compiles into no Foundry document. Such a note is walked, published as a page, present in the content index with an address and no UUID, and addressable by wikilink like any other — on the web the link reaches the page, and in a compiled journal the reader gets the link's text with no document to open. Every pack compiler passes over it without a finding. It is accepted only on a type whose sole document is the JournalEntry its prose becomes (`doc`, `place`, `lore`, `scenario`) and refused by name on a type that compiles an Item, an Actor, a Macro, a Scene or an Adventure, naming the document it would drop. It is read per system like any other `pack:`, and a configured pack may not be called `none`.
+  
+  **`site.trees` and `site.readmeSections` are refused.** A page is a note in the content tree, and there is no second mechanism for mounting a directory of markdown beside it. A configuration declaring either key fails with a message saying so. A package that mounted a directory of pages moves them into `assets/content/` as `doc` notes — each with a `shortcode` and `pack: none` — rewrites their relative links as wikilinks, and declares the section that lists them under `site.sections`. The `sohlKb` site pass no longer rewrites repository-relative links, and its `blob` option has no reader.
+
 ## 22.2.0
 
 ### Minor Changes

package/CONTENT.md

@@ -488,6 +488,17 @@ pack: mysteries
   type one system maps and another does not stays silent for the system that
   declines it.
 
+- **`pack: none` compiles the note into no document, on purpose.** The note is
+  walked, published as a page, present in the content index with an address
+  and no UUID, and addressable by wikilink; every pass passes over it without
+  a finding, and the finding above says nothing about it. It is accepted only
+  on a type whose sole document is the JournalEntry its prose becomes — a
+  `doc`, say — and refused by name on a type that compiles an Item, an Actor,
+  a Macro, a Scene or an Adventure, where it would drop that document. A
+  configured pack may not be called `none`. This is how a page of developer
+  documentation lives in the content tree beside everything else: it is a
+  note like any other, and it reaches no compendium.
+
 **The configuration is found by walking up from the working directory, and from
 the installed package only if that finds nothing.** `engine/pack-config.mjs`
 climbs from `process.cwd()` first, so a build reads the tree it was run in —
@@ -2256,10 +2267,10 @@ note-format knowledge against game-system knowledge, and a homepage carries no
 
 `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. |
+| 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.                |
 
 There is no value meaning "no web presence": every package publishes its
 homepage. A boolean is refused, with a message naming the mode to write
@@ -2273,8 +2284,8 @@ content_ — journal text, artwork, item descriptions, compiled notes — and a
 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.
+pages, and `sections`, `landing` and `backfillSections` emit nothing even when
+they are declared.
 
 That is separate from the **dependency** edge, which such a module also
 declines: being cited by another package is what would stop it being
@@ -2293,9 +2304,12 @@ does not reach it.
 **What it does not do is decide addresses.** Those come from `publish.address`,
 the same setting the content index reads, so a page and its index record cannot
 disagree about where the page is. Everything under `site:` is _framing_ —
-what a section is called, which extra trees are published beside the content,
-and the residue of the generated Hugo configuration that is this repository's
-own:
+what a section is called, and the residue of the generated Hugo configuration
+that is this repository's own. What the site publishes is the content tree and
+nothing beside it: a page of documentation is a note (`type: doc`, with
+`pack: none` where it compiles into no document), so there is no second
+mechanism for mounting a directory of markdown, and a `trees:` or
+`readmeSections:` key is refused with a message saying so.
 
 ```yaml
 site:
@@ -2307,16 +2321,12 @@ site:
   passOptions:
     apiBase: /sohl/api/
     symbolMap: kb/data/api-symbols.json
-    blob: https://github.com/HeroicLands/…/blob/main/
-  trees:
-    - { from: kb/dev-docs, section: dev-docs }
   sections:
     being:
       title: Beings
       banner: banners/creature.webp
       description: Folk, animals and the things that walk the world.
-  readmeSections:
-    dev-docs: { title: Developer Documentation, banner: banners/dev-docs.webp }
+    reference: { title: Reference, listType: doc, listSubType: reference }
   list: { shortcodes: true }
   notfound:
     tagline: Song of Heroic Lands has no page at
@@ -2330,10 +2340,8 @@ site:
 | `base`             | Where the package is served: the prefix on every rendered `href`, and what a manifest `path` is measured against. It reaches no page's own `url:` — see [A page's URL is its address](#a-pages-url-is-its-address). Defaults to `/<contentPackage>/`. |
 | `packages`         | Which content packages this site renders. Defaults to its own.                                                                                                                                                                                        |
 | `sections`         | The Hugo sections this site declares, and what each says about itself — see below.                                                                                                                                                                    |
-| `readmeSections`   | The same, for a `trees` entry, whose landing comes from its own `README`.                                                                                                                                                                             |
 | `landing`          | Frontmatter for the mount's own `_index.md`. Passed through — the vocabulary is the theme's.                                                                                                                                                          |
 | `backfillSections` | Write a bare `_index.md` for any other directory directly under the mount.                                                                                                                                                                            |
-| `trees`            | Extra source trees published beside the content, preserving their source layout below a section.                                                                                                                                                      |
 | `pass`             | A named bundle of this repository's own body rewrites.                                                                                                                                                                                                |
 | `passOptions`      | That bundle's options.                                                                                                                                                                                                                                |
 | `assets`           | The host every package's imagery is served from; the generated `params.cdnBaseURL`.                                                                                                                                                                   |
@@ -2377,12 +2385,6 @@ Whatever the entry may carry is the whole of what the section can say.
 | `listType`    | no       | The content **type** whose pages this section lists.                      |
 | `listSubType` | no       | Narrows that to one **subType**. Only with a `listType`.                  |
 
-`readmeSections` takes the same keys, for a **`trees`** entry: those pages keep
-their source layout below a named section, so the tree's own `README.md` is that
-section's landing. What the section declares wins over what the `README` happens
-to carry — the landing has to match the card that links to it. No content note
-reaches this map any more.
-
 #### Saying what a section lists
 
 A generic list layout has nothing to render, because the membership a section
@@ -2477,15 +2479,9 @@ a site publishes dead `{@link}` tags at exit 0. A map that is read reports
 its symbol count at info level, which is the only way to tell a map that loaded
 from one that loaded empty without reading the emitted HTML.
 
-A bundle supplies up to two hooks, and their order around the shared work is the
-point:
-
-1. `beforeLinks`, on every page, before wikilinks resolve — a `{@link}` tag may
-   sit in prose a wikilink also touches.
-2. `afterLinks`, on pages from an extra tree only — repository-relative links are
-   a property of how those pages are authored, not of content notes.
-
-Both run inside code-fence protection, so neither can rewrite a fenced example.
+A bundle supplies one hook, `beforeLinks`, which runs on every page before
+wikilinks resolve — a `{@link}` tag may sit in prose a wikilink also touches.
+It runs inside code-fence protection, so it cannot rewrite a fenced example.
 
 ### The gates
 
@@ -2499,7 +2495,6 @@ after the links that failed because of it reads as a pile of broken notes.
 | Addresses              | A note with no shortcode to be addressed by, or no section to be filed under.      |
 | Unusable manifest      | A vendored manifest this build cannot read.                                        |
 | Unaddressable manifest | One it can read but cannot look anything up in.                                    |
-| Package conflicts      | One address claimed by two packages.                                               |
 | Tables and wikilinks   | A table directive that cannot be honoured, or a link that lands nowhere.           |
 
 None of them exits the process from inside the library; the command decides. That

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) {
@@ -1561,9 +1583,6 @@ function siteCommand() {
                 for (const f of gates.unaddressable) {
                     console.error(formatUnaddressable(f, loadPackConfig()));
                 }
-                for (const c of gates.conflicts) {
-                    log.error(`address ${c.key} is also published by ${c.package}`);
-                }
                 if (gatesFailed(gates)) {
                     process.exitCode = 1;
                     return;

package/content-config.mjs

@@ -73,7 +73,7 @@ import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-char
 import { ASSET_TYPE_NAMES } from "./engine/asset-types.mjs";
 import { isReservedPackage } from "./engine/packages.mjs";
 import { EMPTY_ICON_REGISTRY, checkIconRegistry } from "./engine/content-icons.mjs";
-import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
+import { MAP_TYPES, NO_PACK, PACK_BY_TYPE } from "./engine/ids.mjs";
 import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
 
@@ -256,10 +256,10 @@ 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.trees` / `site.landing`
- *   emit nothing, and nothing serves a page for its addresses.
+ *   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, the extra trees, the section landings.
+ *   knowledgebase and 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'
@@ -528,6 +528,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.
  */
 
 /**
@@ -762,9 +767,7 @@ const SITE_KEYS = [
     "description",
     "packages",
     "sections",
-    "readmeSections",
     "landing",
-    "trees",
     "pass",
     "passOptions",
     "backfillSections",
@@ -772,7 +775,6 @@ const SITE_KEYS = [
     "notfound",
     "hugo",
 ];
-const SITE_TREE_KEYS = ["from", "section"];
 const SITE_LIST_KEYS = ["shortcodes"];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -780,7 +782,7 @@ const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "ico
 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",
@@ -1079,6 +1081,15 @@ function normalizePack(value, where, nested = false) {
     rejectUnknownKeys(pack, PACK_KEYS, `${where}.`);
 
     const name = requireNonEmptyString(pack.name, `${where}.name`);
+    // A note writes `pack: none` to compile into no document, so a pack of
+    // that name could never be addressed by one.
+    if (name === NO_PACK) {
+        fail(
+            `${where}.name`,
+            `may not be \`${NO_PACK}\` — a note declares \`pack: ${NO_PACK}\` to ` +
+                `compile into no document, so no pack may answer to the name`,
+        );
+    }
     const type = pack.type;
     if (
         typeof type !== "string" ||
@@ -1429,6 +1440,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);
 }
 
@@ -1750,15 +1767,22 @@ function normalizeSiteHugo(value) {
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
- * Everything here is *framing*: what a section is called, which extra trees
- * are published beside the content, 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.
+ * 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.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
@@ -1770,9 +1794,7 @@ function normalizeSite(value) {
         description: "",
         packages: Object.freeze([]),
         sections: Object.freeze({}),
-        readmeSections: Object.freeze({}),
         landing: null,
-        trees: Object.freeze([]),
         pass: "",
         passOptions: Object.freeze({}),
         backfillSections: false,
@@ -1793,27 +1815,20 @@ function normalizeSite(value) {
                 "the location is not configurable. Remove the key",
         );
     }
-    rejectUnknownKeys(input, SITE_KEYS, "site.");
-
-    const trees = [];
-    if (input.trees !== undefined) {
-        if (!Array.isArray(input.trees)) fail("site.trees", "must be a list");
-        input.trees.forEach((entry, i) => {
-            const where = `site.trees[${i}]`;
-            if (!isPlainObject(entry)) fail(where, "must be a mapping");
-            const tree = /** @type {Record<string, unknown>} */ (entry);
-            rejectUnknownKeys(tree, SITE_TREE_KEYS, `${where}.`);
-            trees.push(
-                Object.freeze({
-                    from: requireNonEmptyString(tree.from, `${where}.from`),
-                    section: requireNonEmptyString(tree.section, `${where}.section`),
-                    // The tree's own path, POSIX-separated — what a
-                    // repository-relative link inside it is resolved against.
-                    rel: String(tree.from).split(path.sep).join("/"),
-                }),
-            );
-        });
+    // Refused by name too, and ahead of the vocabulary check for the same
+    // reason: a page is a note in the content tree, and the useful thing to
+    // say is where it goes rather than that the key is unknown.
+    for (const key of ["trees", "readmeSections"]) {
+        if (input[key] === undefined) continue;
+        fail(
+            `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`",
+        );
     }
+    rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     let packages = [];
     if (input.packages !== undefined) {
@@ -1839,9 +1854,7 @@ function normalizeSite(value) {
         description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
-        readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),
         landing,
-        trees: Object.freeze(trees),
         pass: input.pass === undefined ? "" : requireNonEmptyString(input.pass, "site.pass"),
         passOptions:
             input.passOptions === undefined ?

package/docs/api.md

@@ -103,6 +103,7 @@ Deterministic document ids, derived by hashing rather than stored, so compile pa
 | `MAP_TYPES`            | `const MAP_TYPES`                               | —                                                              | enumerating the content types that compile into a Foundry `Scene`                          |
 | `MAP_SUBTYPES`         | `const MAP_SUBTYPES`                            | —                                                              | reading the map subTypes, which differ only in derived canvas defaults                     |
 | `JOURNAL_TYPES`        | `const JOURNAL_TYPES`                           | —                                                              | enumerating content types whose whole document _is_ a JournalEntry                         |
+| `NO_PACK`              | `const NO_PACK`                                 | —                                                              | spelling the `pack:` value (`none`) that routes a note's document into no compendium       |
 | `PACK_BY_TYPE`         | `const PACK_BY_TYPE`                            | —                                                              | looking up the conventional pack name and document type for a content type                 |
 | `RETIRED_TYPES`        | `const RETIRED_TYPES`                           | —                                                              | looking up what a retired content type was replaced by                                     |
 | `assertTypeNotRetired` | `assertTypeNotRetired(type, where)`             | throws                                                         | refusing a note whose type has been retired outright                                       |
@@ -200,6 +201,8 @@ Which pack a note's document lands in, when a document type has more than one co
 | ------------------ | -------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
 | `PackRoutingError` | `class PackRoutingError extends Error` | —                          | catching a note that cannot be routed to any configured pack                                      |
 | `PACK_FIELD`       | `const PACK_FIELD`                     | —                          | naming the frontmatter field a note declares its pack in                                          |
+| `NO_PACK`          | `const NO_PACK`                        | —                          | spelling the `pack:` value (`none`) that routes a note's document into no compendium              |
+| `declaresNoPack`   | `declaresNoPack(fm, system)`           | `boolean`                  | asking, without a router, whether a note declares `pack: none` for one system's document          |
 | `createPackRouter` | `createPackRouter(packs)`              | `{resolve, resolveOrNull}` | building a router for one configured pack list, purely, for testing without a config file on disk |
 | `routerFor`        | `routerFor(config)`                    | the router                 | getting the router for a resolved configuration, built once per configuration                     |
 | `packRouter`       | `packRouter()`                         | the router                 | asking, as every module that emits a UUID does, where a note's document lives                     |
@@ -605,25 +608,23 @@ 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                                                                   |
-| ---------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `walkSiteTree`         | `function walkSiteTree(dir, skip`                 | {string[]} Absolute paths.                                                                                                             | Every `.md` file under `dir`, depth-first in directory order.                 |
-| `collectContentPages`  | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                    |
-| `collectTreePages`     | `function collectTreePages(tree, ctx)`            | {{pages: object[], fmLinkFindings: object[]}}                                                                                          | An extra tree's pages — a documentation tree published alongside the content. |
-| `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, afterLinks?: 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 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. |
 
 ### `engine.contentLint`
 
@@ -1138,13 +1139,12 @@ Which of SoHL's facts a note's summary panel carries, and how they group. Read o
 
 ### `sohl.kbPasses`
 
-The `sohl` knowledgebase's own body passes: two rewrites driven by a TypeDoc symbol map and a repository layout only this package has, named from `site.passOptions` the same way an asset transform is named from configuration. Neither rewrite ever fails a build — an unresolved `{@link}` degrades to a code span, and a relative link outside the documentation tree becomes a GitHub blob URL — but building the bundle from a misconfigured `symbolMap` fails loudly before any page renders.
+The `sohl` knowledgebase's own body pass: a rewrite driven by a TypeDoc symbol map only this package has, named from `site.passOptions` the same way an asset transform is named from configuration. The rewrite never fails a build — an unresolved `{@link}` degrades to a code span — but building the bundle from a misconfigured `symbolMap` fails loudly before any page renders.
 
-| Export             | Signature                                 | Returns                                                | Use it when                                                                                                                                                                     |
-| ------------------ | ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveApiLinks`  | `resolveApiLinks(body, symbols, apiBase)` | `string` — the body with every tag resolved            | resolving inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags in a markdown body against the API symbol map                                                          |
-| `rewriteRepoLinks` | `rewriteRepoLinks(body, docRel, options)` | `string` — the body with every relative link rewritten | rewriting a developer doc's repository-relative links so they resolve on the published site (documentation-tree links become routes, everything else becomes a GitHub blob URL) |
-| `sohlKbPass`       | `sohlKbPass(options)`                     | `{beforeLinks: Function, afterLinks: Function}`        | building the `sohl` knowledgebase pass bundle the site renderer calls around wikilink resolution                                                                                |
+| Export            | Signature                                 | Returns                                     | Use it when                                                                                                            |
+| ----------------- | ----------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `resolveApiLinks` | `resolveApiLinks(body, symbols, apiBase)` | `string` — the body with every tag resolved | resolving inline TypeDoc `{@link}` / `{@linkcode}` / `{@linkplain}` tags in a markdown body against the API symbol map |
+| `sohlKbPass`      | `sohlKbPass(options)`                     | `{beforeLinks: Function}`                   | building the `sohl` knowledgebase pass bundle the site renderer calls before wikilink resolution                       |
 
 ### Flat exports (not under a namespace)
 

package/docs/commands.md

@@ -1064,6 +1064,29 @@ named. Reads the configured `itemBuilders` registries; writes (or checks)
 the destination file, or prints to stdout when none is configured and
 `--out` is not given.
 
+**A destination under `paths.content` gets a complete note, not a typeless
+page.** The content-tree walk collects every published page by its `type:`,
+so a generated page filed there needs the envelope every other note carries
+or the walk drops it silently — no build failure, no page, every wikilink
+into it dead. So when `--out` (or `docs.itemFields.out`) resolves inside the
+content tree, the written file carries:
+
+- `type: doc`, `subType: reference` — out-of-world lookup material, like
+  every other generated reference page;
+- `shortcode`, derived from the destination's basename — lowercase
+  alphanumerics only, so `item-frontmatter.md` derives `itemfrontmatter` —
+  unless `docs.itemFields.frontmatter.shortcode` gives one;
+- `name.full`, from the page's title;
+- `pack: none` — the page publishes to the website and compiles into no
+  compendium document.
+
+`docs.itemFields.frontmatter` is deep-merged over that envelope, so a
+consumer may add keys (`description`, `tags`) or override any of the derived
+ones. `--check` then compares the **whole** file, envelope included — a page
+committed with a hand-written or stale envelope reads as out of date exactly
+as a stale body does. A destination outside the content tree gets the page
+body alone, with no frontmatter, exactly as before.
+
 **OPTIONS**
 
 | Positional | Type                         | Default | Description             |