@kungfu-tech/buildchain 2.8.16 → 2.8.17

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-07T15:39:12.336Z",
-  "publishedAt": "2026-07-07T15:39:12.336Z",
+  "generatedAt": "2026-07-08T00:24:24.491Z",
+  "publishedAt": "2026-07-08T00:24:24.491Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "19d02b246e1242f10bdb93a2a85d2f38b25c79b0",
+  "sourceRevision": "186482073690d8f922f5f4ecbea20849dda724a4",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.8.16",
+    "version": "2.8.17",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:f4300eed89765cee0df38eb92de4d9d3adce4fbf954c735aead3bea74f05d975"
+      "digest": "sha256:03f52660d03223fff7daf500f995645d78a46fffd8cddec9d8c01bbee0863145"
     },
     {
       "id": "install",
@@ -85,7 +85,7 @@
       "path": "docs/readme-badges.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:3f4a44ea7f3b70cadc78a343fe53ade74b78fa369c19630cc9b926c1e460f66f"
+      "digest": "sha256:c886d5d469d143571ae68497643be754b1616b562fddc780a5708f49b4c46242"
     },
     {
       "id": "homebrew",
@@ -181,7 +181,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:165011e2a932461805925c714c2c1c07f1ee60c4b3a614b6dcdda4b81ec22d68"
+      "digest": "sha256:e76aefe23b83f1b99b8c13cee1ca99760fd9902a41fbec25e193426329826340"
     },
     {
       "id": "publish-transaction",
@@ -229,7 +229,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4c7334fe2284fec3c1249124b0ff85f1242eb7a76d4b2c537c8b2cb6e0e598c1"
+      "digest": "sha256:5063ebb76db3cd36797561782e6c741e30d60bfa0dac8f798dbbd34c4ab2b3c0"
     }
   ],
   "facts": [
@@ -240,6 +240,7 @@
     "workflow-registry.json",
     "release-model.json",
     "artifact-schemas.json",
+    "badge-endpoint-registry.json",
     "product-mechanism.json",
     "release-provenance.json",
     "kfd-claims.json",

package/docs/MAP.md

@@ -69,6 +69,7 @@ replace them.
 | What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
 | 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 |
+| 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 |
 | How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |
 | How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |
 | How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |
@@ -102,6 +103,8 @@ replace them.
   [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).
 - **S3 artifact relay / self-hosted runner artifact transfer** ->
   [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).
+- **local Git checkout cache / self-hosted source transport** ->
+  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).
 - **runtime train validation / temporary `buildchain-ref` override** ->
   [`runtime-train-validation.md`](runtime-train-validation.md) and
   [`reusable-build-surface.md`](reusable-build-surface.md).

package/docs/readme-badges.md

@@ -2,8 +2,8 @@
 
 Buildchain can generate a managed README badge block from repository-owned
 facts. The README keeps only a projection; the source facts remain in
-`buildchain.toml`, package metadata, workflow files, and the repository's own
-release passport.
+`buildchain.toml`, package metadata, workflow files, KFD standards metadata,
+and the repository's own release passport.
 
 The managed block is delimited by:
 
