@heroiclands/package-build 22.1.1 → 22.3.0

package/docs/commands.md

@@ -166,7 +166,7 @@ Publish this package's DataModel field sets as `schema.json`.
 **SYNOPSIS**
 
 ```
-package-build schema [--check]
+package-build schema
 ```
 
 **DESCRIPTION**
@@ -174,23 +174,20 @@ package-build schema [--check]
 Publishes the registries named in `packageBuild.schema` as `schema.json`, read
 by `content-build content-format schema` and, in a consuming package, by
 `content-build lint`'s emitted-versus-declared check. A repository that
-declares no registries has nothing to publish. `--check` compares the
-committed file against what the source would produce now instead of
-rewriting it, so CI can gate on the file being current. Reads the registries
-`packageBuild.schema` names; writes (or checks) `schema.json` at the
-repository root.
+declares no registries has nothing to publish. Reads the registries
+`packageBuild.schema` names; writes `build/schema.json`. A release publishes
+it beside the archive and the manifest when `packageBuild.assets` names
+`build/schema.json` (see `package-build release`); a module's
+`content-build deps fetch` keeps the copy from the archive it downloads.
 
 **OPTIONS**
 
-| Option    | Type    | Default | Description                                                                    |
-| --------- | ------- | ------- | ------------------------------------------------------------------------------ |
-| `--check` | boolean | `false` | Fail when the committed `schema.json` is out of date rather than rewriting it. |
+None.
 
 **EXIT STATUS**
 
-1 when `--check` finds the committed file does not match what the source
-would produce. 1 on any other thrown error. Otherwise 0 — including when
-`packageBuild.schema` is empty, which logs and publishes nothing.
+1 on any thrown error. Otherwise 0 — including when `packageBuild.schema` is
+empty, which logs and publishes nothing.
 
 **EXAMPLES**
 
@@ -202,7 +199,7 @@ package-build: no `packageBuild.schema` declared; nothing to publish.
 **SEE ALSO**
 
 `content-build content-format schema`, `content-build lint [root]`,
-[Configuration](configuration.md).
+`package-build release`, [Configuration](configuration.md).
 
 ### `package-build manifest`
 
@@ -670,14 +667,17 @@ package-build release [--no-pdf]
 
 The artifact name comes from `packageKind` — a system ships as
 `system.json`'s sibling, a module as `module.json`'s — so no repository
-states it a second time. When the package publishes content
-(`publish.site: content`), it also builds the content-tree book (see
-`content-build pdf`) and reports it alongside the archive; `--no-pdf` skips
-that step for a release that has a tree but does not want the book this
-time. A book that fails to build is reported, never fatal — the archive
-above is the release regardless. Reads the staged package and (for the book)
-the content tree; writes `<artifact>.zip` and, unless skipped, the book,
-both under `build/dist`.
+states it a second time. It also publishes the content index the manifest
+advertises (`flags.metadataUrl`) and, when the stage carries one,
+`schema.json` — a repository that names `build/schema.json` in
+`packageBuild.assets` gets it released beside the archive; one that does not
+gets none. When the package publishes content (`publish.site: content`), it
+also builds the content-tree book (see `content-build pdf`) and reports it
+alongside the archive; `--no-pdf` skips that step for a release that has a
+tree but does not want the book this time. A book that fails to build is
+reported, never fatal — the archive above is the release regardless. Reads
+the staged package and (for the book) the content tree; writes
+`<artifact>.zip` and, unless skipped, the book, both under `build/dist`.
 
 **OPTIONS**
 
@@ -701,7 +701,7 @@ $ package-build release
 
 **SEE ALSO**
 
-`content-build pdf`, [Configuration](configuration.md).
+`content-build pdf`, `package-build schema`, [Configuration](configuration.md).
 
 ### `package-build deploy <stage>`
 

package/docs/configuration.md

