@kungfu-tech/buildchain 2.10.2 → 2.10.3

package/dist/site/public-surface-audit.json

@@ -2061,9 +2061,9 @@
     "cliRegistryPath": "dist/site/cli-registry.json",
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
-    "cliRegistryDigest": "d86d5cc6f0ef0e711a81edc8dec6178cd3f16f0c46ec4fdadbe8133bdc69789d",
-    "workflowRegistryDigest": "a53dd3b746f8d697eaa79fb23efcbbeaa6018efb2c3af0d875526ab6bef939ad",
-    "pageRegistryDigest": "31d865289f7b62a44db869d1d323c11d5c4b2ebd248912e0545580f070d0a5d5"
+    "cliRegistryDigest": "281c186e9dbdf45e55e8afcd59cfee66518f42c146d1b79dfd8837048c00bec8",
+    "workflowRegistryDigest": "b24b2a68ae83941cbb6a719a62b4eafbd0f5e859e5810ae766ce9a5db69ddfae",
+    "pageRegistryDigest": "c3be81db06f3a183ce53cd0e9199b88be9c8b1d615c395f7fdbfac139796c455"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/release-provenance.json

@@ -31,6 +31,7 @@
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",
       "./site/page-registry.json": "./dist/site/page-registry.json",
+      "./site/capability-registry.json": "./dist/site/capability-registry.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",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-08T08:27:16.923Z",
-  "publishedAt": "2026-07-08T08:27:16.923Z",
+  "generatedAt": "2026-07-08T10:30:54.924Z",
+  "publishedAt": "2026-07-08T10:30:54.924Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "04fc1e0ec35cfd1d47dbfa67eeabae6cf1f042bd",
+  "sourceRevision": "c01d56a7410ded5f631a83950227873cef32c37b",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.2",
+    "version": "2.10.3",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3712026dcfcf44c16bc4def2acf246caee1ec036543c0fea265fa17b19d4de31"
+      "digest": "sha256:67a0e6b63a943904eacbf7d26227e3c9ad650d17e8aa937c40b3fdad8f389fdd"
     },
     {
       "id": "install",
@@ -71,6 +71,14 @@
       "exists": true,
       "digest": "sha256:75d8bade4b0b96b26941b11835c2debcdada8f1723412935fb8ae6884f08f9f3"
     },
+    {
+      "id": "release-candidate",
+      "title": "Release Candidate Passport",
+      "path": "docs/release-candidate.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:6b5107cded122925e8560a9b117ff1c96f5cf05d934caf83d7e4b2a4d777175e"
+    },
     {
       "id": "release-propagation",
       "title": "Release propagation",
@@ -133,7 +141,7 @@
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:595ad74e82f179844da7bb3545b1fa7a0cd99c083160b7ed08861dfb5b2603ab"
+      "digest": "sha256:6b5bc2ee0f785b16d762f140f14a9163c07caf0d424200c2ececc74f7bb2271c"
     },
     {
       "id": "migration-inventory",
@@ -165,7 +173,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:85e014b7e053b74b620e5b438d54453e20b22f758a33dfd5ae970403fa41d9d7"
+      "digest": "sha256:2f55874feb9acecce1c471b96e07bb9a198a8da93efd0f859d69f353bf9c36a8"
     },
     {
       "id": "build-facts",
@@ -245,11 +253,12 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3a11e4c38c058181ab6d36242a8898e13a3a452304838e806c2d1b86d1348a83"
+      "digest": "sha256:58673b84879a219572fe39aa8b4d01cfc34fabf664b3318753d61043821edaff"
     }
   ],
   "facts": [
     "page-registry.json",
+    "capability-registry.json",
     "cli-registry.json",
     "manual-registry.json",
     "node-api-registry.json",

package/dist/site/workflow-registry.json

@@ -58,6 +58,7 @@
       ],
       "inputCount": 48,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -66,6 +67,7 @@
       "inputs": [],
       "inputCount": 0,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -76,6 +78,7 @@
       ],
       "inputCount": 1,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -88,6 +91,7 @@
       ],
       "inputCount": 3,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -124,6 +128,7 @@
       ],
       "inputCount": 27,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -174,6 +179,7 @@
       ],
       "inputCount": 41,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -187,6 +193,7 @@
       ],
       "inputCount": 4,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -200,6 +207,7 @@
       ],
       "inputCount": 4,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -222,6 +230,7 @@
       ],
       "inputCount": 13,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -235,6 +244,7 @@
       ],
       "inputCount": 4,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -272,6 +282,7 @@
       ],
       "inputCount": 28,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -284,6 +295,7 @@
       ],
       "inputCount": 3,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -298,6 +310,7 @@
       ],
       "inputCount": 5,
       "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -309,6 +322,7 @@
       ],
       "inputCount": 2,
       "surface": "release-passport",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -319,6 +333,7 @@
       ],
       "inputCount": 1,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "repository-internal"
     },
     {
@@ -330,6 +345,7 @@
       ],
       "inputCount": 2,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -341,6 +357,7 @@
       ],
       "inputCount": 2,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -352,6 +369,7 @@
       ],
       "inputCount": 2,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -376,6 +394,7 @@
       ],
       "inputCount": 15,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -388,6 +407,7 @@
       ],
       "inputCount": 3,
       "surface": "release-governance",
