@kungfu-tech/buildchain 3.0.3-alpha.1 → 3.0.3-alpha.2

package/scripts/buildchain-cli-help.mjs

@@ -0,0 +1,256 @@
+export const BUILDCHAIN_USAGE = `Usage:
+  buildchain --help
+  buildchain version
+  buildchain layout [--cwd <dir>] [--json]
+  buildchain portable-cache plan --manifest <file-or-json> [--output <file>]
+                                 [--github-output <file>] [--json]
+  buildchain portable-cache receipt --plan <file-or-json> [--matched-key <key>]
+                                    [--cache-hit true|false]
+                                    [--validation-status pass|fail]
+                                    [--validation-reason <text>]
+                                    [--cold-fallback-status not-run|passed|failed]
+                                    [--output <file>] [--json]
+  buildchain candidate timeline --input <file-or-json> [--output <file>] [--json]
+  buildchain init [--cwd <dir>] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force]
+                  [--package-manager pnpm|npm|yarn] [--runner-preset <preset>]
+                  [--artifact-name <template>]
+  buildchain validate [--cwd <dir>] [--require-version-state]
+                      [--require-lifecycle-stages <comma-list>]
+  buildchain lifecycle run <stage> [--cwd <dir>] [--required]
+                             [--artifact-name <name>] [--artifact-path <path>]...
+                             [--manifest-path <path>] [--summary-path <path>]
+                             [--process-summary <json>]
+  buildchain npm dry-run [--cwd <dir>] [--expected-tag <tag>] [--registry <url>]
+                         [--dist-tag <tag>] [--skip-npm-publish-dry-run] [--json]
+  buildchain release --dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                 [--tags <comma-list>] [--json]
+  buildchain release explain --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                     [--tags <comma-list>] [--json]
+  buildchain release dry-run --target-ref <ref> [--sha <sha>] [--source-ref <ref>]
+                                      [--tags <comma-list>] [--json]
+  buildchain release line open --major <n> --minor <n> [--source-ref <ref>]
+                               [--initial-version <version>] [--write] [--json]
+  buildchain release-governance reconcile --repository <owner/repo>
+                               --branch <dev|alpha|release/vN/vN.N>
+                               --candidate-sha <sha> [--apply] [--json]
+  buildchain github-governance <plan|apply|rollback|protection-policy-plan|ruleset-policy-plan> ...
+  buildchain release <inspect|recover|finalize|abort> ...
+  buildchain transaction inspect ...
+  buildchain collect github-release --tag <tag> [--repository <owner/repo>]
+                                    [--assets-dir <dir>] [--assets-json <json-or-path>]
+                                    [--release-json <json-or-path>] [--package-set-json <json-or-path>]
+                                    [--product-name <name>]
+                                    [--publish-evidence-json <json-or-path>]
+                                    [--trusted-publishing-json <json-or-path>]
+                                    [--transaction-json <json-or-path>]
+                                    [--anchor-manifest-json <json-or-path>]
+                                    [--impact-json <json-or-path>]
+                                    [--build-summary-json <json-or-path>]
+                                    [--build-facts-json <json-or-path>]...
+                                    [--platform-manifest-json <json-or-path>]...
+                                    [--dist-tag-evidence-json <json-or-path>]
+                                    [--kfd-1-witness-json <json-or-path>]...
+                                    [--kfd-2-claim-json <json-or-path>]...
+                                    [--kfd-3-prebuild-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-witness-json <json-or-path>]...
+                                    [--kfd-3-artifact-verify-cmd <command>]
+                                    [--kfd-support-matrix-json <json-or-path>]
+                                    [--kfd-product-gate-json <json-or-path>]...
+                                    [--invariant-passport-json <json-or-path>]...
+                                    [--invariant-passport-cmd <command>]
+                                    [--release-evidence-json <json-or-path>]...
+                                    [--github-artifact-attestation-policy-json <json-or-path>]...
+                                    [--kfd-agent-hub-evidence-json <json-or-path>]
+                                    [--base-passport-json <json-or-path>] [--require-base-kfd]
+                                    [--release-extra-json <json-or-path>]
+                                    [--publish-json <json-or-path>] [--output-dir <dir>] [--json]
+  buildchain create publication-admission --input-json <file-or-json> [--output <file>] [--json]
+  buildchain create runner-provenance --input-json <file-or-json> [--output <file>] [--json]
+  buildchain create github-artifact-attestation-policy --input-json <file-or-json> [--output <file>] [--json]
+  buildchain verify release-passport <file-or-url> [--json]
+  buildchain verify github-artifact-attestation <artifact>
+                          --evidence <file> --bundle <file>
+                          --platform-manifest <file> --release-passport <file> [--json]
+  buildchain verify publication-admission <file-or-json>
+                          --registry-json <file-or-json>
+                          --runner-json <file-or-json>
+                          --control-plane-audit-json <file-or-json>
+                          --publication-evidence-json <file-or-json>
+                          [--expected-json <file-or-json>] [--used-nonce <nonce>]... [--json]
+  buildchain audit publication-control-plane --repository <owner/repo> --branch <protected-branch>
+  buildchain audit github-governance [--organization <owner>] [--repository <owner/repo>]
+                                     [--output <file>] [--require-qualifying] [--json]
+                          [--source-sha <merged-branch-sha>] [--workflow-repository <owner/repo>]
+                          [--workflow <path>] [--workflow-ref <sha-or-ref>]
+                          [--job <id>] [--environment <name>] [--package <name>]
+                          [--publisher-mode npm-trusted-publisher|github-token|oidc-role]
+                          [--npm-trust-json <file-or-json>]
+                          [--provider-audit-json <file>] [--output <file>] [--allow-nonqualifying]
+  buildchain verify artifact <file|dir|url|npm:...|oci:...|github-release:...>
+                             [--passport <file-or-url>] [--locator-config <json>]
+                             [--repository <owner/repo>] [--tag <tag>]
+                             [--npm-registry <url>] [--json]
+  buildchain verify artifact-envelope <file-or-json> [--assessment-time <epoch>]
+                             [--expected-root <sha256:...>] [--expected-issuer <issuer>]
+                             [--expected-publisher <publisher>]
+                             [--expected-contract <version>] [--json]
+  buildchain project kfx-admission <file-or-json> [--assessment-time <epoch>]
+                             [--expected-root <sha256:...>] [--expected-issuer <issuer>]
+                             [--expected-publisher <publisher>]
+                             [--expected-contract <version>] [--json]
+  buildchain verify infra-contract-evidence-bundle <file> [--json]
+  buildchain verify observability-log <jsonl> [--min-events <n>]
+                                             [--require-phase <csv>]
+                                             [--require-component <csv>]
+                                             [--require-event <csv>] [--allow-errors] [--json]
+  buildchain explain release --passport <file-or-url> [--for human|agent] [--json]
+  buildchain explain artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--for human|agent] [--json]
+  buildchain inspect release --passport <file-or-url> [--json]
+  buildchain inspect artifact <subject> [--passport <file-or-url>] [--npm-registry <url>] [--json]
+  buildchain doctor [--cwd <dir>] [--require-publish-source-lock] [--json]
+  buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M>
+                             [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>]
+                             [--check-response-timeout-minutes <n>]
+                             [--max-entries-to-build <n>] [--apply]
+  buildchain log <info|warn|error> --event <name> [--phase <phase>]
+                 [--component <name>] [--source <name>] [--attribute key=value]...
+                 [--path <jsonl>] [--json]
+  buildchain log summary [--path <jsonl>] [--json]
+  buildchain diagnostics summary <diagnostics.json>... [--artifact <file>]...
+                                      [--output <file>] [--json]
+  buildchain facts module [--cwd <dir>] [--module <id>] [--module-root <path>]
+                          [--version-source <id>] [--output <file>]
+                          [--output-path <path>]... [--legacy-kungfu-buildinfo <file>] [--json]
+  buildchain facts aggregate [--cwd <dir>] [--product <id>]
+                             [--module-fact <file>]... [--artifact <path>]...
+                             [--output <file>] [--json]
+  buildchain facts verify [--cwd <dir>] --fact <file> [--json]
+  buildchain kfd ...
+  buildchain kfd hub <init|inspect|test|explain> [--cwd <dir>]
+                     [--declaration <path>] [--output-dir <path>]
+                     [--write] [--force] [--for agent] [--json]
+  buildchain kfd status [--cwd <dir>] [--json]
+  buildchain kfd migrate-layout [--cwd <dir>] [--write] [--force] [--json]
+  buildchain kfd schema list [--standard kfd-1|kfd-2|kfd-3|kfd-4] [--json]
+  buildchain kfd schema show <kfd-1|kfd-2|kfd-3|kfd-4> [--schema <name>] [--json]
+  buildchain kfd upstream roles [--json]
+  buildchain kfd upstream collect [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd upstream check [--cwd <dir>] [--aggregate-json <file-or-json>] [--json]
+  buildchain kfd aggregate [--cwd <dir>] [--json]
+  buildchain kfd 1 schema [--schema <name>] [--json]
+  buildchain kfd 1 witness [--cwd <dir>] [--source-sha <sha>] [--output <file>] [--json]
+  buildchain kfd 1 gate --witness-json <file-or-json>... [--cwd <dir>] [--artifact-root <dir>]
+                        [--output <file>] [--json]
+  buildchain kfd 1 verify --gate-json <file-or-json> [--json]
+  buildchain kfd 2 schema [--schema <name>] [--json]
+  buildchain kfd 2 taxonomy --entry-json <file-or-json>... [--kind residualRisk|downgradeReason] [--json]
+  buildchain kfd 2 claims [--cwd <dir>] [--output-dir <dir>] [--json]
+  buildchain kfd 2 product-claims <check|write|render> [--cwd <dir>] [--registry <path>]
+                                      [--output-dir <dir>] [--version <version>]
+                                      [--channel <channel>] [--tag <tag>] [--source-sha <sha>] [--json]
+  buildchain kfd 2 trust-claims [--claims-json <file-or-json>] [--json]
+  buildchain kfd 2 trust-assessment [--assessment-json <file-or-json>] [--json]
+  buildchain kfd 3 ...
+  buildchain kfd 3 detect [--cwd <dir>] [--kind <kind>]... [--artifact <path>] [--json]
+  buildchain kfd 3 register <node-api|python-api|cli|binary|documentation|site-bundle>
+                           [--cwd <dir>] [--registry <path>] [--artifact <path>]
+                           [--product <name>] [--json]
+  buildchain kfd 3 audit [--cwd <dir>] [--registry <path>] [--artifact <path>] [--json]
+  buildchain kfd 3 witness [--cwd <dir>] [--registry <path>] [--kind prebuild|artifact]
+                            [--source-sha <sha>] [--artifact <path>] [--output <file>] [--json]
+  buildchain kfd 3 query [<product>] [--cwd <dir>] [--registry <path>]
+                          [--passport <file-or-url>] [--artifact <path>] [--json]
+  buildchain kfd 4 schema [--schema <name>] [--json]
+  buildchain kfd 4 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 4 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd 5 schema [--schema <name>] [--json]
+  buildchain kfd 5 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 5 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd 7 schema [--schema <name>] [--json]
+  buildchain kfd 7 gate --input-json <file-or-json> [--cwd <dir>] [--output <file>] [--json]
+  buildchain kfd 7 verify --gate-json <file-or-json> [--expected-source-sha <sha>] [--json]
+  buildchain kfd support project --matrix-json <file-or-json> --gate-json <file-or-json>...
+                                  [--expected-source-sha <sha>] [--checked-at <date-time>]
+                                  [--output <file>] [--json]
+  buildchain kfd support verify --projection-json <file-or-json>
+                                  [--expected-source-sha <sha>] [--checked-at <date-time>] [--json]
+  buildchain sample process-tree [--interval-ms <n>] [--label <name>]
+                                 [--output <jsonl>] [--summary-output <json>]
+                                 [--requested-parallelism <n>] [--json]
+                                 -- <command> [args...]
+  buildchain mark --event <name> [--phase <phase>] [--component <name>]
+                  [--attribute key=value]... [--path <jsonl>] [--json]
+  buildchain span --event <name> [--phase <phase>] [--component <name>]
+                  [--path <jsonl>] -- <command> [args...]
+  buildchain web-surface ...
+  buildchain infra-contract ...
+  buildchain publication-artifact manifest [--cwd <dir>] [--source-sha <sha>]
+                                           [--output <file>] [--passport-output <file>]
+                                           [--registry-output <file>] [--source-bundle <file>]
+                                           [--no-source-bundle] [--json]
+  buildchain publication-artifact npm-package [--cwd <dir>] [--output-dir <dir>] [--package-name <name>] [--json]
+  buildchain publication-artifact reproducibility [--cwd <dir>] [--source-sha <sha>]
+                                                   [--output <file>] [--promote]
+                                                   [--no-toolchain-pull]
+                                                   [--allow-unpinned-toolchain] [--json]
+  buildchain paper scaffold --package <name> --repository <owner/repo> [--write] [--json]
+  buildchain paper migrate [--cwd <dir>] [--write] [--json]
+  buildchain paper work start <topic> [--cwd <dir>] [--branch <branch>] [--execute] [--json]
+  buildchain paper work submit [--cwd <dir>] [--title <title>] [--body <body>] [--execute] [--json]
+  buildchain paper fleet audit [--root <dir>] [--offline] [--json]
+  buildchain paper fleet update [--root <dir>] [--write] [--json]
+  buildchain paper preflight [--cwd <dir>] [--offline] [--json]
+  buildchain paper bootstrap npm [--cwd <dir>] [--execute]
+                                  [--confirm-public-package <name>] [--json]
+  buildchain paper build [--cwd <dir>] [--execute] [--json]
+  buildchain paper alpha [--cwd <dir>] [--source-ref <ref>] [--target-ref <ref>]
+                          [--execute] [--json]
+  buildchain paper status [--cwd <dir>] [--json]
+  buildchain paper resume [--cwd <dir>] [--buildchain-ref <ref>] [--execute] [--json]
+  buildchain release-propagation <plan|write-lock> ...
+  buildchain badges readme [--cwd <dir>] [--readme <path>] [--check] [--write] [--json]
+  buildchain badges bundle [--cwd <dir>] [--readme <path>] [--claims <csv>] [--check] [--write] [--json]
+  buildchain homebrew update-formula --package <name> --release-passport <file-or-url> [--write] [--json]
+  buildchain homebrew check [--cwd <dir>] [--package <name>] [--release-passport <file-or-url>] [--json]
+  buildchain publish-source <lock|manifest|verify-lock|verify-channel-ref|validate-anchored-release> ...
+  buildchain build-contract ...
+
+Examples:
+  buildchain init --type package --package-manager pnpm
+  buildchain validate --require-version-state --require-lifecycle-stages build,verify
+  buildchain lifecycle run build --artifact-path dist --artifact-name "{repo}-{version}-{platform}"
+  buildchain npm dry-run --json
+  buildchain release --dry-run --target-ref alpha/v3/v3.0
+  buildchain release line open --major 3 --minor 1 --source-ref release/v3/v3.0 --json
+  buildchain span --event native.build -- cmake --build build
+  buildchain collect github-release --tag v3.0.0 --assets-dir dist --output-dir .buildchain/release-passport
+  buildchain create publication-admission --input-json admission-input.json --output admission.json
+  buildchain create runner-provenance --input-json runner-input.json --output runner.json
+  buildchain verify release-passport .buildchain/release-passport/buildchain.release.json
+  buildchain verify publication-admission admission.json --registry-json publication-authority-registry.json --runner-json runner.json --control-plane-audit-json control-plane.json --expected-json expected.json --json
+  buildchain audit publication-control-plane --repository kungfu-systems/buildchain --branch release/v3/v3.0
+  buildchain verify artifact ./dist/buildchain-x86_64-unknown-linux-gnu.tar.gz --passport .buildchain/release-passport/buildchain.release.json
+  buildchain verify artifact-envelope .buildchain/kfx/artifact-verification-envelope.json --json
+  buildchain project kfx-admission .buildchain/kfx/artifact-verification-envelope.json --json
+  buildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json
+  buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build
+  buildchain infra-contract --mode plan --source-sha <sha>
+  buildchain infra-contract --mode ci --source-sha <sha>
+  buildchain infra-contract --mode plan --source-sha <sha> --execute-adapter-commands true
+  buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id>
+  buildchain infra-contract --mode apply --plan <plan.json> --source-sha <sha> --approval-id <id> --dry-run false --execute-adapter-commands true
+  buildchain infra-contract --mode propagation-apply --propagation-plan <plan.json> --dry-run true
+  buildchain infra-contract --mode evidence-bundle --artifact <artifact.json> --propagation-result <result.json>
+  buildchain publication-artifact manifest --source-sha <sha> --json
+  buildchain paper preflight --json
+  buildchain paper status --json
+  buildchain release-propagation plan --graph graph.json --upstream-release release.json --json
+  buildchain kfd status --json
+  buildchain kfd schema list --json
+  buildchain kfd 1 witness --json
+  buildchain kfd 2 claims --json
+  buildchain kfd 2 trust-assessment --json
+  buildchain kfd upstream collect --json
+  buildchain kfd aggregate --json
+  buildchain kfd 3 query buildchain --json
+`;

