@heroiclands/package-build 22.1.0 → 22.2.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @heroiclands/package-build
 
+## 22.2.0
+
+### Minor Changes
+
+- 241451e: **`schema.json` is a release asset, not a committed file.** `package-build schema` writes `build/schema.json` instead of the repository root, and `--check` is gone — there is no committed copy left to compare against. `package-build release` publishes `schema.json` beside the archive and the manifest, the way it already publishes the content index, whenever the staged tree carries one.
+  
+  To keep publishing a schema: drop the committed `schema.json` and any lint step that runs `package-build schema --check`; add `{ from: build/schema.json, to: schema.json }` to `packageBuild.assets`, and run `package-build schema` before `package-build assets` in the build chain so the release never ships one older than the source it was cut from.
+- 483b630: **`content-build site` refuses to generate a configuration with no `site.assets`.** The theme resolves every relative asset — the brand logo, the 404 hero, every CDN-resolved image — against `site.assets`, and there is no defensible default: a package that built a site with the key absent published every one of those as a broken relative path. Declare `site.assets` — the `https://` host every package's imagery is served from — in `package-build.config.yaml` for any package that publishes a site.
+- 985f599: **A package now describes itself once for Foundry and once for the site.** Foundry's package browser wants a pitch — HTML, any length — and a site's `<meta name="description">` wants one plain sentence; deriving both from `package.json`'s `description` forced one string onto both. Declare `packageBuild.manifest.descriptionHtml` in `package-build.config.yaml` for the Foundry pitch (HTML allowed, emitted as the manifest's `description`) and `site.description` for the site's meta description (plain text, required for `content-build site`). `package.json`'s own `description` is read by neither any more — a warning names both keys when one is still declared — and the field can be deleted.
+
+## 22.1.1
+
+### Patch Changes
+
+- f02b25a: **A relationship may declare `contentIndex: false`.** A `requires` or
+  `systems` entry naming a package Foundry installs but the content tree never
+  cites by wikilink no longer needs a fetched index just to satisfy
+  `deps fetch`. `contentIndex` (default `true`) narrows a relationship declaring
+  it `false` to the Foundry manifest only: `deps fetch` fetches nothing for it,
+  and a wikilink into it fails at the link, naming the key, rather than
+  resolving against a stale declaration or an index nobody fetched. It cannot be
+  combined with `itemCatalog: true`, which extracts items from the same index
+  this declares there is none of.
+- 07bf15d: **The generated Hugo configuration emits tag pages for a site whose notes carry `tags:`.** `content-build site` reads whether any note in the tree carries `tags:` and, when at least one does, writes `[taxonomies] tag = "tags"` and `[outputs] taxonomy = ["HTML"], term = ["HTML"]` into `build/hugo/hugo.toml`, and leaves `taxonomy` and `term` enabled among `disableKinds`. A site whose notes carry no `tags:` gets the same configuration as before — `taxonomy`, `term` and `RSS` all disabled, no `[taxonomies]` or `[outputs]` block. `site.hugo.disableKinds`, `.taxonomies` and `.outputs` stay refused under `site.hugo`, each naming this derivation as the source.
+
 ## 22.1.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1782,6 +1782,28 @@ asked for — a build that downloads silently is not reproducible and fails
 strangely offline. The cache is keyed by version, so changing the pinned version
 is a miss rather than a silent overwrite.
 
+### A relationship may be a Foundry dependency only
+
+`requires` and `systems` install with Foundry whether or not the tree cites
+them, and a package may need the one without the other — thalornaaltart
+`requires` Thalorna so Foundry installs the base module, and its one homepage
+note links nowhere. Declare `contentIndex: false` on that entry to say so:
+
+```yaml
+relationships:
+  requires:
+    - id: thalorna
+      type: module
+      manifest: https://github.com/HeroicLands/thalorna/releases/latest/download/module.json
+      contentIndex: false
+```
+
+`deps fetch` fetches nothing for it — no cache directory, nothing to go stale —
+and a wikilink into it fails at the link, naming `contentIndex`, rather than
+resolving against a stale declaration or an index nobody fetched. It cannot be
+combined with `itemCatalog: true`, which extracts items from the same index
+this declares there is none of.
+
 ### `packagebuild` needs no declaration
 
 package-build ships a set of images of its own — section banners chiefly — and a