+      "capabilityGroup": "release-passport-trust",
       "status": "active"
     },
     {
@@ -401,6 +421,7 @@
       ],
       "inputCount": 4,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "repository-internal"
     },
     {
@@ -416,6 +437,7 @@
       ],
       "inputCount": 6,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -437,6 +459,7 @@
       ],
       "inputCount": 12,
       "surface": "dev-governance",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -448,6 +471,7 @@
       ],
       "inputCount": 2,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -469,6 +493,7 @@
       ],
       "inputCount": 12,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -482,6 +507,7 @@
       ],
       "inputCount": 4,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -495,6 +521,7 @@
       ],
       "inputCount": 4,
       "surface": "repository-patrol",
+      "capabilityGroup": "governance-versioning",
       "status": "active"
     },
     {
@@ -548,6 +575,7 @@
       ],
       "inputCount": 44,
       "surface": "release-governance",
+      "capabilityGroup": "reusable-build",
       "status": "active"
     },
     {
@@ -565,6 +593,7 @@
       ],
       "inputCount": 8,
       "surface": "release-governance",
+      "capabilityGroup": "release-passport-trust",
       "status": "active"
     },
     {
@@ -573,6 +602,7 @@
       "inputs": [],
       "inputCount": 0,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -595,6 +625,7 @@
       ],
       "inputCount": 13,
       "surface": "release-propagation",
+      "capabilityGroup": "site-and-propagation",
       "status": "preview"
     },
     {
@@ -603,6 +634,7 @@
       "inputs": [],
       "inputCount": 0,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -613,6 +645,7 @@
       ],
       "inputCount": 1,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
     {
@@ -621,6 +654,7 @@
       "inputs": [],
       "inputCount": 0,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "compatibility-fixture"
     },
     {
@@ -629,6 +663,7 @@
       "inputs": [],
       "inputCount": 0,
       "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
       "status": "active"
     }
   ],
@@ -691,6 +726,7 @@
         "verification-command"
       ],
       "inputCount": 51,
+      "capabilityGroup": "release-passport-trust",
       "status": "active"
     },
     {
@@ -742,6 +778,7 @@
         "workflow"
       ],
       "inputCount": 43,
+      "capabilityGroup": "observability-diagnostics",
       "status": "active"
     },
     {
@@ -770,6 +807,7 @@
         "summary-path"
       ],
       "inputCount": 20,
+      "capabilityGroup": "reusable-build",
       "status": "active"
     },
     {
@@ -781,6 +819,7 @@
         "require-version-state"
       ],
       "inputCount": 3,
+      "capabilityGroup": "reusable-build",
       "status": "active"
     }
   ]