@@ -752,28 +752,36 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                     | Type     | Default               |
-| ----------------------- | -------- | --------------------- |
-| `site.base`             | string   | `""`                  |
-| `site.assets`           | string   | `""`                  |
-| `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`               |
-| `site.list`             | object   | `{shortcodes: false}` |
-| `site.notfound`         | object   | `null`                |
-| `site.hugo`             | object   | `{}`                  |
+| Key                     | Type     | Default                                     |
+| ----------------------- | -------- | ------------------------------------------- |
+| `site.base`             | string   | `""`                                        |
+| `site.assets`           | string   | `""`, but required for `content-build site` |
+| `site.description`      | string   | `""`, but required for `content-build site` |
+| `site.packages`         | string[] | `[]`                                        |
+| `site.sections`         | object   | `{}`                                        |
+| `site.landing`          | object   | `null`                                      |
+| `site.pass`             | string   | `""`                                        |
+| `site.passOptions`      | object   | `{}`                                        |
+| `site.backfillSections` | boolean  | `false`                                     |
+| `site.list`             | object   | `{shortcodes: false}`                       |
+| `site.notfound`         | object   | `null`                                      |
+| `site.hugo`             | object   | `{}`                                        |
 
 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`,
@@ -785,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, 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
@@ -798,11 +806,30 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
+`content-build site` refuses to generate a configuration with no
+`site.assets` at all — there is no defensible default, because the theme
+resolves every relative asset against it:
+
+> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+
 The generated Hugo configuration carries the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
 The two are one value read by two readers: the toolchain emits it into a
 page, and the theme joins it onto anything the toolchain left relative.
 
+`site.description` is the site's `<meta name="description">` — one plain
+sentence, distinct from the Foundry package browser's pitch
+([`packageBuild.manifest.descriptionHtml`](#packagebuildmanifest), which
+allows HTML). Required for `content-build site`, the way `packageBuild.manifest.title`
+is:
+
+> ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
+
+Markup belongs in `descriptionHtml`, not here — a value containing `<` is
+refused:
+
+> ``package-build config: `site.description` contains `<` — this is plain text for the site's `<meta name="description">`; markup belongs in `packageBuild.manifest.descriptionHtml`.``
+
 `site.packages` names which content packages' notes the site walks, beyond
 this one's own; `site.pass` names a repository's own body-rewrite bundle
 (the one part of the site contract that is code, exactly as `itemBuilders`
@@ -812,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 |
 | ---------------------------------- | -------------------------- | -------- | ------- |
@@ -968,9 +978,9 @@ in it has one source, and that source is where it is edited:
 | `disableKinds`                    | whether any note in the tree carries `tags:`, which the site walk discovers: `["taxonomy", "term", "RSS"]` when none does, `["RSS"]` when at least one does |
 | `taxonomies`                      | the same fact — written as `{ tag = "tags" }` when at least one note carries `tags:`, absent otherwise                                                      |
 | `outputs`                         | the same fact — written as `{ taxonomy = ["HTML"], term = ["HTML"] }` when at least one note carries `tags:`, absent otherwise                              |
-| `params.description`              | `package.json` `description`; absent when the package declares none                                                                                         |
+| `params.description`              | `site.description`, which is required                                                                                                                       |
 | `params.author`                   | `package.json` `author`, its `name`; absent when the package declares none                                                                                  |
-| `params.cdnBaseURL`               | `site.assets`; absent when unset                                                                                                                            |
+| `params.cdnBaseURL`               | `site.assets`, which is required                                                                                                                            |
 | `params.brand`                    | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                           |
 | `params.list`                     | `site.list`                                                                                                                                                 |
 | `params.notfound`                 | `site.notfound`; absent when undeclared                                                                                                                     |
@@ -991,6 +1001,17 @@ none fails the site build:
 
 > ``package-build config: `packageBuild.manifest.title` is not declared, and the site's `title` reads from it.``
 
+`params.description` reads from `site.description` the same way, and fails
+the same way when it is absent:
+
+> ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
+
+`params.cdnBaseURL` reads from `site.assets`, and the theme resolves every
+relative asset against it, so a configuration declaring none fails the site
+build the same way:
+
+> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+
 Nothing else is emitted. A site whose notes carry no `tags:` publishes no
 taxonomy pages — `[taxonomies]` and `[outputs]` go unwritten, and Hugo's
 defaults never apply because `taxonomy` and `term` are disabled kinds. A site
@@ -1305,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
@@ -1436,11 +1457,22 @@ that has a wrong answer rather than an unknown one: a key the build
 silently overwritten and the two would be free to disagree with nothing to
 say so.
 
+`packageBuild.manifest.descriptionHtml` is the exception worth calling out on
+its own: it is not forbidden, it **is** how `description` is authored. It is
+the pitch Foundry's package browser shows — HTML allowed, any length — and it
+is emitted into the generated manifest as `description`; the key itself never
+survives into the manifest under its own name. `package.json`'s own
+`description` is read by neither this nor the site (see
+[`site.description`](#site)) — a declared one is reported as a warning naming
+both real keys, so it cannot drift back into use:
+
+> `package.json: warning: \`description\` is read by nothing; the Foundry pitch is \`packageBuild.manifest.descriptionHtml\` and the site's is \`site.description\`` — a JSON manifest carries no line to point at, so only the file is named.
+
 | Forbidden key                         | Derived from                                                     |
 | ------------------------------------- | ---------------------------------------------------------------- |
 | `packageBuild.manifest.id`            | `foundryPackage`, itself derived from `package.json` `name`      |
 | `packageBuild.manifest.version`       | `package.json` `version`                                         |
