@kungfu-tech/buildchain 3.0.4-alpha.4 → 3.0.4-alpha.6

package/docs/site-bundle-contract.md

@@ -58,8 +58,13 @@ 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.
+`package.json#exports` and closes each JavaScript subpath over its exact exported
+symbols. Each symbol includes its source-derived signature and parameters,
+conservative return/error contract, detected side effects, maturity, example
+import, and source location, so agents do not have to infer supported APIs from
+internal paths. `cli-registry.json` similarly retains every governed command
+path, syntax, option, alias, and side-effect-free help command projected from
+the runtime registry and usage authority.
 `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
@@ -130,6 +135,7 @@ import siteManifest from "@kungfu-tech/buildchain/site/site-manifest.json" with
 ## Generation
 
 ```bash
+pnpm run generate:reference
 pnpm run generate:site
 pnpm run check:site
 ```
@@ -148,9 +154,9 @@ The P0 bundle includes:
   Node API overview, and fixtures;
 - site manifest;
 - publication archive registry for downstream papers surfaces;
-- CLI command registry;
+- CLI command registry plus full-path generated human reference;
 - manual registry for packaged agent-facing documentation;
-- Node API registry for public package exports;
+- Node API registry plus per-symbol generated human reference for public package exports;
 - workflow/action registry;
 - release model facts;
 - artifact and evidence schema index;

package/docs/versioning.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-08-01
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -79,9 +79,10 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                              |       |
-| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                             | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |
-| 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                               | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                       |       |
+| 2026-08-01 | extend-minor | `v3.0`  | cli-reference-registry, node-api-symbol-registry, golden-path-manual                                                                                                         | additive | Add generated, drift-checked CLI and Node API reference registries to the public site bundle, plus a package-tested first-user Golden Path; existing command execution and import semantics remain unchanged.                                                                                                                          |       |
+| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                            |       |
+| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                              | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |
+| 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                              | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                        |       |
 | 2026-07-29 | extend-minor | `v3.0`  | artifact-signing-config, apple-developer-id-authority, artifact-signing-evidence                                                                                             | additive | Extend the consumer-neutral signing declaration to macOS compound archives, including nested wheel Mach-O signing, PEP 427 RECORD repair, safe archive reconstruction, and whole-product notarization under the same protected authority.                                                                                              |       |
 | 2026-07-28 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default.                                                                                                           |       |
 | 2026-07-26 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-evidence                                                                                                                             | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle.                                                                                                              | #1862 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.4-alpha.4",
+  "version": "3.0.4-alpha.6",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -108,11 +108,14 @@
   },
   "packageManager": "pnpm@11.7.0",
   "scripts": {
-    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && node scripts/check-action-bundles.mjs",
-    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs",
+    "check": "pnpm run check:static && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json bin/internal/command-registry.mjs scripts/authorize-promotion-runtime-override.cjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
-    "generate:site": "node scripts/generate-site-bundle.mjs",
-    "check:site": "node scripts/generate-site-bundle.mjs --check",
+    "generate:reference": "node scripts/generate-public-reference.mjs",
+    "check:reference": "node scripts/generate-public-reference.mjs --check",
+    "generate:site": "pnpm run generate:reference && node scripts/generate-site-bundle.mjs",
+    "check:site": "pnpm run check:reference && node scripts/generate-site-bundle.mjs --check",
+    "check:golden-path": "node scripts/verify-golden-path.mjs",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",
     "binary:build": "node scripts/build-standalone-binary.mjs",

package/packages/core/buildchain-agent-manuals.js

@@ -0,0 +1,37 @@
+export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
+  { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
+  { id: "getting-started", title: "Golden Path", path: "docs/getting-started.md", plane: "use" },
+  { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
+  { 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: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.md", plane: "verify" },
+  { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
+  { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
+  { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.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" },
+  { id: "binary-distribution", title: "Binary distribution contract", path: "docs/binary-distribution.md", plane: "verify" },
+  { id: "consumer-issue-reporting", title: "Consumer issue reporting", path: "docs/consumer-issue-reporting.md", plane: "use" },
+  { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
+  { id: "toolkit-observability", title: "Toolkit observability", path: "docs/toolkit-observability.md", plane: "use" },
+  { id: "site-bundle-contract", title: "Site bundle contract", path: "docs/site-bundle-contract.md", plane: "use" },
+  { id: "migration-inventory", title: "Migration inventory", path: "docs/migration-inventory.md", plane: "verify" },
+  { id: "ownership", title: "Ownership", path: "docs/ownership.md", plane: "why" },
+  { id: "product-mechanism", title: "Product mechanism", path: "docs/product-mechanism.md", plane: "why" },
+  { id: "cli", title: "CLI and npm package", path: "docs/cli.md", plane: "use" },
+  { id: "cli-reference", title: "Generated CLI reference", path: "docs/cli-reference.md", plane: "use" },
+  { id: "node-api-reference", title: "Generated Node API reference", path: "docs/node-api-reference.md", plane: "use" },
+  { id: "build-facts", title: "Build Facts", path: "docs/build-facts.md", plane: "use" },
+  { id: "kfd-support", title: "KFD support and KFD-3 surface registration", path: "docs/kfd-support.md", plane: "verify" },
+  { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
+  { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
+  { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
+  { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
+  { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
+  { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
+  { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
+  { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },
+  { id: "web-surface-deployments", title: "Web surface deployments", path: "docs/web-surface-deployments.md", plane: "use" },
+]);

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

@@ -7,45 +7,13 @@ import {
   collectPublicSurfaceReverseAudit,
 } from "./public-surface-audit.js";
 import { normalizeKfd3DistributionDeclaration } from "./kfd3-surface-register.js";
+import { BUILDCHAIN_AGENT_MANUALS } from "./buildchain-agent-manuals.js";
+
+export { BUILDCHAIN_AGENT_MANUALS } from "./buildchain-agent-manuals.js";
 
 export const BUILDCHAIN_KFD_CLAIM_REGISTRY_CONTRACT = "kungfu-buildchain-kfd-claim-registry";
 export const BUILDCHAIN_KFD_COLLABORATION_INTERFACE_CONTRACT = "kungfu-buildchain-kfd-collaboration-interface";
 
-export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
-  { id: "map", title: "Buildchain documentation map", path: "docs/MAP.md", plane: "use" },
-  { id: "auditable-demo", title: "Auditable demo artifact pipeline", path: "docs/auditable-demo.md", plane: "verify" },
-  { 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: "github-artifact-attestation", title: "GitHub-native Linux artifact attestation", path: "docs/github-artifact-attestation.md", plane: "verify" },
-  { id: "controller-evidence", title: "Controller evidence contract", path: "docs/controller-evidence.md", plane: "verify" },
-  { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
-  { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.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" },
-  { id: "binary-distribution", title: "Binary distribution contract", path: "docs/binary-distribution.md", plane: "verify" },
-  { id: "consumer-issue-reporting", title: "Consumer issue reporting", path: "docs/consumer-issue-reporting.md", plane: "use" },
-  { id: "infra-contract", title: "Infra Contract", path: "docs/infra-contract.md", plane: "use" },
-  { id: "toolkit-observability", title: "Toolkit observability", path: "docs/toolkit-observability.md", plane: "use" },
-  { id: "site-bundle-contract", title: "Site bundle contract", path: "docs/site-bundle-contract.md", plane: "use" },
-  { id: "migration-inventory", title: "Migration inventory", path: "docs/migration-inventory.md", plane: "verify" },
-  { id: "ownership", title: "Ownership", path: "docs/ownership.md", plane: "why" },
-  { id: "product-mechanism", title: "Product mechanism", path: "docs/product-mechanism.md", plane: "why" },
-  { id: "cli", title: "CLI and npm package", path: "docs/cli.md", plane: "use" },
-  { id: "build-facts", title: "Build Facts", path: "docs/build-facts.md", plane: "use" },
-  { id: "kfd-support", title: "KFD support and KFD-3 surface registration", path: "docs/kfd-support.md", plane: "verify" },
-  { id: "kfd-agent-hub", title: "KFD Agent Hub Builder flow", path: "docs/kfd-agent-hub.md", plane: "use" },
-  { id: "lifecycle-protocol", title: "Lifecycle protocol", path: "docs/lifecycle-protocol.md", plane: "use" },
-  { id: "reusable-build-surface", title: "Reusable build surface", path: "docs/reusable-build-surface.md", plane: "use" },
-  { id: "publish-transaction", title: "Publish transaction", path: "docs/publish-transaction.md", plane: "verify" },
-  { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
-  { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
-  { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
-  { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },
-  { id: "web-surface-deployments", title: "Web surface deployments", path: "docs/web-surface-deployments.md", plane: "use" },
-]);
-
 const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/buildchain-site.json",
   "dist/site/site-manifest.json",
@@ -203,7 +171,6 @@ function uniqueById(entries) {
     return true;
   });
 }
-
 function uniquePaths(paths) {
   return [...new Set(paths.filter(Boolean))].sort();
 }

package/packages/core/paper-agent-entry.js

@@ -199,10 +199,14 @@ function ciContext({ env, developmentRef }) {
   const pullRequest = ["pull_request", "pull_request_target"].includes(event);
   const channelBranches = expectedCiBranches(developmentRef);
   const channelIndex = channelBranches.indexOf(targetBranch);
+  const versionStatePrefix = `buildchain/version-state/${targetBranch.replaceAll("/", "-")}/`;
+  const generatedVersionState =
+    channelBranches.includes(targetBranch) &&
+    sourceBranch.startsWith(versionStatePrefix) &&
+    /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
-        targetBranch === developmentRef) ||
-      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1])
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
+      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
     : channelBranches.includes(refName);
   return {
     mode: "ci",
@@ -213,7 +217,7 @@ function ciContext({ env, developmentRef }) {
     pullRequest,
     ok: branchOk,
     message: pullRequest
-      ? `Pull requests must target ${developmentRef} from an allowed work branch or promote adjacent protected channels.`
+      ? `Pull requests must target ${developmentRef} from an allowed work branch, promote adjacent protected channels, or carry an exact target-bound generated version state.`
       : `Channel checks must run on ${channelBranches.join(", ")}.`,
   };
 }

package/packages/core/paper.js

@@ -421,6 +421,7 @@ ${passportInput}    secrets:
       BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
       BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
       BUILDCHAIN_GENERATED_WRITE_TOKEN: \${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}
+      BUILDCHAIN_PROMOTION_TOKEN: \${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
 `;
 }
 