package/scripts/generate-site-bundle.mjs

@@ -33,6 +33,7 @@ import {
   enumerateWorkflowInputs,
 } from "../packages/core/public-surface-audit.js";
 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_COMMAND_REGISTRY,
@@ -406,193 +407,6 @@ function pageCapabilityMeta(relPath, category) {
   return { capabilityGroup: capabilityGroup("getting-started"), audience: ["agent"], maturity: "stable" };
 }
 
-function cliCommandMeta(id) {
-  const map = new Map(Object.entries({
-    audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
-    "audit-publication-control-plane": { group: "release-passport-trust", purpose: "Read GitHub publication controls, bind provider-enforced npm identity, and emit a sanitized expiring receipt." },
-    "audit-github-governance": { group: "governance-versioning", purpose: "Read the managed GitHub zone, aggregate native protection and ownership, and emit sanitized fail-closed governance receipts." },
-    badges: { group: "distribution-indexes", purpose: "Inspect README badge command families." },
-    "badges-bundle": { group: "distribution-indexes", purpose: "Generate or verify the combined KFD and Release Passport badge bundle." },
-    "badges-readme": { group: "distribution-indexes", purpose: "Generate or verify managed README badge blocks." },
-    "build-contract": { group: "governance-versioning", purpose: "Resolve Buildchain runtime contract metadata for floating-ref drift checks." },
-    "build-facts": { group: "observability-diagnostics", purpose: "Collect and verify Git source, version, module output, product artifact, and legacy Kungfu buildinfo facts." },
-    candidate: { group: "observability-diagnostics", purpose: "Inspect source-bound candidate evidence command families." },
-    "candidate-timeline": { group: "observability-diagnostics", purpose: "Create a critical-path-safe timeline across pull-request and Merge Queue attempts." },
-    collect: { group: "release-passport-trust", purpose: "Inspect release evidence collection command families." },
-    "collect-github-release": { group: "release-passport-trust", purpose: "Collect GitHub Release assets into a release passport." },
-    create: { group: "release-passport-trust", purpose: "Create canonical sealed publication evidence documents." },
-    "create-publication-admission": { group: "release-passport-trust", purpose: "Create a canonical short-lived publication admission envelope from exact consumer bindings." },
-    "create-github-artifact-attestation-policy": { group: "release-passport-trust", purpose: "Create an exact source, signer, Linux build, and Release Passport attestation policy." },
-    "create-runner-provenance": { group: "release-passport-trust", purpose: "Create runner provenance evidence with an explicit qualification floor." },
-    diagnostics: { group: "observability-diagnostics", purpose: "Inspect diagnostics command families." },
-    "diagnostics-summary": { group: "observability-diagnostics", purpose: "Summarize diagnostics artifacts into JSON and cross-platform lifecycle timing tables." },
-    doctor: { group: "getting-started", purpose: "Report local integration readiness." },
-    explain: { group: "release-passport-trust", purpose: "Inspect release and artifact explanation command families." },
-    "explain-artifact": { group: "release-passport-trust", purpose: "Explain artifact evidence for humans or agents." },
-    "explain-release": { group: "release-passport-trust", purpose: "Explain a release passport for humans or agents." },
-    facts: { group: "observability-diagnostics", purpose: "Inspect build facts command families." },
-    help: { group: "getting-started", purpose: "Print Buildchain CLI help." },
-    homebrew: { group: "distribution-indexes", purpose: "Inspect Homebrew distribution-index command families." },
-    "homebrew-check": { group: "distribution-indexes", purpose: "Verify Homebrew tap metadata against upstream release passport evidence." },
-    "homebrew-update-formula": { group: "distribution-indexes", purpose: "Generate Homebrew Formula metadata from upstream release passport evidence." },
-    "github-governance": { group: "governance-versioning", purpose: "Plan, apply, or roll back one root-bound GitHub branch-protection rollout after a frozen read-only inventory." },
-    "infra-contract": { group: "governance-versioning", purpose: "Validate and publish provider-neutral infrastructure contract evidence." },
-    init: { group: "getting-started", purpose: "Bootstrap a repository with Buildchain configuration and caller workflow files." },
-    inspect: { group: "release-passport-trust", purpose: "Inspect release and artifact evidence command families." },
-    "inspect-artifact": { group: "release-passport-trust", purpose: "Inspect artifact evidence." },
-    "inspect-release": { group: "release-passport-trust", purpose: "Inspect release passport evidence." },
-    kfd: { group: "kfd-trust", purpose: "Inspect KFD standards, schemas, and versioned KFD command families." },
-    "kfd-hub": { group: "kfd-trust", purpose: "Initialize, inspect, test, and explain one declarative KFD Agent Hub adapter adoption." },
-    layout: { group: "kfd-trust", purpose: "Return the versioned repository-layout and KFD registry discovery contract for tools such as Shifu." },
-    "kfd-schema": { group: "kfd-trust", purpose: "Inspect KFD schema command families." },
-    "kfd-schema-list": { group: "kfd-trust", purpose: "List machine-readable schemas exposed by the KFD package standards metadata." },
-    "kfd-schema-show": { group: "kfd-trust", purpose: "Print a machine-readable KFD schema from the KFD package standards metadata." },
-    "kfd-status": { group: "kfd-trust", purpose: "Report implemented KFD support and the active .buildchain repository layout." },
-    "kfd-migrate-layout": { group: "kfd-trust", purpose: "Plan or apply migration of legacy root Buildchain files into .buildchain/." },
-    "kfd-1": { group: "kfd-trust", purpose: "Inspect KFD-1 contract-world witness, gate, verify, and schema command families." },
-    "kfd-1-gate": { group: "kfd-trust", purpose: "Generate KFD-1 release gate evidence from declared contract-world witnesses." },
-    "kfd-1-schema": { group: "kfd-trust", purpose: "Print the default KFD-1 schema exposed by the KFD package standards metadata." },
-    "kfd-1-verify": { group: "kfd-trust", purpose: "Validate KFD-1 release gate evidence." },
-    "kfd-1-witness": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-1 self contract-world witness." },
-    "kfd-2": { group: "kfd-trust", purpose: "Inspect KFD-2 trust taxonomy, public claims, and schema command families." },
-    "kfd-2-claims": { group: "kfd-trust", purpose: "Generate Buildchain's KFD-2 public trust claim evidence." },
-    "kfd-2-product-claims": { group: "kfd-trust", purpose: "Validate and render product-owned KFD-2 claims in the canonical .buildchain/kfd layout." },
-    "kfd-2-schema": { group: "kfd-trust", purpose: "Print the default KFD-2 schema exposed by the KFD package standards metadata." },
-    "kfd-2-taxonomy": { group: "kfd-trust", purpose: "Validate KFD-2 trust taxonomy entries from the KFD package standards metadata." },
-    "kfd-2-trust-assessment": { group: "kfd-trust", purpose: "Expose and validate the KFD package foundation KFD-2 trust assessment." },
-    "kfd-2-trust-claims": { group: "kfd-trust", purpose: "Expose and validate the KFD package foundation KFD-2 trust claims." },
-    "kfd-3": { group: "kfd-trust", purpose: "Inspect KFD-3 surface detection, registry, witness, audit, and query command families under the unified KFD namespace." },
-    "kfd-3-audit": { group: "kfd-trust", purpose: "Compare detected, declared, and enforced KFD-3 public surfaces." },
-    "kfd-3-detect": { group: "kfd-trust", purpose: "Detect standard KFD-3 public surface candidates from source and artifact metadata." },
-    "kfd-3-query": { group: "kfd-trust", purpose: "Return an agent-readable KFD-3 capability map for a product, registry, or release passport." },
-    "kfd-3-register": { group: "kfd-trust", purpose: "Declare detected KFD-3 public surfaces into a product-owned surface registry." },
-    "kfd-3-witness": { group: "kfd-trust", purpose: "Generate release-passport-compatible KFD-3 surface witnesses from a product registry." },
-    "kfd-4-schema": { group: "kfd-trust", purpose: "Print the default KFD-4 schema exposed by the KFD package standards metadata." },
-    "kfd-4-gate": { group: "kfd-trust", purpose: "Evaluate source-bound KFD-4 observer-perspective and contrastive-replay product evidence." },
-    "kfd-4-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-4 product-gate result without widening product support." },
-    "kfd-5-schema": { group: "kfd-trust", purpose: "Print the default KFD-5 schema exposed by the KFD package standards metadata." },
-    "kfd-5-gate": { group: "kfd-trust", purpose: "Evaluate source-bound KFD-5 Primitive discovery qualification evidence." },
-    "kfd-5-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-5 product-gate result without widening product support." },
-    "kfd-7-schema": { group: "kfd-trust", purpose: "Print the default KFD-7 schema exposed by the KFD package standards metadata." },
-    "kfd-7-gate": { group: "kfd-trust", purpose: "Evaluate a source-bound KFD-7 Domain Profile, evidence obligations, and independent review." },
-    "kfd-7-verify": { group: "kfd-trust", purpose: "Verify a retained KFD-7 product-gate result without widening product support." },
-    "kfd-support": { group: "kfd-trust", purpose: "Project and verify a product-owned KFD-1 through KFD-13 support matrix against KFD-4/5/7 gates." },
-    "kfd-aggregate": { group: "kfd-trust", purpose: "Return a product KFD view that combines own KFD status with upstream KFD aggregate facts." },
-    "kfd-upstream": { group: "kfd-trust", purpose: "Inspect KFD upstream aggregate command families." },
-    "kfd-upstream-check": { group: "kfd-trust", purpose: "Validate a KFD upstream aggregate document and fail closed on missing evidence." },
-    "kfd-upstream-collect": { group: "kfd-trust", purpose: "Collect declared KFD-aware upstream package evidence and hashes from Buildchain config." },
-    "kfd-upstream-roles": { group: "kfd-trust", purpose: "List Buildchain-managed KFD upstream role values and inference policy." },
-    lifecycle: { group: "reusable-build", purpose: "Run configured lifecycle commands and write deterministic artifact manifests." },
-    dev: { group: "governance-versioning", purpose: "Inspect protected development-channel governance command families." },
-    "dev-merge-queue": { group: "governance-versioning", purpose: "Plan or apply an exact-branch GitHub merge queue after required workflow event compatibility is verified." },
-    log: { group: "observability-diagnostics", purpose: "Inspect Buildchain logging command families." },
-    logging: { group: "observability-diagnostics", purpose: "Emit timestamped build events, summarize logs, and enforce required phases." },
-    mark: { group: "observability-diagnostics", purpose: "Emit a single Buildchain log event." },
-    npm: { group: "release-passport-trust", purpose: "Inspect npm publishing command families." },
-    "portable-cache": { group: "observability-diagnostics", purpose: "Plan exact portable dependency/compiler cache inputs and seal provider outcomes." },
-    "portable-cache-plan": { group: "observability-diagnostics", purpose: "Validate a consumer-neutral cache manifest and emit exact GitHub Actions cache inputs." },
-    "portable-cache-receipt": { group: "observability-diagnostics", purpose: "Seal exact, compatible, miss, or corrupt provider evidence against one cache plan." },
-    "npm-dry-run": { group: "release-passport-trust", purpose: "Verify npm publish shape before a release transaction." },
-    paper: { group: "reusable-build", purpose: "Inspect the unified paper repository and publication command families." },
-    "paper-alpha": { group: "release-passport-trust", purpose: "Plan or open the protected dev-to-alpha paper publication PR without direct publication." },
-    "paper-bootstrap-npm": { group: "release-passport-trust", purpose: "Dry-run or explicitly bootstrap the public npm package and bind GitHub Trusted Publishing." },
-    "paper-build": { group: "reusable-build", purpose: "Plan or execute the existing two-clean-build reproducibility gate for a paper." },
-    "paper-migrate": { group: "getting-started", purpose: "Plan or write the bounded Buildchain-owned control-file migration for an existing paper repository." },
-    "paper-preflight": { group: "reusable-build", purpose: "Report exact source, runtime, permission, npm trust, deterministic build, and release-state readiness." },
-    "paper-resume": { group: "release-passport-trust", purpose: "Plan or dispatch recovery of the exact existing sealed paper release transaction." },
-    "paper-scaffold": { group: "getting-started", purpose: "Plan or write an idempotent, no-overwrite, release-ready paper repository scaffold." },
-    "paper-status": { group: "reusable-build", purpose: "Report explicit evidence for every paper lifecycle state without unsupported inference." },
-    "publish-source": { group: "release-passport-trust", purpose: "Create, inspect, or verify publish-gate source-lock refs." },
-    "publication-artifact": { group: "reusable-build", purpose: "Generate publication artifact manifests, passports, and source bundles for paper/report repositories." },
-    "publication-artifact-manifest": { group: "reusable-build", purpose: "Write a site-consumable publication artifact manifest, publication passport, and source bundle." },
-    "publication-artifact-npm-package": { group: "reusable-build", purpose: "Synthesize the declared npm paper package from a publication artifact manifest, passport, registry, source bundle, and primary artifact." },
-    project: { group: "release-passport-trust", purpose: "Inspect read-only consumer projection command families." },
-    "project-kfx-admission": { group: "release-passport-trust", purpose: "Project one verified sealed envelope into direct KFX admission inputs without reconstructing evidence." },
-    "publication-artifact-reproducibility": { group: "reusable-build", purpose: "Prove exact PDF, source bundle, publication evidence, and npm tarball bytes across two independent clean builds." },
-    "release-dry-run": { group: "governance-versioning", purpose: "Explain what a channel merge would publish before the PR is merged." },
-    "release-line-open": { group: "governance-versioning", purpose: "Plan or write the initial version-state commit for a new minor release line." },
-    "release-governance": { group: "governance-versioning", purpose: "Reconcile a managed branch's Buildchain aggregate check to an already-tested pull request SHA." },
-    "release-propagation": { group: "site-and-propagation", purpose: "Plan channel-preserving downstream release PRs and write exact upstream release locks." },
-    "release-transaction": { group: "release-passport-trust", purpose: "Inspect, recover, finalize, or abort durable release transactions." },
-    sample: { group: "observability-diagnostics", purpose: "Inspect sampler command families." },
-    "sample-process-tree": { group: "observability-diagnostics", purpose: "Sample process-tree diagnostics for a wrapped command." },
-    span: { group: "observability-diagnostics", purpose: "Run a command inside a Buildchain log span." },
-    "transaction-inspect": { group: "release-passport-trust", purpose: "Inspect durable release transaction state." },
-    validate: { group: "getting-started", purpose: "Validate .buildchain/buildchain.toml and declared lifecycle surfaces." },
-    verify: { group: "release-passport-trust", purpose: "Inspect release and artifact verification command families." },
-    "verify-artifact": { group: "release-passport-trust", purpose: "Verify artifact subjects against release passport evidence." },
-    "verify-artifact-envelope": { group: "release-passport-trust", purpose: "Verify exact roots, identity, lifecycle, revocation, and an existing KFD assessment in a sealed artifact envelope." },
-    "verify-github-artifact-attestation": { group: "release-passport-trust", purpose: "Verify GitHub keyless attestation identity plus local artifact, manifest, Passport, predicate, bundle, and evidence bindings." },
-    "verify-infra-contract-evidence-bundle": { group: "governance-versioning", purpose: "Fail closed unless an infra-contract lifecycle evidence bundle is complete, hash-bound, and validation-consistent." },
-    "verify-observability-log": { group: "observability-diagnostics", purpose: "Verify Buildchain observability log events." },
-    "verify-publication-admission": { group: "release-passport-trust", purpose: "Independently verify sealed publication admission, runner provenance, control-plane audit, nonce freshness, and exact artifact bindings." },
-    "verify-release-passport": { group: "release-passport-trust", purpose: "Fail closed unless a release passport and its evidence are complete." },
-    version: { group: "getting-started", purpose: "Print the package or embedded binary version." },
-    "web-surface": { group: "site-and-propagation", purpose: "Plan, verify, and apply Buildchain web-surface deployments." },
-  }));
-  const meta = map.get(id);
-  if (!meta) {
-    throw new Error(`missing CLI command capability metadata: ${id}`);
-  }
-  return { capabilityGroup: capabilityGroup(meta.group), purpose: meta.purpose, audience: ["agent", "operator"], maturity: "stable" };
-}
-
-function nodeApiMeta(exportName) {
-  const map = new Map(Object.entries({
-    ".": { group: "api-cli-reference", summary: "Root toolkit export for Buildchain's public Node API." },
-    "./core": { group: "api-cli-reference", summary: "Alias for the root public toolkit export." },
-    "./badges": { group: "distribution-indexes", summary: "Badge bundle facts, rendering, checking, and update APIs." },
-    "./readme-badges": { group: "distribution-indexes", summary: "Managed README badge block facts, rendering, drift checks, and updates." },
-    "./homebrew": { group: "distribution-indexes", summary: "Homebrew tap fact collection, Formula rendering, update, and check APIs." },
-    "./build-facts": { group: "observability-diagnostics", summary: "Git source, version, module output, product artifact, and legacy Kungfu build fact APIs." },
-    "./candidate-timeline": { group: "observability-diagnostics", summary: "Source-bound candidate event normalization, per-attempt critical-path-safe aggregation, and compact reporting APIs." },
-    "./channel-candidate": { group: "governance-versioning", summary: "Exact-source channel candidate decisions, same-SHA workflow evidence validation, and deterministic source-lock reference APIs." },
-    "./cache-evidence": { group: "observability-diagnostics", summary: "Content-addressed cache operation receipts and source/platform-bound evidence-set verification APIs." },
-    "./diagnostics": { group: "observability-diagnostics", summary: "Native diagnostics collection, summarization, cache, compiler, and process-sampler APIs." },
-    "./logging": { group: "observability-diagnostics", summary: "Buildchain JSONL logging, span, summary, and verification APIs." },
-    "./portable-dev-cache": { group: "observability-diagnostics", summary: "Portable dependency/compiler cache plan, exact-root verification, and provider receipt APIs." },
-    "./publication-artifact": { group: "reusable-build", summary: "Publication artifact manifest, source bundle, and publication passport APIs." },
-    "./publication-package": { group: "reusable-build", summary: "Publication npm package synthesis APIs for Buildchain-managed paper release presets." },
-    "./publication-reproducibility": { group: "reusable-build", summary: "Two-clean-build publication byte reproducibility receipt APIs." },
-    "./publication-sealed-bundle": { group: "reusable-build", summary: "Build-once publication bundle manifests and exact-byte resume verification APIs." },
-    "./paper": { group: "reusable-build", summary: "Unified paper scaffold, preflight, npm bootstrap, build, Alpha, status, and resume planning APIs." },
-    "./publication-authority": { group: "release-passport-trust", summary: "Sealed publication authority registry, runner provenance, control-plane audit, admission, and independent verification APIs." },
-    "./publication-control-plane-audit": { group: "release-passport-trust", summary: "Read-only publication control-plane snapshot evaluation APIs." },
-    "./buildchain-publication-authority": { group: "release-passport-trust", summary: "Buildchain-owned closed-world publication authority descriptor registry." },
-    "./github-governance-authority": { group: "governance-versioning", summary: "Fail-closed GitHub ownership, effective-policy, managed-zone admission, rollout-plan, and immutable receipt APIs." },
-    "./artifact-passport": { group: "release-passport-trust", summary: "Artifact passport digest and evidence helper APIs." },
-    "./artifact-verification-envelope": { group: "release-passport-trust", summary: "Sealed exact-root, lifecycle, identity, and existing KFD assessment inputs for KFX admission." },
-    "./artifact-signing": { group: "reusable-build", summary: "Credential-free artifact signing declarations, source-bound requests, authority receipts, profile resolution, and fail-closed validation APIs." },
-    "./artifact-signing-result": { group: "release-passport-trust", summary: "Immutable signed-result, final-payload, receipt, evidence-root, and provider-verification binding APIs." },
-    "./detached-artifact-signature": { group: "release-passport-trust", summary: "Buildchain-authority Ed25519 detached signature and verification APIs for arbitrary binary artifacts." },
-    "./anchored-version-material": { group: "reusable-build", summary: "Anchored/manual derived version material preflight, exact-tree binding, and digest evidence APIs." },
-    "./release-passport": { group: "release-passport-trust", summary: "Release passport collection, verification, explanation, and evidence APIs." },
-    "./github-artifact-attestation": { group: "release-passport-trust", summary: "GitHub keyless artifact attestation policy, predicate, provider evidence, and fail-closed verification APIs." },
-    "./kfd-agent-hub": { group: "kfd-trust", summary: "Declarative Agent Hub adapter inspection, fixed-suite execution, exact KFD cut locking, and agent explanation APIs." },
-    "./release-passport-contract": { group: "release-passport-trust", summary: "Standalone release passport JSON Schema, ownership/check manifest, and structural validation APIs." },
-    "./release-candidate": { group: "reusable-build", summary: "PR-stage release-candidate artifact, passport, and promote-only resolver APIs." },
-    "./stable-candidate-ledger": { group: "governance-versioning", summary: "Immutable alpha candidate ledger, qualification, revocation, selection, and exact stable source-lock APIs." },
-    "./release-propagation": { group: "site-and-propagation", summary: "Release propagation graph, plan, and exact upstream lock APIs." },
-    "./release-activation-transaction": { group: "release-passport-trust", summary: "Ordered cross-repository activation, exact receipt-set binding, retry, abort, rollback, and shadow-rehearsal APIs." },
-    "./release-line-bootstrap": { group: "governance-versioning", summary: "Semver release-line bootstrap planning and version-state APIs." },
-    "./buildchain-contract": { group: "governance-versioning", summary: "Runtime contract world and compatibility digest APIs for floating-ref drift checks." },
-    "./controller-evidence": { group: "reusable-build", summary: "Project-independent controller descriptors, source/runtime-bound plans, receipts, aggregates, and validation APIs." },
-    "./surface-manifest": { group: "site-and-propagation", summary: "Surface manifest timestamp and reproducibility policy APIs." },
-    "./issue-reporting": { group: "observability-diagnostics", summary: "Buildchain-owned issue reporting API for workflow friction feedback." },
-    "./buildchain-layout": { group: "kfd-trust", summary: "Versioned Buildchain repository-layout discovery contract plus canonical .buildchain path resolution and migration APIs." },
-    "./kfd": { group: "kfd-trust", summary: "Unified KFD standards, schema discovery, KFD-1/KFD-2/KFD-3 grouped APIs, KFD-4 schema discovery, upstream KFD aggregate facts, and Buildchain KFD claim helpers." },
-    "./kfd-product-gates": { group: "kfd-trust", summary: "Fail-closed KFD-4, KFD-5, and KFD-7 product evidence gates plus non-widening KFD support-matrix release projections." },
-    "./public-surface-audit": { group: "kfd-trust", summary: "Reverse audit APIs for CLI, workflow, action, site page, and documentation command surfaces." },
-    "./kfd-gate": { group: "kfd-trust", summary: "KFD-1/KFD-2/KFD-3 release gate evidence and validation APIs." },
-    "./buildchain-kfd-claims": { group: "kfd-trust", summary: "Buildchain self KFD claim registry, witnesses, and public claim APIs." },
-  }));
-  const meta = map.get(exportName);
-  if (!meta) {
-    throw new Error(`missing Node API capability metadata: ${exportName}`);
-  }
-  return { capabilityGroup: capabilityGroup(meta.group), summary: meta.summary, audience: ["developer", "agent"], maturity: "stable" };
-}
-
 function createCliRegistry(packageJson) {
   const commands = enumerateCliCommandsFromBin({ root });
   const documentedTopLevelCommands = new Set();