-| `packageBuild.manifest.description`   | `package.json` `description`                                     |
+| `packageBuild.manifest.description`   | `packageBuild.manifest.descriptionHtml`                          |
 | `packageBuild.manifest.url`           | `package.json` `repository`                                      |
 | `packageBuild.manifest.bugs`          | `package.json` `repository`                                      |
 | `packageBuild.manifest.manifest`      | `package.json` `repository` and the release tag                  |
@@ -1451,7 +1483,7 @@ say so.
 
 > ``package-build config: `packageBuild.manifest.version` is derived from package.json `version` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
 
-> ``package-build config: `packageBuild.manifest.description` is derived from package.json `description` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
+> ``package-build config: `packageBuild.manifest.description` is derived from `packageBuild.manifest.descriptionHtml` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
 
 > ``package-build config: `packageBuild.manifest` must be a mapping.``
 

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

package/engine/ids.mjs

@@ -86,6 +86,18 @@ export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap
  */
 export const JOURNAL_TYPES = Object.freeze(new Set(["doc", "place", "lore", "scenario"]));
 
+/**
+ * The `pack:` value that routes a note's document into no compendium.
+ *
+ * One reading, on the key that already decides which compendium receives a
+ * note: the note publishes to the site and compiles into nothing. Declared
+ * here, beside the pack table, so the configuration can refuse a pack of this
+ * name and the router can read the value from one spelling.
+ *
+ * @type {string}
+ */
+export const NO_PACK = "none";
+
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.

package/engine/note-claims.mjs

@@ -91,6 +91,7 @@ import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES, currentType } fr
 import { itemTypes } from "./item-registry.mjs";
 import { docEntryTypes } from "./item-docs.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { declaresNoPack } from "./pack-router.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
@@ -641,6 +642,12 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
     // {@link claimedNoteTypes} states: its JSON is checked in, it has no pass,
     // and no note is routed into it.
     const configured = new Set((config.packs ?? []).filter((p) => !p.prebuilt).map((p) => p.type));
+    // Every system a pack declares, plus the shared position: a note that
+    // answers `pack: none` for all of them compiles into nothing anywhere.
+    const routed = [
+        undefined,
+        ...new Set((config.packs ?? []).map((p) => p.system).filter(Boolean)),
+    ];
 
     // The corpus this compile derived once, required rather than
     // derived here: this module is imported *by* the content index, so it