package/packages/core/publication-package.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { loadBuildchainConfig } from "./buildchain-config.js";
 
 export const PUBLICATION_NPM_PACKAGE_CONTRACT = "kungfu-buildchain-publication-npm-package";
+const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
 
 function toPosix(value) {
   return String(value || "").split(path.sep).join("/");
@@ -154,6 +155,11 @@ export function preparePublicationNpmPackage({
   if (!fs.existsSync(passportFile)) {
     throw new Error(`publication passport is missing: ${facts.publication.passportPath}`);
   }
+  const manifest = readJson(manifestFile);
+  const gitHead = String(manifest.source?.sha || "").trim().toLowerCase();
+  if (!GIT_SHA_PATTERN.test(gitHead)) {
+    throw new Error("publication npm package requires an exact 40-character source Git SHA");
+  }
   if (!files.some((file) => file.path === facts.publication.primaryArtifact)) {
     throw new Error(`publication primary artifact is missing from npm package: ${facts.publication.primaryArtifact}`);
   }
@@ -174,6 +180,7 @@ export function preparePublicationNpmPackage({
     description: `${facts.publication.title} publication artifact package.`,
     license: sourcePackage.license || "UNLICENSED",
     repository,
+    gitHead,
     type: "module",
     files: [
       ".buildchain/publication/",

package/scripts/check-inventory.mjs

@@ -15,11 +15,10 @@ import {
   generateChannelPromotionWorkflow,
   parsePromotionShellRouting,
 } from "./generate-channel-promotion-workflow.mjs";
-
+import { assertPublicReferenceRegistry } from "./site-reference-registry.mjs";
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
 const commonJsSourcePattern = /\b(require\s*\(|module\.exports|exports\.|require\.main|createRequire)\b/;
-
 function assertSelfReleaseImpactContract(impact, { expectedVersion = "" } = {}) {
   if (!impact || typeof impact !== "object" || Array.isArray(impact)) {
     throw new Error("Buildchain self release impact must be a JSON object");
@@ -700,6 +699,7 @@ for (const exported of nodeApiRegistry.exports || []) {
   }
   assertPublicLifecycle(exported, `node-api-registry.json export ${exported.export || exported.specifier}`);
 }
+assertPublicReferenceRegistry({ cliRegistry, nodeApiRegistry });
 const workflowRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/workflow-registry.json"), "utf8"));
 for (const workflow of workflowRegistry.workflows || []) {
   assertPublicLifecycle(workflow, `workflow-registry.json workflow ${workflow.id || workflow.path}`);

package/scripts/generate-public-reference.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { BUILDCHAIN_USAGE } from "./buildchain-cli-help.mjs";
+import {
+  createCliReference,
+  createNodeApiReference,
+  renderCliReference,
+  renderNodeApiReference,
+} from "./public-reference.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export function publicReferenceOutputs({ repoRoot = root } = {}) {
+  const packageJson = JSON.parse(
+    fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"),
+  );
+  return {
+    "docs/cli-reference.md": renderCliReference(
+      createCliReference(BUILDCHAIN_USAGE),
+    ),
+    "docs/node-api-reference.md": renderNodeApiReference(
+      createNodeApiReference({ root: repoRoot, packageJson }),
+    ),
+  };
+}
+
+export function generatePublicReference({
+  check = false,
+  repoRoot = root,
+} = {}) {
+  const outputs = publicReferenceOutputs({ repoRoot });
+  const stale = [];
+  for (const [relPath, content] of Object.entries(outputs)) {
+    const filePath = path.join(repoRoot, relPath);
+    const current = fs.existsSync(filePath)
+      ? fs.readFileSync(filePath, "utf8")
+      : "";
+    if (current !== content) {
+      if (check) stale.push(relPath);
+      else fs.writeFileSync(filePath, content);
+    }
+  }
+  if (stale.length > 0) {
+    throw new Error(`public reference is stale: ${stale.join(", ")}`);
+  }
+  return {
+    contract: "kungfu-buildchain-public-reference-generation/v1",
+    check,
+    files: Object.keys(outputs),
+  };
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    process.stdout.write(
+      `${JSON.stringify(generatePublicReference({ check: process.argv.includes("--check") }), null, 2)}\n`,
+    );
+  } catch (error) {
+    console.error(`buildchain public reference: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/generate-site-bundle.mjs

@@ -35,6 +35,12 @@ import {
 import { createSurfaceTimestampPolicy } from "../packages/core/surface-manifest.js";
 import { cliCommandMeta, nodeApiMeta } from "./site-capability-metadata.mjs";
 import { projectHomepageIntro } from "./site-bundle-homepage.mjs";
+import { BUILDCHAIN_USAGE } from "./buildchain-cli-help.mjs";
+import {
+  cliReferenceById,
+  createCliReference,
+} from "./public-reference.mjs";
+import { createSiteNodeApiRegistry } from "./site-reference-registry.mjs";
 import {
   BUILDCHAIN_COMMAND_REGISTRY,
   resolveBuildchainCommand,
@@ -341,9 +347,12 @@ function publicSurfaceLifecycle({ owner, maturity, nonDuplicationRationale }) {
 
 const manualMetaById = new Map(Object.entries({
   map: { capabilityGroup: "getting-started", audience: ["agent", "consumer"], maturity: "stable", order: 10 },
+  "getting-started": { capabilityGroup: "getting-started", audience: ["consumer", "agent"], maturity: "stable", order: 15 },
   install: { capabilityGroup: "getting-started", audience: ["consumer"], maturity: "stable", order: 20 },
   "product-mechanism": { capabilityGroup: "getting-started", audience: ["agent", "maintainer"], maturity: "stable", order: 30 },
   cli: { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 40 },
+  "cli-reference": { capabilityGroup: "api-cli-reference", audience: ["agent", "developer", "operator"], maturity: "stable", order: 42 },
+  "node-api-reference": { capabilityGroup: "api-cli-reference", audience: ["agent", "developer"], maturity: "stable", order: 44 },
   "release-passport": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 100 },
   "github-artifact-attestation": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 108 },
   "publication-authority": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 105 },
@@ -409,6 +418,8 @@ function pageCapabilityMeta(relPath, category) {
 
 function createCliRegistry(packageJson) {
   const commands = enumerateCliCommandsFromBin({ root });
+  const reference = createCliReference(BUILDCHAIN_USAGE);
+  const referenceById = cliReferenceById(reference);
   const documentedTopLevelCommands = new Set();
   for (const entry of commands) {
     const command = entry.usage.split(/\s+/)[1] || "";
@@ -433,6 +444,13 @@ function createCliRegistry(packageJson) {
       const meta = cliCommandMeta(entry.id);
       return {
         ...entry,
+        ...(referenceById.get(entry.id) || {
+          paths: [],
+          syntaxes: [],
+          options: [],
+          aliases: [],
+          helpCommands: [],
+        }),
         purpose: meta.purpose,
         capabilityGroup: meta.capabilityGroup,
         audience: meta.audience,
@@ -738,40 +756,7 @@ function buildSiteBundle() {
     pages,
   };
 
-  const nodeApiRegistry = {
-    schemaVersion: 1,
-    contract: "kungfu-buildchain-node-api-registry",
-    package: packageJson.name,
-    moduleSystem: packageJson.type || "module",
-    exports: Object.entries(packageJson.exports || {})
-      .filter(([specifier]) => !specifier.startsWith("./site/") && specifier !== "./package.json")
-      .map(([specifier, target]) => {
-        const meta = nodeApiMeta(specifier);
-        return {
-          specifier: specifier === "." ? packageJson.name : `${packageJson.name}/${specifier.replace(/^\.\//, "")}`,
-          export: specifier,
-          target,
-          digest: typeof target === "string" ? sha256File(target.replace(/^\.\//, "")) : "",
-          summary: meta.summary,
-          capabilityGroup: meta.capabilityGroup,
-          audience: meta.audience,
-          ...publicSurfaceLifecycle({
-            owner: "buildchain-core",
-            maturity: meta.maturity,
-            nonDuplicationRationale: "Existing package subpath retained as the canonical API boundary for this capability.",
-          }),
-        };
-      }),
-    docs: [
-      { id: "cli-and-node-package", path: "docs/cli.md", digest: sha256File("docs/cli.md") },
-      { id: "build-facts", path: "docs/build-facts.md", digest: sha256File("docs/build-facts.md") },
-      { id: "kfd-support", path: "docs/kfd-support.md", digest: sha256File("docs/kfd-support.md") },
-      { id: "readme-badges", path: "docs/readme-badges.md", digest: sha256File("docs/readme-badges.md") },
-      { id: "homebrew", path: "docs/homebrew.md", digest: sha256File("docs/homebrew.md") },
-      { id: "site-bundle-contract", path: "docs/site-bundle-contract.md", digest: sha256File("docs/site-bundle-contract.md") },
-    ],
-    guidance: "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths.",
-  };
+  const nodeApiRegistry = createSiteNodeApiRegistry({ root, packageJson, nodeApiMeta, sha256File, publicSurfaceLifecycle });
 
   const workflowRegistry = {
     schemaVersion: 1,