package/docs/MAP.md

@@ -18,8 +18,27 @@ 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.
 
+`dist/site/capability-registry.json` is the capability navigation entrypoint.
+It groups the public surface into stable product areas so sites and agents do
+not have to infer structure from file names. Each page, manual, CLI command,
+workflow, action, and Node API export also carries a `capabilityGroup`,
+`audience`, and `maturity` field in its own registry.
+
+| Capability group | Primary facts | Primary manuals |
+| --- | --- | --- |
+| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |
+| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |
+| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
+| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
+| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
+| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |
+| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |
+| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |
+| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |
+
 | Capability | Machine-readable entry | Manual entry |
 | --- | --- | --- |
+| Capability-grouped KFD-3 navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | 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) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
 | KFD-3 surface registration and capability query | `buildchain.kfd3.json`, `dist/site/kfd-claims.json`, `buildchain.release.json` | [`kfd-support.md`](kfd-support.md) |

package/docs/cli.md

@@ -58,6 +58,10 @@ 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.
+For navigation, start with `dist/site/capability-registry.json`: it groups
+manuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD
+claim facts by product capability before an agent chooses a concrete command or
+manual.
 
 Current public import families include:
 
@@ -74,6 +78,7 @@ import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-pr
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
 import contractWorld from "@kungfu-tech/buildchain/site/buildchain-contract.json" with { type: "json" };
+import capabilityRegistry from "@kungfu-tech/buildchain/site/capability-registry.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" };
 import publicSurfaceAudit from "@kungfu-tech/buildchain/site/public-surface-audit.json" with { type: "json" };

package/docs/site-bundle-contract.md

@@ -13,6 +13,7 @@ release mechanics, command registry, workflow registry, or artifact schema.
 dist/site/
   buildchain-site.json
   site-manifest.json
+  capability-registry.json
   cli-registry.json
   manual-registry.json
   node-api-registry.json
@@ -36,6 +37,12 @@ of parsing `README.md` themselves.
 It also includes a `pages` collection that mirrors `page-registry.json`, so a
 site repository can build the full Buildchain public documentation surface from
 the npm package without scanning the source checkout.
+`capability-registry.json` is the navigation spine for that page surface. It
+groups manuals, pages, CLI commands, workflows, actions, Node API exports, and
+KFD claim facts into stable product capability groups. Site repositories should
+render navigation from this registry first, then use `page-registry.json`,
+`manual-registry.json`, `cli-registry.json`, `node-api-registry.json`, and
+`workflow-registry.json` for the concrete entries inside each group.
 `page-registry.json` is the complete page fact source: README homepage content,
 all packaged `docs/*.md` manuals, action README files, the Node API package
 overview, and fixture guides.
@@ -126,6 +133,8 @@ this gate, so release candidates cannot publish an out-of-date site bundle.
 The P0 bundle includes:
 
 - README-derived homepage fields and display plan;
+- capability-grouped navigation facts for docs, CLI, Node API, workflows,
+  actions, and KFD claims;
 - complete markdown page registry for public Buildchain docs, action manuals,
   Node API overview, and fixtures;
 - site manifest;

package/docs/web-surface-deployments.md

@@ -513,6 +513,24 @@ preflight, and health check so a reviewer or agent can audit why the production
 site changed and whether every declared host and every existing nested route was
 actually covered.
 
