@heroiclands/package-build 24.1.0 → 25.0.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @heroiclands/package-build
 
+## 25.0.0
+
+### Major Changes
+
+**Languages and scripts**
+
+- Add `data.roman` to every configured language note: an NFC string listing each
+  permitted Roman character once, with capitals, accents, digits and punctuation
+  explicit.
+- Use `""` for no written characters; omit spaces and line breaks, and declare
+  inventories without ranges, automatic case expansion or inheritance. Maps and
+  fonts grant no extra Roman characters.
+- Language-tagged source and visible link labels are checked before mapping;
+  configured names and their BCP 47 tags select the same inventory.
+- Invalid characters and non-NFC spellings are reported at their original
+  positions; link destinations, attributes and verse structure are excluded.
+- Only period maps to Semaron's pause; recognized native signs require explicit
+  native presentation and a face that draws them, while mappings never broaden
+  Roman inventories.
+- Unassociated external tags such as `en` and `zxx` retain ordinary behavior;
+  standalone `package-build markdown` does not load language inventories.
+
+## 24.1.1
+
+### Patch Changes
+
+**Content builds**
+
+- Build indexes, calendars, assets and packs with
+  `package-build content build --calendaria-version 1.4.2`, sharing preparation
+  across validation and compilation.
+
 ## 24.1.0
 
 ### Minor Changes

package/README.md

