@kungfu-tech/buildchain 2.11.2-alpha.1 → 2.11.2-alpha.2

package/bin/buildchain.mjs

@@ -10,6 +10,7 @@ import { runLifecycle } from "../scripts/run-lifecycle-core.mjs";
 import { verifyInfraContractEvidenceBundle } from "../scripts/infra-contract-core.mjs";
 import { runReleasePropagationCli } from "../scripts/release-propagation.mjs";
 import { runPublicationArtifactCli } from "../scripts/publication-artifact.mjs";
+import { runPublicationPackageCli } from "../scripts/publication-package.mjs";
 import { validateBuildchainConfig } from "../packages/core/buildchain-config.js";
 import { detectPackageManager } from "../packages/core/package-manager.js";
 import {
@@ -206,6 +207,7 @@ function usage() {
                                            [--output <file>] [--passport-output <file>]
                                            [--registry-output <file>] [--source-bundle <file>]
                                            [--no-source-bundle] [--json]
+  buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]
   buildchain release-propagation <plan|write-lock> ...
   buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
   buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]
@@ -1791,6 +1793,10 @@ async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === "publication-artifact" || command === "publication") {
+    if (args[0] === "npm-package" || args[0] === "package") {
+      runPublicationPackageCli(args.slice(1));
+      return;
+    }
     runPublicationArtifactCli(args);
     return;
   }

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.11.2-alpha.1",
+    "version": "2.11.2-alpha.2",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -344,7 +344,7 @@
         "README badge block checks and writes are generated from machine-readable repository facts"
       ],
       "breakingDigest": "sha256:90a73892b2d6c214048448d5f45df75639bdf7b7e8fefd9c596e04b087407bcc",
-      "auditDigest": "sha256:af9dac0e27f5daed03718f2e446425f1334f0773f3e028aaf0f59b375540ba05"
+      "auditDigest": "sha256:c41e3e069f70d038537fc7d399eabb01bc33873cc361e20798cac7a7c9ce3e31"
     },
     {
       "contractVersion": 1,
@@ -434,7 +434,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:d239e141275fdeb411de8b745b0658f3c71bce42cb60b77aaeab99e098e4233a"
+      "auditDigest": "sha256:30cf2ab67331fecaf3242ab60cb048b70c7e59fad526656d47f2897ebedc2f3b"
     },
     {
       "contractVersion": 1,
@@ -456,9 +456,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:5516090e12e99b46c686b9ec425e4237ef2da75907d6c4c3bda2754598d7ca42"
+      "auditDigest": "sha256:7b380d62fe8844c8fbf8d9a233559bfffa1457e9d664ed1bbf46da87cf225d46"
     }
   ],
   "compatibilityDigest": "sha256:967df7e854fdf582294ddfb6403eff25c00db9518a24051e7d47cbd75527c785",
-  "contractDigest": "sha256:4271947b04311f71f804bcfbde882f0ec7777f41ecfe17a382a339da29e7b762"
+  "contractDigest": "sha256:fc639e404d3daae788a4930026cc059b1769e08f6e2dd59ffb889a90f88284d8"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-09T15:39:27.573Z",
-  "publishedAt": "2026-07-09T15:39:27.573Z",
+  "generatedAt": "2026-07-09T16:06:47.861Z",
+  "publishedAt": "2026-07-09T16:06:47.861Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2e87aaee5e94ac19ac676c3999349c55b8253730",
+  "sourceRevision": "b93fcd8237e6060596fc6bcb82198e9097356f5b",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.2-alpha.1",
+    "version": "2.11.2-alpha.2",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -397,7 +397,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/cli.md",
-      "digest": "sha256:4b31f7ff5330cde8ab32b237f533c7af76463cce570d67dd14669c3a14c83c84",
+      "digest": "sha256:81624885888c9e357db128f644f93dcab2286910df426b532730b0141d7cb00d",
       "headings": [
         {
           "level": 1,
@@ -425,7 +425,7 @@
           "anchor": "npm-publish-gate"
         }
       ],
-      "markdown": "# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@2.2.5`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n  await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v2`.\n\n## Commands\n\n`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\n\nSupported presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n  validation, observation, contract publication, and downstream propagation\n  planning without default mutation. Provider adapters expose built-in command\n  plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n  publication repositories that produce PDFs, metadata, source bundles, and\n  site-consumable manifests without becoming web-surface repositories. The\n  scaffold uses Buildchain's pinned\n  `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n  LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n  whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n  explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n  --require-version-state \\\n  --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n  --artifact-path dist \\\n  --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, switches the default\nbranch, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --write \\\n  --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n  collectPublicSurfaceReverseAudit,\n  assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4 is schema-only until Buildchain has a\nreal verification protocol for it.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\n```\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native-build\" });\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n  --module native-core \\\n  --output .buildchain/facts/native-core.json \\\n  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n  --product kungfu \\\n  --module-fact .buildchain/facts/native-core.json \\\n  --artifact dist/kungfu.zip \\\n  --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --json\n```\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n  --package buildchain \\\n  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \\\n  --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.3.2 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.3.2/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.3.2/state.json \\\n  --package-set-json package-set.json \\\n  --impact-json impact.json \\\n  --trusted-publishing-json trusted-publishing.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n  --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v2/v2.3\"}' \\\n  --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n  --repository kungfu-systems/libnode \\\n  --tag v22.22.3-kf.3-alpha.18 \\\n  --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n   Release asset URLs, or `--repository <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n  \"locators\": [\n    {\n      \"match\": {\n        \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n        \"digest\": \"sha256:...\"\n      },\n      \"passport\": \"../release-passport/buildchain.release.json\"\n    }\n  ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v2/v2.2\nbuildchain release --dry-run --target-ref release/v2/v2.2 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.2\nbuildchain release explain --target-ref alpha/v2/v2.1 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v2.1.0-alpha.0\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v2.0.13-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v2.0.13` publishes to npm with dist-tag `latest`.\n- moving refs such as `v2`, `v2.0`, and `v2.0-alpha` do not match the publish\n  workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
+      "markdown": "# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@2.2.5`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n  await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v2`.\n\n## Commands\n\n`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\n\nSupported presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n  validation, observation, contract publication, and downstream propagation\n  planning without default mutation. Provider adapters expose built-in command\n  plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n  publication repositories that produce PDFs, metadata, source bundles, and\n  site-consumable manifests without becoming web-surface repositories. The\n  scaffold uses Buildchain's pinned\n  `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n  LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n  whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n  explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n  --require-version-state \\\n  --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n  --artifact-path dist \\\n  --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, switches the default\nbranch, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --write \\\n  --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n  collectPublicSurfaceReverseAudit,\n  assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4 is schema-only until Buildchain has a\nreal verification protocol for it.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\n```\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native-build\" });\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n  --module native-core \\\n  --output .buildchain/facts/native-core.json \\\n  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n  --product kungfu \\\n  --module-fact .buildchain/facts/native-core.json \\\n  --artifact dist/kungfu.zip \\\n  --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --json\n```\n\nGenerate the Buildchain-owned npm paper package contents from declared\npublication facts:\n\n```bash\nbuildchain publication-artifact npm-package --json\n```\n\nThis command reads `project.type = \"publication-artifact\"`,\n`publication.version`, and `[publish] kind = \"npm-paper-package\"` plus\n`publish.package`; it writes `.buildchain/publication/npm-package` by default.\nThe `paper-release.yml@v2` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n  --package buildchain \\\n  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v2.8.15/buildchain.release.json \\\n  --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.3.2 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.3.2/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.3.2/state.json \\\n  --package-set-json package-set.json \\\n  --impact-json impact.json \\\n  --trusted-publishing-json trusted-publishing.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v2.3.2/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n  --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v2/v2.3\"}' \\\n  --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n  --repository kungfu-systems/libnode \\\n  --tag v22.22.3-kf.3-alpha.18 \\\n  --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n   Release asset URLs, or `--repository <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n  \"locators\": [\n    {\n      \"match\": {\n        \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n        \"digest\": \"sha256:...\"\n      },\n      \"passport\": \"../release-passport/buildchain.release.json\"\n    }\n  ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v2/v2.2\nbuildchain release --dry-run --target-ref release/v2/v2.2 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v2/v2.2\nbuildchain release explain --target-ref alpha/v2/v2.1 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v2.1.0-alpha.0\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v2.0.13-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v2.0.13` publishes to npm with dist-tag `latest`.\n- moving refs such as `v2`, `v2.0`, and `v2.0-alpha` do not match the publish\n  workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
     },
     {
       "id": "manual:consumer-issue-reporting",
@@ -775,7 +775,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/MAP.md",
-      "digest": "sha256:7e1b72dfc0ad91323156295617e320fee94a644efee54667b017e690fcebf64e",
+      "digest": "sha256:886d073bd37ac655e1ad9659baf161c72ef796b6032c5c3332218ac8198c2aeb",
       "headings": [
         {
           "level": 1,
@@ -803,7 +803,7 @@
           "anchor": "how-this-map-is-maintained"
         }
       ],
-      "markdown": "# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v2 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |\n| KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |\n| KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |\n| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |\n| Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, and site-consumable manifests? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |\n| How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **v2.1 vs v2.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v2` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
+      "markdown": "# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v2 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |\n| KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |\n| KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |\n| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |\n| Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, site-consumable manifests, npm packages, and GitHub Releases? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |\n| How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **v2.1 vs v2.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v2` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
     },
     {
       "id": "manual:migration-inventory",
@@ -966,7 +966,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:1088128dc3773bfeb6ed0e619eaae3096987e1f02a8eb3f0d0415cf903cfa682",
+      "digest": "sha256:d4a6057fa7836ea7ba919c72b6231ea568f43f2b59f19da3b1cc715ed0d3549f",
       "headings": [
         {
           "level": 1,
@@ -983,6 +983,11 @@
           "title": "Reusable Workflow",
           "anchor": "reusable-workflow"
         },
+        {
+          "level": 2,
+          "title": "Paper Release Preset",
+          "anchor": "paper-release-preset"
+        },
         {
           "level": 2,
           "title": "CLI And Node API",
@@ -994,7 +999,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release.yml@v2\n    permissions:\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      toolchain-type: config\n      verify-command: make check\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe preset:\n\n- resolves the same floating Buildchain runtime and contract lock as the build\n  workflow;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- publishes the package through npm Trusted Publishing;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publish-transaction",
@@ -2177,7 +2182,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:7e1b72dfc0ad91323156295617e320fee94a644efee54667b017e690fcebf64e"
+      "digest": "sha256:886d073bd37ac655e1ad9659baf161c72ef796b6032c5c3332218ac8198c2aeb"
     },
     {
       "id": "install",
@@ -2297,7 +2302,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4b31f7ff5330cde8ab32b237f533c7af76463cce570d67dd14669c3a14c83c84"
+      "digest": "sha256:81624885888c9e357db128f644f93dcab2286910df426b532730b0141d7cb00d"
     },
     {
       "id": "build-facts",

package/dist/site/capability-registry.json

@@ -82,9 +82,9 @@
       "counts": {
         "manualCount": 3,
         "pageCount": 15,
-        "cliCommandCount": 3,
-        "nodeApiCount": 2,
-        "workflowCount": 2,
+        "cliCommandCount": 4,
+        "nodeApiCount": 3,
+        "workflowCount": 3,
         "actionCount": 2
       },
       "manuals": [

package/dist/site/cli-registry.json

@@ -677,6 +677,18 @@
       ],
       "maturity": "stable"
     },
+    {
+      "id": "publication-artifact-npm-package",
+      "source": "bin/buildchain.mjs",
+      "usage": "buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]",
+      "purpose": "Synthesize the declared npm paper package from a publication artifact manifest, passport, registry, source bundle, and primary artifact.",
+      "capabilityGroup": "reusable-build",
+      "audience": [
+        "agent",
+        "operator"
+      ],
+      "maturity": "stable"
+    },
     {
       "id": "publish-source",
       "source": "bin/buildchain.mjs",