+Channels declared with `access_control = "managed-network"` use a different
+health strategy by default. Buildchain does not require a GitHub-hosted runner
+to fetch a URL that is intentionally reachable only from an approved network.
+Instead, after a live apply the health check uses the deploy role to run S3
+`head-object` checks for each surface manifest and the smoke target object, such
+as the surface `index.html` or a nested `docs/index.html`. The check records
+`healthStrategy = "s3-object"` and skips the public HTTP fetch. Dry-run and
+plan-only checks fall back to deployment evidence: each surface must have a
+manifest key, bucket, object prefix, `sync-static-artifact`, and
+`write-deployment-manifest` evidence, recorded as
+`healthStrategy = "deployment-evidence"`. If the workflow is running on a runner
+that is allowed to reach the managed network, set
+`BUILDCHAIN_WEB_SURFACE_HEALTH_ALLOWED_RUNNER=true` or pass
+`--allowed-managed-network-runner true` to keep the normal HTTP smoke checks.
+Set `BUILDCHAIN_WEB_SURFACE_HEALTH_S3_OBJECTS=false` or pass
+`--managed-network-s3-object-verification false` only when an external channel
+policy owns managed-network object verification.
+
 ## Cleanup Plans
 
 Preview cleanup is an auditable cleanup contract. It can run as a dry-run plan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.10.2",
+  "version": "2.10.3",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -34,6 +34,7 @@
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
     "./site/page-registry.json": "./dist/site/page-registry.json",
+    "./site/capability-registry.json": "./dist/site/capability-registry.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",

package/packages/core/buildchain-kfd-claims.js

@@ -14,6 +14,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
   { id: "install", title: "Install and verify Buildchain", path: "docs/install.md", plane: "use" },
   { id: "release-passport", title: "Release Passport protocol", path: "docs/release-passport.md", plane: "verify" },