@@ -681,6 +688,20 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // Every document it produces has somewhere to go.
         if (produces.length && !missing.length) continue;
 
+        // `pack: none`, on a type whose only document is the JournalEntry its
+        // prose becomes: the note compiles into nothing **by declaration**, so
+        // a missing JournalEntry pack drops nothing it meant to keep. A type
+        // that also produces an Item or an Actor is not excused here — the
+        // router refuses that declaration by name when a pass asks it, and
+        // where no pass does, the finding below still says nothing claims the
+        // note.
+        if (
+            produces.every((docType) => docType === "JournalEntry") &&
+            routed.every((system) => declaresNoPack(fm, system))
+        ) {
+            continue;
+        }
+
         // Some do and some do not: the note compiles, and one of its documents
         // is dropped in silence. A type nothing produces at all falls past this
         // to the unclaimed messages below, where `produces` being empty is itself

package/engine/pack-config.mjs

@@ -570,9 +570,22 @@ export function configFromData(data, configPath) {
             );
         }
     }
-    const { pkg } = readPackageJson(rootDir);
+    const { manifestPath, pkg } = readPackageJson(rootDir);
     if (pkg.homepage !== undefined) input.homepage = pkg.homepage;
     if (pkg.author !== undefined) input.author = pkg.author;
+    // `description` is npm metadata nothing displays for a private package —
+    // read by neither the manifest nor the site, so a declared one is a
+    // warning rather than a silent no-op that looks like it did something.
+    if (pkg.description !== undefined) {
+        emitDiagnostic({
+            file: manifestPath,
+            severity: "warning",
+            message:
+                "`description` is read by nothing; the Foundry pitch is " +
+                "`packageBuild.manifest.descriptionHtml` and the site's is " +
+                "`site.description`",
+        });
+    }
 
     if (input.itemBuilders !== undefined) {
         const declared = input.itemBuilders;

package/engine/pack-router.mjs

@@ -65,11 +65,22 @@
  *   a shared value that cannot describe a system-specific pack, so it does not
  *   answer and that system falls through to its own default. Both were silent
  *   losses of one system's whole document set.
+ * - **`pack: none` routes the document nowhere, on purpose.** The note is
+ *   walked, indexed, published and linkable, and no compendium receives it:
+ *   {@link createPackRouter}'s `resolve` answers `undefined`, which no pass's
+ *   name equals, so every pass passes over the note as one it does not own.
+ *   It is accepted only on a type whose sole document is the JournalEntry its
+ *   prose becomes — `doc` and the other journal-only types. On a type that
+ *   compiles an Item, an Actor, a Macro, a Scene or an Adventure it is refused
+ *   by name, because there the declaration would drop the document the type
+ *   exists to produce. Read per system like any other `pack:`, so a block may
+ *   say `none` for one system and the shared declaration may name a pack for
+ *   the rest.
  *
  * @module
  */
 
-import { packForType } from "./ids.mjs";
+import { NO_PACK, packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { blockProperty, systemBlock } from "./system-block.mjs";
 
@@ -95,6 +106,35 @@ export class PackRoutingError extends Error {
  */
 export const PACK_FIELD = "pack";
 
+/**
+ * The `pack:` value that routes a note's document into no compendium — see
+ * {@link module:engine/ids.NO_PACK}. Re-exported here because this is the
+ * module that reads it; a configured pack may not take the name, so the value
+ * can never be mistaken for one.
+ */
+export { NO_PACK };
+
+/**
+ * Whether a note declares `pack: none` for one system's document.
+ *
+ * The same reading {@link createPackRouter}'s `resolve` applies: the system's
+ * block wins where it declares a pack, and the shared top-level value stands
+ * otherwise. Asked with no system, it reads the shared value alone, which is
+ * what every single-system build and the content index read.
+ *
+ * Pure, so the readers that never route — the Foundry-address pass, the link
+ * index, the unclaimed-type check — can ask it without a router.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} [system] - The system whose document is asked about.
+ * @returns {boolean} True when the answer for that document is `none`.
+ */
+export function declaresNoPack(fm, system) {
+    const declared =
+        system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+    return declared === NO_PACK;
+}
+
 /**
  * Build the router for one configured pack list.
  *
@@ -103,7 +143,7 @@ export const PACK_FIELD = "pack";
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string|undefined,
  *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
@@ -179,6 +219,14 @@ export function createPackRouter(packs) {
     /** @param {object} fm */
     const noteLabel = (fm) => fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "a note";
 
+    /**
+     * `"a"` or `"an"`, so a document class reads as English in a message.
+     *
+     * @param {string} word - The word the article precedes.
+     * @returns {string} The article.
+     */
+    const article = (word) => (/^[AEIOUaeiou]/.test(word) ? "an" : "a");
+
     /**
      * The pack a note declaring none is routed to.
      *
@@ -212,8 +260,11 @@ export function createPackRouter(packs) {
      * @param {string} [system] - The system whose document is being routed. Its
      *   block's `pack:` wins over the shared one; without it only the shared
      *   declaration is read, which is every single-system build.
-     * @returns {string} The pack name.
-     * @throws {PackRoutingError} When the note routes nowhere.
+     * @returns {string|undefined} The pack name — or `undefined` where the
+     *   note declares `pack: none`, which no pass's name equals, so every pass
+     *   passes over the note as one it does not own.
+     * @throws {PackRoutingError} When the note routes nowhere, or declares
+     *   `pack: none` on a type that compiles a document beside its prose.
      */
     function resolve(fm, docType, system) {
         const inBlock = system === undefined ? undefined : systemBlock(fm, system)?.[PACK_FIELD];
@@ -225,6 +276,29 @@ export function createPackRouter(packs) {
         // JournalEntry — is not what the author was addressing.
         const ownDocType = packForType(fm?.type).docType;
 
+        // `none`: the note compiles into no document. Only a type whose own
+        // document *is* the JournalEntry may say so — for every other type
+        // the declaration would drop the Item, Actor, Macro, Scene or
+        // Adventure the type exists to produce, and its prose with it. The
+        // document class comes from the same table every pass routes by, so
+        // the refusal names what the compile would have written. Asked only
+        // by the pass that writes the note's own document, as every `pack:`
+        // is, so the refusal is reported once rather than once per pass.
+        if (declared === NO_PACK && docType === ownDocType) {
+            if (ownDocType !== "JournalEntry") {
+                const spelled = authoredInBlock ? `${system}.pack: ${NO_PACK}` : `pack: ${NO_PACK}`;
+                throw new PackRoutingError(
+                    `${noteLabel(fm)} declares \`${spelled}\`, but a ${fm?.type} note ` +
+                        `compiles into ${article(ownDocType)} ${ownDocType}, and ` +
+                        `\`pack: ${NO_PACK}\` would drop it. Only a type whose sole ` +
+                        `document is the JournalEntry its prose becomes may ` +
+                        `declare it — name the pack the ${ownDocType} goes to, or ` +
+                        `leave \`pack:\` unset for the default.`,
+                );
+            }
+            return undefined;
+        }
+
         // **A declaration naming another system's pack is not this system's
         // answer**, and which of two things that means depends on where
         // it was written.
@@ -328,7 +402,10 @@ export function createPackRouter(packs) {
          * @param {object} fm - The note's frontmatter.
          * @param {string} docType - The document type being addressed.
          * @param {string} [system] - The system whose document is addressed.
-         * @returns {string|undefined} The pack name, or `undefined`.
+         * @returns {string|undefined} The pack name, or `undefined` — for a
+         *   note that routes nowhere and for one declaring `pack: none`
+         *   alike. A caller that must tell the two apart asks
+         *   {@link declaresNoPack}.
          */
         resolveOrNull(fm, docType, system) {
             try {