@heroiclands/package-build 22.2.0 → 22.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 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

@@ -1561,9 +1561,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'
@@ -762,9 +762,7 @@ const SITE_KEYS = [
     "description",
     "packages",
     "sections",
-    "readmeSections",
     "landing",
-    "trees",
     "pass",
     "passOptions",
     "backfillSections",
@@ -772,7 +770,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"];
@@ -1079,6 +1076,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" ||
@@ -1750,15 +1756,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 +1783,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 +1804,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 +1843,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/configuration.md

@@ -759,9 +759,7 @@ Any other key under `docs.itemFields` is refused:
 | `site.description`      | string   | `""`, but required for `content-build site` |
 | `site.packages`         | string[] | `[]`                                        |
 | `site.sections`         | object   | `{}`                                        |
-| `site.readmeSections`   | object   | `{}`                                        |
 | `site.landing`          | object   | `null`                                      |
-| `site.trees`            | array    | `[]`                                        |
 | `site.pass`             | string   | `""`                                        |
 | `site.passOptions`      | object   | `{}`                                        |
 | `site.backfillSections` | boolean  | `false`                                     |
@@ -771,10 +769,19 @@ Any other key under `docs.itemFields` is refused:
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` 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](#the-generated-hugo-configuration) that is
-genuinely this repository's own.
+which named pass bundle supplies the repository's own body rewrites, and the
+residue of the [generated Hugo configuration](#the-generated-hugo-configuration)
+that is genuinely 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`, addressed by its shortcode, and
+`pack: none` where it compiles into no Foundry document — so there is no
+second mechanism for mounting a directory of markdown, and a configuration
+that names one is refused with a message saying where the page goes instead:
+
+> ``package-build config: `site.trees` 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`.``
+
+> ``package-build config: `site.readmeSections` 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`.``
 
 Where the Hugo tree is written is not a choice. `content-build site` writes
 the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
@@ -786,7 +793,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections, list, notfound, hugo).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, landing, pass, passOptions, backfillSections, list, notfound, hugo).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -832,25 +839,8 @@ names a registry):
 
 > ``package-build config: `site.packages[<index>]` must be a non-empty string.``
 
-`site.trees` are the extra trees published beside the content, each naming
-where it comes from and which section it publishes into:
-
-| Key (under `site.trees[]`) | Type   | Required |
-| -------------------------- | ------ | -------- |
-| `site.trees[].from`        | string | yes      |
-| `site.trees[].section`     | string | yes      |
-
-> ``package-build config: `site.trees` must be a list.``
-
-> ``package-build config: `site.trees[<index>]` must be a mapping.``
-
-> ``package-build config: `site.trees[<index>].from` must be a non-empty string.``
-
-> ``package-build config: `site.trees[<index>].<key>` is not a recognized option (expected one of: from, section).``
-
-`site.sections` (and `site.readmeSections`, the same shape) is a closed
-vocabulary — a section's _only_ place to speak, since it exists solely as
-the generated `_index.md` this build writes for it:
+`site.sections` is a closed vocabulary — a section's _only_ place to speak,
+since it exists solely as the generated `_index.md` this build writes for it:
 
 | Key (under `site.sections.<name>`) | Type                       | Required | Default |
 | ---------------------------------- | -------------------------- | -------- | ------- |
@@ -1336,9 +1326,9 @@ its content tree's addresses mount inside the package.
 Every HeroicLands package publishes at least an authored homepage at
 `https://www.heroiclands.org/<contentPackage>/` — there is no value meaning
 _no web presence at all_. `homepage` is the floor: the authored homepage