package/bin/content-build.mjs

@@ -1492,7 +1492,10 @@ function pdfCommand() {
  * **The Hugo configuration is generated before anything is written.** Its
  * sources — `package.json`'s `homepage`, the cached navigation, the installed
  * theme — are each a way the build can fail, and failing before the output
- * tree is cleared leaves the last good site in place to be looked at.
+ * tree is cleared leaves the last good site in place to be looked at. It is
+ * generated again once the site walk completes, because whether the site
+ * emits taxonomy pages is read from the walk — whether any note carries
+ * `tags:` — and that is not known until then.
  *
  * **Each gate is reported and the run stops at the first that fires.** They are
  * ordered so the report names the cause rather than its symptoms: an unusable
@@ -1510,7 +1513,14 @@ function siteCommand() {
         handler: async () => {
             try {
                 const config = loadPackConfig();
-                const hugo = generateHugoConfig(config);
+                // Generated once before the walk, purely to fail fast on a
+                // missing or mismatched source — `homepage`, the manifest
+                // title, the cached navigation, the installed theme — while
+                // the last good site is still in place to be looked at. Its
+                // `disableKinds`/`taxonomies`/`outputs` are provisional: only
+                // the site walk below knows whether any note carries `tags:`,
+                // so the value actually written is regenerated after it runs.
+                generateHugoConfig(config);
                 const result = buildSite({
                     config,
                     sqlTables: await prepareTreeSqlTables(config.paths.content, {
@@ -1628,6 +1638,7 @@ function siteCommand() {
                         `${s.tree ?? 0} tree page(s) + ${s.landings} ` +
                         `landing(s) to ${path.relative(process.cwd(), s.out)}`,
                 );
+                const hugo = generateHugoConfig(config, { hasTags: result.hasTags });
                 const { file } = writeHugoConfig(config, hugo);
                 log.info(`wrote ${path.relative(process.cwd(), file)}`);
             } catch (err) {
@@ -1860,7 +1871,22 @@ function depsCommand() {
                 if (indexes) log.info(`Fetched ${indexes} dependency content index(es).`);
                 const count = await fetchAllCatalogs(config);
                 if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
-                if (!indexes && !count) log.info("This package declares no dependencies.");
+                if (!indexes && !count) {
+                    // Distinguished from a package declaring nothing at all: a
+                    // relationship may still be declared, just narrowed to the
+                    // Foundry manifest by `contentIndex: false` — reporting
+                    // "no dependencies" there would read as though the
+                    // declaration itself had gone missing.
+                    const declared = Object.values(config.relationships ?? {}).some(
+                        (entries) => entries?.length,
+                    );
+                    log.info(
+                        declared ?
+                            "No declared dependency needs a fetched content index or item " +
+                                "catalogue."
+                        :   "This package declares no dependencies.",
+                    );
+                }
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;

package/bin/package-build.mjs

@@ -334,9 +334,11 @@ async function formatGenerated(text, filepath) {
  * so the system publishes the field sets as data — the same shape the link
  * manifest already uses for addresses.
  *
- * `--check` fails when the committed copy disagrees with what the source would
- * produce now, because a generated file nothing checks drifts from its
- * generator silently — and this one is read by other repositories.
+ * Writes under `build/`, alongside every other generated artifact: a release
+ * publishes it beside the archive and the manifest (see `package-build
+ * release`), and `packageBuild.assets` carries it into the staged tree from
+ * there. There is nothing committed to compare it against, so there is no
+ * `--check`.
  *
  * @returns {object} The yargs command module.
  */
@@ -344,15 +346,8 @@ function schemaCommand() {
     return {
         command: "schema",
         describe: "Publish this package's DataModel field sets as schema.json",
-        builder: (y) =>
-            y.option("check", {
-                type: "boolean",
-                default: false,
-                describe:
-                    "Fail when the committed schema.json is out of date " +
-                    "rather than rewriting it",
-            }),
-        handler: handler(async (argv) => {
+        builder: (y) => y,
+        handler: handler(async () => {
             const config = loadPackageBuildConfig();
             if (!config.schema.length) {
                 console.log(
@@ -369,25 +364,13 @@ function schemaCommand() {
                 version: pkg.version,
             });
 
-            const out = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
+            const out = path.join(config.rootDir, "build", SCHEMA_ARTIFACT_FILE);
             const text = await formatGenerated(JSON.stringify(artifact), out);
             const counts = Object.entries(artifact.documents)
                 .map(([kind, subtypes]) => `${Object.keys(subtypes).length} ${kind}`)
                 .join(", ");
 
-            if (argv.check) {
-                const current = fs.existsSync(out) ? fs.readFileSync(out, "utf8") : null;
-                if (current !== text) {
-                    die(
-                        `${SCHEMA_ARTIFACT_FILE} does not match what this ` +
-                            `package's data models would produce — regenerate ` +
-                            `it with \`package-build schema\`.`,
-                    );
-                }
-                console.log(`✅ ${SCHEMA_ARTIFACT_FILE} is up to date ` + `(${counts} subtypes).`);
-                return;
-            }
-
+            fs.mkdirSync(path.dirname(out), { recursive: true });
             fs.writeFileSync(out, text, "utf8");
             console.log(
                 `✅ Wrote ${SCHEMA_ARTIFACT_FILE} for ${artifact.system} ` +

package/config.mjs

@@ -91,7 +91,7 @@ const SECTION_KEYS = [
 export const DERIVED_MANIFEST_KEYS = Object.freeze({
     id: "`foundryPackage`, itself derived from package.json `name`",
     version: "package.json `version`",
-    description: "package.json `description`",
+    description: "`packageBuild.manifest.descriptionHtml`",
     url: "package.json `repository`",
     bugs: "package.json `repository`",
     manifest: "package.json `repository` and the release tag",
@@ -152,11 +152,16 @@ const ARTIFACT_OF_KIND = Object.freeze({
  * message, so {@link loadPackageBuildConfig} — the half that knows which file
  * was read — can resolve it to a line and column. This half stays pure.
  *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
  * @param {string} where - Dotted path of the offending key.
  * @param {string} problem - What is wrong with it.
  * @returns {never}
  */
-function fail(where, problem) {
+export function fail(where, problem) {
     throw Object.assign(new TypeError(`package-build config: \`${where}\` ${problem}.`), {
         field: where,
     });

package/content-config.mjs

@@ -503,6 +503,14 @@ export function publishesContentPages(config) {
  *                                   package this one targets — for a system
  *                                   relationship, `verified` is what
  *                                   `_stats.systemVersion` is stamped from.
+ * @property {boolean} [contentIndex]  Whether `deps fetch` fetches this
+ *                                   dependency's content index. Default
+ *                                   `true`. `false` declares the dependency
+ *                                   for the Foundry manifest only — nothing
+ *                                   this tree cites by wikilink — and refuses
+ *                                   `itemCatalog: true` on the same entry,
+ *                                   since a catalogue is fetched from the same
+ *                                   index.
  */
 
 /**
@@ -751,6 +759,7 @@ const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
     "base",
     "assets",
+    "description",
     "packages",
     "sections",
     "readmeSections",
@@ -780,6 +789,7 @@ const RELATIONSHIP_KEYS = [
     "manifest",
     "compatibility",
     "itemCatalog",
+    "contentIndex",
 ];
 const AUTHOR_KEYS = ["name", "email", "url"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
@@ -1566,6 +1576,33 @@ function normalizeSiteAssets(value) {
     return assets.replace(/\/+$/, "");
 }
 
+/**
+ * The site's `<meta name="description">`, plain text.
+ *
+ * Foundry's package browser wants a pitch — HTML, any length,
+ * `packageBuild.manifest.descriptionHtml` — and a `<meta>` tag wants one
+ * plain sentence. The two audiences are different enough that one string
+ * cannot serve both, so this is the site's own, checked for markup rather
+ * than trusted to carry none: a value with a `<` in it is refused, naming
+ * `descriptionHtml` as where markup belongs.
+ *
+ * @param {unknown} value - The configured value, or `undefined`.
+ * @returns {string} The description; `""` when unset.
+ */
+function normalizeSiteDescription(value) {
+    if (value === undefined) return "";
+    const description = requireNonEmptyString(value, "site.description");
+    if (description.includes("<")) {
+        fail(
+            "site.description",
+            "contains `<` — this is plain text for the site's " +
+                '`<meta name="description">`; markup belongs in ' +
+                "`packageBuild.manifest.descriptionHtml`",
+        );
+    }
+    return description;
+}
+
 /**
  * A map of section name → landing metadata.
  *
@@ -1604,8 +1641,10 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     contentDir: "the fixed content mount, `build/hugo/content`",
     themesDir: "where `@heroiclands/hugo-theme` is installed",
     theme: "the installed `@heroiclands/hugo-theme`",
-    disableKinds: "the toolchain, which renders the same kinds on every site",
-    "params.description": "package.json `description`",
+    disableKinds: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    taxonomies: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    outputs: "whether any note in the tree carries `tags:`, which the site walk discovers",
+    "params.description": "`site.description`",
     "params.author": "package.json `author`",
     "params.cdnBaseURL": "`site.assets`",
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
@@ -1728,6 +1767,7 @@ function normalizeSite(value) {
     const empty = Object.freeze({
         base: "",
         assets: "",
+        description: "",
         packages: Object.freeze([]),
         sections: Object.freeze({}),
         readmeSections: Object.freeze({}),
@@ -1796,6 +1836,7 @@ function normalizeSite(value) {
     return Object.freeze({
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
+        description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
         readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),
@@ -2147,6 +2188,24 @@ function normalizeRelationships(value) {
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
+                // Opt-out: declares the dependency for the Foundry manifest
+                // only, so `deps fetch` fetches no content index for it and a
+                // wikilink into it is refused rather than silently dead. A
+                // catalogue is fetched from the same index, so it cannot be
+                // declared alongside `itemCatalog: true`.
+                if (rel.contentIndex !== undefined) {
+                    if (typeof rel.contentIndex !== "boolean") {
+                        fail(`${at}.contentIndex`, "must be true or false");
+                    }
+                    if (rel.contentIndex === false && spec.itemCatalog) {
+                        fail(
+                            `${at}.contentIndex`,
+                            "cannot be false together with `itemCatalog: true` — a catalogue is " +
+                                "fetched from the same index",
+                        );
+                    }
+                    spec.contentIndex = rel.contentIndex;
+                }
                 return Object.freeze(spec);
             }),
         );

package/docs/api.md

@@ -342,6 +342,7 @@ The closed half of a note's frontmatter: the `data:` container and each type's `
 | `applicableTagGroups`     | `applicableTagGroups(type, groups)`          | `object[]`                               | reading the declared tag groups that apply to a note type                                    |
 | `exclusiveTagGroups`      | `exclusiveTagGroups(type, groups)`           | `Array<{slot, tags}>`                    | reading the single-valued tag slots a note type has, such as a being's kind                  |
 | `hasTag`                  | `hasTag(fm, tag)`                            | `boolean`                                | checking whether a note carries a given tag, whatever scalar-or-list form it was authored in |
+| `hasAnyTag`               | `hasAnyTag(fm)`                              | `boolean`                                | checking whether a note carries any `tags:` at all, for the site build's taxonomy decision   |
 | `isDraftNote`             | `isDraftNote(fm)`                            | `boolean`                                | checking whether a note is tagged as an unfinished draft                                     |
 | `subTypeCharsetMessage`   | `subTypeCharsetMessage(value)`               | `string`                                 | building the message for a `subType` outside the address charset                             |
 | `typeCharsetMessage`      | `typeCharsetMessage(type)`                   | `string`                                 | building the message for a `type` outside the address charset                                |
@@ -491,21 +492,22 @@ The shortcodes a note declares it used to be published under. A package's `(type
 
 The published content index — the artifact packages exchange addresses through. **A package publishes its own index; a consumer fetches the ones it depends on.** That is the whole mechanism, and it replaces a vendored link manifest that each repository committed a copy of every other repository's file into. Vendoring failed three ways, and only the last is about staleness:
 
-| Export                         | Signature                                                  | Returns                                                                                                                                                                                | Use it when                                                                   |
-| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                      | The relationship kinds that are dependencies, and therefore citable.          |
-| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                           | What a package's content index is called, wherever it is written or fetched.  |
-| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                             | Every dependency whose published index this build resolves addresses through. |
-| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                | The cache directory for one dependency's index at one version.                |
-| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                      | Whether a dependency's cache is present and complete.                         |
-| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                 | Mark a dependency's cache complete.                                           |
-| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                     | The fetched index files this build resolves foreign addresses against.        |
-| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                 | The same fetched indexes, each paired with the package that published it.     |
-| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                               | The newest cached version among several version-keyed cache directories.      |
-| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | {{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}} The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.  |
-| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                               | Where a dependency's fetched index sits, for naming it in a diagnostic.       |
-| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                               | Whether a fetched index can still be _addressed_, as distinct from read.      |
-| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                             | One finding, in the standard `file:line:column: severity: message` form.      |
+| Export                         | Signature                                                  | Returns                                                                                                                                                                                | Use it when                                                                                                                 |
+| ------------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `METADATA_RELATIONSHIP_KINDS`  | `const METADATA_RELATIONSHIP_KINDS`                        | —                                                                                                                                                                                      | The relationship kinds that are dependencies, and therefore citable.                                                        |
+| `metadataFileName`             | `function metadataFileName(pkg)`                           | {string} The file name, e.g.                                                                                                                                                           | What a package's content index is called, wherever it is written or fetched.                                                |
+| `metadataRelationships`        | `function metadataRelationships(config)`                   | {Array<{id: string, manifest: string, kind: string, verified: string\|undefined}>} The dependencies, in declaration order.                                                             | Every dependency whose published index this build resolves addresses through.                                               |
+| `noContentIndexPackages`       | `function noContentIndexPackages(config)`                  | {ReadonlySet<string>} The content package names.                                                                                                                                       | Every package a relationship declares `contentIndex: false` on, keyed by the content package name a link into it would use. |
+| `metadataCacheDir`             | `function metadataCacheDir(config, id, version)`           | {string} The directory.                                                                                                                                                                | The cache directory for one dependency's index at one version.                                                              |
+| `isComplete`                   | `const isComplete`                                         | {boolean} True when it was fetched to completion.                                                                                                                                      | Whether a dependency's cache is present and complete.                                                                       |
+| `markComplete`                 | `function markComplete(dir)`                               | {void}                                                                                                                                                                                 | Mark a dependency's cache complete.                                                                                         |
+| `cachedMetadataFiles`          | `function cachedMetadataFiles(config)`                     | {string[]} One index file per declared dependency.                                                                                                                                     | The fetched index files this build resolves foreign addresses against.                                                      |
+| `cachedMetadataIndexes`        | `function cachedMetadataIndexes(config)`                   | {Array<{id: string, file: string}>} One entry per declared dependency.                                                                                                                 | The same fetched indexes, each paired with the package that published it.                                                   |
+| `newestVersionDir`             | `function newestVersionDir(dirs)`                          | {string} The newest one.                                                                                                                                                               | The newest cached version among several version-keyed cache directories.                                                    |
+| `loadForeignIndexes`           | `function loadForeignIndexes(config, localPackages, bases` | {{index: Map<string, object>, packages: Set<string>, stale: Array<{package: string, reason: string}>}} The resolved addresses, which packages contributed, and what could not be read. | Resolve every foreign address this build can cite, from the fetched indexes.                                                |
+| `cachedIndexPath`              | `function cachedIndexPath(config, pkg)`                    | {string} A path to name in a diagnostic.                                                                                                                                               | Where a dependency's fetched index sits, for naming it in a diagnostic.                                                     |
+| `unaddressableForeignPackages` | `function unaddressableForeignPackages(foreignIndex)`      | {Array<{package: string, entries: number, sampleKey: string}>} One finding per drifted package, in the order the index first names each.                                               | Whether a fetched index can still be _addressed_, as distinct from read.                                                    |
+| `formatUnaddressableFinding`   | `function formatUnaddressableFinding(finding, config)`     | {string} The formatted diagnostic, path first on the line.                                                                                                                             | One finding, in the standard `file:line:column: severity: message` form.                                                    |
 
 ### `engine.foundryEntries`
 
@@ -834,14 +836,14 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 
 Wikilink resolution for the pack compilers. Content notes link to one another with wikilinks rather than file paths:
 
-| Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                               | Use it when                                                                                                                                                                |
-| -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                       | Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
-| `readQualifier`      | `function readQualifier(target, types, packages)`                       | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type; or `null` when it is not an address at all.                                      | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
-| `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                              | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
-| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                | Builds the link-resolution tables for a content tree.                                                                                                                      |
-| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                     | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
-| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named. | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
+| Export               | Signature                                                               | Returns                                                                                                                                                                                                                                                                                                                                                    | Use it when                                                                                                                                                                |
+| -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `resolveItemDocType` | `function resolveItemDocType(qualifier, types)`                         | {string\|null} The underlying document type, or `null` when the qualifier is not a virtual one.                                                                                                                                                                                                                                                            | Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is not one.                                                                                      |
+| `readQualifier`      | `function readQualifier(target, types, packages, noIndexPackages)`      | {{type: string, shortcode: string, itemDoc: boolean, package?: string, system?: string, reason?: undefined} \| {reason: "unknown-type"\|"no-content-index", package?: string} \| null} The resolved qualifier; a `reason` when the target is definitely qualified but names no known type or no fetched index; or `null` when it is not an address at all. | Read a link target as a **qualified** `type-shortcode` reference, or report that it does not parse as one.                                                                 |
+| `anchorPageId`       | `function anchorPageId(noteId, anchorSlug)`                             | {string} A 16-character alphanumeric id.                                                                                                                                                                                                                                                                                                                   | The deterministic JournalEntryPage id for one anchor: SHA-256 of `"<noteId>-<anchorSlug>"`, base64-encoded, reduced to the 16 alphanumeric characters a Foundry id allows. |
+| `buildWikilinkIndex` | `function buildWikilinkIndex(docs, packageId, foreign, contentPackage)` | {{byShortcode: Map<string, object>, types: Set<string>}} `types` is every type the tree actually contains, so a qualifier naming no real type can be told apart from a missing target.                                                                                                                                                                     | Builds the link-resolution tables for a content tree.                                                                                                                      |
+| `resolveReference`   | `function resolveReference(index, ref, hint)`                           | {{name?: string, uuid?: string, address?: string, subType?: string}\|undefined} The target, or `undefined` where nothing answers.                                                                                                                                                                                                                          | Resolve one reference — a bare shortcode, a short address or a canonical one — to what a compendium can use.                                                               |
+| `convertWikilinks`   | `function convertWikilinks(markdown,`                                   | {{markdown: string, unresolved: Array<{link: string, target: string, offset: number, reason: string, packages?: string[], anchor?: string}>}} Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all three resolvers share — `ambiguous` carries the claiming `packages` and `unknown-anchor` the section it named.                      | Rewrites every wikilink in a markdown body as a Foundry UUID enricher.                                                                                                     |
 
 ### `engine.wikilinkSyntax`
 
@@ -1288,6 +1290,7 @@ console.log(config.stageDir);
 | `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
 | `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
 | `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `content-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
+| `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                          |
 
 ## `./prettier`
 

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>`