@kungfu-tech/buildchain 2.8.17 → 2.9.0

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-08T00:24:24.491Z",
-  "publishedAt": "2026-07-08T00:24:24.491Z",
+  "generatedAt": "2026-07-08T02:47:46.506Z",
+  "publishedAt": "2026-07-08T02:47:46.506Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "186482073690d8f922f5f4ecbea20849dda724a4",
+  "sourceRevision": "2142b74c1ce1b6be6e2227ffe53ba87750afde07",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.8.17",
+    "version": "2.9.0",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -78,7 +78,7 @@
       "route": "/",
       "category": "overview",
       "sourcePath": "README.md",
-      "digest": "sha256:38fb511bf7f90b227757d4df27de683fcb5138adc304b5543a7be787d43b508e",
+      "digest": "sha256:b2b09c09a85739b29e269d2c658459128ffce95188a6582edcda74e0271b714b",
       "headings": [
         {
           "level": 1,
@@ -136,7 +136,7 @@
           "anchor": "read-next"
         }
       ],
-      "markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\n[![KFD-1: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-1/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-2: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-2/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-3: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-3/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)\n[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Install and Verify\n\nFor standalone use, install a platform archive from a GitHub Release and verify\nthe release passport before trusting the binary:\n\n```bash\n# Example for Linux x64. Use the archive that matches your platform.\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain-x86_64-unknown-linux-gnu.tar.gz\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/artifact-evidence.json\nnpx @kungfu-tech/buildchain verify release-passport buildchain.release.json\ntar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz\n./buildchain version\n```\n\nRelease pages publish platform archives, checksums, release passport files, and\na single evidence bundle:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n  license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n  identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n  services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n  posture for GitHub, npm, cloud, credential, release evidence, and other\n  provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectRunnerDiagnostics,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n});\n```\n\n`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: v2\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2\n```\n\nBuildchain supports package and non-package projects through `buildchain.toml`.\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nBuildchain's active GitHub Action surface is deliberately small:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v2\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2\n```\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path | Meaning | Exact tag | Floating refs |\n| --- | --- | --- | --- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y` | publish the next testable alpha for a minor line | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y` |\n| `alpha/vX/vX.Y -> release/vX/vX.Y` | publish production for that minor line | `vX.Y.Z` | `vX.Y`, usually `vX`, `release/vX/vX.Y` |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0` | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n  binary verification.\n- Use signal: the start of `Use Buildchain`, especially the reusable workflow\n  and action surfaces.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Release governance](docs/release-governance.md)",
+      "markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\n[![KFD-1: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-1/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-2: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-2/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-3: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-3/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)\n[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Install and Verify\n\nFor standalone use, install a platform archive from a GitHub Release and verify\nthe release passport before trusting the binary:\n\n```bash\n# Example for Linux x64. Use the archive that matches your platform.\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain-x86_64-unknown-linux-gnu.tar.gz\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/artifact-evidence.json\nnpx @kungfu-tech/buildchain verify release-passport buildchain.release.json\ntar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz\n./buildchain version\n```\n\nRelease pages publish platform archives, checksums, release passport files, and\na single evidence bundle:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n  license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n  identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n  services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n  posture for GitHub, npm, cloud, credential, release evidence, and other\n  provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectRunnerDiagnostics,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n});\n```\n\n`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: v2\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2\n```\n\nBuildchain supports package and non-package projects through `buildchain.toml`.\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nBuildchain's active GitHub Action surface is deliberately small:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v2\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2\n```\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path | Meaning | Exact tag | Floating refs |\n| --- | --- | --- | --- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y` | publish the next testable alpha for a minor line | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y` |\n| `alpha/vX/vX.Y -> release/vX/vX.Y` | publish production for that minor line | `vX.Y.Z` | `vX.Y`, usually `vX`, `release/vX/vX.Y` |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0` | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n  binary verification.\n- Use signal: the start of `Use Buildchain`, especially the reusable workflow\n  and action surfaces.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Release governance](docs/release-governance.md)",
       "slug": "home"
     },
     {
@@ -224,7 +224,7 @@
       "route": "/api/node-package",
       "category": "api",
       "sourcePath": "packages/core/README.md",
-      "digest": "sha256:ffbe30327d6ca9c2f257dd561dd9e5dd3bb62c1feacf3165bb1a60a58e4fe518",
+      "digest": "sha256:3f6e0f6ad0227dc82cd31699ba7e805b5d9d24cd9e99a325e0b536309f8e0f65",
       "headings": [
         {
           "level": 1,
@@ -237,7 +237,7 @@
           "anchor": "toolkit-imports"
         }
       ],
-      "markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n  `@kungfu-tech/buildchain/diagnostics`;\n- release passport creation and verification through\n  `@kungfu-tech/buildchain/release-passport`.\n- managed README badge facts and marker blocks through\n  `@kungfu-tech/buildchain/readme-badges`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n  BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n  BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n  collectRunnerDiagnostics,\n  summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public subpath and treat Markdown as a\nprojection of the returned facts:\n\n```js\nimport { collectReadmeBadgeFacts, renderReadmeBadgeBlock } from \"@kungfu-tech/buildchain/readme-badges\";\n\nconst facts = await collectReadmeBadgeFacts({ cwd: process.cwd() });\nconst markdown = renderReadmeBadgeBlock(facts);\n```",
+      "markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n  `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n  `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n  `@kungfu-tech/buildchain/release-passport`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n  through `@kungfu-tech/buildchain/badges`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n  BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n  BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n  collectRunnerDiagnostics,\n  summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nBuild facts consumers can collect source-bound module/product facts before\npublishing and pass those facts into the release passport:\n\n```js\nimport { collectModuleBuildFacts, writeBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\n\nconst fact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact, output: \".buildchain/facts/native-core.json\" });\n```\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public badge subpath and treat\nMarkdown as a projection of the returned facts:\n\n```js\nimport { collectBadgeBundleFacts, renderBadgeBundleBlock } from \"@kungfu-tech/buildchain/badges\";\n\nconst facts = await collectBadgeBundleFacts({ cwd: process.cwd() });\nconst markdown = renderBadgeBundleBlock(facts);\n```\n\nThe older `@kungfu-tech/buildchain/readme-badges` subpath remains available for\ncallers that need the full README badge surface instead of the default\nKFD-1 / KFD-2 / KFD-3 / Release Passport bundle.",
       "slug": "node-package"
     },
     {
@@ -276,13 +276,54 @@
       ],
       "markdown": "# Binary Distribution\n\nBuildchain's binary distribution is the first high-pressure proof case for the\nRelease Passport protocol. It is not the boundary of the product.\n\n## Asset Rules\n\nGitHub Release assets use platform-specific archives:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe release lane does not upload loose top-level `buildchain` or\n`buildchain.exe` assets. Linux and macOS both name the executable `buildchain`\ninside their archives, so top-level loose assets would collide when matrix\nartifacts are merged.\n\nRelease asset upload is gated before the matrix starts. Manual\n`workflow_dispatch` runs are binary dry-runs only and must keep\n`upload-release=false`; real GitHub Release uploads must come from a true\n`v*` tag-triggered run so an invalid manual upload request cannot spend the\nthree-platform build matrix and then fail at `gh release upload`.\n\nGitHub Release metadata is deterministic and tag-derived. Exact alpha tags such\nas `v2.6.2-alpha.0` are created or updated with `prerelease=true` and\n`make_latest=false`; exact stable tags such as `v2.6.1` are created or updated\nwith `prerelease=false` and `make_latest=true`. The workflow uses\n`scripts/ensure-github-release.mjs` before asset upload instead of relying on\nGitHub's default latest-release heuristic.\n\nEach archive is accompanied by:\n\n- a platform manifest from the standalone binary builder;\n- platform observability event logs and summaries;\n- `checksums.txt`;\n- Release Passport evidence files;\n- `buildchain-release-bundle.tar.gz`;\n- `buildchain-release-bundle.json`.\n\n## Runner Policy\n\nProduction binary builds use GitHub-hosted runners:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners are compatibility fixtures. They can prove that consumers\nwith private runner fleets can still use the protocol, but Buildchain's public\nbinary distribution should stay reproducible on GitHub-hosted runners.\n\n## Evidence Bundle\n\n`buildchain-release-bundle.tar.gz` groups release assets and passport evidence\nunder one archive:\n\n```text\nbuildchain-release-bundle/\n  release-assets/\n  release-passport/\n  buildchain-release-bundle.index.json\n```\n\n`buildchain-release-bundle.json` records the bundle digest and every included\nfile digest. Consumers can download the bundle when they want one artifact for\noffline review, mirroring, or site ingestion.\n\n## Local Smoke\n\n```bash\nnode scripts/build-standalone-binary.mjs --version v0.0.0-local --output-dir dist/binary\nnode bin/buildchain.mjs collect github-release \\\n  --tag v0.0.0-local \\\n  --assets-dir dist/binary \\\n  --output-dir .buildchain/release-passport\nnode scripts/create-release-bundle.mjs \\\n  --assets-dir dist/binary \\\n  --passport-dir .buildchain/release-passport \\\n  --output-dir .buildchain/release-passport \\\n  --tag v0.0.0-local\n```"
     },
+    {
+      "id": "manual:build-facts",
+      "title": "Build Facts",
+      "route": "/docs/build-facts",
+      "category": "manual",
+      "sourcePath": "docs/build-facts.md",
+      "digest": "sha256:75dcf7a6628dac9e982a455de9966044ae771611d4efc04e7264a2d4adb0bd3e",
+      "headings": [
+        {
+          "level": 1,
+          "title": "Build Facts",
+          "anchor": "build-facts"
+        },
+        {
+          "level": 2,
+          "title": "Config",
+          "anchor": "config"
+        },
+        {
+          "level": 2,
+          "title": "CLI",
+          "anchor": "cli"
+        },
+        {
+          "level": 2,
+          "title": "Node API",
+          "anchor": "node-api"
+        },
+        {
+          "level": 2,
+          "title": "Release Passport Integration",
+          "anchor": "release-passport-integration"
+        },
+        {
+          "level": 2,
+          "title": "Kungfu Legacy Projection",
+          "anchor": "kungfu-legacy-projection"
+        }
+      ],
+      "markdown": "# Build Facts\n\nBuild Facts are Buildchain's machine-readable record of what a repository\nbuilt. They sit between lifecycle logs and release passports:\n\n- lifecycle logs explain what ran and how long it took;\n- module build facts bind one module to its Git source digest, version source,\n  platform, lifecycle invocation, and output digests;\n- product build facts aggregate module facts and product artifacts;\n- release passports can carry build facts as first-class evidence.\n\nThe goal is to remove handwritten build metadata from consumer repositories.\nConsumers declare where their version and outputs live; Buildchain collects and\nverifies the facts.\n\n## Config\n\nDeclare build facts in `buildchain.toml`:\n\n```toml\nschema = 1\n\n[[facts.version_sources]]\nid = \"package\"\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[[facts.modules]]\nid = \"native-core\"\nroot = \"src/core\"\nscope = \"core\"\nversion_source = \"package\"\nlifecycle = \"build\"\noutputs = [\"dist/core.node\"]\n\n[[facts.products]]\nid = \"kungfu\"\nmodule_facts = [\".buildchain/facts/native-core.json\"]\nartifacts = [\"dist/kungfu.zip\"]\n\n[[facts.legacy_projections]]\ntype = \"kungfu-buildinfo\"\nmodule = \"native-core\"\npath = \"framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\"\n```\n\nSupported version sources:\n\n- `static`: an explicit `value`;\n- `json`: a JSON file plus dotted `key`;\n- `toml`: a TOML file plus dotted `key`;\n- `regex`: a text file plus regex `pattern`, using a named `version` group or\n  the first capture group;\n- `command`: an explicit command whose output is the version.\n\nPrefer file-based sources. Command sources are allowed for legacy projects but\nare marked as less reproducible because the command output is not a static\nsource file.\n\n## CLI\n\nCollect a module fact:\n\n```bash\nbuildchain facts module \\\n  --module native-core \\\n  --output .buildchain/facts/native-core.json\n```\n\nOverride declarative config from a workflow step when needed:\n\n```bash\nbuildchain facts module \\\n  --cwd \"$GITHUB_WORKSPACE\" \\\n  --module native-core \\\n  --module-root src/core \\\n  --version-source package \\\n  --output-path dist/core.node \\\n  --output .buildchain/facts/native-core.json \\\n  --json\n```\n\nWrite the Kungfu legacy `kungfubuildinfo.json` projection from the same module\nfact:\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```\n\nAggregate product facts:\n\n```bash\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```\n\nVerify a fact before publishing:\n\n```bash\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nVerification fails closed when a declared output is missing, an output digest is\nstale, a module fact was collected from a different Git `HEAD`, or a source\ndigest no longer matches the tracked source files.\n\n## Node API\n\n```js\nimport {\n  aggregateBuildFacts,\n  collectModuleBuildFacts,\n  verifyBuildFacts,\n  writeBuildFacts,\n  writeKungfuBuildInfoProjection,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst moduleFact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact: moduleFact, output: \".buildchain/facts/native-core.json\" });\n\nconst productFact = aggregateBuildFacts({ productId: \"kungfu\" });\nconst verification = verifyBuildFacts({ fact: productFact });\n```\n\nThe root package export also re-exports these APIs from\n`@kungfu-tech/buildchain`.\n\n## Release Passport Integration\n\nPass build facts into a release passport:\n\n```bash\nbuildchain collect github-release \\\n  --tag \"$TAG\" \\\n  --assets-dir dist \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/kungfu.json \\\n  --output-dir .buildchain/release-passport\n```\n\nThe passport records the full build facts in `buildFacts[]` and a compact\nevidence index in `evidence.buildFacts[]`. Agents can start from\n`buildchain.release.json`, discover the module/product facts, and verify that\nthe released artifacts still match the declared source, version, and output\nfacts.\n\n## Kungfu Legacy Projection\n\nKungfu historically consumes `kungfubuildinfo.json`. Buildchain now treats that\nfile as a projection of module build facts, not as an independent source of\ntruth. The projection preserves legacy fields such as `version`,\n`python_version`, `git_branch`, `git_revision`, and `git_pristine`, while adding\na `buildchain` section that points back to the module fact digest, version\nsource digest, and source digest.\n\nRepositories that no longer need the legacy file should consume the module and\nproduct facts directly."
+    },
     {
       "id": "manual:cli",
       "title": "Buildchain CLI, npm Package, and Toolkit API",
       "route": "/docs/cli",
       "category": "manual",
       "sourcePath": "docs/cli.md",
-      "digest": "sha256:cfb0bf32f2b8b44bf352e79c27e34b7980e0f66e5fa10e4f202975fbb4780ad1",
+      "digest": "sha256:60686b5b4d5fe7f3944cb53ab709231fd00bb02b6d51770f1fe8b018122afd8f",
       "headings": [
         {
           "level": 1,
@@ -310,7 +351,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.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\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 contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.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\" };\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.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 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.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\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 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.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 publish-source`, `buildchain badges`, `buildchain homebrew`, and\n`buildchain build-contract` route 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, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --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`. See [`readme-badges.md`](readme-badges.md) for the marker contract\nand `[badges]` 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-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/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\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.\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.\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 contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.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\" };\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.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 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.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\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.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 publish-source`, `buildchain badges`, `buildchain homebrew`, and\n`buildchain build-contract` route 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, 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-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/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\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.\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",
@@ -543,7 +584,7 @@
       "route": "/docs/map",
       "category": "manual",
       "sourcePath": "docs/MAP.md",
-      "digest": "sha256:03f52660d03223fff7daf500f995645d78a46fffd8cddec9d8c01bbee0863145",
+      "digest": "sha256:2d95d0dd56088efb1a9a16d026810cf2e74659963612451f903e37825c260122",
       "headings": [
         {
           "level": 1,
@@ -571,7 +612,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| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\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| 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| 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/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| Generated README badge blocks and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `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 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 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 I generate README status badges 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) | 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- **release chains / upstream package as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **README status badges / KFD badge blocks / 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| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\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| 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/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.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 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 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) | 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 as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.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",
@@ -778,7 +819,7 @@
       "route": "/docs/readme-badges",
       "category": "manual",
       "sourcePath": "docs/readme-badges.md",
-      "digest": "sha256:c886d5d469d143571ae68497643be754b1616b562fddc780a5708f49b4c46242",
+      "digest": "sha256:06eaef737dcc73a6526d856d79275ee87af9670f0e2be39a5596758bfc3527c9",
       "headings": [
         {
           "level": 1,
@@ -811,7 +852,7 @@
           "anchor": "ci-contract"
         }
       ],
-      "markdown": "# README Badge Blocks\n\nBuildchain can generate a managed README badge block from repository-owned\nfacts. The README keeps only a projection; the source facts remain in\n`buildchain.toml`, package metadata, workflow files, KFD standards metadata,\nand the repository's own release passport.\n\nThe managed block is delimited by:\n\n```markdown\n<!-- buildchain:badges:start -->\n...\n<!-- buildchain:badges:end -->\n```\n\nBuildchain owns only that block. Everything outside the markers remains normal\nREADME content.\n\n## Node API\n\nUse the public package export:\n\n```js\nimport {\n  collectReadmeBadgeFacts,\n  renderReadmeBadgeBlock,\n  checkReadmeBadgeBlock,\n  updateReadmeBadgeBlock,\n} from \"@kungfu-tech/buildchain/readme-badges\";\n```\n\n`collectReadmeBadgeFacts({ cwd })` returns a machine-readable object with\ncontract `kungfu-buildchain-readme-badge-facts`. It collects repository\nidentity, package name/version/license, configured platforms, configured\nworkflow status badges, the repository's own Buildchain Release Passport\nlocation and verification result, and KFD badge state. KFD badge labels,\nhuman-facing concept text, standard document links, schema IDs, and interface\ncontracts are read from\n`@kungfu-tech/kfd/standards.json` when the package is installed, or from an\nexplicit `kfd_standards` path/URL. When present, it also summarizes local KFD\nclaim registry and product-mechanism facts from the package-owned site bundle,\nso downstream agents can connect README badges back to Buildchain's\nKFD/source-of-truth surfaces.\n\n`renderReadmeBadgeBlock(facts)` renders deterministic Markdown from that facts\nobject. `checkReadmeBadgeBlock({ readmeText, facts })` compares the current\nREADME marker block against the expected block and reports missing or stale\ndrift. `updateReadmeBadgeBlock({ readmeText, facts })` inserts or replaces the\nmanaged block.\n\nThe Node API is the implementation source. The CLI delegates to it.\n\n## CLI\n\nGenerate facts as JSON:\n\n```bash\nbuildchain badges readme --json\n```\n\nFail closed when the README block is missing or stale:\n\n```bash\nbuildchain badges readme --check\n```\n\nInsert or replace the block:\n\n```bash\nbuildchain badges readme --write\n```\n\nAll commands accept `--cwd <dir>` and `--readme <path>`. Repositories can add\n`buildchain badges readme --check` to CI so badge drift is detected like any\nother generated release-facing surface.\n\n## Configuration\n\nThe optional `[badges]` table in `buildchain.toml` declares local facts that\ncannot be inferred safely:\n\n```toml\n[badges]\nrelease_passport = \"https://github.com/example/project/releases/latest/download/buildchain.release.json\"\nkfd_standards = \"node_modules/@kungfu-tech/kfd/standards.json\"\nkfd_1 = \"declared\"\nkfd_2 = \"planned\"\nkfd_3 = \"aligned\"\nplatforms = [\"macOS\", \"Linux\", \"Windows\"]\nworkflows = [\"verify.yml\", \"build.yml\"]\n```\n\n`release_passport` may be a local path or URL. If omitted, Buildchain tries\n`buildchain.release.json`, then `.buildchain/release-passport/buildchain.release.json`,\nthen the repository's latest GitHub Release asset when the GitHub repository\ncan be discovered.\n\nThe generated `Buildchain Release Passport` badge is a repository capability\nbadge: it says whether the current repository has a Buildchain release passport\nthat can be verified. It does not report the upstream `kungfu-systems/buildchain`\nrepository status. Buildchain's own README dogfoods the same rule because its\nconfigured `release_passport` points at Buildchain's own release passport.\n\nBuildchain-owned badges use stable hosted image URLs by default:\n\n```text\nhttps://buildchain.libkungfu.dev/badges/v1/{badge}/{state}.svg\n```\n\nThe URL is part of the Buildchain badge contract. Consumers do not need to\nregenerate README files when Buildchain replaces the placeholder badge logo\nwith a formal logo; the hosted endpoint owns logo rendering. The package-owned\nsite bundle publishes `badge-endpoint-registry.json` plus Shields-compatible\nJSON payloads under `badges/v1/**` so the site repository can serve or render\nthe exact SVG endpoints without inventing badge facts.\n\nForks or private deployments can override the image host with:\n\n```toml\n[badges]\nbadge_endpoint_base_url = \"https://example.com/buildchain-badges/v1\"\n```\n\n`kfd_standards` is optional. If omitted, Buildchain tries the installed\n`@kungfu-tech/kfd/standards.json` package export. Use the explicit path or URL\nonly when a repository deliberately vendors KFD standards metadata or validates\nagainst a local KFD development checkout. The KFD standards metadata controls\nthe badge vocabulary; the release passport still controls whether a repository\nmay display a KFD state as `passed`.\n\n## KFD Badge Rules\n\nKFD passed is evidence-backed. A repository may display `KFD-1 passed`,\n`KFD-2 passed`, or `KFD-3 passed` only when its own release passport verifies\nsuccessfully and the corresponding passport section has `status: \"passed\"`.\nThe KFD badge vocabulary comes from KFD standards metadata, not Buildchain\nprivate strings: for example KFD-2 uses the `releaseTrustPassport` concept from\n`@kungfu-tech/kfd/standards.json`.\n\nWhen no release passport exists yet, or when the passport cannot be verified,\nBuildchain downgrades each KFD badge to the explicit local declaration such as\n`declared`, `aligned`, or `planned`. A local `passed` declaration is treated as\n`declared`; unknown local states are normalized to a non-passed fallback.\n\nBuildchain's own README may link to Buildchain's own release passport. Other\nrepositories must not claim Buildchain's KFD status as their own; their badge\nlinks must point to their own release passport or evidence page.\n\n## CI Contract\n\nRecommended CI gate:\n\n```bash\nbuildchain badges readme --check\n```\n\nThe check fails when:\n\n- the marker block is missing;\n- generated Markdown differs from repository facts;\n- a previously hand-written KFD passed claim is not backed by the repository's\n  verified release passport facts.\n\nThe machine-readable facts object should be used by downstream site renderers\nor audit tools when Markdown badges are not enough."
+      "markdown": "# README Badge Blocks\n\nBuildchain can generate a managed README badge block from repository-owned\nfacts. The README keeps only a projection; the source facts remain in\n`buildchain.toml`, package metadata, workflow files, KFD standards metadata,\nand the repository's own release passport.\n\nThe managed block is delimited by:\n\n```markdown\n<!-- buildchain:badges:start -->\n...\n<!-- buildchain:badges:end -->\n```\n\nBuildchain owns only that block. Everything outside the markers remains normal\nREADME content.\n\n## Node API\n\nUse the public package export:\n\n```js\nimport {\n  collectBadgeBundleFacts,\n  collectReadmeBadgeFacts,\n  renderBadgeBundleBlock,\n  renderReadmeBadgeBlock,\n  checkBadgeBundleBlock,\n  checkReadmeBadgeBlock,\n  updateBadgeBundleBlock,\n  updateReadmeBadgeBlock,\n} from \"@kungfu-tech/buildchain/badges\";\n```\n\n`@kungfu-tech/buildchain/readme-badges` remains available for compatibility,\nbut new integrations should use `@kungfu-tech/buildchain/badges`.\n\n`collectReadmeBadgeFacts({ cwd })` returns a machine-readable object with\ncontract `kungfu-buildchain-readme-badge-facts`. It collects repository\nidentity, package name/version/license, configured platforms, configured\nworkflow status badges, the repository's own Buildchain Release Passport\nlocation and verification result, and KFD badge state. KFD badge labels,\nhuman-facing concept text, standard document links, schema IDs, and interface\ncontracts are read from\n`@kungfu-tech/kfd/standards.json` when the package is installed, or from an\nexplicit `kfd_standards` path/URL. When present, it also summarizes local KFD\nclaim registry and product-mechanism facts from the package-owned site bundle,\nso downstream agents can connect README badges back to Buildchain's\nKFD/source-of-truth surfaces.\n\n`renderReadmeBadgeBlock(facts)` renders deterministic Markdown from that facts\nobject. `checkReadmeBadgeBlock({ readmeText, facts })` compares the current\nREADME marker block against the expected block and reports missing or stale\ndrift. `updateReadmeBadgeBlock({ readmeText, facts })` inserts or replaces the\nmanaged block.\n\nThe Node API is the implementation source. The CLI delegates to it.\n\n`collectBadgeBundleFacts({ cwd, claims })` is the trust-badge bundle API. It\nuses the same repository facts, but returns contract\n`kungfu-buildchain-badge-bundle-facts` and only renders the Buildchain trust\nclaims: `kfd-1`, `kfd-2`, `kfd-3`, and `release-passport`. Those four claims are\nenabled by default. Callers can pass `claims: \"kfd-1,release-passport\"` or an\narray to narrow the bundle without hand-writing badge Markdown.\n\n## CLI\n\nGenerate facts as JSON:\n\n```bash\nbuildchain badges readme --json\n```\n\nFail closed when the README block is missing or stale:\n\n```bash\nbuildchain badges readme --check\n```\n\nInsert or replace the block:\n\n```bash\nbuildchain badges readme --write\n```\n\nGenerate only the Buildchain trust badge bundle:\n\n```bash\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\n```\n\nNarrow the bundle to specific claims:\n\n```bash\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nAll commands accept `--cwd <dir>` and `--readme <path>`. Repositories can add\n`buildchain badges bundle --check` or `buildchain badges readme --check` to CI\nso badge drift is detected like any other generated release-facing surface.\n\n## Configuration\n\nThe optional `[badges]` table in `buildchain.toml` declares local facts that\ncannot be inferred safely:\n\n```toml\n[badges]\nrelease_passport = \"https://github.com/example/project/releases/latest/download/buildchain.release.json\"\nkfd_standards = \"node_modules/@kungfu-tech/kfd/standards.json\"\nkfd_1 = \"declared\"\nkfd_2 = \"planned\"\nkfd_3 = \"aligned\"\nplatforms = [\"macOS\", \"Linux\", \"Windows\"]\nworkflows = [\"verify.yml\", \"build.yml\"]\n\n[badges.bundle]\nclaims = [\"kfd-1\", \"kfd-2\", \"kfd-3\", \"release-passport\"]\n```\n\n`release_passport` may be a local path or URL. If omitted, Buildchain tries\n`buildchain.release.json`, then `.buildchain/release-passport/buildchain.release.json`,\nthen the repository's latest GitHub Release asset when the GitHub repository\ncan be discovered.\n\nThe generated `Buildchain Release Passport` badge is a repository capability\nbadge: it says whether the current repository has a Buildchain release passport\nthat can be verified. It does not report the upstream `kungfu-systems/buildchain`\nrepository status. Buildchain's own README dogfoods the same rule because its\nconfigured `release_passport` points at Buildchain's own release passport.\n\nBuildchain-owned badges use stable hosted image URLs by default:\n\n```text\nhttps://buildchain.libkungfu.dev/badges/v1/{badge}/{state}.svg\n```\n\nThe URL is part of the Buildchain badge contract. Consumers do not need to\nregenerate README files when Buildchain replaces the placeholder badge logo\nwith a formal logo; the hosted endpoint owns logo rendering. The package-owned\nsite bundle publishes `badge-endpoint-registry.json` plus Shields-compatible\nJSON payloads under `badges/v1/**` so the site repository can serve or render\nthe exact SVG endpoints without inventing badge facts.\n\nForks or private deployments can override the image host with:\n\n```toml\n[badges]\nbadge_endpoint_base_url = \"https://example.com/buildchain-badges/v1\"\n```\n\n`kfd_standards` is optional. If omitted, Buildchain tries the installed\n`@kungfu-tech/kfd/standards.json` package export. Use the explicit path or URL\nonly when a repository deliberately vendors KFD standards metadata or validates\nagainst a local KFD development checkout. The KFD standards metadata controls\nthe badge vocabulary; the release passport still controls whether a repository\nmay display a KFD state as `passed`.\n\n## KFD Badge Rules\n\nKFD passed is evidence-backed. A repository may display `KFD-1 passed`,\n`KFD-2 passed`, or `KFD-3 passed` only when its own release passport verifies\nsuccessfully and the corresponding passport section has `status: \"passed\"`.\nThe KFD badge vocabulary comes from KFD standards metadata, not Buildchain\nprivate strings: for example KFD-2 uses the `releaseTrustPassport` concept from\n`@kungfu-tech/kfd/standards.json`.\n\nWhen no release passport exists yet, or when the passport cannot be verified,\nBuildchain downgrades each KFD badge to the explicit local declaration such as\n`declared`, `aligned`, or `planned`. A local `passed` declaration is treated as\n`declared`; unknown local states are normalized to a non-passed fallback.\n\nBuildchain's own README may link to Buildchain's own release passport. Other\nrepositories must not claim Buildchain's KFD status as their own; their badge\nlinks must point to their own release passport or evidence page.\n\n## CI Contract\n\nRecommended CI gate:\n\n```bash\nbuildchain badges readme --check\n```\n\nor, when the repository only wants the Buildchain trust bundle:\n\n```bash\nbuildchain badges bundle --check\n```\n\nThe check fails when:\n\n- the marker block is missing;\n- generated Markdown differs from repository facts;\n- a previously hand-written KFD passed claim is not backed by the repository's\n  verified release passport facts.\n\nThe machine-readable facts object should be used by downstream site renderers\nor audit tools when Markdown badges are not enough."
     },
     {
       "id": "manual:release-candidate",
@@ -982,7 +1023,7 @@
       "route": "/docs/release-passport",
       "category": "manual",
       "sourcePath": "docs/release-passport.md",
-      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094",
+      "digest": "sha256:495e1c46ce45268a9ed6502fe115af45a8cd1d8e644cb4332da9b551f919f578",
       "headings": [
         {
           "level": 1,
@@ -1030,7 +1071,7 @@
           "anchor": "binary-distribution"
         }
       ],
-      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: exact tag, line, channel, source SHA, target ref, release SHA,\n  release material SHA, publish tooling SHA, and durable release-state ref.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.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.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
+      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: exact tag, line, channel, source SHA, target ref, release SHA,\n  release material SHA, publish tooling SHA, and durable release-state ref.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `buildFacts`: module/product build facts that bind Git source digests,\n  version sources, lifecycle invocations, platforms, outputs, product\n  artifacts, and verification results to the release.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/product.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.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport. `buildFacts[]`\nrecords first-class module/product build facts, while\n`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,\nids, and digests for quick audit traversal. See\n[`build-facts.md`](build-facts.md) for the fact collection and verification\ncontract.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
     },
     {
       "id": "manual:release-propagation",
@@ -1298,7 +1339,7 @@
       "route": "/docs/versioning",
       "category": "manual",
       "sourcePath": "docs/versioning.md",
-      "digest": "sha256:77b92fc979cc100beab3f8a13cd791dea992737b986ace505104edff4810a296",
+      "digest": "sha256:2c79f7d1a072a40c75d889beac38ae843b2170587fc570ce40722d3968b6506e",
       "headings": [
         {
           "level": 1,
@@ -1326,7 +1367,7 @@
           "anchor": "runner-policy"
         }
       ],
-      "markdown": "# Buildchain Versioning\n\nBuildchain uses semantic version lines to describe public contracts, not only\ncode size. A release can be small in diff size and still open a new minor line\nwhen it adds a durable surface that consumers, workflows, or agents can depend\non.\n\n## Lines\n\n| Line | Meaning |\n| --- | --- |\n| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface. |\n| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |\n| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite. |\n\nKungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each\nreceive many patch releases. The major ref, such as `v2`, points at the\nselected stable major entrypoint; the minor ref, such as `v2.2`, points at the\nlatest stable production patch for that minor line.\n\n## Welded Surfaces\n\nThese surfaces are classified independently; the final release impact is the\nhighest impact across the affected registered surfaces:\n\n- reusable workflow inputs, outputs, and artifact contracts;\n- public CLI command families and their machine-readable JSON shapes;\n- public npm exports such as `@kungfu-tech/buildchain/logging`;\n- config protocols such as `buildchain.toml`;\n- release governance state machines and protected ref semantics;\n- release evidence contracts such as passport, artifact evidence, impact\n  ledger, and agent index files;\n- binary distribution shapes that users can install or automate against.\n\nFor each surface:\n\n- content, documentation, or implementation-only work that does not touch a\n  registered surface is patch;\n- additive fields, new commands, new exports, new evidence sections, or new\n  registered surfaces are minor;\n- removals, incompatible renames, changed meanings, newly required fields,\n  weakened trust gates, or changed ref flow are major.\n\nThe release passport records this as `surfaceImpacts[]` plus\n`versionImpact.final`. The final impact must equal the highest surface impact,\nso an agent cannot silently label a release patch when one machine surface needs\nminor review.\n\n`surfaceImpacts[]` is mandatory for production release passports (`release/*`)\nand major publish-gate passports. Alpha, local, and legacy passport contexts\nkeep the field optional so temporary validation can proceed without pretending\nto be a production release decision.\n\nExample: a KFD document such as KFD-2 is content and remains patch, but adding a\n`kind` field to the machine-consumed KFD `registry.json` is an additive change\nto the `kfd-registry-schema` surface and therefore requires minor-impact\nreview. This avoids both false shortcuts: \"new KFD means minor\" and \"all KFD\nrepository changes are patch\".\n\n## Decision Log\n\n| Date | Action | Line | Faces | Class | Rationale | PR |\n| --- | --- | --- | --- | --- | --- | --- |\n| 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |\n| 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |\n| 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |\n| 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |\n| 2026-07-02 | open-minor | `v2.2` | release-passport, binary-distribution | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. | |\n| 2026-07-02 | open-minor | `v2.1` | logging-sdk, cli-observability, package-subpaths | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. | |\n\n## Runner Policy\n\nThe `v2.2` binary distribution lane uses GitHub-hosted runners for production\nassets because that is the easiest release path for external users to reproduce:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners remain compatibility fixtures. They prove Buildchain's\nprotocol does not depend on GitHub-hosted images, but they do not define the\npublic binary distribution path."
+      "markdown": "# Buildchain Versioning\n\nBuildchain uses semantic version lines to describe public contracts, not only\ncode size. A release can be small in diff size and still open a new minor line\nwhen it adds a durable surface that consumers, workflows, or agents can depend\non.\n\n## Lines\n\n| Line | Meaning |\n| --- | --- |\n| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface. |\n| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |\n| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite. |\n\nKungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each\nreceive many patch releases. The major ref, such as `v2`, points at the\nselected stable major entrypoint; the minor ref, such as `v2.2`, points at the\nlatest stable production patch for that minor line.\n\n## Welded Surfaces\n\nThese surfaces are classified independently; the final release impact is the\nhighest impact across the affected registered surfaces:\n\n- reusable workflow inputs, outputs, and artifact contracts;\n- public CLI command families and their machine-readable JSON shapes;\n- public npm exports such as `@kungfu-tech/buildchain/logging`;\n- config protocols such as `buildchain.toml`;\n- release governance state machines and protected ref semantics;\n- release evidence contracts such as passport, artifact evidence, impact\n  ledger, and agent index files;\n- binary distribution shapes that users can install or automate against.\n\nFor each surface:\n\n- content, documentation, or implementation-only work that does not touch a\n  registered surface is patch;\n- additive fields, new commands, new exports, new evidence sections, or new\n  registered surfaces are minor;\n- removals, incompatible renames, changed meanings, newly required fields,\n  weakened trust gates, or changed ref flow are major.\n\nThe release passport records this as `surfaceImpacts[]` plus\n`versionImpact.final`. The final impact must equal the highest surface impact,\nso an agent cannot silently label a release patch when one machine surface needs\nminor review.\n\n`surfaceImpacts[]` is mandatory for production release passports (`release/*`)\nand major publish-gate passports. Alpha, local, and legacy passport contexts\nkeep the field optional so temporary validation can proceed without pretending\nto be a production release decision.\n\nExample: a KFD document such as KFD-2 is content and remains patch, but adding a\n`kind` field to the machine-consumed KFD `registry.json` is an additive change\nto the `kfd-registry-schema` surface and therefore requires minor-impact\nreview. This avoids both false shortcuts: \"new KFD means minor\" and \"all KFD\nrepository changes are patch\".\n\n## Decision Log\n\n| Date | Action | Line | Faces | Class | Rationale | PR |\n| --- | --- | --- | --- | --- | --- | --- |\n| 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |\n| 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |\n| 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |\n| 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |\n| 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |\n| 2026-07-02 | open-minor | `v2.2` | release-passport, binary-distribution | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. | |\n| 2026-07-02 | open-minor | `v2.1` | logging-sdk, cli-observability, package-subpaths | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. | |\n\n## Runner Policy\n\nThe `v2.2` binary distribution lane uses GitHub-hosted runners for production\nassets because that is the easiest release path for external users to reproduce:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners remain compatibility fixtures. They prove Buildchain's\nprotocol does not depend on GitHub-hosted images, but they do not define the\npublic binary distribution path."
     },
     {
       "id": "manual:web-surface-deployments",
@@ -1334,7 +1375,7 @@
       "route": "/docs/web-surface-deployments",
       "category": "manual",
       "sourcePath": "docs/web-surface-deployments.md",
-      "digest": "sha256:5063ebb76db3cd36797561782e6c741e30d60bfa0dac8f798dbbd34c4ab2b3c0",
+      "digest": "sha256:70995864ece77573756e1c197a936d86011f84b356d75683881b59b5aa537d8c",
       "headings": [
         {
           "level": 1,
@@ -1402,7 +1443,7 @@
           "anchor": "boundaries"
         }
       ],
-      "markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n  web:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-contract-lock-path: buildchain.contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n      build-command: pnpm build\n      artifact-path: dist\n```\n\nThe caller repository commits `buildchain.contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n  caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n  apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"reproducible\": true,\n  \"timestampPolicy\": \"ci-injected\",\n  \"deterministicInputs\": [\n    \"web-surface artifact content\",\n    \"buildchain.toml web-surface channels/deploy/surfaces\",\n    \"sourceSha\",\n    \"artifactHash\",\n    \"deployment channel\",\n    \"deployment alias\"\n  ],\n  \"sourceRevision\": \"...\",\n  \"timestampPolicyDetails\": {\n    \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n    \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n    \"timestampFieldsParticipateInArtifactDigest\": false,\n    \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n  },\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"artifactPathPrefix\": \"\",\n      \"viewerPathPrefix\": \"/\",\n      \"directoryIndex\": \"index.html\",\n      \"directoryIndexResolution\": true,\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"routing\": {\n        \"contract\": \"kungfu-buildchain-web-surface-path-prefix-rewrite\",\n        \"viewerPathPrefix\": \"/\",\n        \"artifactPathPrefix\": \"\",\n        \"objectPrefix\": \"sha-abcdef123456\",\n        \"directoryIndex\": \"index.html\",\n        \"directoryIndexResolution\": true\n      },\n      \"smokeUrls\": [\n        {\n          \"kind\": \"root\",\n          \"requestPath\": \"/\",\n          \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev/\",\n          \"required\": true\n        }\n      ],\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nFor multi-surface sites, each surface host is treated as a root-relative view\nof that surface's artifact path prefix. For example, a `buildchain` surface with\n`path = \"/buildchain/\"` and preview URL\n`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree\n`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer\nrequest for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore\nresolves against the artifact's `dist/buildchain/docs/index.html`, not\n`dist/docs/index.html` and not the hub surface root. The deployment manifest\nrecords this as `routing.contract =\n\"kungfu-buildchain-web-surface-path-prefix-rewrite\"` with\n`viewerPathPrefix = \"/\"`, `artifactPathPrefix = \"buildchain\"`, and\n`directoryIndexResolution = true`.\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter preview, staging, and production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface root URL and any nested smoke URLs\nrecorded in each surface binding. Nested smoke URLs are derived from nested HTML\nartifact files under the surface path prefix, with directory index resolution\nsuch as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain\npreview host. If a surface has no nested HTML route, Buildchain records only\nthe root smoke URL; absence of nested HTML is not a deployment failure. When a\nnested route is present, the check fails closed if a deploy reports success but\nthat child page returns 403 or another unexpected status. Production additionally fails if a\nresponse is unreachable, returns an unexpected status, or still sends\n`x-robots-tag: noindex`. The health check also verifies that each surface\nbinding recorded a deployment manifest pointer. The production release passport\nembeds the deploy plan, apply result, production preflight, and health check so\na reviewer or agent can audit why the production site changed and whether every\ndeclared host and every existing nested route was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- Production runs when `production-apply` is true and either:\n  - a trusted `workflow_dispatch` passes `production-approved=true`; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
+      "markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n  web:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-contract-lock-path: buildchain.contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n      build-command: pnpm build\n      artifact-path: dist\n```\n\nThe caller repository commits `buildchain.contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n  caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n  apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"reproducible\": true,\n  \"timestampPolicy\": \"ci-injected\",\n  \"deterministicInputs\": [\n    \"web-surface artifact content\",\n    \"buildchain.toml web-surface channels/deploy/surfaces\",\n    \"sourceSha\",\n    \"artifactHash\",\n    \"deployment channel\",\n    \"deployment alias\"\n  ],\n  \"sourceRevision\": \"...\",\n  \"timestampPolicyDetails\": {\n    \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n    \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n    \"timestampFieldsParticipateInArtifactDigest\": false,\n    \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n  },\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"artifactPathPrefix\": \"\",\n      \"viewerPathPrefix\": \"/\",\n      \"directoryIndex\": \"index.html\",\n      \"directoryIndexResolution\": true,\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"routing\": {\n        \"contract\": \"kungfu-buildchain-web-surface-path-prefix-rewrite\",\n        \"viewerPathPrefix\": \"/\",\n        \"artifactPathPrefix\": \"\",\n        \"objectPrefix\": \"sha-abcdef123456\",\n        \"directoryIndex\": \"index.html\",\n        \"directoryIndexResolution\": true\n      },\n      \"smokeUrls\": [\n        {\n          \"kind\": \"root\",\n          \"requestPath\": \"/\",\n          \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev/\",\n          \"required\": true\n        }\n      ],\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nFor multi-surface sites, each surface host is treated as a root-relative view\nof that surface's artifact path prefix. For example, a `buildchain` surface with\n`path = \"/buildchain/\"` and preview URL\n`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree\n`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer\nrequest for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore\nresolves against the artifact's `dist/buildchain/docs/index.html`, not\n`dist/docs/index.html` and not the hub surface root. The deployment manifest\nrecords this as `routing.contract =\n\"kungfu-buildchain-web-surface-path-prefix-rewrite\"` with\n`viewerPathPrefix = \"/\"`, `artifactPathPrefix = \"buildchain\"`, and\n`directoryIndexResolution = true`.\n\nWhen a surface uses an S3 object prefix, Buildchain also writes directory-index\nalias objects during apply. The root `dist/buildchain/index.html` is copied to\nthe prefix keys `pr-29/buildchain` and `pr-29/buildchain/`, while nested indexes\nsuch as `dist/buildchain/docs/index.html` are copied to `pr-29/buildchain/docs`\nand `pr-29/buildchain/docs/`. This makes surface-host requests for `/` and\n`/docs/` resolve to the surface's `index.html` files even when the CloudFront\norigin is an S3 REST origin rather than an S3 website endpoint.\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter preview, staging, and production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface root URL and any nested smoke URLs\nrecorded in each surface binding. Nested smoke URLs are derived from nested HTML\nartifact files under the surface path prefix, with directory index resolution\nsuch as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain\npreview host. If a surface has no nested HTML route, Buildchain records only\nthe root smoke URL; absence of nested HTML is not a deployment failure. When a\nnested route is present, the check fails closed if a deploy reports success but\nthat child page returns 403 or another unexpected status. Surface root checks\nexpect the apply result to have written directory-index alias objects, so a\nmulti-host preview root such as `https://buildchain-pr-29.preview.libkungfu.dev/`\nmust resolve to the surface `index.html`, not the bare prefix directory.\nProduction additionally fails if a response is unreachable, returns an\nunexpected status, or still sends `x-robots-tag: noindex`. The health check also\nverifies that each surface binding recorded a deployment manifest pointer. The\nproduction release passport embeds the deploy plan, apply result, production\npreflight, and health check so a reviewer or agent can audit why the production\nsite changed and whether every declared host and every existing nested route was\nactually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- Production runs when `production-apply` is true and either:\n  - a trusted `workflow_dispatch` passes `production-approved=true`; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
     },
     {
       "id": "fixture:infra-contract-aws-cdk-shaped",
@@ -1584,7 +1625,7 @@
   "pageRegistry": {
     "path": "page-registry.json",
     "contract": "kungfu-buildchain-site-page-registry",
-    "pageCount": 41,
+    "pageCount": 42,
     "categories": [
       "action",
       "api",
@@ -1611,7 +1652,7 @@
         "homepagePriority": 10,
         "defaultPresentation": "release-passport-install",
         "includeInFirstScreen": true,
-        "markdown": "For standalone use, install a platform archive from a GitHub Release and verify\nthe release passport before trusting the binary:\n\n```bash\n# Example for Linux x64. Use the archive that matches your platform.\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain-x86_64-unknown-linux-gnu.tar.gz\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/artifact-evidence.json\nnpx @kungfu-tech/buildchain verify release-passport buildchain.release.json\ntar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz\n./buildchain version\n```\n\nRelease pages publish platform archives, checksums, release passport files, and\na single evidence bundle:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges readme --check\nbuildchain badges readme --write\n```"
+        "markdown": "For standalone use, install a platform archive from a GitHub Release and verify\nthe release passport before trusting the binary:\n\n```bash\n# Example for Linux x64. Use the archive that matches your platform.\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain-x86_64-unknown-linux-gnu.tar.gz\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/artifact-evidence.json\nnpx @kungfu-tech/buildchain verify release-passport buildchain.release.json\ntar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz\n./buildchain version\n```\n\nRelease pages publish platform archives, checksums, release passport files, and\na single evidence bundle:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```"
       },
       {
         "id": "use-buildchain",
@@ -1703,7 +1744,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:03f52660d03223fff7daf500f995645d78a46fffd8cddec9d8c01bbee0863145"
+      "digest": "sha256:2d95d0dd56088efb1a9a16d026810cf2e74659963612451f903e37825c260122"
     },
     {
       "id": "install",
@@ -1719,7 +1760,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094"
+      "digest": "sha256:495e1c46ce45268a9ed6502fe115af45a8cd1d8e644cb4332da9b551f919f578"
     },
     {
       "id": "release-propagation",
@@ -1735,7 +1776,7 @@
       "path": "docs/readme-badges.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:c886d5d469d143571ae68497643be754b1616b562fddc780a5708f49b4c46242"
+      "digest": "sha256:06eaef737dcc73a6526d856d79275ee87af9670f0e2be39a5596758bfc3527c9"
     },
     {
       "id": "homebrew",
@@ -1815,7 +1856,15 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:cfb0bf32f2b8b44bf352e79c27e34b7980e0f66e5fa10e4f202975fbb4780ad1"
+      "digest": "sha256:60686b5b4d5fe7f3944cb53ab709231fd00bb02b6d51770f1fe8b018122afd8f"
+    },
+    {
+      "id": "build-facts",
+      "title": "Build Facts",
+      "path": "docs/build-facts.md",
+      "plane": "use",
+      "exists": true,
+      "digest": "sha256:75dcf7a6628dac9e982a455de9966044ae771611d4efc04e7264a2d4adb0bd3e"
     },
     {
       "id": "lifecycle-protocol",
@@ -1871,7 +1920,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:77b92fc979cc100beab3f8a13cd791dea992737b986ace505104edff4810a296"
+      "digest": "sha256:2c79f7d1a072a40c75d889beac38ae843b2170587fc570ce40722d3968b6506e"
     },
     {
       "id": "web-surface-deployments",
@@ -1879,7 +1928,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:5063ebb76db3cd36797561782e6c741e30d60bfa0dac8f798dbbd34c4ab2b3c0"
+      "digest": "sha256:70995864ece77573756e1c197a936d86011f84b356d75683881b59b5aa537d8c"
     }
   ],
   "releaseModel": {