@@ -16,6 +16,8 @@ npm install -D @heroiclands/package-build
 
 The generated project includes a homepage, website and book targets, npm scripts, and a local `.gitignore`. [Getting started](docs/getting-started.md) routes you to a [system](docs/guides/system-project.md), [module](docs/guides/module-project.md), or [content authoring](docs/authoring/first-note.md) path. The [content-language-server](https://github.com/HeroicLands/content-language-server) provides editor navigation and completion.
 
+Build indexes, calendars, staged assets and packs together with `package-build content build --calendaria-version 1.4.2`. The [complete content build](docs/commands.md#package-build-content-build) shares one source capture across publication, lint, links and compilation and reports each build stage's time.
+
 Run selected content operations together with `package-build content run index lint links compile`. The [shared content command](docs/commands.md#package-build-content-run-targets) captures one source tree for the selected checks and outputs; standalone commands remain available.
 
 Language annotations keep authored spelling: `[Zaron]{lang=vyl}` stays Roman.

package/bin/content-commands.mjs

@@ -135,6 +135,10 @@ import { serveSite } from "../engine/site-serve.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
 import { prepareLinkSqlTables, prepareTreeSqlTables } from "../engine/sql-tables.mjs";
+import { createContentTimings } from "../engine/content-timings.mjs";
+import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
+import { stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { DEPLOYED_ASSET_TYPES } from "../engine/asset-types.mjs";
 import { createContentSession, CONTENT_TARGETS } from "../engine/content-session.mjs";
 import { createFirstUseChecker } from "../engine/first-use.mjs";
 import { createNameCatalog, createNamesReport, namesReportFinding } from "../engine/names.mjs";
@@ -297,7 +301,7 @@ export function registerContentCommands(cli) {
         .command(proseCommand())
         .command(contentFormatCommand())
         .command(withIndexPreflight(linksCommand()))
-        .command(withIndexPreflight(contentCommand()))
+        .command(contentCommand())
         .command(formatCommand())
         .command(markdownCommand())
         .command(
@@ -1494,25 +1498,187 @@ function markdownCommand() {
     };
 }
 
-/**
- * `package-build links` — check that every link in a content tree lands.
- *
- * Reports a dead `#anchor`, a dead qualified address, and a wikilink authored
- * in frontmatter, plus a vendored manifest that has drifted out of reach. All
- * of it is package-agnostic, so a consumer needs no script of its own: the
- * manifest directory is the only thing it might name, and that comes from its
- * configuration.
- *
- * @returns {object} The yargs command module.
- */
-// eslint-disable-next-line
+/** Content operations with a shared invocation-local capture. */
 function contentCommand() {
     return {
-        command: "content <action> <targets..>",
+        command: "content",
+        describe: "Run content operations in one in-memory session",
+        builder: (yargs) =>
+            yargs
+                .command(withIndexPreflight(contentRunCommand()))
+                .command(contentBuildCommand())
+                .demandCommand(1, "Choose content run or content build."),
+        handler: () => {},
+    };
+}
+
+/** The complete build writes only outside the captured input roots. */
+function contentBuildOutputs(config, packaging) {
+    const roots = [
+        config.paths.content,
+        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(config.paths.assets, entry.root)),
+    ];
+    const stage = path.resolve(packaging.rootDir, packaging.stageDir);
+    const outputs = [
+        config.paths.contentIndex,
+        config.paths.packJson,
+        config.paths.stage,
+        stage,
+        path.join(config.rootDir, "build/calendars"),
+    ];
+    const contains = (parent, child) => {
+        const relative = path.relative(path.resolve(parent), path.resolve(child));
+        return (
+            relative === "" ||
+            (!relative.startsWith(`..${path.sep}`) &&
+                relative !== ".." &&
+                !path.isAbsolute(relative))
+        );
+    };
+    for (const output of [...outputs, ...packaging.assets.map(({ to }) => path.resolve(stage, to))])
+        for (const root of roots)
+            if (contains(root, output) || contains(output, root))
+                throw new Error(
+                    `content build output ${output} overlaps captured input ${root}; keep build outputs outside source roots`,
+                );
+    return [
+        ...new Set([
+            config.paths.contentIndex,
+            config.paths.packJson,
+            path.join(config.rootDir, "build/calendars"),
+            ...config.packDirectories.map((name) => path.join(config.paths.stage, name)),
+        ]),
+    ];
+}
+
+/** Publish, generate calendars, stage assets and check/compile one live session. */
+function contentBuildCommand() {
+    return {
+        command: "build",
+        describe:
+            "Publish fresh indexes, emit calendars, stage assets, lint, check links and compile",
+        builder: (yargs) =>
+            yargs
+                .option("calendaria-version", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "Calendaria import format version",
+                })
+                .check((argv) => {
+                    if (!/^\d+\.\d+\.\d+$/.test(argv.calendariaVersion))
+                        throw new Error("--calendaria-version requires a version such as 1.4.2");
+                    return true;
+                }),
+        handler: async (argv) => {
+            const timings = createContentTimings();
+            let session;
+            const shared = {
+                ...argv,
+                references: true,
+                [PREPARATION_REPORTED]: true,
+                [REPORTED_FAILURES]: new Set(),
+            };
+            const fail = (error) => {
+                reportContentFailure(error, shared);
+                process.exitCode = 1;
+            };
+            try {
+                const config = loadPackConfig();
+                const marker = path.join(config.paths.contentIndex, ".publication-ready");
+                fs.rmSync(marker, { force: true });
+                const packaging = loadPackageBuildConfig();
+                const outputs = contentBuildOutputs(config, packaging);
+                for (const output of outputs) fs.rmSync(output, { recursive: true, force: true });
+                cachedMetadataIndexes(config);
+                session = await createContentSession({ config, timings, trackChanges: true });
+                shared[CONTENT_SESSION] = session;
+                let prepared = false;
+                const reportedProblems = new Set();
+                try {
+                    assertCompendiumOperation(config, "compile");
+                    await session.prepare(["index"]);
+                    prepared = true;
+                } catch (error) {
+                    if (error.findings) {
+                        for (const finding of error.findings) {
+                            emitDiagnostic(finding);
+                            reportedProblems.add(finding);
+                        }
+                        shared[REPORTED_FAILURES].add(error);
+                        process.exitCode = 1;
+                    } else fail(error);
+                }
+                for (const problem of session.problems) {
+                    if (!reportedProblems.has(problem)) emitDiagnostic(problem);
+                    process.exitCode = 1;
+                }
+                let staged = false;
+                if (
+                    prepared &&
+                    (await timings.measure("index publication", () =>
+                        contentIndexCommand().handler(shared),
+                    ))
+                ) {
+                    fs.writeFileSync(marker, `${config.contentPackage}\n`);
+                    try {
+                        await timings.measure("calendars", () => {
+                            const result = emitCalendarArtifacts({
+                                config,
+                                calendariaVersion: argv.calendariaVersion,
+                                sources: session.sources,
+                            });
+                            log.info(
+                                `${result.calendars} calendars emitted (${result.files} files).`,
+                            );
+                        });
+                        await timings.measure("assets", () =>
+                            stagePackageBuildAssets({
+                                config: packaging,
+                                packConfig: config,
+                                session,
+                            }),
+                        );
+                        staged = true;
+                    } catch (error) {
+                        fail(error);
+                    }
+                    try {
+                        session.assertUnchanged();
+                    } catch (error) {
+                        fs.rmSync(marker, { force: true });
+                        throw error;
+                    }
+                }
+                await timings.measure("validation", () => lintCommand().handler(shared));
+                await timings.measure("links", () => linksCommand().handler(shared));
+                if (staged)
+                    await timings.measure("compile", () =>
+                        packageCommand().handler({ ...shared, action: "compile" }),
+                    );
+            } catch (error) {
+                fail(error);
+            } finally {
+                const summary = timings.snapshot();
+                log.info(
+                    `Content timings (exclusive): ${Object.entries(summary.stages)
+                        .map(([name, ms]) => `${name} ${Number(ms).toFixed(1)} ms`)
+                        .join("; ")}; total ${summary.totalMs.toFixed(1)} ms.`,
+                );
+                log.info(
+                    `Content work: ${session?.sources.size ?? 0} sources; ${session?.parsed.size ?? 0} parsed notes; ${session?.records.length ?? 0} records; reuse ${JSON.stringify(summary.hits)}; peak RSS ${(process.resourceUsage().maxRSS / 1024).toFixed(1)} MiB.`,
+                );
+                session?.dispose();
+            }
+        },
+    };
+}
+
+function contentRunCommand() {
+    return {
+        command: "run <targets..>",
         describe: "Run selected content operations with one in-memory source capture",
         builder: (yargs) =>
             yargs
-                .positional("action", { type: "string", choices: ["run"] })
                 .positional("targets", { type: "string", array: true, choices: CONTENT_TARGETS })
                 .option("references", {
                     type: "boolean",
@@ -1801,9 +1967,11 @@ function contentIndexCommand() {
                         `${config.contentPackage} → ${path.relative(process.cwd(), written.file)} ` +
                             `(${written.rows} ${relation} rows)`,
                     );
+                return true;
             } catch (err) {
                 reportContentFailure(err, argv);
                 process.exitCode = 1;
+                return false;
             } finally {
                 if (!argv[CONTENT_SESSION]) session?.dispose();
             }

package/bin/package-build.mjs

@@ -87,20 +87,13 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
-import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
-import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "../engine/diagnostics.mjs";
+import { loadAssetTransform, stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments, siteBase } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
-import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
-import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
-import { baseStyleStageEntry } from "../engine/base-styles.mjs";
-import {
-    checkScriptFonts,
-    copyScriptFonts,
-    STAGED_FONTS_DIR,
-} from "../engine/script-font-delivery.mjs";
+import { cleanBuildArtifacts, resetStage } from "../stage.mjs";
 import {
     CDN_ENV,
     cdnCredentials,
@@ -438,171 +431,13 @@ function cleanCommand() {
     };
 }
 
-/**
- * A finding for each `packageBuild.assets` row that would stage a picture root
- * itself, located at the row's `from` when the configuration is YAML.
- *
- * @param {readonly {from: string, to: string}[]} rows - The configured rows.
- * @param {{rootDir: string, assetsBase: string}} opts - Where they resolve.
- * @returns {object[]} The findings.
- */
-function pictureRootRowFindings(rows, { rootDir, assetsBase }) {
-    const offending = rowsStagingPictureRoots(rows, { rootDir, assetsBase });
-    if (!offending.length) return [];
-    const file = packConfigPath();
-    const text =
-        file.endsWith(".yaml") || file.endsWith(".yml") ? fs.readFileSync(file, "utf8") : "";
-    return offending.map(({ index, from, root }) => ({
-        file,
-        ...(text ? positionOfYamlPath(text, ["packageBuild", "assets", index, "from"]) : {}),
-        severity: "error",
-        message:
-            `\`packageBuild.assets[${index}]\` copies \`${from}\`, which reaches ${root}/ — ` +
-            "the stage copies the icon and image roots itself, flat and filtered by " +
-            "each file's provenance, so a row copying them would ship every file " +
-            "unfiltered. Remove the row",
-    }));
-}
-
-/**
- * The repository's `packageBuild.assetTransform`, loaded.
- *
- * One loader for every command that writes a picture, so the stage and the CDN
- * hold the same bytes for the same file.
- *
- * @param {object} config - The resolved package-build configuration.
- * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
- *   The transform, or `undefined` when the repository names none.
- */
-async function loadAssetTransform(config) {
-    if (!config.assetTransform) return undefined;
-    const module = await import(`file://${config.assetTransform}`).catch((err) =>
-        die(
-            `cannot load \`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}): ${err.message}`,
-        ),
-    );
-    const transform = module.transform;
-    if (typeof transform !== "function") {
-        die(
-            `\`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}) exports no \`transform\` ` +
-                `function. It must export ` +
-                `\`transform(sourcePath) -> string | null\`.`,
-        );
-    }
-    return transform;
-}
-
-/**
- * `assets` — stage the repository's static files into the package root.
- *
- * The table is data (`packageBuild.assets`). A repository that has to *change*
- * a file on the way — SoHL rewrites each SVG's hard-coded fill so icons follow
- * the Foundry theme — names a module in `packageBuild.assetTransform`, whose
- * `transform(sourcePath)` returns replacement text or `null` to copy verbatim.
- * That is the one genuine piece of code in the job, and it stays the
- * repository's.
- *
- * @returns {object} The yargs command module.
- */
+/** Stage the configured package assets. */
 function assetsCommand() {
     return {
         command: "assets",
         describe: "Stage static assets into the package root",
         builder: (y) => y,
-        handler: handler(async () => {
-            const config = loadPackageBuildConfig();
-            const packConfig = loadPackConfig();
-            const assetsBase = packConfig.paths.assets;
-            const findings = [
-                ...pictureRootRowFindings(config.assets, {
-                    rootDir: config.rootDir,
-                    assetsBase,
-                }),
-                ...checkForeignAssetBindings(packConfig, { assets: config.assets }),
-            ];
-            if (findings.length) {
-                const error = new Error(findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-
-            const transform = await loadAssetTransform(config);
-
-            // `to:` is relative to the staged package root, so a
-            // repository's table reads `lang`, not `build/stage/lang`.
-            const entries = config.assets.map(({ from, to }) => [
-                from,
-                path.join(config.stageDir, to),
-            ]);
-            let { entries: count, files } = stageAssets(entries, {
-                cwd: config.rootDir,
-                transform,
-            });
-
-            // The picture roots, staged by the toolchain rather than by a row:
-            // flat, filtered by each file's provenance, and listed in the
-            // package's asset set.
-            const pictures = stagePackageAssets({
-                assetsBase,
-                contentPackage: packConfig.contentPackage,
-                stageDir: path.resolve(config.rootDir, config.stageDir),
-                // The manifest's title names the set; a package with none is
-                // named by its content package.
-                title:
-                    typeof config.manifest?.title === "string" && config.manifest.title.trim() ?
-                        config.manifest.title
-                    :   packConfig.contentPackage,
-                transform,
-                shippingLicenses: config.shippingLicenses,
-            });
-            if (pictures.findings.length) {
-                const error = new Error(pictures.findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            files += pictures.staged.length;
-            if (pictures.staged.length || pictures.excluded.length) {
-                console.log(
-                    `Pictures: ${pictures.staged.length} staged, ` +
-                        `${pictures.excluded.length} left out by provenance.`,
-                );
-            }
-
-            // Staged in its own pass, without the repository's transform: the
-            // sheet is this toolchain's file rather than one of the
-            // repository's assets, and a `transform` written to retheme a
-            // package's own SVGs has no business being handed it.
-            if (config.baseStyles) {
-                const staged = stageAssets([baseStyleStageEntry(config.stageDir)], {
-                    cwd: config.rootDir,
-                });
-                count += staged.entries;
-                files += staged.files;
-            }
-
-            // The installed fonts, when the package has installed the fonts
-            // package and a note sets text in one of its faces: the
-            // stylesheet, the WOFF2 files and the licence, which the
-            // manifest's `styles` names.
-            const fontFindings = checkScriptFonts(packConfig);
-            if (fontFindings.length) {
-                const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            const fonts = copyScriptFonts(
-                packConfig,
-                path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
-                ["woff2"],
-            );
-            if (fonts) {
-                count += 1;
-                files += fonts;
-            }
-            console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
-        }),
+        handler: handler(() => stagePackageBuildAssets()),
     };
 }
 

package/docs/api.md

@@ -1384,17 +1384,29 @@ Linting a content tree's **addresses** — the rules every package's notes are a
 
 The charset authored content is held to, so a book can choose its face. The packs and the website render in whatever font the reader's browser or Foundry supplies, and a glyph nobody has is somebody else's problem. **A book is not that.** A PDF embeds the faces it sets, so every character in the corpus is a claim on the book's typeface — and the claim is silent, which is what makes it expensive.
 
-| Export               | Signature                                  | Returns                                                                                                                                                                  | Use it when                                                                |
-| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| `isLetterTier`       | `function isLetterTier(cp)`                | {boolean} Whether Tier 1 admits it.                                                                                                                                      | Tier 1 — the letters, and the two whitespace characters a file is made of. |
-| `TYPOGRAPHY`         | `const TYPOGRAPHY`                         | —                                                                                                                                                                        | Tier 2 — typography, enumerated one codepoint at a time.                   |
-| `NOTATION`           | `const NOTATION`                           | —                                                                                                                                                                        | Tier 3 — the notation the rules and price tables are written in.           |
-| `isAllowedCodePoint` | `function isAllowedCodePoint(cp)`          | {boolean} Whether it is allowed outside a code fence.                                                                                                                    | Whether the charset admits a code point anywhere in a note.                |
-| `isDiagramCodePoint` | `function isDiagramCodePoint(cp)`          | {boolean} Whether a fence may carry it.                                                                                                                                  | Whether a code point is diagram furniture, admitted inside a fence only.   |
-| `refusalFor`         | `function refusalFor(cp)`                  | {string} A clause naming what it is and what to do instead.                                                                                                              | The reason a code point is refused.                                        |
-| `decomposedRuns`     | `function decomposedRuns(text)`            | {Array<{sequence: string, composed: string, index: number}>} Each offending run, in the order it appears.                                                                | Every non-NFC run in a string, with the composed form it should have been. |
-| `checkText`          | `function checkText(text, file)`           | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} What is wrong, in file order.                                                | Check one file's text against the charset and the normalization rule.      |
-| `lintContentCharset` | `function lintContentCharset(contentBase,` | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` The findings, and how many files produced them. | Walk a content tree and check every authored file in it.                   |
+| Export                     | Signature                                  | Returns                                                                                                                                                                  | Use it when                                                                                  |
+| -------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `isLetterTier`             | `function isLetterTier(cp)`                | {boolean} Whether Tier 1 admits it.                                                                                                                                      | Tier 1 — the letters, and the two whitespace characters a file is made of.                   |
+| `TYPOGRAPHY`               | `const TYPOGRAPHY`                         | —                                                                                                                                                                        | Tier 2 — typography, enumerated one codepoint at a time.                                     |
+| `NOTATION`                 | `const NOTATION`                           | —                                                                                                                                                                        | Tier 3 — the notation the rules and price tables are written in.                             |
+| `isSettingScriptCodePoint` | `isSettingScriptCodePoint(cp)`             | `boolean`                                                                                                                                                                | recognizing native setting-script input before the selected face checks the individual glyph |
+| `isAllowedCodePoint`       | `function isAllowedCodePoint(cp)`          | {boolean} Whether it is allowed outside a code fence.                                                                                                                    | Whether the charset admits a code point anywhere in a note.                                  |
+| `isDiagramCodePoint`       | `function isDiagramCodePoint(cp)`          | {boolean} Whether a fence may carry it.                                                                                                                                  | Whether a code point is diagram furniture, admitted inside a fence only.                     |
+| `refusalFor`               | `function refusalFor(cp)`                  | {string} A clause naming what it is and what to do instead.                                                                                                              | The reason a code point is refused.                                                          |
+| `decomposedRuns`           | `function decomposedRuns(text)`            | {Array<{sequence: string, composed: string, index: number}>} Each offending run, in the order it appears.                                                                | Every non-NFC run in a string, with the composed form it should have been.                   |
+| `checkText`                | `function checkText(text, file)`           | {Array<{file: string, line: number, column: number, severity: "warning", message: string}>} What is wrong, in file order.                                                | Check one file's text against the charset and the normalization rule.                        |
+| `lintContentCharset`       | `function lintContentCharset(contentBase,` | `{{findings: Array<{file: string, line: number, column: number, severity: "warning", message: string}>, files: number}}` The findings, and how many files produced them. | Walk a content tree and check every authored file in it.                                     |
+
+### `engine.romanCharacters`
+
+Exact permitted Roman source characters for configured languages, before script
+mapping. Inventories come from `data.roman` on each language's own note.
+
+| Export                   | Signature                                     | Returns                       | Use it when                                                                                   |
+| ------------------------ | --------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------- |
+| `romanInventoryProblems` | `romanInventoryProblems(value)`               | `string[]`                    | checking NFC, repeated characters and forbidden whitespace or controls in a literal inventory |
+| `romanInventoriesOf`     | `romanInventoriesOf(records, languages)`      | `Map<string, RomanInventory>` | looking up a configured language's own inventory by name or BCP 47 tag                        |
+| `romanTextProblems`      | `romanTextProblems(text, inventory, native?)` | `{offset, message}[]`         | validating visible unescaped source with exact offsets and an optional native-sign predicate  |
 
 ### `engine.pathCharset`
 

package/docs/authoring/links-and-markup.md

@@ -644,6 +644,14 @@ has an error is set exactly as written.
 
 ## Marking language, font and mapping
 
+Each configured language note declares `data.roman`, a literal NFC string of
+permitted source characters. Include capitals, accents, digits and punctuation
+explicitly; an empty string declares no written characters. Spaces and line
+breaks are structural. `package-build lint` checks Roman source before mapping,
+including language-only runs and visible link labels. The configured name and
+its BCP 47 tag select the same inventory; external tags without a configured
+language note keep their ordinary behavior.
+
 `lang=` identifies the language. It preserves the authored spelling and the
 surrounding prose font. Add **`.nativefont`** to request native script:
 

package/docs/commands.md

@@ -1556,6 +1556,89 @@ package-build: This repository declares no end-to-end suite to `run`. Name one u
 
 ## Content operations
 
+### `package-build content build`
+
+**NAME**
+
+Build indexes, calendars, assets and packs from one captured content tree.
+
+**SYNOPSIS**
+
+```text
+package-build content build --calendaria-version <version>
+```
+
+**DESCRIPTION**
+
+The complete content build runs these existing operations in order:
+
+1. Capture authored sources and prepare and publish fresh metadata, dictionary
+   and terms indexes.
+2. Emit calendar definitions and Calendaria imports from the published index.
+3. Stage the configured assets, including calendars, provenance-filtered
+   pictures, base styles and fonts.
+4. Run content lint, link checks and pack compilation with the same live session.
+
+Finish dependency fetching and source generation before invoking the command.
+Public and complete SQL preparations remain separate and each is reused by
+operations needing that audience. No resolved index or source cache survives
+into another invocation. Standalone commands and `content run` remain available.
+
+The command clears its index directory, generated calendar directory, pack JSON
+and configured compiled pack directories before preparing the new build. Other
+stage files, including a manifest written by a parallel packaging task, remain.
+Use `package-build stage reset` before starting the complete packaging workflow
+when the entire stage must start empty. Build output paths must be outside the
+captured content and picture roots. A phase that changes those inputs fails the
+build, invalidates publication readiness and stops further use of the capture;
+source generation belongs before this command.
+
+After all three index files are published successfully, the command writes
+`<paths.contentIndex>/.publication-ready` (normally
+`build/content-index/.publication-ready`). It removes that marker at startup.
+The marker means this invocation published a complete fresh index, even when
+calendar emission, asset staging, lint, link checks or compilation later fails.
+A subsequent index consumer can check it to report independent findings after a
+build failure. Clear the marker before a surrounding workflow starts as well,
+so failures before the command starts cannot expose an earlier run's index.
+Never restore the marker or resolved indexes from a cache.
+
+Preparation failure blocks publication and compilation but preserves useful
+independent lint and link findings. Calendar or asset failure blocks compilation;
+ordinary lint or link findings do not block an otherwise valid compile. Pack
+generation still refuses to compile incomplete output. An advisory warning does
+not fail the command.
+
+The final timing summary includes eager capture and index derivation, SQL by
+audience, publication, calendars, assets, validation, rendering and native pack
+compilation. Stage times are exclusive: a nested SQL preparation is charged to
+SQL rather than its calling stage. Counts, preparation reuse and peak process
+RSS accompany the timings; importing the CLI and validating its arguments happen
+before the measured build interval.
+
+**OPTIONS**
+
+| Option                 | Type   | Default  | Description                            |
+| ---------------------- | ------ | -------- | -------------------------------------- |
+| `--calendaria-version` | string | required | Calendaria import version, e.g. 1.4.2. |
+
+**EXIT STATUS**
+
+0 when every operation succeeds. 1 when arguments, preparation or any build
+operation fails. Publication readiness alone does not mean the build passed.
+
+**EXAMPLES**
+
+```bash
+package-build deps fetch
+package-build content build --calendaria-version 1.4.2
+```
+
+**SEE ALSO**
+
+`package-build content run`, `package-build content-index`, `package-build calendars`,
+`package-build assets`, `package-build package compile`.
+
 ### `package-build content run <targets..>`
 
 **NAME**
@@ -2132,6 +2215,14 @@ dependencies; exact Item UUID validation remains part of compilation. Reads
 the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
+Every configured language note declares `data.roman`, its exact NFC Roman
+source characters. Lint checks language-tagged text before mapping, using the
+same inventory for a configured name and its BCP 47 tag. Visible linked labels
+are checked; destinations, attributes and verse structure are excluded. An
+explicit empty inventory declares no written characters. External tags without
+a language-note association retain their ordinary behavior. Standalone
+`package-build markdown` does not load these inventories.
+
 Name marking is advisory: lint checks explicit `.name` spans and authored link
 labels against the [name-marking
 conventions](authoring/links-and-markup.md#marking-names-in-prose). Plain prose