-and nothing else, no content-tree walk, no `site.sections` / `site.trees` /
-`site.landing` output. `content` is the homepage plus every page the
-content tree publishes. `publishesContentPages(config)`, exported from
+and nothing else, no content-tree walk, no `site.sections` / `site.landing`
+output. `content` is the homepage plus every page the content tree
+publishes. `publishesContentPages(config)`, exported from
 `content-config.mjs` alongside [`compilesFoundryDocuments`](#packagekind),
 answers the one question every reader of the mode actually asks — the site
 build, to decide whether to walk the tree at all, and the content index, to

package/docs/content-format.md

@@ -801,13 +801,43 @@ hm3:
 Where no pack of that type is the default, the build refuses rather than
 guessing, and names the candidates.
 
-Three declarations are refused, each with the reason:
+**`pack: none` compiles the note into no document.** The note is walked,
+published as a page, present in the content index with an address and no
+Foundry UUID, and addressable by wikilink like any other; every pack compiler
+passes over it without a finding, and the check that reports a note nothing
+compiles says nothing about it. Write it on a page that belongs on the website
+and in no compendium — a page of developer documentation, a page about the
+package itself:
 
-| written                             | why it is refused                                                                 |
-| ----------------------------------- | --------------------------------------------------------------------------------- |
-| a **companion** pack                | A companion is written by another pack's pass, so no note may be routed into one. |
-| a pack **nothing answers to**       | The message lists the configured packs of that document type.                     |
-| a pack of **another document type** | A note's `pack:` names a pack of its own document type.                           |
+```yaml
+type: doc
+subType: concept
+shortcode: architecture
+pack: none
+```
+
+A link to such a note resolves everywhere the note is addressable. On the web
+it is an ordinary link to the page. In a compiled journal there is no document
+to open, so the reader gets the link's text as prose and no `@UUID` — the
+mirror of a link into a package that publishes documents and no pages.
+
+It is accepted only on a type whose **sole document is the JournalEntry its
+prose becomes** — `doc`, `place`, `lore` and `scenario`. On a type that
+compiles an Item, an Actor, a Macro, a Scene or an Adventure it is refused by
+name, because there it would drop the document the type exists to produce;
+the message names that document. It is read per system like any other
+`pack:`, so `<system>.pack: none` withholds one system's document while the
+shared declaration names a pack for the rest, and a configured pack may not
+be called `none`.
+
+Four declarations are refused, each with the reason:
+
+| written                                     | why it is refused                                                                            |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| a **companion** pack                        | A companion is written by another pack's pass, so no note may be routed into one.            |
+| a pack **nothing answers to**               | The message lists the configured packs of that document type.                                |
+| a pack of **another document type**         | A note's `pack:` names a pack of its own document type.                                      |
+| **`none`** on a type with a second document | The Item, Actor, Macro, Scene or Adventure the type compiles into would be dropped, by name. |
 
 #### Template priority: which template wins
 

package/engine/foundry-entries.mjs

@@ -70,6 +70,7 @@ import { resolveNoteId } from "./note-ids.mjs";
 import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { isHomepage } from "./homepage.mjs";
+import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDeclaredFolder } from "./folder-notes.mjs";
 import {
@@ -179,7 +180,17 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // and its id is hashed under the `folder` namespace against its own
         // address rather than under `document`. Emitting one would publish an
         // `Item` UUID for a `Folder`, at an id no document carries.
-        id && !NEVER_PACKED_TYPES.has(String(type)) && !DERIVED_PACKED_TYPES.has(String(type)) ?
+        //
+        // And a note declaring **`pack: none`** is in no pack by its own
+        // statement: it publishes a page and compiles into nothing, so it has
+        // an address and no UUID. The shared declaration is what is read,
+        // because an entry names one document and this pass routes no system.
+        (
+            id &&
+            !NEVER_PACKED_TYPES.has(String(type)) &&
+            !DERIVED_PACKED_TYPES.has(String(type)) &&
+            !(routeFm && declaresNoPack(routeFm))
+        ) ?
             compendiumUuid(
                 foundryPackageId,
                 type,

package/engine/frontmatter-lint.mjs

@@ -1265,9 +1265,8 @@ export function lintNote(
             message: draftRetiredMessage(),
         });
     }
-    // Anchored at column 1 for the same reason `aliases` is: `section` names a
-    // configuration key too (`site.trees[].section`), and a nested one under
-    // some other block is not this field.
+    // Anchored at column 1 for the same reason `aliases` is: a nested
+    // `section` under some other block is not this field.
     if (Object.hasOwn(fm, "section")) {
         findings.push({
             file: note.file,

package/engine/helpers.mjs

@@ -38,7 +38,7 @@ import { foundryAddressProblem, pathnameProblem, resolvePathname } from "./pathn
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
-import { packRouter } from "./pack-router.mjs";
+import { declaresNoPack, packRouter } from "./pack-router.mjs";
 import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { PACKAGE_BASE } from "./content-address.mjs";
@@ -741,6 +741,9 @@ export function buildContentLinkIndex(
             // its prose compiles into lands — two documents, two packs.
             pack: router.resolveOrNull(fm, packForType(fm.type).docType),
             docPack: router.resolveOrNull(fm, "JournalEntry"),
+            // Whether the note declares `pack: none` and so has no document
+            // at all: a link to it names a page, never a compendium entry.
+            none: declaresNoPack(fm),
             shortcode: fm.shortcode ?? null,
             // What the note *is*, carried so a caller resolving a reference
             // can group by the family its target declares rather than only by