@@ -32,11 +32,15 @@ import {
 `collectReadmeBadgeFacts({ cwd })` returns a machine-readable object with
 contract `kungfu-buildchain-readme-badge-facts`. It collects repository
 identity, package name/version/license, configured platforms, configured
-workflow status badges, release passport location and verification result, and
-KFD badge state. When present, it also summarizes local KFD claim registry and
-product-mechanism facts from the package-owned site bundle, so downstream
-agents can connect README badges back to Buildchain's KFD/source-of-truth
-surfaces.
+workflow status badges, the repository's own Buildchain Release Passport
+location and verification result, and KFD badge state. KFD badge labels,
+human-facing concept text, standard document links, schema IDs, and interface
+contracts are read from
+`@kungfu-tech/kfd/standards.json` when the package is installed, or from an
+explicit `kfd_standards` path/URL. When present, it also summarizes local KFD
+claim registry and product-mechanism facts from the package-owned site bundle,
+so downstream agents can connect README badges back to Buildchain's
+KFD/source-of-truth surfaces.
 
 `renderReadmeBadgeBlock(facts)` renders deterministic Markdown from that facts
 object. `checkReadmeBadgeBlock({ readmeText, facts })` compares the current
@@ -78,6 +82,7 @@ cannot be inferred safely:
 ```toml
 [badges]
 release_passport = "https://github.com/example/project/releases/latest/download/buildchain.release.json"
+kfd_standards = "node_modules/@kungfu-tech/kfd/standards.json"
 kfd_1 = "declared"
 kfd_2 = "planned"
 kfd_3 = "aligned"
@@ -90,11 +95,47 @@ workflows = ["verify.yml", "build.yml"]
 then the repository's latest GitHub Release asset when the GitHub repository
 can be discovered.
 
+The generated `Buildchain Release Passport` badge is a repository capability
+badge: it says whether the current repository has a Buildchain release passport
+that can be verified. It does not report the upstream `kungfu-systems/buildchain`
+repository status. Buildchain's own README dogfoods the same rule because its
+configured `release_passport` points at Buildchain's own release passport.
+
+Buildchain-owned badges use stable hosted image URLs by default:
+
+```text
+https://buildchain.libkungfu.dev/badges/v1/{badge}/{state}.svg
+```
+
+The URL is part of the Buildchain badge contract. Consumers do not need to
+regenerate README files when Buildchain replaces the placeholder badge logo
+with a formal logo; the hosted endpoint owns logo rendering. The package-owned
+site bundle publishes `badge-endpoint-registry.json` plus Shields-compatible
+JSON payloads under `badges/v1/**` so the site repository can serve or render
+the exact SVG endpoints without inventing badge facts.
+
+Forks or private deployments can override the image host with:
+
+```toml
+[badges]
+badge_endpoint_base_url = "https://example.com/buildchain-badges/v1"
+```
+
+`kfd_standards` is optional. If omitted, Buildchain tries the installed
+`@kungfu-tech/kfd/standards.json` package export. Use the explicit path or URL
+only when a repository deliberately vendors KFD standards metadata or validates
+against a local KFD development checkout. The KFD standards metadata controls
+the badge vocabulary; the release passport still controls whether a repository
+may display a KFD state as `passed`.
+
 ## KFD Badge Rules
 
 KFD passed is evidence-backed. A repository may display `KFD-1 passed`,
 `KFD-2 passed`, or `KFD-3 passed` only when its own release passport verifies
 successfully and the corresponding passport section has `status: "passed"`.
+The KFD badge vocabulary comes from KFD standards metadata, not Buildchain
+private strings: for example KFD-2 uses the `releaseTrustPassport` concept from
+`@kungfu-tech/kfd/standards.json`.
 
 When no release passport exists yet, or when the passport cannot be verified,
 Buildchain downgrades each KFD badge to the explicit local declaration such as

package/docs/reusable-build-surface.md

@@ -214,6 +214,55 @@ The lock is intentionally small. It does not copy the full contract. The full
 contract remains in the Buildchain ref and package; the consumer records only
 what it accepted and the policy used to compare future floating-ref movement.
 
+## Locked Source Checkout Cache
+
+Self-hosted runners that build large repositories can opt into a locked source
+checkout cache. This changes only the Git object transport. Buildchain still
+resolves `publish-source-sha` before any build runner starts, checks out that
+exact commit, and verifies `HEAD` plus the resolved source tree SHA before
+lifecycle commands run.
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    with:
+      runner-preset: kungfu-v4-self-hosted
+      checkout-cache-mode: auto
+      checkout-cache-mirror-url-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE }}
+      checkout-cache-reference-repository-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE }}
+      checkout-cache-fallback: github
+      checkout-cache-timeout-seconds: 60
+```
+
+`checkout-cache-mode` accepts:
+
+| Mode | Behavior |
+| --- | --- |
+| `off` | Default. Buildchain fetches the locked commit from GitHub. |
+| `auto` | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
+| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable. |
+
+The cache can be a local/LAN mirror URL template or a runner-local bare
+reference repository template. Templates support `{owner}`, `{repo}`,
+`{repository}`, `{repositorySlug}`, and `{sha}`. The workflow also reads
+repository or organization variables named
+`BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE` and
+`BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE`, so consumers can keep
+private LAN topology out of repository YAML.
+
+Do not read cache URLs or reference paths from PR-controlled files such as
+`buildchain.toml`. These values are trusted workflow inputs or repo/org
+variables. Buildchain does not pass GitHub credentials to cache mirrors or
+reference repositories. If it must fall back to GitHub, the workflow token is
+used only for the GitHub fetch path.
+
+Each platform diagnostics artifact includes `source-checkout.json` and embeds a
+compact `sourceCheckout` summary in `diagnostics.json`: mode, transport,
+hit/miss, fallback reason, duration, final HEAD verification, and tree
+verification. Remote URLs are sanitized and local reference paths are represented
+by a short display name plus fingerprint, not by secret-bearing credentials.
+
 When a Buildchain maintainer asks for downstream validation, the expected
 request is:
 

package/docs/web-surface-deployments.md

@@ -457,18 +457,20 @@ node scripts/web-surface.mjs \
   --output .buildchain/web-surface-production-health.json
 ```
 
-The health check fetches every surface root URL and the nested smoke URLs
-recorded in each surface binding. Nested smoke URLs are derived from the
+The health check fetches every surface root URL and any nested smoke URLs
+recorded in each surface binding. Nested smoke URLs are derived from nested HTML
 artifact files under the surface path prefix, with directory index resolution
 such as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain
-preview host. This fails closed when a deploy reports success but a child page
-returns 403 or another unexpected status. Production additionally fails if a
+preview host. If a surface has no nested HTML route, Buildchain records only
+the root smoke URL; absence of nested HTML is not a deployment failure. When a
+nested route is present, the check fails closed if a deploy reports success but
+that child page returns 403 or another unexpected status. Production additionally fails if a
 response is unreachable, returns an unexpected status, or still sends
 `x-robots-tag: noindex`. The health check also verifies that each surface
 binding recorded a deployment manifest pointer. The production release passport
 embeds the deploy plan, apply result, production preflight, and health check so
 a reviewer or agent can audit why the production site changed and whether every
-declared host and nested route was actually covered.
+declared host and every existing nested route was actually covered.
 
 ## Cleanup Plans
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.8.16",
+  "version": "2.8.17",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/diagnostics.js

@@ -33,6 +33,8 @@ export const BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT =
   "kungfu-buildchain-process-sample-report";
 export const BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT =
   "kungfu-buildchain-process-sample-summary";
+export const BUILDCHAIN_LOCKED_SOURCE_CHECKOUT_CONTRACT =
+  "kungfu-buildchain-locked-source-checkout-cache";
 
 const DEFAULT_SECRET_KEY_PATTERN =
   /(authorization|cookie|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)/i;
@@ -1084,6 +1086,7 @@ export function createDiagnosticsArtifact({
   processSamples = [],
   processSummary = undefined,
   requestedParallelism = 0,
+  sourceCheckout = undefined,
   links = {},
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
@@ -1107,6 +1110,7 @@ export function createDiagnosticsArtifact({
     git: collectGitDiagnostics({ cwd: resolvedCwd }),
     lifecycleObservability: lifecycleObservability || summarizeLifecycleObservability({ events, logPath }),
     process: processSummary || summarizeProcessSamples({ samples: processSamples, requestedParallelism }),
+    ...(sourceCheckout ? { sourceCheckout } : {}),
     links,
   };
 }
@@ -1509,6 +1513,18 @@ export function summarizeDiagnosticsArtifacts(inputs = []) {
           ? entry.native.cacheDirs
           : [],
       process: entry.process || {},
+      sourceCheckout: entry.sourceCheckout
+        ? {
+            mode: entry.sourceCheckout.policy?.mode || "",
+            transport: entry.sourceCheckout.cache?.transport || "",
+            hit: Boolean(entry.sourceCheckout.cache?.hit),
+            fallbackUsed: Boolean(entry.sourceCheckout.cache?.fallbackUsed),
+            fallbackReason: entry.sourceCheckout.cache?.fallbackReason || "",
+            durationMs: Number(entry.sourceCheckout.durationMs || 0),
+            headOk: Boolean(entry.sourceCheckout.verification?.headOk),
+            treeOk: Boolean(entry.sourceCheckout.verification?.treeOk),
+          }
+        : undefined,
       diagnosticsContract,
       ...(diagnosticsManifest ? { diagnosticsManifest } : {}),
       links: entry.links || {},

package/packages/core/index.js

@@ -60,6 +60,7 @@ export {
   BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT,
   BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,
   BUILDCHAIN_LIFECYCLE_OBSERVABILITY_CONTRACT,
+  BUILDCHAIN_LOCKED_SOURCE_CHECKOUT_CONTRACT,
   BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT,
   BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT,
   classifyProcessCommand,
@@ -196,8 +197,10 @@ export {
   README_BADGE_BLOCK_END,
   README_BADGE_BLOCK_START,
   README_BADGE_FACTS_CONTRACT,
+  README_BADGE_HOSTED_BASE_URL,
   checkReadmeBadgeBlock,
   collectReadmeBadgeFacts,
+  createReadmeBadgeEndpointRegistry,
   readReadme,
   renderReadmeBadgeBlock,
   updateReadmeBadgeBlock,

package/packages/core/readme-badges.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
+import { createRequire } from "node:module";
 import { loadBuildchainConfig } from "./buildchain-config.js";
 import {
   readJsonFromLocation,
@@ -11,6 +12,7 @@ import {
 export const README_BADGE_FACTS_CONTRACT = "kungfu-buildchain-readme-badge-facts";
 export const README_BADGE_BLOCK_START = "<!-- buildchain:badges:start -->";
 export const README_BADGE_BLOCK_END = "<!-- buildchain:badges:end -->";
+export const README_BADGE_HOSTED_BASE_URL = "https://buildchain.libkungfu.dev/badges/v1";
 
 const KFD_KEYS = [
   { key: "kfd-1", id: "kfd1", label: "KFD-1", text: "contract world" },
@@ -18,6 +20,14 @@ const KFD_KEYS = [
   { key: "kfd-3", id: "kfd3", label: "KFD-3", text: "collaboration interface" },
 ];
 
+const KFD_BADGE_CONCEPTS = {
+  "kfd-1": "contractWorld",
+  "kfd-2": "releaseTrustPassport",
+  "kfd-3": "collaborationInterface",
+};
+
+const requireFromHere = createRequire(import.meta.url);
+
 const STATE_COLORS = {
   passed: "2ea44f",
   aligned: "0969da",
@@ -30,6 +40,22 @@ const STATE_COLORS = {
   unknown: "6e7781",
 };
 
+const BUILDCHAIN_BADGE_IDS = [
+  "kfd-1",
+  "kfd-2",
+  "kfd-3",
+  "buildchain-release-passport",
+];
+
+const BUILDCHAIN_BADGE_LOGO_PLACEHOLDER = {
+  contract: "kungfu-buildchain-badge-logo-policy",
+  mode: "hosted-placeholder",
+  placeholder: "buildchain-monogram",
+  futureLogoUpdateRequiresConsumerAction: false,
+  owner: "Buildchain site badge endpoint",
+  note: "README image URLs point at stable Buildchain-hosted badge endpoints; the rendered logo is controlled by the endpoint, not by consumer README text.",
+};
+
 function readJsonIfExists(filePath) {
   if (!filePath || !fs.existsSync(filePath)) {
     return undefined;
@@ -37,6 +63,18 @@ function readJsonIfExists(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
+function readPackageJsonForResolvedFile(filePath) {
+  let current = path.dirname(filePath);
+  while (current && current !== path.dirname(current)) {
+    const packagePath = path.join(current, "package.json");
+    if (fs.existsSync(packagePath)) {
+      return readJsonIfExists(packagePath) || {};
+    }
+    current = path.dirname(current);
+  }
+  return {};
+}
+
 function readTextIfExists(filePath) {
   return fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
 }
@@ -59,6 +97,61 @@ function badgeUrl({ label, message, color }) {
   return `https://img.shields.io/badge/${encodeBadge(label)}-${encodeBadge(message)}-${color || "6e7781"}.svg`;
 }
 
+function badgeEndpointBaseUrl(badgeConfig = {}) {
+  return String(
+    badgeConfig.badge_endpoint_base_url ||
+    badgeConfig.badgeEndpointBaseUrl ||
+    README_BADGE_HOSTED_BASE_URL,
+  ).replace(/\/+$/, "");
+}
+
+function hostedBadgeUrl({ badgeConfig = {}, id, state }) {
+  return `${badgeEndpointBaseUrl(badgeConfig)}/${encodeURIComponent(id)}/${encodeURIComponent(state || "unknown")}.svg`;
+}
+
+export function createReadmeBadgeEndpointRegistry({ kfdSpecs = KFD_KEYS } = {}) {
+  const states = Object.keys(STATE_COLORS).filter((state) => state !== "unknown");
+  const specs = [
+    ...kfdSpecs.map((entry) => ({
+      id: entry.key,
+      label: entry.label,
+      messageTemplate: `${entry.text} {state}`,
+      linkRole: "repository-release-passport",
+    })),
+    {
+      id: "buildchain-release-passport",
+      label: "buildchain",
+      messageTemplate: "release passport {state}",
+      linkRole: "repository-release-passport",
+    },
+  ];
+  return {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-readme-badge-endpoint-registry",
+    endpointBaseUrl: README_BADGE_HOSTED_BASE_URL,
+    imagePathTemplate: "/badges/v1/{badge}/{state}.svg",
+    jsonPathTemplate: "/badges/v1/{badge}/{state}.json",
+    consumerActionForLogoChange: "none",
+    logoPolicy: BUILDCHAIN_BADGE_LOGO_PLACEHOLDER,
+    shieldsEndpointCompatible: true,
+    badges: specs.map((spec) => ({
+      ...spec,
+      states: states.map((state) => ({
+        state,
+        path: `badges/v1/${spec.id}/${state}.json`,
+        svgPath: `badges/v1/${spec.id}/${state}.svg`,
+        payload: {
+          schemaVersion: 1,
+          label: spec.label,
+          message: spec.messageTemplate.replace("{state}", state),
+          color: STATE_COLORS[state] || STATE_COLORS.unknown,
+          logoPolicy: BUILDCHAIN_BADGE_LOGO_PLACEHOLDER,
+        },
+      })),
+    })),
+  };
+}
+
 function normalizeState(value, fallback = "planned") {
   const normalized = String(value || fallback).trim().toLowerCase();
   if (["passed", "aligned", "declared", "planned", "draft", "downgraded", "failed", "missing"].includes(normalized)) {
@@ -81,6 +174,128 @@ function normalizeStringArray(value) {
     .filter(Boolean);
 }
 
+function resolveLocalFactPath({ cwd, location }) {
+  const value = String(location || "").trim();
+  if (!value || /^https?:\/\//.test(value)) {
+    return "";
+  }
+  return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}
+
+function kfdStandardsLocation({ cwd, badgeConfig = {} }) {
+  return String(
+    badgeConfig.kfd_standards ||
+    badgeConfig.kfdStandards ||
+    badgeConfig.kfd_standards_path ||
+    badgeConfig.kfdStandardsPath ||
+    process.env.BUILDCHAIN_KFD_STANDARDS_PATH ||
+    "",
+  ).trim();
+}
+
+async function loadKfdStandards({ cwd, badgeConfig = {} }) {
+  const configured = kfdStandardsLocation({ cwd, badgeConfig });
+  if (configured) {
+    const localPath = resolveLocalFactPath({ cwd, location: configured });
+    const value = /^https?:\/\//.test(configured)
+      ? await readJsonFromLocation(configured)
+      : readJsonIfExists(localPath);
+    if (!value || typeof value !== "object") {
+      throw new Error(`KFD standards metadata is not readable: ${configured}`);
+    }
+    return {
+      location: configured,
+      resolvedPath: localPath,
+      source: /^https?:\/\//.test(configured) ? "configured-url" : "configured-path",
+      sha256: localPath && fs.existsSync(localPath) ? sha256File(localPath) : hashText(JSON.stringify(value)),
+      package: {},
+      value,
+      error: "",
+    };
+  }
+  try {
+    const resolvedPath = requireFromHere.resolve("@kungfu-tech/kfd/standards.json", {
+      paths: [cwd],
+    });
+    const value = readJsonIfExists(resolvedPath);
+    const packageJson = readPackageJsonForResolvedFile(resolvedPath);
+    return {
+      location: "@kungfu-tech/kfd/standards.json",
+      resolvedPath,
+      source: "package-export",
+      sha256: sha256File(resolvedPath),
+      package: {
+        name: packageJson.name || "@kungfu-tech/kfd",
+        version: packageJson.version || "",
+      },
+      value,
+      error: "",
+    };
+  } catch (error) {
+    return {
+      location: "@kungfu-tech/kfd/standards.json",
+      resolvedPath: "",
+      source: "fallback",
+      sha256: "",
+      package: {},
+      value: undefined,
+      error: error.message,
+    };
+  }
+}
+
+function summarizeKfdStandards(loaded) {
+  const standards = loaded?.value?.standards && typeof loaded.value.standards === "object"
+    ? loaded.value.standards
+    : {};
+  const summary = {
+    contract: loaded?.value?.contract || "",
+    schemaVersion: loaded?.value?.schemaVersion || undefined,
+    metadataSchema: loaded?.value?.metadataSchema || undefined,
+    source: loaded?.source || "fallback",
+    location: loaded?.location || "",
+    sha256: loaded?.sha256 || "",
+    package: loaded?.package || {},
+    error: loaded?.error || "",
+    standards: {},
+  };
+  for (const fallback of KFD_KEYS) {
+    const standard = standards[fallback.key] || {};
+    const conceptKey = KFD_BADGE_CONCEPTS[fallback.key];
+    summary.standards[fallback.key] = {
+      key: standard.key || fallback.key,
+      id: standard.id || fallback.label,
+      label: standard.label || fallback.label,
+      title: standard.title || "",
+      status: standard.status || "",
+      revision: standard.revision || undefined,
+      documentUrl: standard.document?.url || "",
+      documentPath: standard.document?.path || "",
+      documentSha256: standard.document?.sha256 || "",
+      badgeText: standard.concepts?.[conceptKey] || fallback.text,
+      interfaceContract: conceptKey ? standard.interfaces?.[conceptKey]?.contract || "" : "",
+      schemaId: conceptKey ? standard.interfaces?.[conceptKey]?.schemaId || standard.schemaIds?.[conceptKey] || "" : "",
+    };
+  }
+  return summary;
+}
+
+function kfdBadgeSpecs(kfdStandards) {
+  return KFD_KEYS.map((fallback) => {
+    const standard = kfdStandards?.standards?.[fallback.key] || {};
+    return {
+      ...fallback,
+      label: standard.label || fallback.label,
+      text: standard.badgeText || fallback.text,
+      title: standard.title || "",
+      standardDocumentUrl: standard.documentUrl || "",
+      standardDocumentSha256: standard.documentSha256 || "",
+      interfaceContract: standard.interfaceContract || "",
+      schemaId: standard.schemaId || "",
+    };
+  });
+}
+
 function readRepositoryFromGit(cwd) {
   const remote = spawnSync("git", ["config", "--get", "remote.origin.url"], {
     cwd,
@@ -273,28 +488,20 @@ function localFactFileSummary(cwd, candidates = []) {
   return undefined;
 }
 
-function buildBadgeEntries(facts) {
+function buildBadgeEntries(facts, { badgeConfig = {} } = {}) {
   const entries = [];
   for (const kfd of facts.kfd) {
     entries.push({
       id: kfd.key,
       alt: `${kfd.label}: ${kfd.state}`,
-      image: badgeUrl({
-        label: kfd.label,
-        message: `${kfd.text} ${kfd.state}`,
-        color: STATE_COLORS[kfd.state] || STATE_COLORS.unknown,
-      }),
+      image: hostedBadgeUrl({ badgeConfig, id: kfd.key, state: kfd.state }),
       link: kfd.url,
     });
   }
   entries.push({
-    id: "release-passport",
-    alt: `Release Passport: ${facts.releasePassport.state}`,
-    image: badgeUrl({
-      label: "release passport",
-      message: facts.releasePassport.state,
-      color: STATE_COLORS[facts.releasePassport.state] || STATE_COLORS.unknown,
-    }),
+    id: "buildchain-release-passport",
+    alt: `Buildchain Release Passport: ${facts.releasePassport.state}`,
+    image: hostedBadgeUrl({ badgeConfig, id: "buildchain-release-passport", state: facts.releasePassport.state }),
     link: facts.releasePassport.url,
   });
   if (facts.package.license) {
@@ -344,13 +551,19 @@ export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
       ? `${repository.url}/blob/HEAD/${posixPath(releasePassportLocation)}`
       : releasePassportLocation;
   const releaseState = releasePassportState({ report, error, badgeConfig });
-  const kfd = KFD_KEYS.map((entry) => {
+  const kfdStandards = summarizeKfdStandards(await loadKfdStandards({ cwd: resolvedCwd, badgeConfig }));
+  const kfd = kfdBadgeSpecs(kfdStandards).map((entry) => {
     const passed = kfdSectionPassed({ passport, report, key: entry.key });
     const state = passed ? "passed" : declaredKfdState({ badgeConfig, key: entry.key, id: entry.id });
     return {
       key: entry.key,
       label: entry.label,
       text: entry.text,
+      title: entry.title,
+      standardDocumentUrl: entry.standardDocumentUrl,
+      standardDocumentSha256: entry.standardDocumentSha256,
+      interfaceContract: entry.interfaceContract,
+      schemaId: entry.schemaId,
       state,
       source: passed ? "release-passport" : "declaration",
       url: releasePassportUrl,
@@ -382,6 +595,7 @@ export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
       "dist/site/kfd-claims.json",
       ".buildchain/kfd-claims.json",
     ]),
+    kfdStandards,
     productMechanism: localFactFileSummary(resolvedCwd, [
       "dist/site/product-mechanism.json",
       "product-mechanism.json",
@@ -390,9 +604,15 @@ export async function collectReadmeBadgeFacts({ cwd = process.cwd() } = {}) {
     kfd,
     platforms: collectPlatformFacts({ badgeConfig, passport }),
     workflows: discoverWorkflowFacts({ cwd: resolvedCwd, repository, badgeConfig }),
+    badgeRuntime: {
+      provider: "buildchain-hosted",
+      endpointBaseUrl: badgeEndpointBaseUrl(badgeConfig),
+      hostedBadgeIds: BUILDCHAIN_BADGE_IDS,
+      logoPolicy: BUILDCHAIN_BADGE_LOGO_PLACEHOLDER,
+    },
     badges: [],
   };
-  facts.badges = buildBadgeEntries(facts);
+  facts.badges = buildBadgeEntries(facts, { badgeConfig });
   return facts;
 }