+  { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
   { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
@@ -42,6 +43,7 @@ const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/buildchain-site.json",
   "dist/site/site-manifest.json",
   "dist/site/page-registry.json",
+  "dist/site/capability-registry.json",
   "dist/site/cli-registry.json",
   "dist/site/manual-registry.json",
   "dist/site/node-api-registry.json",
@@ -264,6 +266,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/manual-registry.json",
         "dist/site/node-api-registry.json",
         "dist/site/page-registry.json",
+        "dist/site/capability-registry.json",
         "dist/site/buildchain-site.json",
         "dist/site/site-manifest.json",
       ],

package/scripts/check-inventory.mjs

@@ -171,6 +171,9 @@ if (rootPackage.exports?.["./site/site-manifest.json"] !== "./dist/site/site-man
 if (rootPackage.exports?.["./site/page-registry.json"] !== "./dist/site/page-registry.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/page-registry.json");
 }
+if (rootPackage.exports?.["./site/capability-registry.json"] !== "./dist/site/capability-registry.json") {
+  throw new Error("root package must export @kungfu-tech/buildchain/site/capability-registry.json");
+}
 if (rootPackage.exports?.["./site/manual-registry.json"] !== "./dist/site/manual-registry.json") {
   throw new Error("root package must export @kungfu-tech/buildchain/site/manual-registry.json");
 }
@@ -208,6 +211,7 @@ const installDoc = fs.readFileSync(path.join(root, "docs/install.md"), "utf8");
 const siteBundle = JSON.parse(fs.readFileSync(path.join(root, "dist/site/buildchain-site.json"), "utf8"));
 const siteManifest = JSON.parse(fs.readFileSync(path.join(root, "dist/site/site-manifest.json"), "utf8"));
 const pageRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/page-registry.json"), "utf8"));
+const capabilityRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/capability-registry.json"), "utf8"));
 const badgeEndpointRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/badge-endpoint-registry.json"), "utf8"));
 const publicSurfaceAudit = JSON.parse(fs.readFileSync(path.join(root, "dist/site/public-surface-audit.json"), "utf8"));
 if (!cliSource.startsWith("#!/usr/bin/env node")) {
@@ -334,6 +338,15 @@ if (pageRegistry.contract !== "kungfu-buildchain-site-page-registry") {
 if (siteBundle.pageRegistry?.path !== "page-registry.json" || siteBundle.pageRegistry?.pageCount !== pageRegistry.pageCount) {
   throw new Error("buildchain-site.json must link to page-registry.json with matching page count");
 }
+if (capabilityRegistry.contract !== "kungfu-buildchain-capability-registry") {
+  throw new Error("capability-registry.json must expose the Buildchain capability registry contract");
+}
+if (siteBundle.capabilityRegistry?.path !== "capability-registry.json" || siteBundle.capabilityRegistry?.groupCount !== capabilityRegistry.groups?.length) {
+  throw new Error("buildchain-site.json must link to capability-registry.json with matching group count");
+}
+if (!siteManifest.facts?.includes("capability-registry.json") || !siteBundle.entrypoints?.includes("capability-registry.json")) {
+  throw new Error("site bundle entrypoints must include capability-registry.json");
+}
 if (!siteManifest.facts?.includes("page-registry.json") || !siteBundle.entrypoints?.includes("page-registry.json")) {
   throw new Error("site bundle entrypoints must include page-registry.json");
 }
@@ -388,10 +401,37 @@ if (JSON.stringify(bundlePageSources) !== JSON.stringify(expectedPageSources)) {
   throw new Error(`buildchain-site.json pages must include every public markdown page: expected ${expectedPageSources.length}, got ${bundlePageSources.length}`);
 }
 for (const page of pageRegistry.pages || []) {
-  if (!page.id || !page.route || !page.title || !page.category || !page.sourcePath || !page.digest || !page.markdown) {
+  if (!page.id || !page.route || !page.title || !page.category || !page.capabilityGroup || !Array.isArray(page.audience) || !page.maturity || !page.sourcePath || !page.digest || !page.markdown) {
     throw new Error(`page-registry.json page is incomplete: ${page.sourcePath || page.id || "<unknown>"}`);
   }
 }
+const capabilityGroupIds = new Set((capabilityRegistry.groups || []).map((group) => group.id));
+if (capabilityGroupIds.size < 6) {
+  throw new Error("capability-registry.json must expose grouped Buildchain capabilities");
+}
+for (const page of pageRegistry.pages || []) {
+  if (!capabilityGroupIds.has(page.capabilityGroup)) {
+    throw new Error(`page-registry.json page references unknown capability group: ${page.sourcePath || page.id}`);
+  }
+}
+const manualRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/manual-registry.json"), "utf8"));
+for (const manual of manualRegistry.manuals || []) {
+  if (!manual.capabilityGroup || !capabilityGroupIds.has(manual.capabilityGroup) || !Array.isArray(manual.audience) || !manual.maturity || typeof manual.order !== "number") {
+    throw new Error(`manual-registry.json manual missing capability metadata: ${manual.path || manual.id}`);
+  }
+}
+const cliRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/cli-registry.json"), "utf8"));
+for (const command of cliRegistry.commands || []) {
+  if (!command.capabilityGroup || !capabilityGroupIds.has(command.capabilityGroup) || !Array.isArray(command.audience) || !command.maturity || !command.purpose || command.purpose.includes("Add a specific purpose")) {
+    throw new Error(`cli-registry.json command missing capability metadata: ${command.id || command.usage}`);
+  }
+}
+const nodeApiRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/node-api-registry.json"), "utf8"));
+for (const exported of nodeApiRegistry.exports || []) {
+  if (!exported.capabilityGroup || !capabilityGroupIds.has(exported.capabilityGroup) || !Array.isArray(exported.audience) || !exported.maturity || !exported.summary) {
+    throw new Error(`node-api-registry.json export missing capability metadata: ${exported.export || exported.specifier}`);
+  }
+}
 if (!pageRegistry.pages?.some((page) => page.sourcePath === "actions/promote-buildchain-ref/README.md")) {
   throw new Error("page-registry.json must include action manuals");
 }
@@ -476,6 +516,7 @@ for (const requiredSnippet of [
   "GitHub Release",
   "release propagation",
   "Homebrew tap distribution indexes",
+  "capability-registry.json",
   "manual-registry.json",
   "node-api-registry.json",
   "README badge",
@@ -865,7 +906,7 @@ if (!badgeEndpointRegistry.badges?.some((entry) => entry.id === "buildchain-rele
   throw new Error("badge endpoint registry must include Buildchain Release Passport badge");
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }