@kungfu-tech/buildchain 2.8.2-alpha.1 → 2.8.2

package/dist/site/manual-registry.json

@@ -0,0 +1,132 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-agent-manual-registry",
+  "package": "@kungfu-tech/buildchain",
+  "source": "npm package docs/",
+  "manuals": [
+    {
+      "id": "install",
+      "title": "Install and verify Buildchain",
+      "path": "docs/install.md",
+      "plane": "use",
+      "digest": "sha256:34bc161a26595f95684694d341616e47bfd65b0c51a63225e68a575179636175"
+    },
+    {
+      "id": "release-passport",
+      "title": "Release Passport protocol",
+      "path": "docs/release-passport.md",
+      "plane": "verify",
+      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333"
+    },
+    {
+      "id": "release-propagation",
+      "title": "Release propagation",
+      "path": "docs/release-propagation.md",
+      "plane": "use",
+      "digest": "sha256:10c2bb3bc4ebd692c49fa55f286b77ed3e8caa1526298ad910c00fc80251a893"
+    },
+    {
+      "id": "binary-distribution",
+      "title": "Binary distribution contract",
+      "path": "docs/binary-distribution.md",
+      "plane": "verify",
+      "digest": "sha256:36899140a9b2e9ce1565ed41f3d64f73a8829fad3d59a04b9498d9479c85c4be"
+    },
+    {
+      "id": "toolkit-observability",
+      "title": "Toolkit observability",
+      "path": "docs/toolkit-observability.md",
+      "plane": "use",
+      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1"
+    },
+    {
+      "id": "site-bundle-contract",
+      "title": "Site bundle contract",
+      "path": "docs/site-bundle-contract.md",
+      "plane": "use",
+      "digest": "sha256:e6b4f2e76c713063ff750b0a8d6d96595addae2fd48f913744dc86559add0641"
+    },
+    {
+      "id": "product-mechanism",
+      "title": "Product mechanism",
+      "path": "docs/product-mechanism.md",
+      "plane": "why",
+      "digest": "sha256:da50022f96f8876bb275a7832190cb1f6ab0fa6aab9d045dda924a7abddc3edf"
+    },
+    {
+      "id": "cli",
+      "title": "CLI and npm package",
+      "path": "docs/cli.md",
+      "plane": "use",
+      "digest": "sha256:a8a348181d6419b746e863d1cacc9d6a91aa6ac5cc2b60819843d44487957c49"
+    },
+    {
+      "id": "lifecycle-protocol",
+      "title": "Lifecycle protocol",
+      "path": "docs/lifecycle-protocol.md",
+      "plane": "use",
+      "digest": "sha256:02e1be97935c0d9520ea22e8ef0dc61d9b860c347f07127074600cdca02713ce"
+    },
+    {
+      "id": "reusable-build-surface",
+      "title": "Reusable build surface",
+      "path": "docs/reusable-build-surface.md",
+      "plane": "use",
+      "digest": "sha256:e5b2222fddd0624b6aff1c999bb156df26eebbd7b365ec65ef3622611dc055ea"
+    },
+    {
+      "id": "publish-transaction",
+      "title": "Publish transaction",
+      "path": "docs/publish-transaction.md",
+      "plane": "verify",
+      "digest": "sha256:dd45cf98f0847e3968f150a09bed84aa1f59cb2687ac988e9519f08dc9c91877"
+    },
+    {
+      "id": "release-governance",
+      "title": "Release governance",
+      "path": "docs/release-governance.md",
+      "plane": "why",
+      "digest": "sha256:8aab1af617e511011974cb63f04240463fc99c427cb3b29e5f5d385c88620464"
+    },
+    {
+      "id": "release-flow",
+      "title": "Release flow",
+      "path": "docs/release-flow.md",
+      "plane": "verify",
+      "digest": "sha256:0a2f46501a64905067cc5872b45ac4824f9e632d59bfdfb2f6a794dfc5f959ea"
+    },
+    {
+      "id": "versioning",
+      "title": "Versioning",
+      "path": "docs/versioning.md",
+      "plane": "why",
+      "digest": "sha256:77b92fc979cc100beab3f8a13cd791dea992737b986ace505104edff4810a296"
+    },
+    {
+      "id": "web-surface-deployments",
+      "title": "Web surface deployments",
+      "path": "docs/web-surface-deployments.md",
+      "plane": "use",
+      "digest": "sha256:614aea65d745e8978d8329545753adf13b8914f84fe35b0148abbd1aff0c0dc2"
+    },
+    {
+      "id": "infra-contract",
+      "title": "Infra Contract",
+      "path": "docs/infra-contract.md",
+      "plane": "use",
+      "digest": "sha256:7826e8c70ac2d90ddd8d4e38bcdd1bcfa36eef5106431d7ad94b2fe9c8d3d5dc"
+    }
+  ],
+  "requiredAgentManuals": [
+    "docs/MAP.md",
+    "docs/install.md",
+    "docs/cli.md",
+    "docs/reusable-build-surface.md",
+    "docs/release-candidate.md",
+    "docs/release-governance.md",
+    "docs/release-passport.md",
+    "docs/publish-transaction.md",
+    "docs/site-bundle-contract.md"
+  ],
+  "guidance": "Agent consumers should use this registry to find packaged Buildchain manuals before inferring behavior from workflow snippets or release notes."
+}

package/dist/site/node-api-registry.json

@@ -0,0 +1,93 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-node-api-registry",
+  "package": "@kungfu-tech/buildchain",
+  "moduleSystem": "module",
+  "exports": [
+    {
+      "specifier": "@kungfu-tech/buildchain",
+      "export": ".",
+      "target": "./packages/core/index.js",
+      "digest": "sha256:cfbe85e8fcac0f1c525ed99d9d488898575d9ea21cc7855e454b55df49cd2e0e"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/core",
+      "export": "./core",
+      "target": "./packages/core/index.js",
+      "digest": "sha256:cfbe85e8fcac0f1c525ed99d9d488898575d9ea21cc7855e454b55df49cd2e0e"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/artifact-passport",
+      "export": "./artifact-passport",
+      "target": "./packages/core/artifact-passport.js",
+      "digest": "sha256:2f882bf245658fb7a204004d7aa3a22f7e34816e4ba101fb0969a002d05fc12c"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/buildchain-contract",
+      "export": "./buildchain-contract",
+      "target": "./packages/core/buildchain-contract.js",
+      "digest": "sha256:0ec4fb82b4a01f303688a74e020e6b718db248cf0470be25d088e7d669e38679"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/diagnostics",
+      "export": "./diagnostics",
+      "target": "./packages/core/diagnostics.js",
+      "digest": "sha256:d447f864c719632872c9d90f0e30e2b6d45311bc5115d4f3c661d21164d75ebc"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/issue-reporting",
+      "export": "./issue-reporting",
+      "target": "./packages/core/issue-reporting.js",
+      "digest": "sha256:d6e0a450a52b7a4fba84bff855d5370e0cfa2ec3c4be737b3c9099a72f705e2d"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/logging",
+      "export": "./logging",
+      "target": "./packages/core/logging.js",
+      "digest": "sha256:8cc29b88dc7968de3b43d495b54c0b53f90984beb85883705d764c40d4da1b4e"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/kfd-gate",
+      "export": "./kfd-gate",
+      "target": "./packages/core/kfd-gate.js",
+      "digest": "sha256:6a99ee108c385837ee9f1dbb75848f6ea434b6474977e6e567ae81f8fc9a555c"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/release-candidate",
+      "export": "./release-candidate",
+      "target": "./packages/core/release-candidate.js",
+      "digest": "sha256:0aa35ae7482fdb9543214275118da7111c6592b715d2622c525f83f253e5d6dc"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/release-passport",
+      "export": "./release-passport",
+      "target": "./packages/core/release-passport.js",
+      "digest": "sha256:22017d4cbe0d89aecfcada7b93f5cdf2935837b2236ae4aeff23f19dbf3d26cb"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/release-propagation",
+      "export": "./release-propagation",
+      "target": "./packages/core/release-propagation.js",
+      "digest": "sha256:1960be557e57d738cb242ccf3df9ad41cdf156037648a7ab584905b6629f5840"
+    },
+    {
+      "specifier": "@kungfu-tech/buildchain/buildchain-kfd-claims",
+      "export": "./buildchain-kfd-claims",
+      "target": "./packages/core/buildchain-kfd-claims.js",
+      "digest": "sha256:03e866a7cf7b9d84c71c2353a0865b301a8656dcbaeb67ea47813897f44a0bbc"
+    }
+  ],
+  "docs": [
+    {
+      "id": "cli-and-node-package",
+      "path": "docs/cli.md",
+      "digest": "sha256:a8a348181d6419b746e863d1cacc9d6a91aa6ac5cc2b60819843d44487957c49"
+    },
+    {
+      "id": "site-bundle-contract",
+      "path": "docs/site-bundle-contract.md",
+      "digest": "sha256:e6b4f2e76c713063ff750b0a8d6d96595addae2fd48f913744dc86559add0641"
+    }
+  ],
+  "guidance": "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths."
+}

package/dist/site/release-model.json

@@ -33,5 +33,16 @@
     "versionSource": "package.json#version",
     "alphaDistTag": "alpha",
     "stableDistTag": "latest"
+  },
+  "githubRelease": {
+    "exactTagRelease": true,
+    "prereleaseTags": "semver prerelease tags set prerelease=true and make_latest=false",
+    "stableTags": "stable semver tags set make_latest=true",
+    "evidenceAssets": [
+      "publish evidence JSON",
+      "buildchain.release.json",
+      "release passport assets"
+    ],
+    "owner": "promote-buildchain-ref"
   }
 }

package/dist/site/release-provenance.json

@@ -19,9 +19,13 @@
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./release-propagation": "./packages/core/release-propagation.js",
+      "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",
       "./site/cli-registry.json": "./dist/site/cli-registry.json",
+      "./site/manual-registry.json": "./dist/site/manual-registry.json",
+      "./site/node-api-registry.json": "./dist/site/node-api-registry.json",
+      "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
       "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
       "./site/release-model.json": "./dist/site/release-model.json",
       "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",

package/dist/site/site-manifest.json

@@ -17,121 +17,140 @@
       "title": "Install and verify Buildchain",
       "path": "docs/install.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:34bc161a26595f95684694d341616e47bfd65b0c51a63225e68a575179636175"
     },
     {
       "id": "release-passport",
       "title": "Release Passport protocol",
       "path": "docs/release-passport.md",
       "plane": "verify",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333"
     },
     {
       "id": "release-propagation",
       "title": "Release propagation",
       "path": "docs/release-propagation.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:10c2bb3bc4ebd692c49fa55f286b77ed3e8caa1526298ad910c00fc80251a893"
     },
     {
       "id": "binary-distribution",
       "title": "Binary distribution contract",
       "path": "docs/binary-distribution.md",
       "plane": "verify",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:36899140a9b2e9ce1565ed41f3d64f73a8829fad3d59a04b9498d9479c85c4be"
     },
     {
       "id": "toolkit-observability",
       "title": "Toolkit observability",
       "path": "docs/toolkit-observability.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:239949a75ca81b6002a2e148f7028402dbd98c00e246acd8d0955855781206a1"
     },
     {
       "id": "site-bundle-contract",
       "title": "Site bundle contract",
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:e6b4f2e76c713063ff750b0a8d6d96595addae2fd48f913744dc86559add0641"
     },
     {
       "id": "product-mechanism",
       "title": "Product mechanism",
       "path": "docs/product-mechanism.md",
       "plane": "why",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:da50022f96f8876bb275a7832190cb1f6ab0fa6aab9d045dda924a7abddc3edf"
     },
     {
       "id": "cli",
       "title": "CLI and npm package",
       "path": "docs/cli.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:a8a348181d6419b746e863d1cacc9d6a91aa6ac5cc2b60819843d44487957c49"
     },
     {
       "id": "lifecycle-protocol",
       "title": "Lifecycle protocol",
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:02e1be97935c0d9520ea22e8ef0dc61d9b860c347f07127074600cdca02713ce"
     },
     {
       "id": "reusable-build-surface",
       "title": "Reusable build surface",
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:e5b2222fddd0624b6aff1c999bb156df26eebbd7b365ec65ef3622611dc055ea"
     },
     {
       "id": "publish-transaction",
       "title": "Publish transaction",
       "path": "docs/publish-transaction.md",
       "plane": "verify",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:dd45cf98f0847e3968f150a09bed84aa1f59cb2687ac988e9519f08dc9c91877"
     },
     {
       "id": "release-governance",
       "title": "Release governance",
       "path": "docs/release-governance.md",
       "plane": "why",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:8aab1af617e511011974cb63f04240463fc99c427cb3b29e5f5d385c88620464"
     },
     {
       "id": "release-flow",
       "title": "Release flow",
       "path": "docs/release-flow.md",
       "plane": "verify",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:0a2f46501a64905067cc5872b45ac4824f9e632d59bfdfb2f6a794dfc5f959ea"
     },
     {
       "id": "versioning",
       "title": "Versioning",
       "path": "docs/versioning.md",
       "plane": "why",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:77b92fc979cc100beab3f8a13cd791dea992737b986ace505104edff4810a296"
     },
     {
       "id": "web-surface-deployments",
       "title": "Web surface deployments",
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:614aea65d745e8978d8329545753adf13b8914f84fe35b0148abbd1aff0c0dc2"
     },
     {
       "id": "infra-contract",
       "title": "Infra Contract",
       "path": "docs/infra-contract.md",
       "plane": "use",
-      "exists": true
+      "exists": true,
+      "digest": "sha256:7826e8c70ac2d90ddd8d4e38bcdd1bcfa36eef5106431d7ad94b2fe9c8d3d5dc"
     }
   ],
   "facts": [
     "cli-registry.json",
+    "manual-registry.json",
+    "node-api-registry.json",
     "workflow-registry.json",
     "release-model.json",
     "artifact-schemas.json",
     "product-mechanism.json",
     "release-provenance.json",
+    "kfd-claims.json",
     "agent-index.json"
   ]
 }

package/docs/MAP.md

@@ -12,6 +12,27 @@ running artifact), *use* (consume / extend) - and a **status**:
 - `to write` - planned; the material exists but is not yet a single doc.
 - `retired` - intentionally not part of the active Buildchain v2 surface.
 
+## Capability Coverage
+
+This package should be usable by an agent from the npm artifact alone. The
+machine-readable `dist/site/` bundle is the first fact source; the Markdown
+manuals explain those facts and give operator examples.
+
+| Capability | Machine-readable entry | Manual entry |
+| --- | --- | --- |
+| 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) |
+| Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
+| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
+| 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) |
+| release propagation for package/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |
+| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |
+| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |
+
+`dist/site/kfd-claims.json` is generated from
+`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the
+source claim registry; this map and the manuals explain those claims but do not
+replace them.
+
 ## Map
 
 | Your question | Document | Plane | Status |

package/docs/cli.md

@@ -51,6 +51,31 @@ non-JavaScript environments. JavaScript code that already depends on
 `@kungfu-tech/buildchain` should import the toolkit API instead of spawning
 `npx buildchain` or a downloaded binary.
 
+## Node API and Package Exports
+
+Buildchain's public Node API is the package `exports` surface, not arbitrary
+internal file paths. The npm package also ships
+`dist/site/node-api-registry.json` and exports it as
+`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate
+the supported imports from the installed package.
+
+Current public import families include:
+
+```js
+import * as buildchain from "@kungfu-tech/buildchain";
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+import { verifyKfd1ReleaseGate } from "@kungfu-tech/buildchain/kfd-gate";
+import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
+import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
+import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
+import manualRegistry from "@kungfu-tech/buildchain/site/manual-registry.json" with { type: "json" };
+import nodeApiRegistry from "@kungfu-tech/buildchain/site/node-api-registry.json" with { type: "json" };
+```
+
+Use `dist/site/manual-registry.json` to find the packaged operating manuals and
+their SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the
+floating-ref contract world for a runtime such as `@v2`.
+
 ## Commands
 
 `buildchain init` writes a starter `buildchain.toml` and a reusable workflow

package/docs/release-candidate.md

@@ -82,13 +82,13 @@ other package as `role: platform`. Consumer workflows therefore stay
 declarative and do not need their own artifact download or publish-evidence
 generation scripts.
 
-When `github-release: true`, the wrapper also owns the GitHub Release side of
-the publish model. Once the release transaction is complete, it creates or
-updates the exact-tag GitHub Release, applies prerelease/latest metadata from
-the semver tag, and uploads the publish evidence file together with the
-generated release passport assets. This keeps npm/registry publication,
-Buildchain release passport persistence, and `release.published` propagation in
-one declarative reusable workflow.
+When `github-release: true`, the wrapper forwards GitHub Release publication to
+the underlying `promote-buildchain-ref` semver model. Once the release
+transaction is complete, the action creates or updates the exact-tag GitHub
+Release, applies prerelease/latest metadata from the semver tag, and uploads the
+publish evidence file together with the generated release passport assets. This
+keeps npm/registry publication, Buildchain release passport persistence, and
+`release.published` propagation in one declarative reusable workflow.
 
 Products that publish KFD release trust evidence can keep that path declarative
 too. Pass KFD-1 self contract witnesses, KFD-2 public claim files, and KFD-3

package/docs/release-governance.md

@@ -62,6 +62,11 @@ Buildchain implements the same governance loop with:
   promotion; this workflow dogfoods the declarative
   `release-candidate-promote.yml` wrapper and does not hand-wire resolver,
   artifact download, publish-gate, or promote action steps;
+- Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so
+  the release passport consumes generated KFD-1 witnesses, KFD-2 public claim
+  JSON, and KFD-3 collaboration-interface witnesses from
+  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release
+  notes;
 - `actions/promote-buildchain-ref` for branch, tag, version-state, and
   governance checks;
 - package-manager adapters that can update version state for pnpm, npm, and
@@ -435,13 +440,16 @@ from the reusable build outputs. Workflows that only collect passports or run
 dry-run package checks do not move publish refs and are not publish-gate
 publication models.
 
-The same wrapper is the declarative GitHub Release publication entrypoint for
-semver releases. Consumers set `github-release: true`; after the publish
-transaction reaches `complete`, Buildchain creates or updates the exact-tag
-GitHub Release and uploads the generated `buildchain.release.json`,
-release-passport assets, and publish evidence. Semver prerelease tags are marked
-`prerelease=true` and `make_latest=false`; stable semver tags are marked latest.
-This is the supported path for downstream `release.published` propagation.
+Semver GitHub Release publication is owned by `promote-buildchain-ref`, not by
+consumer shell glue. Consumers normally use the `release-candidate-promote.yml`
+wrapper and set `github-release: true`; the wrapper passes that declaration to
+the action. After the publish transaction reaches `complete`, Buildchain creates
+or updates the exact-tag GitHub Release and uploads the generated
+`buildchain.release.json`, release-passport assets, and publish evidence. Semver
+prerelease tags are marked `prerelease=true` and `make_latest=false`; stable
+semver tags are marked latest. This is the supported path for downstream
+`release.published` propagation across semver, major, and promote-only release
+candidate publication models.
 
 Buildchain also does not maintain bare exact tags such as `1.0.0`. The supported
 exact release and alpha refs are v-prefixed:

package/docs/release-passport.md

@@ -204,6 +204,33 @@ machine-bound but only supported by prose downgrade the KFD-2 audit and produce
 a warning, so agents can distinguish "verified", "needs review", and "not
 bound to evidence" without reading release notes.
 
+For Buildchain's own releases, public release claims are not authored in prose
+inside the workflow. The source registry is
+`packages/core/buildchain-kfd-claims.js`, published as
+`dist/site/kfd-claims.json` and exported as
+`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the
+version-invariant source of public claims and collaboration surfaces: it does
+not store the exact release version, promotion SHA, or exact runtime contract
+digest. Those run-specific facts belong in the release passport and generated
+witnesses. During Buildchain promotion,
+`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the
+current source/artifact hashes and generates:
+
+- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,
+  actions, Node exports, and site-consumption facts;
+- one KFD-2 claim JSON per public Buildchain release claim;
+- KFD-3 pre-build and artifact witnesses for the same public collaboration
+  surfaces.
+
+The generated claim set covers Buildchain's KFD release passport support,
+agent-first single source of truth, floating `@v2` contract drift protection,
+semver GitHub Release evidence publication, channel-preserving release
+propagation, and npm publish evidence/finalization. Buildchain self promotion
+passes those files into `promote-buildchain-ref`; `verifyReleasePassport()` then
+fails closed if any claim is missing source bindings, machine evidence, hashes,
+artifact coordinates, verification result, audit boundary, responsibility, or
+residual risk.
+
 ### KFD-3 collaboration-interface release gate
 
 KFD-3 asks a different release question than KFD-1. KFD-1 proves that named
@@ -211,6 +238,15 @@ payload bytes match one contract world. KFD-3 proves that a product's shipped
 participant-facing collaboration/control surface is closed over its declared
 interface.
 
+For Buildchain itself, the declared interface starts in
+`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The
+registry enumerates public human/agent surfaces across manuals, schema and
+standard metadata, package exports, site-consumption contracts, workflows, and
+actions. `dist/site/kfd-claims.json` is the packaged machine-readable form used
+by downstream sites and by Buildchain's own release passport. Exact release
+version/SHA binding is deliberately deferred to the promotion witness, so the
+source registry can remain stable across semver version-state bumps.
+
 The product remains the fact source. Before build/publish, the product writes a
 pre-build witness:
 

package/docs/site-bundle-contract.md

@@ -14,10 +14,13 @@ dist/site/
   buildchain-site.json
   site-manifest.json
   cli-registry.json
+  manual-registry.json
+  node-api-registry.json
   workflow-registry.json
   release-model.json
   artifact-schemas.json
   buildchain-contract.json
+  kfd-claims.json
   product-mechanism.json
   release-provenance.json
   agent-index.json
@@ -28,6 +31,15 @@ dist/site/
 world used by floating-ref contract locks. It records public workflow/action/CLI
 surfaces, compatibility digests, and audit digests for the files that implement
 those surfaces.
+`manual-registry.json` enumerates the packaged Markdown manuals with source
+digests so an agent can find complete operating documentation from the npm
+artifact. `node-api-registry.json` enumerates public Node import surfaces from
+`package.json#exports`, so agents do not have to infer supported APIs from
+internal paths.
+`kfd-claims.json` is the Buildchain-owned KFD claim registry. It is generated
+from `packages/core/buildchain-kfd-claims.js` and enumerates the public release
+claims plus the KFD-3 collaboration surfaces that Buildchain self-verifies
+during release promotion.
 
 ## npm Consumption
 
@@ -63,10 +75,16 @@ The P0 bundle includes:
 
 - site manifest;
 - CLI command registry;
+- manual registry for packaged agent-facing documentation;
+- Node API registry for public package exports;
 - workflow/action registry;
 - release model facts;
 - artifact and evidence schema index;
-- Buildchain runtime contract world for `@v2` floating-ref compatibility checks;
+- Buildchain runtime contract world for `@v2` floating-ref compatibility checks,
+  KFD-1/KFD-2/KFD-3 release gates, GitHub Release evidence publication, and
+  site-consumption contracts;
+- Buildchain KFD claim registry for release-passport self verification and
+  agent-first public claim discovery;
 - product mechanism manifest;
 - release provenance;
 - agent read order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.2-alpha.1",
+  "version": "2.8.2",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -22,9 +22,13 @@
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./release-propagation": "./packages/core/release-propagation.js",
+    "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
     "./site/cli-registry.json": "./dist/site/cli-registry.json",
+    "./site/manual-registry.json": "./dist/site/manual-registry.json",
+    "./site/node-api-registry.json": "./dist/site/node-api-registry.json",
+    "./site/kfd-claims.json": "./dist/site/kfd-claims.json",
     "./site/workflow-registry.json": "./dist/site/workflow-registry.json",
     "./site/release-model.json": "./dist/site/release-model.json",
     "./site/artifact-schemas.json": "./dist/site/artifact-schemas.json",