{
"schemaVersion": 1,
"contract": "kungfu-buildchain-site-bundle",
"generatedAt": "2026-08-13T09:05:27.306Z",
"publishedAt": "2026-08-13T09:05:27.306Z",
"reproducible": true,
"timestampPolicy": "ci-injected",
"deterministicInputs": [
"README.md",
"docs/*.md",
"actions/*/README.md",
"fixtures/*/README.md",
"packages/core/README.md",
"package.json#exports",
"tests/buildchain-inventory.json",
"sourceRevision",
"sourceDateEpoch",
"package content",
"declared Buildchain surface manifest contract"
],
"sourceDateEpoch": "0",
"sourceRevision": "45a49dcaa0fcef59bc66481a85c39514d08972cc",
"timestampPolicyDetails": {
"contract": "kungfu-buildchain-surface-timestamp-policy",
"timestampFields": [
"generatedAt",
"publishedAt"
],
"timestampFieldsParticipateInArtifactDigest": true,
"artifactDigestScope": "npm package dist/site JSON files",
"note": "Human-readable timestamps are separate from reproducibility inputs; do not infer reproducibility from epoch timestamps."
},
"product": {
"name": "Buildchain",
"formalName": "Buildchain by Kungfu",
"category": "Buildchain Release Passport"
},
"package": {
"name": "@kungfu-tech/buildchain",
"version": "4.0.0",
"versionSource": "package.json#version"
},
"source": {
"package": "@kungfu-tech/buildchain",
"homepageTextSource": "README.md",
"docsMap": "docs/MAP.md",
"manualRegistry": "manual-registry.json",
"siteFactsDir": "dist/site"
},
"routes": {
"home": "/",
"docsPattern": "/docs/{id}",
"llms": "/llms.txt",
"manifest": "/manifest.json"
},
"sourceOfTruth": "npm package @kungfu-tech/buildchain/dist/site",
"humanFirst": true,
"agentFirst": true,
"entrypoints": [
"page-registry.json",
"capability-registry.json",
"cli-registry.json",
"manual-registry.json",
"node-api-registry.json",
"workflow-registry.json",
"controller-registry.json",
"publication-authority-registry.json",
"public-surface-audit.json",
"release-model.json",
"artifact-schemas.json",
"badge-endpoint-registry.json",
"publication-registry.json",
"product-mechanism.json",
"release-provenance.json",
"kfd-upstream-aggregate.json",
"kfd-claims.json",
"agent-index.json",
"site-manifest.json"
],
"capabilityRegistry": {
"path": "capability-registry.json",
"contract": "kungfu-buildchain-capability-registry",
"groupCount": 9,
"defaultOrder": [
"getting-started",
"release-passport-trust",
"reusable-build",
"kfd-trust",
"site-and-propagation",
"distribution-indexes",
"observability-diagnostics",
"governance-versioning",
"api-cli-reference"
]
},
"pages": [
{
"id": "overview:home",
"title": "Buildchain",
"route": "/",
"category": "overview",
"capabilityGroup": "getting-started",
"audience": [
"consumer",
"agent"
],
"maturity": "stable",
"sourcePath": "README.md",
"digest": "sha256:6eaf6142c4cf66bbfba30b941fce230905eb4b1fce5720b135a7275e2fb12cf9",
"headings": [
{
"level": 1,
"title": "Buildchain",
"anchor": "buildchain"
},
{
"level": 2,
"title": "Buildchain beginner bootstrap",
"anchor": "buildchain-beginner-bootstrap"
},
{
"level": 2,
"title": "Choose Your Path",
"anchor": "choose-your-path"
},
{
"level": 2,
"title": "Where Buildchain sits in the Agent Supply Chain",
"anchor": "where-buildchain-sits-in-the-agent-supply-chain"
},
{
"level": 2,
"title": "Install and Verify",
"anchor": "install-and-verify"
},
{
"level": 2,
"title": "Project Governance",
"anchor": "project-governance"
},
{
"level": 2,
"title": "Use Buildchain",
"anchor": "use-buildchain"
},
{
"level": 2,
"title": "Release Model",
"anchor": "release-model"
},
{
"level": 2,
"title": "Toolkit Observability",
"anchor": "toolkit-observability"
},
{
"level": 2,
"title": "Site Fact Source",
"anchor": "site-fact-source"
},
{
"level": 2,
"title": "Homepage Content Contract",
"anchor": "homepage-content-contract"
},
{
"level": 2,
"title": "Local Verification",
"anchor": "local-verification"
},
{
"level": 2,
"title": "Read Next",
"anchor": "read-next"
}
],
"markdown": "# Buildchain\n\n\n## Buildchain beginner bootstrap\n\n[](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/public-evidence.json)\n\nAnimation scenario:\n\n```text\n$ buildchain init --cwd ./starter --type package --package-manager npm\n$ buildchain layout --cwd ./starter --json\n$ buildchain version\n```\n\nNative renditions: [1080p MP4](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo.mp4) · [1080p WebM](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo.webm) · [720p MP4](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo-720p.mp4) · [720p WebM](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/demo-720p.webm)\n\n[Static poster / reduced-motion fallback](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/poster.png)\n\n\nEvidence and claim boundary
\n\nThis exact standalone-binary scenario proves deterministic local bootstrap behavior only; it does not grant release, repository, network, or production authority.\n\n[Release Passport](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/release-passport.json) · [auditable evidence](docs/evidence/auditable-demo/aa5cc40f4a62ed516e163e7e2c9dae0bcf32b3c77143a17105dfc4e5eaf9f01a/beginner-bootstrap/public-evidence.json)\n\n \n\n\n\n\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Choose Your Path\n\n| You are... | Start here | You will get... |\n| --- | --- | --- |\n| adopting Buildchain for the first time | [Golden Path](docs/getting-started.md) | an exact install, project declaration, validated config, reusable workflow, release dry-run, and Passport inspection |\n| looking up a CLI command | [Generated CLI Reference](docs/cli-reference.md) | governed syntax, options, aliases, and side-effect-free help paths |\n| writing JavaScript automation | [Generated Node API Reference](docs/node-api-reference.md) | every public subpath and symbol with source-derived signatures and behavior boundaries |\n| operating an advanced build or release | [Documentation Map](docs/MAP.md) | capability-, intent-, and maturity-based navigation to normative contracts |\n\nProduction release operators should also read the\n[Buildchain v4 production release runbook](docs/v4-production-release.md).\n\nThe Golden Path is the beginner lane. Advanced workflow, signing, publishing,\nand governance manuals remain separate so a first-time consumer does not need\nto understand the entire release control plane before reaching a valid local\nconfiguration.\n\n## Where Buildchain sits in the Agent Supply Chain\n\nBuildchain binds a product's declarations to the exact source cut, build,\nartifacts, checks, and promotion record that produced a release. In the wider\nAgent Supply Chain it sits between KFD-3 product discovery and KFD-2\npurpose-bound assessment:\n\n```text\nKFD-3 declaration -> Buildchain exact-artifact evidence -> KFD-2 assessment\n```\n\nBuildchain can prove that a declared claim and an exact artifact remain\nconsistent, or fail/downgrade when their evidence drifts. It does not invent\nthe product fact, decide whether a receiver should trust it for a purpose,\ncertify every platform, or prove external adoption. Receivers and downstream\nKFD-2 assessors retain the admission decision and residual risk.\n\nTo evaluate the layer, inspect a release's `buildchain.release.json` and\n`artifact-evidence.json`, verify them with the CLI, and report missing product\nor protocol evidence through the repository issue tracker.\n\n## Install and Verify\n\nNew repository adopters should follow the [15–30 minute Golden Path](docs/getting-started.md).\nThe commands below are the shorter verification-only route for an existing\nconsumer.\n\nFor v4, use the published npm package and verify the release passport before\ntrusting release evidence:\n\n```bash\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v4.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@4.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@4.0.0 version\n```\n\nThe v4.0.0 release publishes evidence assets and platform archives through the\nsame protected promotion transaction.\nThe names below describe the optional archive contract used by legacy release\nlines:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n createBuildchainLogger,\n verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n path: \".buildchain/logs/native-build.jsonl\",\n source: \"user\",\n component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n path: logger.path,\n requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n posture for GitHub, npm, cloud, credential, release evidence, and other\n provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n collectBuildchainDiagnostics,\n collectRunnerDiagnostics,\n writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n contract: \"consumer-build-diagnostics\",\n buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n runner: collectRunnerDiagnostics(),\n});\n```\n\n`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v4\n if: failure()\n with:\n token: ${{ steps.buildchain-issue-token.outputs.token }}\n summary: \"Reusable build failed before artifact finalization\"\n failure-code: reusable-build-failed\n buildchain-ref: v4\n diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\npnpm add -D @kungfu-tech/buildchain@\npnpm exec buildchain paper work start \npnpm exec buildchain paper work submit\npnpm exec buildchain paper preflight --offline\npnpm exec buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files. `work start` and `work submit` validate the canonical remote,\nexact development SHA, clean source, safe branch, and fast-forward boundary\nbefore changing local or GitHub state. External mutations such as npm\nbootstrap, Alpha PR creation, and release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains seven active entries. Five are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n- `actions/release-tail`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer snapshot from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n planning, capability-aware runner dispatch, receipt validation, and one\n stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n qualification, transcript-bound renderer smoke, optional media rendering\n from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n profiles with independently verified rendition roles;\n- `.github/workflows/.declarative-auditable-demo.yml` for standalone binary\n consumers that provide only a versioned multi-demo argv scenario and exact\n same-run binary artifact coordinates; Buildchain owns isolated native\n capture, Gate, Release Passport, materialization, and protected README PRs;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n promote-only publication from a PR-stage release candidate, without a second\n heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v4\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4\n```\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path | Meaning | Exact tag | Floating refs |\n| --------------------------------------- | ------------------------------------------------------ | ---------------- | ---------------------------------------------------- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y` | publish the next testable alpha for a minor line | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y` |\n| `alpha/vX/vX.Y -> release/vX/vX.Y` | publish production for that minor line | `vX.Y.Z` | `vX.Y`, usually `vX`, `release/vX/vX.Y` |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0` | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n binary verification.\n- Use signal: the start of `Use Buildchain`, especially the reusable workflow\n and action surfaces.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [GitHub governance authority](docs/github-governance-authority.md)\n- [GitHub-native Linux artifact attestation](docs/github-artifact-attestation.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Shifu Gate profile orchestration](docs/shifu-gate-profiles.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Declarative release-tail contract](docs/release-tail-contract.md)\n- [Release governance](docs/release-governance.md)",
"slug": "home"
},
{
"id": "action:github-artifact-attestation",
"title": "GitHub Artifact Attestation Evidence",
"route": "/actions/github-artifact-attestation",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/github-artifact-attestation/README.md",
"digest": "sha256:5d18b6cb88a311e660d5895b3264b1a3e3813d00c43a1655a0a9f5ddd5b51895",
"headings": [
{
"level": 1,
"title": "GitHub Artifact Attestation Evidence",
"anchor": "github-artifact-attestation-evidence"
}
],
"markdown": "# GitHub Artifact Attestation Evidence\n\nThis internal Buildchain action validates one downloaded Linux release artifact\nagainst its platform manifest and Release Passport, writes the custom predicate\nconsumed by `actions/attest`, and finalizes the retained v1 evidence document.\n\nConsumers should call\n`.github/workflows/github-artifact-attestation.yml`; they should not call this\naction directly. The action parses data files only. It never checks out or\nexecutes consumer source or the downloaded subject."
},
{
"id": "action:macos-credential-island",
"title": "macOS Credential Island",
"route": "/actions/macos-credential-island",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/macos-credential-island/README.md",
"digest": "sha256:174ffb3e3424effc02164ad3577268fc060bfeefb223d0a2bc8d4cc43e66b110",
"headings": [
{
"level": 1,
"title": "macOS Credential Island",
"anchor": "macos-credential-island"
}
],
"markdown": "# macOS Credential Island\n\nThis action signs one sealed macOS application on an isolated macOS runner. It\ndoes not check out consumer source and does not execute files from the input\nartifact. Buildchain validates the source-bound input manifest, imports one\nexact Developer ID Application identity into a temporary keychain, signs the\napplication, submits Apple notarization, staples the application and DMG,\nverifies Gatekeeper, and writes bounded JSON evidence.\n\nDMG assembly uses a unique execution- and attempt-bound image path and volume\nname. Only the exact `hdiutil: create failed - Resource busy` failure is retried,\nwith three attempts and a total retry delay of seven seconds. Certificate,\nentitlement, signature, notarization, provenance, and policy failures remain\nterminal. Attempt artifacts stay below the owned temporary root, and successful\nevidence binds the request, unsigned archive, runtime, runner attempt, toolchain,\nretry history, cleanup result, and signed output digests.\n\nThe reusable Buildchain workflow invokes this action from a job bound to the\ncaller's protected GitHub Environment. The job downloads the exact sealed\nBuildchain input and immutable action runtime, then uploads the signed payload\nand its Buildchain platform manifest. It has no consumer checkout. Do not add a\npackage manager, lifecycle, hook, or consumer-script execution to that job.\n\nThe supported `electron-desktop-v1` entitlements profile is owned by\nBuildchain. Consumer-provided entitlement files are intentionally unsupported;\notherwise pull-request bytes could expand the signing authority."
},
{
"id": "action:promote-buildchain-ref",
"title": "promote-buildchain-ref",
"route": "/actions/promote-buildchain-ref",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/promote-buildchain-ref/README.md",
"digest": "sha256:d5e6c15dde52a15034118d2fdcc3b1bda7488a069b93a6aa201b874e6b884ed4",
"headings": [
{
"level": 1,
"title": "promote-buildchain-ref",
"anchor": "promote-buildchain-ref"
},
{
"level": 2,
"title": "Dry Run",
"anchor": "dry-run"
},
{
"level": 2,
"title": "Publish Transactions",
"anchor": "publish-transactions"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-ref-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v3/v3.0` creates or reuses the next exact prerelease tag such as\n `v3.0.3-alpha.0`, writes that version into package version state, points the\n alpha and dev channel branches at the version commit, then promotes\n `v3.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;\n- `release/v3/v3.0` creates or reuses the next exact release tag such as\n `v3.0.2`, writes that version into package version state, points the release\n channel branch and release tags at the release commit, then prepares a second\n source commit for the next exact prerelease tag such as `v3.0.3-alpha.0` and\n points the alpha/dev channel branches plus `v3.0-alpha` at that prerelease\n commit, and moves `v3-alpha` only if no higher v3 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n as `release/v3/v3.0`, writes the next major production version such as\n `v4.0.0`, points `publish-gate/major`, `release/v4/v4.0`, `v4.0`, and `v4`\n at that release commit, then prepares `v4.0.1-alpha.0` for\n `alpha/v4/v4.0`, `dev/v4/v4.0`, `v4.0-alpha`, and `v4-alpha`. The older `major-gate`\n branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v3/v3.1` creates `v3.1.N`, promotes `v3.1`, and promotes `v3` only\nwhen the next minor tag such as `v3.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nWhen the requested version already matches every declared version-state file,\ndry-run planning still runs `lifecycle.version-state` and any explicit\n`verification-command` so it can discover declared derived material. It does\nnot fall back to the repository-wide `lifecycle.verify` in that no-op case;\nfull product verification can require candidate artifacts that are deliberately\nnot present until the later admission phase. Non-dry-run version-state writes\ncontinue to require the configured verification lifecycle before any ref moves.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\nGitHub may return either `403` or a deliberately opaque `404` when a\nnon-administrator token reads the full branch-protection endpoint. In that\ncase, promotion reads the provider's branch summary and accepts only an\nalready-protected branch that enforces the exact required check for everyone.\nIt does not interpret the opaque response as missing protection or try to\nrewrite policy with a developer token. The independent publication-authority\naudit remains responsible for the complete read-only governance proof.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n with:\n token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n generated-ref-update-token: ${{ github.token }}\n sha: ${{ github.sha }}\n target-ref: release/v3/v3.0\n publish-transaction: \"true\"\n publish-mode: publish-final-version\n publish-auth: trusted-publishing\n publish-required-artifacts-json: >-\n [\n {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"3.0.0\",\"digest\":\"sha256:...\"}\n ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n with:\n token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n sha: ${{ needs.build.outputs.publish-source-sha }}\n target-ref: release/v22/v22.22\n require-publish-source-lock: \"true\"\n publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n publish-transaction: \"true\"\n publish-mode: publish-final-version\n publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n with:\n token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n sha: ${{ needs.build.outputs.publish-source-sha }}\n target-ref: alpha/v22/v22.22\n promote-only-release-candidate: \"true\"\n release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n release-candidate-family-evidence-required: \"true\"\n release-candidate-family-evidence-root: sha256:\n release-candidate-family-initiative-id: 2026-07-30-example-initiative\n release-candidate-family-assignment-id: 2026-07-30-example-release\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nThe four family-evidence inputs are optional. When enabled, the action requires\nthe candidate passport to carry the exact\n`kungfu-buildchain-initiative-family-release-evidence/v1` envelope and checks\nits family root, Initiative id, and Assignment id before any promotion\nmutation. Buildchain only transports and validates this adapter-edge release\nevidence; Kungfu Work Control remains authoritative for native Family State v1\nand its additive v2 typed envelope.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nBuild-once callers additionally pass `publish-sealed-bundle-root` and\n`publish-sealed-bundle-manifest`. The action verifies the typed manifest and\npersists every declared file below\n`sealed-bundle//files/` on the same durable ref before it starts\nthe publish command. A fresh runner can omit both inputs: the action restores\nthe exact binary bundle into `.buildchain/recovered-publication//`,\nre-verifies it, and exports the recovered npm tarball through\n`BUILDCHAIN_SEALED_NPM_TARBALL` with its exact integrity and SHA-256. This path\nnever repacks the npm tarball.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_SEALED_BUNDLE_ROOT\nBUILDCHAIN_SEALED_NPM_TARBALL\nBUILDCHAIN_SEALED_NPM_INTEGRITY\nBUILDCHAIN_SEALED_NPM_SHA256\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-publication-state`, `transaction-sealed-bundle-root`,\n`transaction-resume-command`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`transaction-publication-state` provides the stable\n`prepared`, `sealed`, `package-published`, `alpha-complete`, or\n`release-complete` operator view. `transaction-resume-command` is the exact\nconsumer-facing resume entrypoint bound into the sealed manifest.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run. When sealed release assets are present, those restored\nfiles replace caller-supplied artifact paths. After upload succeeds, the action\nwrites the `github_release` milestone back to the durable transaction; an\ninterruption before that write is safe to retry because release creation and\nasset replacement are idempotent.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-kfd-adopter-manifest-json` to the standard full-cut\nadopter manifest and `release-passport-kfd-product-gate-jsons` to the\nnewline-separated KFD-4, KFD-5, and KFD-7 gate results. Buildchain binds the\nexact published KFD package, registry, verifier set, source, decision witness,\nand product-gate roots into both Passport and artifact evidence. The optional\n`release-passport-kfd-support-matrix-json` is comparison-only; it must exactly\nmatch the derived `kfd-support.json` compatibility projection and cannot widen\ncandidate, unsupported, draft, or non-shipped states.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nSet `release-passport-evidence-jsons` to newline-separated product-owned release\nevidence attachment indexes. Each JSON document must declare `schemaVersion`, a\nstable `id`, a product contract, and the exact release source SHA, tag, and\nchannel. Buildchain copies and hashes the documents, verifies their coordinates\nagainst the final Passport, and retains them in the release evidence bundle\nwithout interpreting product-specific or legal claims.\n\nWhen release coordinates are not known until promotion, set\n`release-passport-attachment-command`. Buildchain supplies\n`BUILDCHAIN_RELEASE_SOURCE_SHA`, `BUILDCHAIN_RELEASE_TAG`,\n`BUILDCHAIN_RELEASE_CHANNEL`, `BUILDCHAIN_RELEASE_VERSION`,\n`BUILDCHAIN_RELEASE_DEPLOYMENT_COORDINATE`, `BUILDCHAIN_RELEASE_TARGET_REF`, and\n`BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR`; the command must emit a JSON array or\nan object with a non-empty `files` array. Direct Action callers may still use\nthe v2 alias `release-passport-evidence-command`. Reusable v3 workflows reserve\nthat older name for the distinct post-activation released-evidence command.\n\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nSet `release-passport-github-artifact-attestation-policy-jsons` to one or more\nnewline-separated `buildchain.github-artifact-attestation-policy/v1` paths when\nthe Release Passport must require GitHub keyless provenance for Linux release\nartifacts. The higher-level v3 promotion workflow exposes the single-artifact\n`github-artifact-attestation-policy-json` input and owns staging, signing,\nprovider verification, immutable GitHub Release evidence upload, and read-back;\ndirect action callers own those post-Passport steps themselves.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`. An explicit recovery of an already `complete` transaction is also\naccepted when the requested source SHA, version, exact tag, channel, and target\nall match the durable record exactly. It returns the completed transaction\nwithout republishing package bytes; a source accepted only through later branch\nhistory is not sufficient for this terminal-state reuse.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n protection for administrators and require approving PR review plus the strict\n `check` job from the `Verify` workflow; when GitHub withholds that\n administration endpoint from the workflow token, the exact transaction must\n instead prove a protected current head, same-repository merged PR,\n independent approval, and the required successful `check` from its configured\n GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n provider-enforced policy when the workflow token cannot read or rewrite the\n administrative protection document, and fails closed if the public branch\n summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n `publish-gate/alpha/vN/vN.M/ -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n `publish-gate/release/vN/vN.M/ -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n the release source tree must match that alpha tag tree, so release does not\n introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n declared `version.files` and the configured anchor manifest, and only when the\n checked-out release material has passed `lifecycle.verify` or the explicit\n `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n with either the `verification-command` input or `buildchain.toml`\n `lifecycle.verify` before any tags or channel refs move.\n\nThe reusable promotion workflow keeps governance reads, generated status checks,\nand generated ref updates on the run-scoped `github.token`. When branch\nprotection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`\nonly through `generated-pull-request-token` so the same-repository recovery PR can\nbe listed or created without broadening the governance client. Protected branch\nreview and check rules guard human channel merges, while the reusable build trust\ngate checks the source-lock channel HEAD and merged same-repository PR lineage\nbefore heavy build runners start. This action still independently rechecks PR\nlineage, alpha/release tree equivalence, and generated version-state verification\nbefore moving channel refs and tags.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v3.0` and `v3`, and floating alpha\ntags are minor-line tags such as `v3.0-alpha` plus cross-minor major tags such\nas `v3-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v3.0-alpha` and `v3-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
},
{
"id": "action:release-tail",
"title": "Declarative Release Tail",
"route": "/actions/release-tail",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release-tail/README.md",
"digest": "sha256:f2a4344525a8422b0b063e213cdfddeadcc0cdb3c098e9bdbc112c4984e43861",
"headings": [
{
"level": 1,
"title": "Declarative Release Tail",
"anchor": "declarative-release-tail"
}
],
"markdown": "# Declarative Release Tail\n\nThis Action executes the versioned `buildchain.release-tail/v1` declaration\nthrough one durable Buildchain transaction. It accepts only data bindings for\nsealed artifacts, rooted JSON documents, HTTP provider endpoints and released\nevidence inputs. It does not accept a command, script, executable path, plugin\nor repository callback.\n\nEvery mutation is preceded and followed by provider readback. Buildchain core,\nnot the adapter, compares the observed subject and target roots, owns retry and\nterminal classification, checkpoints state and emits the standardized receipt.\nTokens remain Action inputs and are never written to the transaction or\nreceipt."
},
{
"id": "action:report-buildchain-issue",
"title": "report-buildchain-issue",
"route": "/actions/report-buildchain-issue",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/report-buildchain-issue/README.md",
"digest": "sha256:6c03ae2b3570ef2f3f8aa3dc42bfa05df3bb7639f85344ebe25f792d21b4276a",
"headings": [
{
"level": 1,
"title": "report-buildchain-issue",
"anchor": "report-buildchain-issue"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-consumer-issue-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# report-buildchain-issue\n\nCreate or update a Buildchain repository issue from a consumer workflow or from\nBuildchain's own workflow-friction feedback loop.\n\nThis action is intended for consumer repositories that need to report\nBuildchain-owned failures with enough evidence for maintainers to act. It\nrequires a token that can write issues on the target Buildchain repository.\nFor cross-repository consumers, generate that token with a GitHub App\ninstallation token or another scoped credential owned by the consumer\norganization.\n\n```yaml\n- uses: actions/create-github-app-token@v2\n id: buildchain-issue-token\n with:\n app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n owner: kungfu-systems\n repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n if: failure()\n with:\n token: ${{ steps.buildchain-issue-token.outputs.token }}\n summary: \"Reusable build failed before artifact finalization\"\n failure-code: reusable-build-failed\n buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}\n diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action computes a stable fingerprint from the consumer repository,\nworkflow, job, failure code, and Buildchain ref. When an open issue already\nexists for that fingerprint, it comments with the new run instead of opening a\nduplicate issue.\n\nBy default issue reporting is fail-soft:\n\n- `fail-on-error: \"false\"` prevents a reporting outage from hiding the original\n build failure.\n- transient GitHub API 429/5xx errors and connection failures are retried.\n- if a configured label is missing, issue creation is retried without labels.\n- if issue creation/commenting is still unavailable, the action writes the full\n copyable issue title, fingerprint, and body into the workflow summary.\n- common token, private-key, password, and authorization values are redacted\n before submission.\n\nUse `dry-run: \"true\"` to verify the computed fingerprint and body shape without\ncalling GitHub.\n\nFor Buildchain-owned workflow friction, use `report-kind: workflow-friction`.\nThis uses a separate marker and default labels so duplicate PRs, duplicate\nbuilds, transient API failures, stale release-state, or missing RC evidence can\nbe grouped without mixing with consumer failure reports:\n\n```yaml\npermissions:\n issues: write\n\nsteps:\n - uses: actions/create-github-app-token@v2\n id: buildchain-issue-token\n with:\n app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n owner: kungfu-systems\n repositories: buildchain\n\n - uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n if: failure()\n with:\n token: ${{ steps.buildchain-issue-token.outputs.token || secrets.BUILDCHAIN_ISSUE_TOKEN || secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token }}\n report-kind: workflow-friction\n target-repository: kungfu-systems/buildchain\n repository: ${{ github.repository }}\n workflow: ${{ github.workflow }}\n run-id: ${{ github.run_id }}\n run-attempt: ${{ github.run_attempt }}\n channel: alpha/v3/v3.0\n source-sha: ${{ github.sha }}\n friction-class: duplicate-build\n related-runs-json: ${{ steps.classify.outputs.related-runs-json }}\n heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}\n comment-cooldown-hours: \"24\"\n```\n\n`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain\nstill deduplicates by fingerprint but skips adding another comment if the\nexisting issue already received a recent update."
},
{
"id": "action:run-lifecycle",
"title": "run-lifecycle",
"route": "/actions/run-lifecycle",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/run-lifecycle/README.md",
"digest": "sha256:6f0fa7439801d0557e59c6112235b2db0bd4439fcd1660a5cac14994be7c4314",
"headings": [
{
"level": 1,
"title": "run-lifecycle",
"anchor": "run-lifecycle"
}
],
"markdown": "# run-lifecycle\n\nRun a Buildchain lifecycle stage or an explicit command and write a deterministic\nartifact manifest.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3\n with:\n stage: build\n required: \"true\"\n artifact-name: my-product-linux-x64-${{ github.sha }}\n artifact-paths: |\n dist\n build/stage\n```\n\nWhen `command` is provided, it overrides `buildchain.toml` for that invocation.\nWhen `command` is empty, the action loads `buildchain.toml` and runs the named\nstage.\n\n`timeout-minutes` defaults to 120 and bounds either command source. A\nstage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout\nerrors identify the lifecycle stage and platform so a hung self-hosted build can\nbe diagnosed after the runner is released.\n\nThe action writes both a full manifest and a compact summary. It also exposes\nthe summary as outputs for reusable workflow callers:\n\nFor a `build` stage, paths selected by `[[signing.artifacts]]` for the current\n`platform-id` are automatically included in the lifecycle manifest even when\nthey sit outside `artifact-paths`. This binds every byte sent to the signing\nauthority without changing which ordinary product paths the caller uploads.\n\n| Output | Meaning |\n| --- | --- |\n| `manifest-path` | Full manifest path |\n| `summary-path` | Compact summary path |\n| `artifact-name` | Resolved artifact name |\n| `artifact-file-count` | Number of manifest files |\n| `artifact-total-bytes` | Total manifest bytes |\n| `artifact-summary-json` | One-line JSON summary |\n| `expected-artifacts-ok` | `true` when expectations passed |\n\n`expected-artifacts-json` can require exact paths, file count bounds, and a\nminimum byte total:\n\n```yaml\nwith:\n expected-artifacts-json: >-\n {\"minFiles\":2,\"requiredPaths\":[\"dist/app.tar.gz\",\"dist/checksums.txt\"]}\n```\n\nFor long native builds, set `sample-process-tree: \"true\"` and pass\n`process-summary-path`. The action wraps either the explicit `command` or the\nconfigured lifecycle stage with `buildchain sample process-tree`, then embeds\nthe produced summary in the lifecycle diagnostics artifact:\n\n```yaml\nwith:\n stage: build\n sample-process-tree: \"true\"\n process-summary-path: .buildchain/diagnostics/process-summary.json\n```\n\nCustom wrappers can still pass an existing sampler report or summary with\n`process-summary-path`; the action reads it after the lifecycle command\nfinishes, so commands may generate the file during the same invocation.\nSet `process-summary-required: \"false\"` when the summary is an optional sidecar,\nfor example when a reusable workflow may skip an optional build stage.\nThe diagnostics directory also includes `diagnostics-manifest.json`, a compact\ninventory of the diagnostics sidecars with byte counts and sha256 hashes."
},
{
"id": "action:validate-config",
"title": "validate-config",
"route": "/actions/validate-config",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/validate-config/README.md",
"digest": "sha256:ef48cd786973d9b6a1970c73ed780444415369075392f23404cdba5e1f988410",
"headings": [
{
"level": 1,
"title": "validate-config",
"anchor": "validate-config"
},
{
"level": 2,
"title": "Usage",
"anchor": "usage"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-config-validation-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# validate-config\n\nBuildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle\ncommands.\n\nUse this action during repository migration when a heavyweight project needs to\nprove that its Buildchain version state and lifecycle declaration are ready, but\nthe actual build should not run yet.\n\n## Usage\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n with:\n require-version-state: \"true\"\n require-lifecycle-stages: \"install,build,verify\"\n```\n\nThe action checks:\n\n- `buildchain.toml` exists and uses schema `1`;\n- configured version-state files exist and expose a string version;\n- anchored/manual version strategy declarations and JSON/TOML anchor manifests\n are structurally valid when configured;\n- web-surface project, channel, deploy adapter, retention, and staging security\n declarations are structurally valid when configured;\n- required lifecycle stages are declared and structurally valid.\n\nIt does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,\nor any other lifecycle command.\n\nOutputs include `project-type`, `project-name`, `project-site`, `channels`, and\n`deploy-adapters-json`, so callers can route site workflows without reparsing\nTOML in every repository."
},
{
"id": "api:node-package",
"title": "Buildchain Core Package",
"route": "/api/node-package",
"category": "api",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "packages/core/README.md",
"digest": "sha256:a73db80985e32c2ebb4ae94e30bc0e9bdc06f04eae189e8af25f89e901c14573",
"headings": [
{
"level": 1,
"title": "Buildchain Core Package",
"anchor": "buildchain-core-package"
},
{
"level": 2,
"title": "Toolkit Imports",
"anchor": "toolkit-imports"
}
],
"markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n `@kungfu-tech/buildchain/release-passport`.\n- anchored/manual derived witness preflight and exact-tree evidence through\n `@kungfu-tech/buildchain/anchored-version-material`.\n- sealed exact-root and KFD assessment inputs for KFX admission through\n `@kungfu-tech/buildchain/artifact-verification-envelope`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n through `@kungfu-tech/buildchain/badges`.\n- publication artifact manifests, source bundles, and publication artifact\n passports through `@kungfu-tech/buildchain/publication-artifact`.\n- two-clean-build byte reproducibility receipts through\n `@kungfu-tech/buildchain/publication-reproducibility`.\n- build-once publication bundle manifests and exact-byte verification through\n `@kungfu-tech/buildchain/publication-sealed-bundle`.\n- governed Paper work-branch start/submit, fleet audit/update, scaffold,\n preflight, status, npm bootstrap, build, Alpha, and resume plans through\n `@kungfu-tech/buildchain/paper`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n collectRunnerDiagnostics,\n summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } =\n await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } =\n await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nBuild facts consumers can collect source-bound module/product facts before\npublishing and pass those facts into the release passport:\n\n```js\nimport {\n collectModuleBuildFacts,\n writeBuildFacts,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst fact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact, output: \".buildchain/facts/native-core.json\" });\n```\n\nKFX producers can seal one passing artifact verification with exact roots,\nidentity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers\nverify or project the same envelope instead of reconstructing bindings:\n\n```js\nimport {\n projectArtifactVerificationEnvelopeToKfx,\n verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\nPublication repositories can produce site-consumable paper/report facts without\nbecoming web-surface repositories. When `[publication.archive]` is configured,\nthe same API also maintains the append-only publication registry used by site\nrepositories for latest and historical version pages. The preferred\n`latex-docker` toolchain records the pinned build-images LaTeX builder digest in\nthe publication artifact passport:\n\n```js\nimport { writePublicationArtifact } from \"@kungfu-tech/buildchain/publication-artifact\";\n\nwritePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });\n```\n\nBefore publication admission, prove the exact PDF, source bundle, manifests,\nand npm tarball twice from the same Git commit:\n\n```js\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nconst receipt = verifyPublicationReproducibility({\n sourceSha: process.env.GITHUB_SHA,\n promote: true,\n});\nif (!receipt.qualifying) throw new Error(\"publication is not reproducible\");\n```\n\nBind the promoted bytes into the durable build-once publication envelope:\n\n```js\nimport {\n createPublicationSealedBundle,\n verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\nThe sealed manifest names the exact npm tarball and release assets. Promotion\npersists those binary files before registry publication and verifies them again\nwhen a fresh runner resumes.\n\nPaper automation can use the same typed contracts as the CLI:\n\n```js\nimport {\n collectPaperPreflight,\n collectPaperStatus,\n planPaperMigration,\n planPaperScaffold,\n writePaperMigration,\n} from \"@kungfu-tech/buildchain/paper\";\n```\n\nPlanning and observation are side-effect free. `writePaperScaffold()` and\n`writePaperMigration()` perform the bounded local writes, while external\nmutations remain explicit CLI operations guarded by `--execute`.\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public badge subpath and treat\nMarkdown as a projection of the returned facts:\n\n```js\nimport {\n collectBadgeBundleFacts,\n renderBadgeBundleBlock,\n} from \"@kungfu-tech/buildchain/badges\";\n\nconst facts = await collectBadgeBundleFacts({ cwd: process.cwd() });\nconst markdown = renderBadgeBundleBlock(facts);\n```\n\nThe older `@kungfu-tech/buildchain/readme-badges` subpath remains available for\ncallers that need the full README badge surface instead of the default\nKFD-1 / KFD-2 / KFD-3 / Release Passport bundle.",
"slug": "node-package"
},
{
"id": "manual:artifact-verification-envelope",
"title": "Artifact Verification Envelope",
"route": "/docs/artifact-verification-envelope",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/artifact-verification-envelope.md",
"digest": "sha256:514911d2a5ee8ea65e070ffb0fc81a87f0ae35d7d87ff61999e47f784a7e9769",
"headings": [
{
"level": 1,
"title": "Artifact Verification Envelope",
"anchor": "artifact-verification-envelope"
},
{
"level": 2,
"title": "Public API",
"anchor": "public-api"
},
{
"level": 2,
"title": "Canonicalization and roots",
"anchor": "canonicalization-and-roots"
},
{
"level": 2,
"title": "Fail-closed behavior",
"anchor": "fail-closed-behavior"
}
],
"markdown": "# Artifact Verification Envelope\n\nBuildchain can turn a passing exact-artifact passport verification into one\nsealed, versioned input for Kungfu KFX admission. The envelope carries the\npublic verification result together with exact package, source, dependency,\nbuild-plan, toolchain, artifact, qualification, and verifier roots; issuer and\npublisher identity; lifecycle and revocation facts; and an existing ADR-0052\nKFD assessment.\n\nThe envelope does not create a second KFD evaluator. It validates and binds an\nassessment produced by the Kungfu KFD lifecycle. It also does not claim that an\nartifact is malware-free, universally safe, fit for every workspace, or\nauthorized as a Product System component.\n\n## Public API\n\nImport the dedicated package subpath:\n\n```js\nimport {\n projectArtifactVerificationEnvelopeToKfx,\n sealArtifactVerificationReport,\n verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\n`verifyArtifactPassport` also accepts an optional `verificationEnvelope`\nobject. Existing callers that omit it receive the unchanged\n`kungfu-buildchain-artifact-verification` v1 result.\n\n```js\nconst attestation = await verifyArtifactPassport({\n subject: \"dist/example.kfx\",\n passportLocation: \"dist/buildchain.release.json\",\n verificationEnvelope: {\n bindings,\n kfdAssessment,\n issuedAt,\n expiresAt,\n revocation,\n },\n});\n```\n\nThe result keeps the artifact-verification v1 fields that existing consumers\nunderstand and adds:\n\n- `bindings`: the schema-closed `kungfu.kfx-trust-inputs/v1` exact roots and\n identities;\n- `issuedAt`, `expiresAt`, `revoked`, and a root-bound `revocation` fact;\n- `kfdAssessment`: the pinned fresh `kungfu.trust.assessment/v1` lifecycle\n result;\n- `envelope`: the envelope contract, canonicalization version, and exact\n content root.\n\n`projectArtifactVerificationEnvelopeToKfx` returns the same sealed report as\n`attestation`, its exact `bindings` as `trustInputs`, and its existing\n`kfdAssessment`. A consumer does not reconstruct fields, recompute the KFD\ndecision, or inspect private Buildchain structures.\n\nThe read-only CLI uses those same functions for portable verification and\nprojection:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n --assessment-time 150 \\\n --expected-root sha256:... \\\n --expected-issuer buildchain.libkungfu.dev \\\n --expected-publisher kungfu-systems \\\n --expected-contract buildchain.release/v1 \\\n --json\n\nbuildchain project kfx-admission envelope.json \\\n --assessment-time 150 \\\n --json\n```\n\nThe projection's `envelopeRoot` is the same root returned by the Node verifier.\nThe CLI never adds consumer-side bindings or KFD conclusions.\n\n## Canonicalization and roots\n\nThe v1 envelope uses `buildchain-stable-json/v1`: object keys are sorted\nrecursively, array order is retained, and the root is lowercase SHA-256 with a\n`sha256:` prefix. `envelope.root` is excluded from its own root basis.\n\nThe KFD report hash is independently recomputed over the report with\n`report_hash` removed. The envelope is accepted only when:\n\n- the base artifact passport verification passes;\n- `bindings.artifactRoot` equals both the exact subject digest and the matched\n passport artifact digest;\n- every binding root is canonical lowercase SHA-256;\n- `bindings.qualificationRoot` equals the recomputed KFD `report_hash`;\n- the assessment key matches the report and its lifecycle state is `fresh`;\n- the report binds purpose, query proof, contract world, policy, and at least\n one fact-surface root;\n- lifecycle bounds are active and revocation facts are internally consistent;\n- any caller-pinned envelope root, issuer, publisher, or contract version\n matches exactly.\n\n## Fail-closed behavior\n\n`verifyArtifactVerificationEnvelope` returns a machine-readable check report.\nIt rejects sibling artifacts, root tampering, identity drift, invalid contract\nversions, expired or revoked envelopes, stale assessments, altered KFD report\ncontent, and missing fact-surface bindings. Callers may pin expected authority\nfields without changing the envelope.\n\nThe canonical root detects changed serialized content; authenticity still\ndepends on the pinned Buildchain verifier and release passport authority. The\nenvelope is supply-chain and evidence input. Kungfu Product and Workspace\npolicy retain operation, capability, and System-role authority."
},
{
"id": "manual:auditable-demo",
"title": "Auditable Demo Pipeline",
"route": "/docs/auditable-demo",
"category": "manual",
"capabilityGroup": "reusable-build",
"audience": [
"consumer",
"agent"
],
"maturity": "preview",
"sourcePath": "docs/auditable-demo.md",
"digest": "sha256:c49e734fdfe3b74d317e23a523e198f1194b2c7cd16cca87e8e3a3ffc7bf589f",
"headings": [
{
"level": 1,
"title": "Auditable Demo Pipeline",
"anchor": "auditable-demo-pipeline"
},
{
"level": 2,
"title": "Declarative Standalone Binary Scenarios",
"anchor": "declarative-standalone-binary-scenarios"
},
{
"level": 2,
"title": "Authority Boundary",
"anchor": "authority-boundary"
},
{
"level": 2,
"title": "Required Gate",
"anchor": "required-gate"
},
{
"level": 2,
"title": "Selective Render",
"anchor": "selective-render"
},
{
"level": 2,
"title": "Media Qualification Profiles",
"anchor": "media-qualification-profiles"
},
{
"level": 2,
"title": "Consumer Example",
"anchor": "consumer-example"
},
{
"level": 2,
"title": "Failure Evidence",
"anchor": "failure-evidence"
}
],
"markdown": "---\nstatus: draft\nperiod: 2026-07\ntheme: auditable-demo-pipeline\ndoc_type: technical-contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-05\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-08-02\n invisible_context_boundary: No hidden model build, parameter count, or private corpus is asserted.\n---\n\n# Auditable Demo Pipeline\n\nBuildchain's auditable demo workflow turns an exact GitHub build artifact into\ntwo distinct evidence products:\n\n1. a required qualified Gate bundle; and\n2. an optional rendered media bundle that can exist only after that exact Gate\n bundle passes.\n\nThe public reusable workflow is\n`.github/workflows/.auditable-demo.yml`. It is consumer-neutral: Buildchain\ndoes not know how a Kungfu, library, service, or application artifact should be\ninterpreted. The consumer owns a small checked-in executable adapter.\n\nFor standalone binary CLIs, the higher-level first-class surface is\n`.github/workflows/.declarative-auditable-demo.yml`. A consumer checks in only\n`.buildchain/auditable-demo.json`, builds and uploads its exact same-run binary\nplus metadata, and passes the producer-owned artifact name and digest to that\nworkflow. Buildchain then owns capture, Gate adaptation, independent native\n1080p and 720p rendering, Release Passport construction, content-addressed\nmaterialization, and the protected README update pull request. No\nproduct-specific capture, adapter, passport, or materializer is required.\n\n## Declarative Standalone Binary Scenarios\n\nThe schema is `contracts/auditable-demo-scenario-v1.schema.json`. One scenario\ncan declare up to eight demos, and each demo can contain up to twelve ordered\nliteral argv steps. Steps in one demo share a disposable workspace; separate\ndemos and the two rendition captures do not. Commands are never accepted as a\nshell string. An omitted or explicit `standard` duration class remains bounded\nto 60 seconds. A reviewed `execution.durationClass: long-form` declaration may\nraise the scenario and literal step ceilings to 180 seconds; it does not change\nthe default. Both classes retain 4 MiB per step, a clean Home/XDG environment,\nno inherited credentials, and a network-disabled read-only container with\nbounded tmpfs.\n\nConsumers may optionally add a\n`buildchain.declarative-demo-presentation/v1` presentation. This contract\nbinds one consumer-owned proof label, question, summary, and optional\ntransition to every demo in declared order. Buildchain verifies that each\nquestion is the same title used by capture and media; it does not invent or\nreinterpret the product argument.\n\nThe presentation also chooses one of two README materialization modes. The\ndefault, when no presentation is declared, remains the original full generated\nblock with commands, renditions, evidence, and claim boundary. `media-only`\nupdates only the image inside each existing README marker so consumer-authored\nnarrative and transitions survive regeneration. The generated technical\ndetails move to a separately declared Markdown specification, where stable\nper-demo markers preserve proof order and idempotent updates. The publication\npull request stages that specification together with the README and\ncontent-addressed evidence. No presentation field grants publication or Work\nauthority.\n\nThe optional top-level `compositionMode` is an explicit visual contract.\nOmitting it preserves `presentation-framed`; declaring `terminal-fill` makes\nthe bounded PTY replay the complete pixel surface without renderer-owned\nwindow chrome. Buildchain carries that choice into both native scenes. It does\nnot infer full-frame intent from output resolution.\n\nThe optional `buildchain.declarative-demo-playback/v1` contract separates\nobserved command latency from presentation timing. Its\n`deterministic-readable` mode preserves the captured terminal event payloads\nand their order, records the observed final-event time as non-authoritative\nevidence, and maps event ordinals onto the declared `activeDurationMs` before a\nbounded `finalHoldMs`. Both native renditions therefore replay at the same\nreadable pace even when an identical command runs faster or slower. Omitting\nthe contract preserves the original PTY timestamp behavior.\n\nThe uploaded metadata must bind the executable SHA-256, declare an empty\nruntime dependency set, and provide a bounded `executableFiles` array of exact\nartifact-relative paths and SHA-256 digests. GitHub Artifact transport does not\nretain Unix executable modes, so Buildchain restores mode `0755` only for this\ndigest-verified executable closure and verifies the same closure again inside\nthe network-disabled capture boundary. It never recursively changes artifact\nmodes. This metadata controls assembly only and grants no execution,\npublication, or identity authority. Capture rejects an artifact name or upload\ndigest that does not resolve to exactly one live artifact from the current workflow run.\n\nConsumers may also declare one bounded, non-interactive `transportSmoke` argv\nin the same scenario and opt the reusable build into\n`pre-upload-transport-smoke-scenario-path`. Before any GitHub Artifact or S3\nrelay upload, Buildchain copies the exact distribution directory, removes Unix\nexecute bits to simulate transport, restores only the digest-bound executable\nclosure, and runs that real binary with a clean Home/XDG environment. A missing\nlauncher, runtime, or embedded interpreter therefore fails before the expensive\nupload begins. This is a transport diagnostic with no authority grants; the\nlater network-disabled capture and Gate remain the qualification authority.\nIt retains ANSI terminal bytes with the real PTY read timestamps, verifies\ndeclared stdout and JSON file facts, enforces the total deadline while a step is\nrunning, and removes the disposable workspace before emitting evidence.\n\nBoth manual validation and alpha or release refreshes call the same reusable\nworkflow. Manual callers select Gate-only or full rendering and can explicitly\nrequest a materialization PR. Release callers select full rendering and the\nsame materializer automatically; there is no separate release-only recording\nimplementation. Publication requires a dedicated update token and target\nbranch. The token is an explicit bounded capability, while actor identity,\nfirst-party/System classification, KFD compliance, Product System metadata,\npackage metadata, registry history, scans, and generated evidence grant no\nauthority.\n\n```yaml\njobs:\n demo:\n needs: exact-binary\n uses: kungfu-systems/buildchain/.github/workflows/.declarative-auditable-demo.yml@BUILDCHAIN_EXACT_SHA\n with:\n source-ref: ${{ github.sha }}\n binary-artifact-name: ${{ needs.exact-binary.outputs.artifact-name }}\n binary-artifact-digest: ${{ needs.exact-binary.outputs.artifact-digest }}\n scenario-path: .buildchain/auditable-demo.json\n renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST\n render-media: true\n render-failure-advisory: false\n media-profile: responsive-web-delivery-v1\n materialize: true\n materialize-base-ref: dev/v1/v1.0\n secrets:\n DEMO_UPDATE_TOKEN: ${{ secrets.DEMO_UPDATE_TOKEN }}\n```\n\nBuildchain recursively consumes this surface in\n`.github/workflows/auditable-demo.yml` using its own exact standalone binary\nand the beginner bootstrap scenario in `.buildchain/auditable-demo.json`.\n\n## Authority Boundary\n\nThe retained build output is authoritative. The adapter reads that exact\nartifact and projects three files:\n\n```text\ncomplete-transcript.txt\npublic-projection.json\nscene.json\n```\n\nIt may additionally emit one declared `terminal-capture.json` using\n`kungfu.terminal-capture/v1`. The optional capture is bounded to 60 seconds by\ndefault or 180 seconds only when its scene explicitly declares `long-form`,\nfixed 80-200 by 24-80 terminal cells, 10,000 events, and 4 MiB of canonical\nbase64 bytes. It must contain a qualified completion sentinel and an explicitly\nempty authority-grant list. Existing three-file adapters remain valid.\n\nThe completion sentinel names a consumer-owned versioned schema, the exact\n`qualified` status, a content root, and an event count. Buildchain validates\nthat envelope generically; it does not reinterpret a command-specific result\nas Agent Work Lab evidence or grant authority from the schema name. The\nconsumer projection and its retained source artifact remain responsible for\nthe exact claim boundary.\n\nTerminal bytes are volatile observations, not Work, Warrant, capability, or\npublication authority. First-party or System identity, KFD compliance, Product\nSystem metadata, package metadata, scan output, registry history, and\nstandalone generation remain non-authoritative unless an exact higher-level\ncontract independently admits them.\n\nThe adapter must not rebuild or rerun the product. It receives:\n\n```text\n--artifact-root PATH\n--output PATH\n--source-coordinate PATH\n```\n\nConsumers with one shared adapter for several deterministic demos may also set\n`adapter-arguments-json` to a bounded JSON array. Buildchain parses the array,\nrejects malformed values, newlines, NUL bytes, more than 32 arguments, values\nlonger than 256 bytes, and attempts to override the three coordinate flags\nabove, then appends the accepted strings directly to the adapter argv. It never\nevaluates a shell command. The exact argument vector and its content root are\nretained in `adapter.json`; the Gate receipt binds that root. Adapter arguments\nselect consumer-owned capture behavior only and grant no authority.\n\n`--source-coordinate` identifies the caller repository, run, artifact id,\nartifact name, upload digest, expiry, and exact source SHA. The workflow finds\nexactly one live artifact with the requested name in the current caller run and\nrejects a digest mismatch before invoking the adapter. Callers must pass the\ndigest emitted by their own `upload-artifact` step; a name resolved later from\nthe Actions API is discovery evidence, not a substitute for that producer\noutput.\n\nBuildchain's reusable build workflow exposes `artifact-coordinates-json` after\nall resolved platform uploads complete. That producer-owned output binds every\nplatform id to its same-run artifact id, name, upload digest, URL, and expiry,\nso a consumer that delegates its build to Buildchain can pass an exact\ncoordinate without rediscovering authority in a downstream job. The build\naggregate fails closed if any declared platform lacks one live, digest-bearing\nartifact coordinate. The compact coordinate set is sorted by platform id so\ndownstream machine consumers do not depend on matrix completion order.\n\nThe adapter runs with a disposable Home/XDG/npm prefix, a minimal environment,\nand no GitHub, npm, or cloud credential injection. It must be a regular,\nnon-symlink, executable file inside the exact checked-out consumer source.\n\n## Required Gate\n\nThe Gate:\n\n- checks out the exact consumer source and exact called-workflow SHA;\n- resolves and downloads one exact same-run GitHub Artifact;\n- invokes the checked-in adapter by argv, never as an evaluated shell string;\n- rejects undeclared adapter outputs, symlinks, invalid UTF-8, invalid scene or\n projection or terminal-capture schemas, implicit capture grants,\n out-of-range transcript references, and oversized input;\n- derives a one-second compatibility scene from the consumer projection;\n- anonymously pulls an immutable `image@sha256:digest` renderer;\n- runs it as non-root with `--network none`, a read-only root filesystem, and a\n bounded tmpfs;\n- verifies the renderer manifest, media probe, exact input roots, exact output\n member set, and complete checksums;\n- independently verifies the requested composition mode, browser-observed\n content viewport, PTY rows and columns, and deterministic cell geometry for\n every frame set; `terminal-fill` is rejected unless the viewport and cell\n grid resolve to the complete declared frame;\n- uploads a content-addressed qualified bundle plus an independent GitHub\n Artifact id, URL, archive digest, and expiry-bearing source coordinate.\n\nThe Gate bundle contains the complete consumer transcript/projection/scene,\nsource artifact coordinate, adapter identity, bounded renderer evidence, a\npassed gate receipt, and checksums covering every member exactly once.\n\n## Selective Render\n\n`render-media: true` enables the full-media step only after every declared demo\nhas passed the required Gate. It recomputes each Gate member root, verifies the\nexact source SHA and renderer digest, and only then renders the complete\nqualified scene.\n\nThe media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,\nrenderer checksums, passed Gate receipt, a versioned media receipt, and\ndistribution checksums. A web-delivery profile also retains\n`media-inspection.json`, whose content root is bound into the receipt.\n`render-media: false` does not weaken or skip the Gate.\n\n`render-failure-advisory: true` makes only the full-media step advisory. A\nrender failure remains visible as a failed step and workflow warning, while the\nrequired Gate keeps its normal failure semantics. Failed or partial media can\nnever open a materialization PR. Use this for an Alpha lane whose binary\npublication must not depend on animation capacity; keep the default `false`\nfor explicit media refreshes and other workflows that require complete media.\n\nWhen the Gate bundle contains a qualified terminal capture, the render job\npasses it read-only to the immutable renderer. The renderer manifest binds the\ncapture root and terminal-state-machine version, but raw capture bytes remain\nin the Gate bundle rather than being copied into the public media bundle.\nMissing, malformed, out-of-bounds, non-full-frame, rendition-mismatched, or\ninternally drifted composition evidence fails before media finalization.\n\n## Media Qualification Profiles\n\nThe single machine-readable source is\n`contracts/auditable-demo-media-profiles-v1.json`. Callers select one reviewed\nprofile through `media-profile`; they cannot pass ffmpeg commands, codec flags,\nshell fragments, arbitrary profile paths, or transcoding instructions.\n\n| Profile | Meaning |\n| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |\n| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |\n| `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |\n| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |\n| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |\n\nFor web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation\ninside the same immutable, network-disabled renderer image. That command is\nBuildchain-controlled; the producer cannot inject flags. The resulting witness\nrecords exact roots and byte counts plus container, codec, pixel format,\ndimensions, duration, frame rate, audio stream count, and progressive-download\nevidence. Finalization re-hashes the retained bytes, rechecks the witness root,\nand parses MP4 top-level boxes itself. The producer's `media-probe.json.passed`\nfield remains supporting evidence, never sufficient authority.\n\nThe default `archive-v1` path preserves the existing v1 media receipt exactly.\nAn explicitly selected web-delivery profile emits a v2 media receipt with a\ncontent-addressed rendition list and explicit roles, MIME types, dimensions,\nand dimension policy. Agents and site builds select `primary-video`,\n`alternate-video`, `responsive-primary-video`,\n`responsive-alternate-video`, `browser-poster`, or evidence-only roles from\nthat receipt; they do not infer semantics from extensions or filenames.\nProfile-declared responsive renditions must match their exact dimensions,\nremain within the source scene, and preserve its aspect ratio. Additional\nproducer-declared renditions remain bounded by the selected profile and cannot\nraise their own byte ceiling. Unbound outputs, implicit upscales, aspect-ratio\ndrift, duplicate singleton roles, unknown profiles, or unsupported required\nversions fail closed.\n\nThe required Gate binds the exact selected media profile and the smoke media\nqualification root before optional full rendering starts. Gate-only validation\nand full rendering therefore exercise the same profile contract; a later media\njob cannot silently switch rendition authority.\n\nInitial byte ceilings are derived from the checked-in\n`auditable-demo-web-delivery-v1` fixture rendered by Build Images\n`v1.3.0-alpha.16` at its exact source SHA and image digest. GIF, MP4, WebM, and\nPNG ceilings are the next power of two above sixteen times the measured member\nbytes. The explicit responsive long-form profile derives its 4 MiB video and\n8 MiB GIF ceilings from the same observed bytes at a bounded 128-times\nmultiplier; it does not change another profile. The not-yet-produced WebP poster\nuses eight times the measured lossless PNG as its conservative proxy. The path-scoped qualification workflow\nregenerates the content-addressed evidence and fails on any byte or fact drift.\nIts matrix retains the original 1280x720 web-delivery baseline on the renderer\nthat produced it and separately measures the responsive profile against a\n1920x1080 fixture and the first exact renderer release that emits both\nsource-resolution and 720p renditions. This keeps historical budget evidence\nreproducible while giving the responsive contract its own immutable\nqualification root.\n\n## Consumer Example\n\nThe build job must expose both the exact artifact name and the digest returned\nby `upload-artifact`:\n\n```yaml\njobs:\n build:\n runs-on: ubuntu-24.04\n outputs:\n artifact-name: product-linux-${{ github.sha }}\n artifact-digest: ${{ steps.upload.outputs.artifact-digest }}\n steps:\n - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09\n - run: ./scripts/build-product\n - id: upload\n uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n with:\n name: product-linux-${{ github.sha }}\n path: dist\n if-no-files-found: error\n retention-days: 14\n compression-level: 0\n\n auditable-demo:\n needs: build\n permissions:\n actions: read\n contents: read\n uses: kungfu-systems/buildchain/.github/workflows/.auditable-demo.yml@BUILDCHAIN_EXACT_SHA\n with:\n source-ref: ${{ github.sha }}\n source-artifact-name: ${{ needs.build.outputs.artifact-name }}\n source-artifact-digest: ${{ needs.build.outputs.artifact-digest }}\n adapter-path: scripts/auditable-demo-adapter\n adapter-arguments-json: '[\"--demo-id\",\"agent-work-lab\"]'\n renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST\n render-media: false\n media-profile: archive-v1\n```\n\nReplace both placeholders with reviewed immutable SHAs or digests. An eligible\nbuild should always call the reusable workflow. Selection policy changes only\n`render-media`; it must never condition away the Gate job.\n\nUse `web-delivery-v1` only when the rendered bundle is intended to become a\nqualified web-delivery source. Use `site-hero-v1` when an optimized browser\nposter is also required. Select `responsive-long-form-web-delivery-v1` only\nwith an explicit long-form scenario. Profile qualification does not prove browser playback,\nresponsive layout, reduced-motion behavior, accessibility, or production\ndeployment; those remain site responsibilities.\n\n## Failure Evidence\n\nGate and render jobs use bounded timeouts and non-cancelling concurrency.\nDiagnostics artifacts are attempted with `always()` so adapter stdout/stderr\nand the resolved source coordinate remain available when qualification fails.\nNo production deployment, publication authority, token, or provider mutation\nis part of this workflow."
},
{
"id": "manual:aws-us-elastic-runner-burst-plane",
"title": "AWS US elastic runner burst plane",
"route": "/docs/aws-us-elastic-runner-burst-plane",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/aws-us-elastic-runner-burst-plane.md",
"digest": "sha256:7baa2a7221b5b521a592275227cf497e4a91912bf968cc0e6c12cbfdcd88632f",
"headings": [
{
"level": 1,
"title": "AWS US elastic runner burst plane",
"anchor": "aws-us-elastic-runner-burst-plane"
},
{
"level": 2,
"title": "Phase 1 contract",
"anchor": "phase-1-contract"
},
{
"level": 2,
"title": "Cost and kill-switch envelope",
"anchor": "cost-and-kill-switch-envelope"
},
{
"level": 2,
"title": "Qualification evidence",
"anchor": "qualification-evidence"
},
{
"level": 3,
"title": "Phase 1 recorded outcome",
"anchor": "phase-1-recorded-outcome"
},
{
"level": 2,
"title": "Phase 2 contract",
"anchor": "phase-2-contract"
},
{
"level": 3,
"title": "Phase 2 operator workflow",
"anchor": "phase-2-operator-workflow"
},
{
"level": 3,
"title": "Lower-level campaign and launch controllers",
"anchor": "lower-level-campaign-and-launch-controllers"
},
{
"level": 2,
"title": "Phase 3 contract",
"anchor": "phase-3-contract"
},
{
"level": 3,
"title": "Phase 3 lifecycle controller",
"anchor": "phase-3-lifecycle-controller"
},
{
"level": 2,
"title": "Provider lifecycle",
"anchor": "provider-lifecycle"
},
{
"level": 2,
"title": "Source boundaries",
"anchor": "source-boundaries"
}
],
"markdown": "---\nstatus: draft\nperiod: 2026-07-28\ntheme: aws-us-elastic-runner-burst-plane\ndoc_type: design\nsource_level: local-files-and-provider-docs\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-08-03\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-08-03\n invisible_information: No hidden model checkpoint, parameters, or private training data were available.\n---\n\n# AWS US elastic runner burst plane\n\nThe local runner fleet remains the normal Kungfu build plane. This AWS US plane\nis an explicit, temporary overflow mechanism with sequential qualification:\n\n1. Linux CodeBuild proof of concept under USD 50.\n2. Windows EC2 one-job JIT runners.\n3. One bounded 24-hour EC2 Mac campaign.\n\nNo later phase can start from design intent alone. The preceding phase must\nproduce a qualifying source-bound receipt, actual cost, and zero-resource\ncleanup proof.\n\n## Phase 1 contract\n\n`aws-us-codebuild-linux` is a Linux-only runner preset. It requires the exact\nCodeBuild project name and resolves the runner label at workflow evaluation\ntime:\n\n```text\ncodebuild---\n```\n\nThe GitHub-hosted `trust-gate` remains ahead of the matrix job. A fork pull\nrequest therefore fails or skips before the CodeBuild `runs-on` label exists as\na queued job. The dedicated consumer workflow is manual-only and does not add\nthe preset to dev, alpha, release, signing, notarization, deployment, or\npublication workflows.\n\nThe CodeBuild project is:\n\n- repository-scoped through an AWS CodeConnections GitHub App;\n- one ephemeral runner and one GitHub job per CodeBuild build;\n- outside a VPC, with no idle VM, NAT gateway, public ingress, SSH, or persistent\n workspace;\n- limited to two concurrent builds, 15 queued minutes, and 40 execution\n minutes;\n- allowed to write only its dedicated CloudWatch log group and request a token\n from its dedicated GitHub App connection;\n- forbidden from receiving signing, notarization, package publication, release,\n deploy, static AWS, long-lived GitHub, or SSH credentials.\n\nThe AWS-managed Ubuntu 24.04 standard image is the immutable base. Before a\nnative lifecycle starts, Buildchain installs the distribution's `gcc-14` and\n`g++-14` packages, exposes only per-job `gcc`/`g++` aliases, and downloads the\npinned Kitware CMake 3.31.6 archive after verifying its reviewed SHA256. The\nresolved package manager, versions, and CMake source digest are retained as\n`aws-native-toolchain.json`; no toolchain state survives the ephemeral\nCodeBuild execution. The toolchain adapter also retains the reviewed Amazon\nLinux 2023 `gcc14` path for compatible projects.\n\n## Cost and kill-switch envelope\n\nThe 2026-07-28 AWS Price List entry for\n`BUILD_GENERAL1_XLARGE` Linux in `us-east-1` is USD 0.0798 per build minute.\nThe contract rounds that rate up to USD 0.08. Twelve fully timed-out accepted\nbuilds reserve at most USD 38.40. At project concurrency two, the fail-closed\ncontroller can see at most two over-cap builds. The envelope conservatively\ncharges both race builds for their complete 40-minute timeout rather than\nassuming fast EventBridge delivery. The bounded CodeBuild maximum is therefore\nUSD 44.80, below the dedicated USD 49 budget and leaving USD 4.20 for the small\ncontroller, state, notification, and log charges.\n\nThe controller stores an idempotent build-id ledger, an atomic accepted-build\ncounter, and worst-case reservation in DynamoDB. Duplicate EventBridge delivery\ndoes not consume the bounded build allowance. It deletes the CodeBuild webhook\nand stops the triggering build when:\n\n- the accepted-build or reserved-cost cap is reached;\n- actual-cost telemetry is missing or more than six hours old;\n- actual CodeBuild spend reaches the budget;\n- AWS Budgets sends the 80% or 95% actual-spend notification;\n- the kill switch was already set.\n\nThe stack starts fail closed: it has no cost telemetry item and CloudFormation\ndoes not create the webhook. Before arming the webhook, the operator must write\na current Cost Explorer observation to the `COST` item, clear only the dedicated\ncontroller's killed state, and create the exact workflow-filtered webhook.\nRe-arming after any kill is a separate provider mutation and requires a new\nexplicit approval.\n\n## Qualification evidence\n\nEach successful job uploads `aws-runner-burst.json`, binding:\n\n- consumer repository, exact source SHA and ref;\n- GitHub run id, attempt and job;\n- CodeBuild project, build id, build ARN and initiator;\n- observation timestamp and canonical digest.\n\nLinux qualification requires:\n\n- at least 10 trusted exact-source successful jobs;\n- observed concurrency of at least two;\n- p95 queue-to-start of at most five minutes;\n- actual incremental AWS spend below USD 49;\n- no idle build and no active cloud residue.\n\n`node scripts/aws-runner-burst.mjs verify-linux --input ` fails\nclosed when cost telemetry is missing/stale or any acceptance predicate is\nfalse.\n\n### Phase 1 recorded outcome\n\nThe Linux phase passed on 2026-07-29. Ten trusted exact-source Kungfu jobs\ncompleted successfully, including four overlapping two-job waves. The observed\nCodeBuild queue-to-start p95 was 0.696 seconds. All 16 paid executions,\nincluding six diagnostic runs, produced a conservative incremental compute\nupper bound of USD 25.798 by rounding every execution up to a whole minute at\nthe live AWS Price List rate.\n\nThe global webhook kill switch was exercised after the tenth qualifying job.\nThe project then reported no webhook or in-progress build, and the card-owned\nEC2 inventory was empty. AWS Billing and Cost Explorer still reported an\nestimated zero during their provider ingestion delay; the retained\nexecution-derived upper bound is therefore the immediate cost proof and must be\nreconciled with the eventual AWS line item in the final campaign report.\n\nThe source-bound evidence and deterministic phase receipt are:\n\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-input.json`\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-receipt.json`\n\n## Phase 2 contract\n\nThe Windows phase uses the explicit `aws-us-ec2-windows-jit` runner preset.\nIts caller supplies one bounded label under\n`aws-us-ec2-windows-jit--`, and Buildchain\nresolves exactly one Windows x64 native lane. The reusable trust gate still\nruns on a GitHub-hosted runner before the JIT label can select EC2.\n\nThe provider creates repository-level GitHub JIT configuration for\n`kungfu-systems/kungfu`. Its `labels` request must contain all four scheduling\nlabels: `self-hosted`, `Windows`, `X64`, and the card-scoped\n`aws-us-ec2-windows-jit--` label. The workflow\ndisplay title also carries both identities, allowing the launch controller to\nverify the queued run against its campaign plan. GitHub's JIT endpoint does\nnot infer the default OS and architecture labels when they are omitted. The\nencoded configuration is never placed in EC2 user data, a tag, a command log,\nor an artifact. The operator writes it to a card-scoped SSM SecureString under\n`/kungfu/burst/windows/`; the instance role can read and delete only that\nprefix. Bootstrap reads the value once, deletes the parameter immediately, and\npasses it only to the pinned runner process.\n\nEach runner uses:\n\n- Amazon's current Windows Server 2025 Full Base AMI, resolved through the\n public SSM AMI parameter and retained by exact AMI id and name;\n- `c7i.4xlarge`, one instance and one JIT runner per job;\n- GitHub Actions Runner 2.336.0 with the official Windows x64 SHA256;\n- PowerShell 7.6.4 with the official Windows x64 MSI SHA256 and Microsoft\n Authenticode verification;\n- pinned PortableGit 2.55.0.3 with its GitHub release SHA256, exposing only its\n `cmd` directory so POSIX compatibility tools cannot shadow Windows tools;\n- a Microsoft Authenticode-verified Visual Studio 2022 Build Tools bootstrap;\n- IMDSv2, an encrypted root volume with delete-on-termination, no inbound\n security-group rule, no key pair, and no warm Auto Scaling capacity.\n\nRunner diagnostics and a redacted lifecycle record are uploaded to the\nprovider's encrypted, private evidence bucket under the exact campaign, run,\nattempt, and instance identity. The runner process exits after one job, Windows\nshuts down, and EC2's instance-initiated shutdown behavior is set to\n`terminate`. A five-minute reaper terminates card-owned stopped or\nthree-hour-old instances and deletes only their dedicated JIT parameter.\n\nAt the 2026-07-29 AWS Price List rate of USD 1.45 per Windows\n`c7i.4xlarge` hour, each accepted instance reserves its complete three-hour\nUSD 4.35 fail-closed lifetime before `RunInstances`. A DynamoDB transaction\nbinds the exact campaign and source, creates an idempotent run ledger entry,\nand atomically refuses a sixth accepted instance. Five accepted instances\ntherefore reserve at most USD 21.75. The campaign also persists the\noperator-observed spend from earlier Windows work, and refuses to arm unless\nthat baseline, all five reservations, and one USD 4.35 fail-closed race\nallowance remain below the USD 110 phase cap.\n\nThe campaign starts unarmed and expires within 24 hours. Its `CONTROL` record\ncan be created only once: a killed or expired campaign cannot be re-armed by\nthe campaign tool. A budget notification or any instance lifetime violation\npersists `KILLED` before cleanup, so later workflow dispatches fail before a\npaid launch. Reservations are never refunded: a controller crash, ambiguous\nlaunch, or successful launch all remain charged to the campaign, favoring a\nfalse stop over an accidental budget overrun.\n\nThe 2026-08-03 timeout-only campaign decision narrows the campaign to two\naccepted instances with one active instance at a time. The second reservation\nis an operator-gated repair retry: it may be used only after the first attempt\nis classified as non-counting and runner, EC2, EBS, SSM, and workflow residue\nhave returned to zero. The two-slot ledger is a maximum spend boundary, not an\nauthorization to consume both reservations.\n\nEach stack owns a stack-scoped reaper log group, so an independent retained\none-shot campaign stack can be created without colliding with another\ncampaign's audit log resource.\n\nThe account-native AWS Budget is defense in depth, not the authoritative launch\ngate. It is owned by the singleton\n`kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained\ncampaign stack. This prevents Budget-name collisions and prevents a stale\ncampaign reaper from becoming the provider-wide cost authority. The Budget\nfilters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,\n`OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and\n95% actual notifications persist the provider kill sentinel, terminate every\ntagged Windows JIT instance, and delete scoped JIT parameters. Every launch\ncontroller refuses to proceed when the sentinel exists or when the Budget\nidentity or dimension filter does not match.\n\nBudget installation is intentionally deployable by the workload account without\nAWS Organizations management-account access. It fails closed unless Cost\nExplorer exposes all three AWS-owned billing dimensions in the requested phase\nwindow. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for\nownership, cleanup, and IAM scoping, but it is not a billing filter. Do not\ncreate an unfiltered fallback Budget or treat an incomplete dimension readback\nas evidence.\nThe DynamoDB campaign reservation remains the atomic launch authority because\nCost Explorer and AWS Budgets can lag provider activity.\n\nQualification requires one runner-profile smoke and three trusted exact-source\nfull Windows jobs all bound to the same campaign, independent cancellation and\ntimeout cleanup exercises, and zero repository runner, EC2 instance,\ndisposable volume, min capacity, and desired capacity within 15 minutes of the\nfinal job.\n\n### Phase 2 operator workflow\n\n`pnpm operator:windows-jit` is the reusable lifecycle entrypoint. Its default\nmode is `plan`, which performs no AWS or GitHub call. A plan binds the account,\nregion, unique campaign and stack names, source SHA/ref, Cost Explorer window,\nworkflow id, network, OIDC provider, expiry, slot ceiling, singleton Budget\nidentity, and exact confirmation digest.\n\nThe modes are deliberately separated:\n\n- `plan` emits the deterministic mutation boundary and digest.\n- `audit` reads AWS and GitHub only. It verifies the account, disabled workflow,\n singleton guard stack, exact Budget filter, SNS thresholds/subscribers,\n provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner\n residue.\n- `install-budget --execute` deploys or updates only the singleton Budget guard.\n It refuses to mutate unless all exact Windows billing dimensions are visible,\n the Windows workflow is disabled, and the account, campaign, source, Budget,\n and plan digest confirmations match.\n- `prepare --execute` requires the installed Budget guard, absent kill\n sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,\n `RunInstances:0002`, and `us-east-1`, zero residue, a\n never-used campaign stack name, and the disabled workflow. The receipt binds\n the query timestamp and exact filter identity. Preparation deploys the\n campaign stack and atomically arms the ledger with that provider-spend\n baseline. It never enables or dispatches the workflow and never creates EC2\n capacity.\n- `close --execute` disables the workflow first, persists `KILLED`, publishes\n the campaign kill switch, and reports terminal success only after EC2, EBS,\n SSM, JIT parameter, and GitHub runner residue is zero. It is safe to rerun\n while the reaper settles.\n\nAll mutating modes require `--execute`, `--confirm-plan-digest`,\n`--confirm-account-id`, `--confirm-campaign-id`, and\n`--confirm-source-sha`. Budget installation and preparation additionally\nrequire `--confirm-budget-name`. A future paid workload still requires a\nseparate exact workflow/run authorization and uses\n`scripts/aws-windows-jit-controller.mjs`; preparation is not paid-launch\nauthority.\n\nStart by recording one reproducible plan:\n\n```bash\npnpm operator:windows-jit plan \\\n --aws-profile us \\\n --account-id 727884401362 \\\n --campaign-id win-REPLACE \\\n --source-sha REPLACE_WITH_EXACT_40_CHARACTER_SHA \\\n --source-ref refs/heads/dev/v4/v4.0 \\\n --observed-at REPLACE_WITH_ISO_TIMESTAMP \\\n --expires-at REPLACE_WITH_ISO_TIMESTAMP_WITHIN_24_HOURS \\\n --cost-start REPLACE_WITH_PHASE_START_DATE \\\n --cost-end REPLACE_WITH_EXCLUSIVE_END_DATE \\\n --max-accepted-instances 1 \\\n --workflow-id 322620360 \\\n --vpc-id REPLACE_WITH_VPC_ID \\\n --subnet-id REPLACE_WITH_SUBNET_ID \\\n --oidc-provider-arn REPLACE_WITH_GITHUB_OIDC_PROVIDER_ARN\n```\n\nReuse those exact arguments for `audit`, `install-budget`, `prepare`, or\n`close`; never regenerate `--observed-at` between the plan and its confirmed\nmutation. Capture stdout as the operator receipt. Do not put credentials,\ntokens, JIT configuration, or signed URLs in arguments or receipts.\n\n### Lower-level campaign and launch controllers\n\n`scripts/aws-windows-jit-campaign-core.mjs` owns the pure one-shot ledger\ncontract used by the operator and launch controller. Arming creates `CONTROL`\nand `CAMPAIGN#` with `attribute_not_exists` conditions, so DynamoDB refuses\na second campaign in the same retained state table. There is deliberately no\nclear or re-arm operation.\n\nEvery `scripts/aws-windows-jit-controller.mjs --execute` call must provide the\nsame `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,\nand `--confirm-state-table`. Before GitHub JIT material is created, the\ncontroller verifies the exact provider Budget/dimension filter and proves the\nglobal Budget kill sentinel absent. After the GitHub, AMI, active-instance,\nSSM, and EC2 DryRun checks pass, the controller\natomically reserves one run. Duplicate run-attempt-qualification identities,\nsource mismatch, expiry, `KILLED`, the sixth accepted instance, or a\nreservation that would exceed the USD 110 ceiling after combining the persisted\nfresh Cost Explorer baseline with all in-flight campaign reservations all fail\nclosed in one DynamoDB transaction before `RunInstances`. AWS Budget alarms are\ndefense in depth for delayed billing telemetry; the atomic ledger is the\nauthoritative launch-time guard. The operator is the only supported mutation\nsurface for campaign preparation and closeout; direct imports of the core are\nnot operator authority.\n\n## Phase 3 contract\n\nThe macOS phase uses the explicit `aws-us-ec2-macos-jit` runner preset. Its\ncaller supplies one unique label under\n`aws-us-ec2-macos-jit-`, and Buildchain resolves exactly one\nnative macOS ARM64 lane with `self-hosted`, `macOS`, `ARM64`, and the unique\ncampaign label. The reusable trust gate remains ahead of the JIT runner.\n\nUnlike Windows, the Mac campaign deliberately reuses one instance on one\n`mac2.metal` Dedicated Host. The operator allocates exactly one tagged host,\nlaunches exactly one tagged instance, and sends three sequential SSM bootstrap\ncommands. Each command consumes and immediately deletes a distinct repository\nJIT SecureString under `/kungfu/burst/macos/`, then runs GitHub Actions Runner\n2.336.0 for exactly one job. The runner archive is pinned to the official\nmacOS ARM64 SHA256. No GitHub, signing, notarization, publication, SSH, or\nstatic AWS credential is admitted to the instance.\n\nThe instance uses the exact retained Amazon EC2 macOS AMI, IMDSv2, an encrypted\ndelete-on-termination root volume, no inbound security-group rule, and the\nAMI's preinstalled SSM Agent and AWS CLI v2. The three accepted jobs must bind\nto the same host id, instance id, AMI id, source SHA, and campaign. At least one\njob must exercise the full native lifecycle.\n\nAWS imposes a 24-hour minimum Dedicated Host allocation. The contract therefore\nkeeps the one host for at least 24 hours even if all three jobs finish earlier.\nAt the recorded USD 0.6498 hourly rate, the minimum commitment rounds to USD\n15.60. A 30-hour fail-closed ceiling rounds to USD 19.49, below the dedicated\nUSD 25 budget. A ten-minute reaper terminates an expired campaign instance and\nretries host release after the minimum allocation and Apple scrub constraints\nallow it. Budget notifications at 80% and 95% invoke the same card-scoped kill\nswitch.\n\nQualification requires three trusted exact-source one-job JIT runs on the one\nhost, including at least one full run, plus proof that:\n\n- the instance terminated and the encrypted disposable volume disappeared;\n- Apple host scrub completed;\n- the Dedicated Host was released between 24 and 30 hours after allocation;\n- the repository has no registered campaign runner;\n- AWS has no active campaign instance or allocated campaign host;\n- actual incremental spend remained below USD 25.\n\n### Phase 3 lifecycle controller\n\n`scripts/aws-macos-jit-controller.mjs` is the operator boundary for the paid\ncampaign. It has three explicit mutation modes:\n\n- `launch-campaign` binds the exact repository source, AMI, availability zone,\n tagged Dedicated Host, and reusable instance. It rejects pre-existing Mac\n capacity and requires successful `AllocateHosts` and `RunInstances` DryRuns\n before either real call.\n- `run-job` binds one queued exact-source GitHub job to the existing campaign\n host and instance. It writes the repository JIT configuration through a\n mode-0600 temporary file into a distinct SSM SecureString, sends only the\n credential-free bootstrap through SSM, and removes the parameter plus runner\n registration if command delivery fails.\n- `close-campaign` refuses execution before the provider's 24-hour minimum,\n verifies the encrypted delete-on-termination root volume, removes scoped JIT\n residue, terminates the exact instance, and requires a `ReleaseHosts` DryRun\n before release. If Apple host scrubbing is still in progress, it reports\n `release-pending`; the ten-minute card-scoped reaper remains the bounded\n retry path.\n\nEvery execute mode requires the exact source SHA and campaign id to be repeated\nthrough `--confirm-source-sha` and `--confirm-campaign-id`. `run-job` also\nrequires `--confirm-run-id`. Omitting `--execute` emits a deterministic plan\nwithout changing AWS or GitHub state.\n\n## Provider lifecycle\n\nThe three infrastructure templates live under\n`infra/aws-us-elastic-runner-burst-plane/`. Creating a change set is the review\nboundary. Executing it, completing the GitHub App connection, creating or\nre-arming a webhook, allocating or releasing a Dedicated Host, writing cost\ntelemetry, dispatching paid jobs, operating a kill switch, and deleting a stack\nare all explicit provider mutations.\n\nThe reviewed Phase 1 provider sequence is below. It deliberately separates\nconnection creation, change-set inspection, stack execution, cost observation,\nand webhook arming:\n\n```bash\nburst_profile=us\nburst_region=us-east-1\nburst_stack=kungfu-buildchain-linux-burst-poc\nburst_project=kungfu-buildchain-linux-burst-poc\nburst_connection_name=kungfu-linux-burst-poc\nburst_change_set=phase1-linux-codebuild-poc\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections create-connection \\\n --provider-type GitHub \\\n --connection-name \"$burst_connection_name\" \\\n --tags Key=kungfu:owner,Value=buildchain \\\n Key=kungfu:plane,Value=aws-us-elastic-runner-burst\n```\n\nThe returned connection is `PENDING` until an operator completes the GitHub App\nhandshake in AWS. Read back `ConnectionStatus=AVAILABLE` before creating the\nchange set. Do not put an OAuth token or GitHub token in the shell:\n\nAWS CodeConnections connection names are limited to 32 characters, so keep the\nshorter connection name even when the stack and project use the longer\nBuildchain-specific name.\n\n```bash\nburst_connection_arn=REPLACE_WITH_AVAILABLE_CONNECTION_ARN\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections get-connection \\\n --connection-arn \"$burst_connection_arn\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation create-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\" \\\n --change-set-type CREATE \\\n --template-body \\\n file://infra/aws-us-elastic-runner-burst-plane/codebuild-poc.template.yml \\\n --capabilities CAPABILITY_IAM \\\n --parameters \\\n ParameterKey=GitHubConnectionArn,ParameterValue=\"$burst_connection_arn\" \\\n ParameterKey=ProjectName,ParameterValue=\"$burst_project\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait change-set-create-complete \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation describe-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n```\n\nOnly after the change-set resource list and IAM diff are accepted:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation execute-change-set \\\n --stack-name \"$burst_stack\" \\\n --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait stack-create-complete \\\n --stack-name \"$burst_stack\"\n```\n\nArming requires a fresh, operator-observed CodeBuild cost value. `COST` is the\nonly mutable telemetry item and `CONTROL` is the only state cleared:\n\n```bash\nburst_table=$(\n aws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation describe-stacks \\\n --stack-name \"$burst_stack\" \\\n --query \"Stacks[0].Outputs[?OutputKey=='StateTable'].OutputValue\" \\\n --output text\n)\nburst_observed_at=$(date -u +%s)\nburst_actual_usd=REPLACE_WITH_CURRENT_CODEBUILD_ACTUAL_USD\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n dynamodb put-item \\\n --table-name \"$burst_table\" \\\n --item \"{\\\"pk\\\":{\\\"S\\\":\\\"COST\\\"},\\\"actual_usd\\\":{\\\"N\\\":\\\"$burst_actual_usd\\\"},\\\"observed_at\\\":{\\\"N\\\":\\\"$burst_observed_at\\\"}}\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n dynamodb delete-item \\\n --table-name \"$burst_table\" \\\n --key '{\"pk\":{\"S\":\"CONTROL\"}}'\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codebuild create-webhook \\\n --project-name \"$burst_project\" \\\n --filter-groups \\\n '[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"},{\"type\":\"WORKFLOW_NAME\",\"pattern\":\"^AWS US Linux Burst Qualification$\"}]]'\n```\n\nThe immediate global kill is idempotent and targets only the dedicated project:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codebuild delete-webhook \\\n --project-name \"$burst_project\"\n```\n\nAfter preserving the qualification evidence and proving no build is in\nprogress, rollback removes only the card-owned stack and connection:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation delete-stack \\\n --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n cloudformation wait stack-delete-complete \\\n --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n codeconnections delete-connection \\\n --connection-arn \"$burst_connection_arn\"\n```\n\nPhase cleanup evidence must include:\n\n- CodeBuild batch/list results showing no in-progress build;\n- controller state and accepted-build ledger;\n- CodeBuild actual cost observation and its timestamp;\n- no EC2 instance, volume, launch template, Auto Scaling group, or dedicated\n host created by this phase;\n- the CodeBuild webhook deleted or the whole stack deleted.\n\n## Source boundaries\n\nThe design follows the current AWS CodeBuild GitHub Actions runner contract:\n`WORKFLOW_JOB_QUEUED` starts an ephemeral runner, the run id maps cancellation,\nand the build terminates after one job. It uses the current GitHub guidance to\nprefer ephemeral autoscaled self-hosted runners and to retain runner logs\nexternally. Provider documentation and the live AWS Price List query are the\nauthoritative external sources; this document is an auditable cache."
},
{
"id": "manual:binary-distribution",
"title": "Binary Distribution",
"route": "/docs/binary-distribution",
"category": "manual",
"capabilityGroup": "release-passport-trust",
"audience": [
"release-operator",
"agent"
],
"maturity": "stable",
"sourcePath": "docs/binary-distribution.md",
"digest": "sha256:b1611dcf0e6825e53921e4c9d31d1afe16fca81e6868360bfad1902587cd52ef",
"headings": [
{
"level": 1,
"title": "Binary Distribution",
"anchor": "binary-distribution"
},
{
"level": 2,
"title": "Asset Rules",
"anchor": "asset-rules"
},
{
"level": 2,
"title": "KFD-3 Distribution Declaration",
"anchor": "kfd-3-distribution-declaration"
},
{
"level": 2,
"title": "Runner Policy",
"anchor": "runner-policy"
},
{
"level": 2,
"title": "Evidence Bundle",
"anchor": "evidence-bundle"
},
{
"level": 2,
"title": "Local Smoke",
"anchor": "local-smoke"
}
],
"markdown": "# Binary Distribution\n\nBuildchain's binary distribution is the first high-pressure proof case for the\nRelease Passport protocol. It is not the boundary of the product.\n\n## Asset Rules\n\nGitHub Release assets use platform-specific archives:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe release lane does not upload loose top-level `buildchain` or\n`buildchain.exe` assets. Linux and macOS both name the executable `buildchain`\ninside their archives, so top-level loose assets would collide when matrix\nartifacts are merged.\n\n`Binary Distribution` is evidence-only. It never receives `contents: write`\nand never calls `gh release upload`; `upload-release=true` is rejected before\nthe matrix starts. A completed promotion explicitly dispatches the workflow at\nthe exact public tag because tags created by `GITHUB_TOKEN` do not recursively\nstart ordinary `push` workflows.\n\nAfter all three runners qualify, the workflow seals a\n`binary-distribution` controller receipt over the exact source/runtime SHA,\nrelease bundle, and Release Passport. `Binary Release Assets` observes the\nsuccessful evidence run, rechecks that its source SHA still equals the exact\ntag, derives the governed alpha/release branch, and asks the credential-free\npublication authority to assemble a short-lived capability. Only the nested\npublisher owns `contents: write`, and it runs behind the protected\n`buildchain-release-assets` Environment.\n\nGitHub Release metadata remains deterministic and tag-derived. Exact alpha tags such\nas `v2.6.2-alpha.0` are created or updated with `prerelease=true` and\n`make_latest=false`; exact stable tags such as `v2.6.1` are created or updated\nwith `prerelease=false` and `make_latest=true`. The sealed publisher uses\n`scripts/ensure-github-release.mjs` before asset upload instead of relying on\nGitHub's default latest-release heuristic.\n\nEach archive is accompanied by:\n\n- a platform manifest from the standalone binary builder;\n- platform observability event logs and summaries;\n- `checksums.txt`;\n- Release Passport evidence files;\n- `buildchain-release-bundle.tar.gz`;\n- `buildchain-release-bundle.json`.\n\nLinux archives may also be accompanied by a GitHub/Sigstore bundle and\n`buildchain.github-artifact-attestation-evidence/v1`. These prove the exact\nGitHub signer workflow and source digest while preserving the original compiler\nrunner in the platform manifest. The GitHub-hosted signer does not rebuild or\nexecute consumer source. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n## KFD-3 Distribution Declaration\n\nBuildchain self-describes this release lane in `dist/site/kfd-claims.json` as\nthe KFD-3 surface `distribution:buildchain-standalone`. Its declaration assigns\nregistration to Shifu, names `binary:build` as the reproducible task, and lists\nthe artifact kind, platform, and path glob for all three archives. Shifu should\ndiscover the registry through `buildchain layout --json`, not by copying the\nregistry path.\n\nThe repository-owned task is:\n\n```bash\npnpm binary:build\n```\n\nThe release workflow still builds each target on its declared runner. The local\ntask is the stable task identity used by the KFD declaration and local smoke\nchecks; it does not replace the three-platform release matrix.\n\n## Runner Policy\n\nProduction binary builds use GitHub-hosted runners:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners are compatibility fixtures. They can prove that consumers\nwith private runner fleets can still use the protocol, but Buildchain's public\nbinary distribution should stay reproducible on GitHub-hosted runners.\n\n## Evidence Bundle\n\n`buildchain-release-bundle.tar.gz` groups release assets and passport evidence\nunder one archive:\n\n```text\nbuildchain-release-bundle/\n release-assets/\n release-passport/\n buildchain-release-bundle.index.json\n```\n\n`buildchain-release-bundle.json` records the bundle digest and every included\nfile digest. Consumers can download the bundle when they want one artifact for\noffline review, mirroring, or site ingestion.\n\nPublication fails closed unless the bundle contains all three archives,\n`checksums.txt`, and `buildchain.release.json`; its archive digest, controller\nreceipt, live control-plane audit, runner provenance, source/runtime SHA, and\nexact target tag must all match the sealed admission.\n\n## Local Smoke\n\n```bash\npnpm binary:build -- --version v0.0.0-local\nnode bin/buildchain.mjs collect github-release \\\n --tag v0.0.0-local \\\n --assets-dir dist/binary \\\n --output-dir .buildchain/release-passport\nnode scripts/create-release-bundle.mjs \\\n --assets-dir dist/binary \\\n --passport-dir .buildchain/release-passport \\\n --output-dir .buildchain/release-passport \\\n --tag v0.0.0-local\n```"
},
{
"id": "manual:build-facts",
"title": "Build Facts",
"route": "/docs/build-facts",
"category": "manual",
"capabilityGroup": "observability-diagnostics",
"audience": [
"maintainer",
"agent"
],
"maturity": "stable",
"sourcePath": "docs/build-facts.md",
"digest": "sha256:75dcf7a6628dac9e982a455de9966044ae771611d4efc04e7264a2d4adb0bd3e",
"headings": [
{
"level": 1,
"title": "Build Facts",
"anchor": "build-facts"
},
{
"level": 2,
"title": "Config",
"anchor": "config"
},
{
"level": 2,
"title": "CLI",
"anchor": "cli"
},
{
"level": 2,
"title": "Node API",
"anchor": "node-api"
},
{
"level": 2,
"title": "Release Passport Integration",
"anchor": "release-passport-integration"
},
{
"level": 2,
"title": "Kungfu Legacy Projection",
"anchor": "kungfu-legacy-projection"
}
],
"markdown": "# Build Facts\n\nBuild Facts are Buildchain's machine-readable record of what a repository\nbuilt. They sit between lifecycle logs and release passports:\n\n- lifecycle logs explain what ran and how long it took;\n- module build facts bind one module to its Git source digest, version source,\n platform, lifecycle invocation, and output digests;\n- product build facts aggregate module facts and product artifacts;\n- release passports can carry build facts as first-class evidence.\n\nThe goal is to remove handwritten build metadata from consumer repositories.\nConsumers declare where their version and outputs live; Buildchain collects and\nverifies the facts.\n\n## Config\n\nDeclare build facts in `buildchain.toml`:\n\n```toml\nschema = 1\n\n[[facts.version_sources]]\nid = \"package\"\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[[facts.modules]]\nid = \"native-core\"\nroot = \"src/core\"\nscope = \"core\"\nversion_source = \"package\"\nlifecycle = \"build\"\noutputs = [\"dist/core.node\"]\n\n[[facts.products]]\nid = \"kungfu\"\nmodule_facts = [\".buildchain/facts/native-core.json\"]\nartifacts = [\"dist/kungfu.zip\"]\n\n[[facts.legacy_projections]]\ntype = \"kungfu-buildinfo\"\nmodule = \"native-core\"\npath = \"framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\"\n```\n\nSupported version sources:\n\n- `static`: an explicit `value`;\n- `json`: a JSON file plus dotted `key`;\n- `toml`: a TOML file plus dotted `key`;\n- `regex`: a text file plus regex `pattern`, using a named `version` group or\n the first capture group;\n- `command`: an explicit command whose output is the version.\n\nPrefer file-based sources. Command sources are allowed for legacy projects but\nare marked as less reproducible because the command output is not a static\nsource file.\n\n## CLI\n\nCollect a module fact:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json\n```\n\nOverride declarative config from a workflow step when needed:\n\n```bash\nbuildchain facts module \\\n --cwd \"$GITHUB_WORKSPACE\" \\\n --module native-core \\\n --module-root src/core \\\n --version-source package \\\n --output-path dist/core.node \\\n --output .buildchain/facts/native-core.json \\\n --json\n```\n\nWrite the Kungfu legacy `kungfubuildinfo.json` projection from the same module\nfact:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json \\\n --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n```\n\nAggregate product facts:\n\n```bash\nbuildchain facts aggregate \\\n --product kungfu \\\n --module-fact .buildchain/facts/native-core.json \\\n --artifact dist/kungfu.zip \\\n --output .buildchain/facts/kungfu.json\n```\n\nVerify a fact before publishing:\n\n```bash\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nVerification fails closed when a declared output is missing, an output digest is\nstale, a module fact was collected from a different Git `HEAD`, or a source\ndigest no longer matches the tracked source files.\n\n## Node API\n\n```js\nimport {\n aggregateBuildFacts,\n collectModuleBuildFacts,\n verifyBuildFacts,\n writeBuildFacts,\n writeKungfuBuildInfoProjection,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst moduleFact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact: moduleFact, output: \".buildchain/facts/native-core.json\" });\n\nconst productFact = aggregateBuildFacts({ productId: \"kungfu\" });\nconst verification = verifyBuildFacts({ fact: productFact });\n```\n\nThe root package export also re-exports these APIs from\n`@kungfu-tech/buildchain`.\n\n## Release Passport Integration\n\nPass build facts into a release passport:\n\n```bash\nbuildchain collect github-release \\\n --tag \"$TAG\" \\\n --assets-dir dist \\\n --build-facts-json .buildchain/facts/native-core.json \\\n --build-facts-json .buildchain/facts/kungfu.json \\\n --output-dir .buildchain/release-passport\n```\n\nThe passport records the full build facts in `buildFacts[]` and a compact\nevidence index in `evidence.buildFacts[]`. Agents can start from\n`buildchain.release.json`, discover the module/product facts, and verify that\nthe released artifacts still match the declared source, version, and output\nfacts.\n\n## Kungfu Legacy Projection\n\nKungfu historically consumes `kungfubuildinfo.json`. Buildchain now treats that\nfile as a projection of module build facts, not as an independent source of\ntruth. The projection preserves legacy fields such as `version`,\n`python_version`, `git_branch`, `git_revision`, and `git_pristine`, while adding\na `buildchain` section that points back to the module fact digest, version\nsource digest, and source digest.\n\nRepositories that no longer need the legacy file should consume the module and\nproduct facts directly."
},
{
"id": "manual:cli",
"title": "Buildchain CLI, npm Package, and Toolkit API",
"route": "/docs/cli",
"category": "manual",
"capabilityGroup": "api-cli-reference",
"audience": [
"agent",
"developer"
],
"maturity": "stable",
"sourcePath": "docs/cli.md",
"digest": "sha256:fad47682ed909f7b16f58bb8c24c51a943eb704a0a50ab6e033d745ee16a809a",
"headings": [
{
"level": 1,
"title": "Buildchain CLI, npm Package, and Toolkit API",
"anchor": "buildchain-cli-npm-package-and-toolkit-api"
},
{
"level": 2,
"title": "Install and Run",
"anchor": "install-and-run"
},
{
"level": 2,
"title": "Node API and Package Exports",
"anchor": "node-api-and-package-exports"
},
{
"level": 2,
"title": "Commands",
"anchor": "commands"
},
{
"level": 3,
"title": "Governed paper lifecycle",
"anchor": "governed-paper-lifecycle"
},
{
"level": 2,
"title": "npm Publish Gate",
"anchor": "npm-publish-gate"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-cli\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-07-31\n invisible_context: not asserted\n---\n\n# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@4.0.0`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude. Paper scaffold and migration maintain the\nexact current entry in `pnpm-workspace.yaml` before refreshing the lockfile.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { verifyGitHubArtifactAttestationEvidence } from \"@kungfu-tech/buildchain/github-artifact-attestation\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\nimport { collectPaperStatus } from \"@kungfu-tech/buildchain/paper\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport { createBuildchainLayoutDiscovery } from \"@kungfu-tech/buildchain/buildchain-layout\";\nimport { createPortableDevCachePlan } from \"@kungfu-tech/buildchain/portable-dev-cache\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v4`.\n\nFor exhaustive lookup, use the generated references rather than scanning this\nconceptual guide:\n\n- [`cli-reference.md`](cli-reference.md) is projected from the governed usage\n model and runtime command registry. `buildchain --help` is intercepted\n before dispatch at every listed path, exits zero, and has no command side\n effects.\n- [`node-api-reference.md`](node-api-reference.md) is projected from\n `package.json#exports` and exact ESM export declarations. The packaged\n `dist/site/node-api-registry.json` carries the same per-symbol signatures,\n parameters, conservative return/error boundaries, side-effect classification,\n maturity, example import, and source location.\n\n## Commands\n\n`buildchain create github-artifact-attestation-policy` seals the expected\nartifact, caller source, original Linux build, immutable Buildchain signer, and\nGitHub permission set before the Release Passport is collected.\n`buildchain verify github-artifact-attestation` invokes `gh attestation verify`\nwith the exact signer/source policy and then verifies the retained bundle,\npredicate, platform manifest, Passport, and Buildchain evidence locally. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n### Governed paper lifecycle\n\n`buildchain paper` is the unified operator surface for one paper repository or\na discovered fleet. Every subcommand returns a versioned JSON contract with\n`--json`:\n\n```bash\nbuildchain paper scaffold --package @kungfu-tech/paper-example \\\n --repository kungfu-systems/paper-example\nbuildchain paper migrate --json\nbuildchain paper agent verify --json\nbuildchain paper work start golden-path --json\nbuildchain paper work submit --json\nbuildchain paper fleet audit --root ../papers --json\nbuildchain paper fleet update --root ../paper-worktrees --json\nbuildchain paper preflight --offline --json\nbuildchain paper bootstrap npm --json\nbuildchain paper build --json\nbuildchain paper alpha --json\nbuildchain paper status --json\nbuildchain paper resume --json\n```\n\nThe safety and authority boundary is explicit:\n\n- `scaffold` plans a 17-file, no-overwrite repository shape by default; add\n `--write` to create only missing files.\n- `migrate` plans the Buildchain-owned authority, workflow, contract lock,\n version pin, package, agent-entry policy, managed `AGENTS.md` section, and\n required-check changes needed by an existing paper repository. It pins an\n exact v3 dependency and adds pnpm-backed paper scripts.\n Add `--write` only after reviewing exact old and new digests; paper content\n and publication configuration are never rewritten. Refresh\n `pnpm-lock.yaml` with `pnpm install --lockfile-only` after a write.\n- `agent verify` is the mandatory resume check on an existing work branch. It\n verifies the digest-bound `.buildchain/paper/agent-entry.json`, the single\n managed `AGENTS.md` section, exact package scripts and v3 dependency, runtime\n source SHA, development target, and current branch lineage. `--ci` derives\n the pull-request source and target from GitHub context and fails closed on a\n non-work source branch or a target other than the configured development\n line.\n- `work start` derives the protected development branch from the configured\n publication semver line and creates a safe local work branch only when the\n worktree is clean, the sole `origin` is the canonical `kungfu-systems`\n repository, and local HEAD equals the exact remotely observed development\n SHA. It never fetches or merges silently.\n- `work submit` accepts only an allowed non-protected work branch that contains\n the exact remote development commit. It rejects divergent remote work,\n wrong-base pull requests, dirty trees, forks, and ambiguous remotes; execution\n uses a normal non-force push and opens or reuses a PR to the derived\n development branch.\n- `fleet audit` discovers `paper-*` repositories from a root and emits one\n deterministic audit root over exact runtime, dependency, lockfile, workflow,\n authority, and repository observations. `fleet update` reuses the migration\n contract for every discovered repository, remains dry-run by default, and\n refuses protected or non-work branches.\n- The scaffolded `.buildchain/paper/provisioning-authority.json` binds both\n build/release caller workflow byte digests, the required verify caller, the\n agent-entry policy and instructions, their exact reusable-workflow SHA, the\n runtime SHA, contract-lock bytes, npm registry and trusted-publisher\n coordinates, and the repository Actions/generated-write policy under one\n digest. A floating Buildchain ref cannot change release policy after that\n authority is accepted.\n- The reusable `check.yml` detects publication-artifact repositories and runs\n `paper preflight --offline --ci` inside the existing required check context.\n Skipping the local CLI therefore cannot admit a missing entry contract,\n drifted Buildchain-owned surface, unsafe source branch, or wrong PR target.\n- `preflight` separates local readiness from readiness for external mutation.\n `--offline` skips live GitHub and npm observations without treating them as\n local failures. Live readiness requires default workflow permissions `read`,\n Actions pull-request approval disabled, and GitHub App or equivalent narrow\n generated-write credential metadata.\n- `bootstrap npm` always performs npm pack and publish dry-runs first. A real\n public bootstrap requires both `--execute` and\n `--confirm-public-package `, uses only the official npm registry,\n fixes the bootstrap version at `0.0.0-bootstrap.0`, and returns only npm URLs\n observed from command output. Success requires public package readback and\n the exact repository/workflow/environment trusted-publisher binding. For\n GitHub, the npm coordinate is the workflow filename (`paper-release.yml`),\n not its `.github/workflows/` repository path.\n- `build` plans the two-clean-build reproducibility proof. Add `--execute` to\n create and verify the sealed publication bundle.\n- `alpha` plans or opens the protected Alpha pull request; it never merges,\n publishes, or advances a floating ref.\n- `status` reports only evidence found in the repository or external\n observations. It never infers a later lifecycle state from an earlier one.\n- `resume` plans or dispatches the repository's thin release workflow; the\n protected workflow remains the release authority.\n\nThe ordered evidence states are `scaffolded`, `governed`, `admitted`,\n`bootstrapped`, `trust-bound`, `content-ready`, `artifact-sealed`,\n`package-published`, `alpha-complete`, `staging-visible`, and\n`production-visible`. A state can be `satisfied`, `not-reached`, `blocked`, or\n`unknown`; consumers must not collapse those distinctions.\n\nThe corresponding Node surface is\n`@kungfu-tech/buildchain/paper`. Planning and status functions are read-only;\n`writePaperScaffold()`, `writePaperMigration()`, and\n`writePaperFleetUpdate()` are the bounded local writers. Work plans expose\nseparate rechecking executors for local branch creation and normal push, and\n`executePaperNpmBootstrap()` preserves the same confirmation boundary used by\nthe CLI.\n\n`buildchain layout` is the stable machine question for repository layout. Tools\nsuch as Shifu should call it instead of copying `.buildchain/` path constants:\n\n```bash\nbuildchain layout --cwd /path/to/repository --json\n```\n\nThe result identifies the Buildchain version pin, repository root and config,\nthe canonical and currently resolved KFD-3 registry paths, and the KFD field\nused to declare Shifu jurisdiction. A repository is in Shifu's distribution\njurisdiction only when a KFD-3 surface explicitly declares\n`distribution.registrar=\"shifu\"`; the presence of Buildchain configuration is\nnot sufficient. The same contract is available through\n`createBuildchainLayoutDiscovery()` from\n`@kungfu-tech/buildchain/buildchain-layout`.\n\n`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\n\n`buildchain portable-cache plan` turns a consumer-owned, secret-free manifest\ninto GitHub Actions cache inputs without letting each consumer invent key or\nrestore-prefix semantics. The exact key binds source SHA and the consumer plan\ndigest; the compatible restore prefix still requires the same provider schema,\nlayer, roots, runner image, platform/architecture, toolchain, dependency lock,\nand build profile.\n\n```bash\nbuildchain portable-cache plan \\\n --manifest .buildchain/portable-cache.json \\\n --output .buildchain/portable-cache-plan.json \\\n --github-output \"$GITHUB_OUTPUT\"\n```\n\nThe emitted `cache-key`, `restore-keys`, and `cache-paths` values are intended\nfor pinned `actions/cache/restore` and `actions/cache/save` actions. After\nrestore and a consumer validation probe, seal the provider result:\n\n```bash\nbuildchain portable-cache receipt \\\n --plan .buildchain/portable-cache-plan.json \\\n --matched-key \"$CACHE_MATCHED_KEY\" \\\n --cache-hit \"$CACHE_HIT\" \\\n --validation-status pass \\\n --cold-fallback-status passed \\\n --output .buildchain/portable-cache-receipt.json\n```\n\nThe receipt distinguishes `exact`, `compatible`, `miss`, and `corrupt`.\nUnknown or contradictory provider evidence fails closed. A miss or corruption\nrequires the consumer's audited cold path; a cache never substitutes for the\nconsumer's current build or tests. Roots must be workspace-relative or under\n`~/`, and manifests cannot carry credentials, absolute host paths, or escape\nsegments. `cold-fallback-status=passed` qualifies a miss only after the current\nsource has completed its normal build and test path.\n\nSupported presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n validation, observation, contract publication, and downstream propagation\n planning without default mutation. Provider adapters expose built-in command\n plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n publication repositories that produce PDFs, metadata, source bundles, and\n site-consumable manifests without becoming web-surface repositories. The\n scaffold uses Buildchain's pinned\n `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n --require-version-state \\\n --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run ` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n --artifact-path dist \\\n --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain dev merge-queue` plans a GitHub merge-queue policy for a protected\nBuildchain dev channel. Declare every workflow that emits a required check; the\ncommand fails closed unless each file handles both `pull_request` and\n`merge_group` without reading `github.event.pull_request` directly:\n\n```bash\nbuildchain dev merge-queue \\\n --repository kungfu-systems/example \\\n --branch dev/v4/v4.0 \\\n --workflow .github/workflows/source-acceptance.yml \\\n --workflow .github/workflows/affected-native-pr.yml\n```\n\nThe default output is a read-only plan. Add `--apply` only after reviewing it.\nApply creates the exact-branch merge-queue ruleset before changing classic\nrequired status checks from strict to loose, preserves the required check\nidentities, and is safe to repeat. `gh` must be authenticated with repository\nAdministration write permission for apply mode.\n\nRepositories can make that policy declarative in `buildchain.toml`:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"enabled\" # enabled, inherit, or disabled\nrequired_workflows = [\".github/workflows/verify.yml\"]\ncheck_response_timeout_minutes = 120\nmax_entries_to_build = 1\nbypass_users = [\"release-owner\"]\n```\n\nUse `buildchain dev merge-queue --from-config` to resolve and reconcile the\ndeclaration. `enabled` requires an exact queue on the target dev branch;\n`disabled` suppresses automatic queue creation; `inherit` copies the active\ndefault dev branch's queue parameters and bypass actors. When the table is\nabsent, release-line bootstrap uses the backward-compatible `inherit` mode.\nEvery inherited or explicitly enabled queue still validates each declared\nrequired workflow before any mutation. For a legacy repository with no table,\nan already-active exact queue on the current default dev branch is accepted as\nthe inheritance evidence; new declarations should list the workflows so future\nchanges are revalidated from source.\nThe `Dev Merge Queue Governance` workflow runs this reconciliation after\ngovernance-relevant changes land on a dev branch; its manual dispatch remains\ndry-run by default.\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n --major 4 \\\n --minor 1 \\\n --source-ref release/v4/v4.0 \\\n --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, reconciles declared or\ninherited merge-queue governance, switches the default branch only after that\nreconciliation succeeds, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n --major 4 \\\n --minor 1 \\\n --source-ref release/v4/v4.0 \\\n --write \\\n --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n collectPublicSurfaceReverseAudit,\n assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(\n collectPublicSurfaceReverseAudit({ root: process.cwd() }),\n);\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4, KFD-5, and KFD-7 expose fail-closed\nproduct-evidence gate and verification protocols; passing those protocols does\nnot itself qualify, certify, activate, or ship support.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd 4 gate --input-json kfd-4-gate-input.json --output kfd-4-gate.json\nbuildchain kfd 5 gate --input-json kfd-5-gate-input.json --output kfd-5-gate.json\nbuildchain kfd 7 gate --input-json kfd-7-gate-input.json --output kfd-7-gate.json\nbuildchain kfd support project --manifest-json adopter-manifest.json \\\n --manifest-gate-json adopter-manifest-gate.json --output kfd-support.json\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence. Product repositories use the `product-claims` subcommand to\nvalidate and render their own declared KFD-2 release claims under the canonical\nBuildchain KFD layout:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 product-claims check --json\nbuildchain kfd 2 product-claims write --json\nbuildchain kfd 2 product-claims render --json\n```\n\nThe default source is `.buildchain/kfd/kfd-2/registry.json`; outputs are\n`.buildchain/kfd/kfd-2/release-claims.json`, per-claim release-passport inputs\nunder `claims/`, and `buildchain-claim-args.txt`. Use `--registry` or\n`--output-dir` only for an explicit product packaging projection. `check` never\nwrites and exits non-zero when outputs drift.\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe JSON summary also includes an additive `controlPlane` block. It counts\nworkflow-friction incident outcomes and production release-intent outcomes,\nincluding incident reuse rate, release-intent suppression rate, and suppression\nreasons. Buildchain writes those outcome events locally; it does not send\ntelemetry outside the runner.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n source: \"user\",\n component: \"native-build\",\n});\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n .buildchain/artifacts/linux-x64/diagnostics.json \\\n .buildchain/artifacts/macos-arm64/diagnostics.json \\\n --output .buildchain/artifacts/diagnostics-summary.json \\\n --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n --module native-core \\\n --output .buildchain/facts/native-core.json \\\n --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n --product kungfu \\\n --module-fact .buildchain/facts/native-core.json \\\n --artifact dist/kungfu.zip \\\n --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n --label native-build \\\n --interval-ms 15000 \\\n --output .buildchain/diagnostics/process-samples.jsonl \\\n --summary-output .buildchain/diagnostics/process-summary.json \\\n -- \\\n make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --json\n```\n\nRun the fail-closed clean-room gate before Alpha or release admission:\n\n```bash\nbuildchain publication-artifact reproducibility \\\n --source-sha \"$(git rev-parse HEAD)\" \\\n --promote \\\n --json\n```\n\nThe command checks two independent clones of the exact commit, isolates caches,\nderives `SOURCE_DATE_EPOCH` from Git, and compares every declared artifact,\nsource bundle, publication evidence file, npm package file, and actual npm\ntarball. It writes\n`.buildchain/publication/reproducibility-receipt.json`. Only a byte-identical\nbuild using the digest-pinned `latex-docker` toolchain is qualifying.\n`--allow-unpinned-toolchain` exists for local diagnostics and never changes the\nreceipt's `qualifying` field.\n\nGenerate the Buildchain-owned npm paper package contents from declared\npublication facts:\n\n```bash\nbuildchain publication-artifact npm-package --json\n```\n\nThis command reads `project.type = \"publication-artifact\"`,\n`publication.version`, and `[publish] kind = \"npm-paper-package\"` plus\n`publish.package`; it writes `.buildchain/publication/npm-package` by default.\nThe `paper-release.yml@v3` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n --package buildchain \\\n --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json \\\n --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n --tag v3.0.0 \\\n --repository kungfu-systems/buildchain \\\n --assets-dir dist \\\n --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n --tag v3.0.0 \\\n --repository kungfu-systems/buildchain \\\n --assets-dir dist \\\n --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n --package-set-json package-set.json \\\n --impact-json impact.json \\\n --trusted-publishing-json trusted-publishing.json \\\n --anchor-manifest-json libnode.release.json \\\n --build-summary-json .buildchain/artifacts/build-summary.json \\\n --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v3/v3.0\"}' \\\n --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\n\n`--invariant-passport-json` attaches a product-owned invariant Passport to the\nrelease gate and may be repeated. `--invariant-passport-cmd` runs a product\ncommand that emits one Passport JSON document. Buildchain verifies the\nPassport root, exact clean source identity, `verified` verdict, complete\nplatform coverage, and residual-risk shape; it does not redefine the product's\ninvariant semantics. Declared invariant Passport input is fail-closed.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nFor a promote-only stable transaction, Buildchain can derive a patch-level\nrelease-governance ledger when the PR-stage release-candidate passport proves\nthe stable source tree is exactly the previously qualified candidate tree.\nThis fallback is unavailable when candidate evidence is absent, stale, or not\ntree-equivalent.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n --repository kungfu-systems/libnode \\\n --tag v22.22.3-kf.3-alpha.18 \\\n --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:@` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry `\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport `.\n2. Sidecar pointer, such as `.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n Release asset URLs, or `--repository --tag `.\n6. Custom `--locator-config `.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n \"schemaVersion\": 1,\n \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n \"locators\": [\n {\n \"match\": {\n \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n \"digest\": \"sha256:...\"\n },\n \"passport\": \"../release-passport/buildchain.release.json\"\n }\n ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:@`, `oci:...`, `s3:...`,\n`github-release:@/`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nSeal an exact artifact verification with the Node API, then verify or project\nthe resulting KFX admission envelope without reconstructing its roots:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n --assessment-time 150 \\\n --expected-root sha256:... \\\n --expected-issuer buildchain.libkungfu.dev \\\n --expected-publisher kungfu-systems \\\n --expected-contract buildchain.release/v1 \\\n --json\n\nbuildchain project kfx-admission envelope.json \\\n --assessment-time 150 \\\n --json\n```\n\nBoth commands call the public artifact-verification-envelope verifier. The\nprojected `attestation`, `trustInputs`, and `kfdAssessment` are direct copies of\nthe sealed envelope, and `envelopeRoot` stays identical across Node and CLI.\nSee [`artifact-verification-envelope.md`](artifact-verification-envelope.md).\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v4/v4.0\nbuildchain release --dry-run --target-ref release/v4/v4.0 --sha \nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v4/v4.0\nbuildchain release explain --target-ref alpha/v4/v4.0 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v4.0.1-alpha.2\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag ` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v4.0.3-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v4.0.2` publishes to npm with dist-tag `latest`.\n- moving refs such as `v4`, `v4.0`, and `v4.0-alpha` do not match the publish\n workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
},
{
"id": "manual:cli-reference",
"title": "Buildchain CLI Reference",
"route": "/docs/cli-reference",
"category": "manual",
"capabilityGroup": "api-cli-reference",
"audience": [
"agent",
"developer",
"operator"
],
"maturity": "stable",
"sourcePath": "docs/cli-reference.md",
"digest": "sha256:0aa0c937ca4f3f239f67c10a3e656ca0934cd3618bf84639525ea1fbd685c055",
"headings": [
{
"level": 1,
"title": "Buildchain CLI Reference",
"anchor": "buildchain-cli-reference"
},
{
"level": 2,
"title": "`architecture`",
"anchor": "architecture"
},
{
"level": 3,
"title": "`buildchain architecture`",
"anchor": "buildchain-architecture"
},
{
"level": 3,
"title": "`buildchain architecture list`",
"anchor": "buildchain-architecture-list"
},
{
"level": 3,
"title": "`buildchain architecture qualify`",
"anchor": "buildchain-architecture-qualify"
},
{
"level": 3,
"title": "`buildchain architecture show`",
"anchor": "buildchain-architecture-show"
},
{
"level": 3,
"title": "`buildchain architecture validate`",
"anchor": "buildchain-architecture-validate"
},
{
"level": 2,
"title": "`audit`",
"anchor": "audit"
},
{
"level": 3,
"title": "`buildchain audit`",
"anchor": "buildchain-audit"
},
{
"level": 3,
"title": "`buildchain audit github-governance`",
"anchor": "buildchain-audit-github-governance"
},
{
"level": 3,
"title": "`buildchain audit publication-control-plane`",
"anchor": "buildchain-audit-publication-control-plane"
},
{
"level": 2,
"title": "`badges`",
"anchor": "badges"
},
{
"level": 3,
"title": "`buildchain badges`",
"anchor": "buildchain-badges"
},
{
"level": 3,
"title": "`buildchain badges bundle`",
"anchor": "buildchain-badges-bundle"
},
{
"level": 3,
"title": "`buildchain badges readme`",
"anchor": "buildchain-badges-readme"
},
{
"level": 2,
"title": "`build-contract`",
"anchor": "build-contract"
},
{
"level": 3,
"title": "`buildchain build-contract`",
"anchor": "buildchain-build-contract"
},
{
"level": 2,
"title": "`candidate`",
"anchor": "candidate"
},
{
"level": 3,
"title": "`buildchain candidate`",
"anchor": "buildchain-candidate"
},
{
"level": 3,
"title": "`buildchain candidate timeline`",
"anchor": "buildchain-candidate-timeline"
},
{
"level": 2,
"title": "`collect`",
"anchor": "collect"
},
{
"level": 3,
"title": "`buildchain collect`",
"anchor": "buildchain-collect"
},
{
"level": 3,
"title": "`buildchain collect github-release`",
"anchor": "buildchain-collect-github-release"
},
{
"level": 2,
"title": "`create`",
"anchor": "create"
},
{
"level": 3,
"title": "`buildchain create`",
"anchor": "buildchain-create"
},
{
"level": 3,
"title": "`buildchain create github-artifact-attestation-policy`",
"anchor": "buildchain-create-github-artifact-attestation-policy"
},
{
"level": 3,
"title": "`buildchain create publication-admission`",
"anchor": "buildchain-create-publication-admission"
},
{
"level": 3,
"title": "`buildchain create runner-provenance`",
"anchor": "buildchain-create-runner-provenance"
},
{
"level": 2,
"title": "`dev`",
"anchor": "dev"
},
{
"level": 3,
"title": "`buildchain dev`",
"anchor": "buildchain-dev"
},
{
"level": 3,
"title": "`buildchain dev merge-queue`",
"anchor": "buildchain-dev-merge-queue"
},
{
"level": 3,
"title": "`buildchain dev pr-admit`",
"anchor": "buildchain-dev-pr-admit"
},
{
"level": 3,
"title": "`buildchain dev proof classify`",
"anchor": "buildchain-dev-proof-classify"
},
{
"level": 3,
"title": "`buildchain dev proof integration`",
"anchor": "buildchain-dev-proof-integration"
},
{
"level": 3,
"title": "`buildchain dev proof replay`",
"anchor": "buildchain-dev-proof-replay"
},
{
"level": 3,
"title": "`buildchain dev proof source`",
"anchor": "buildchain-dev-proof-source"
},
{
"level": 3,
"title": "`buildchain dev proof verify-integration`",
"anchor": "buildchain-dev-proof-verify-integration"
},
{
"level": 3,
"title": "`buildchain dev proof verify-source`",
"anchor": "buildchain-dev-proof-verify-source"
},
{
"level": 3,
"title": "`buildchain dev warrant cancel-queued`",
"anchor": "buildchain-dev-warrant-cancel-queued"
},
{
"level": 3,
"title": "`buildchain dev warrant close`",
"anchor": "buildchain-dev-warrant-close"
},
{
"level": 3,
"title": "`buildchain dev warrant heartbeat`",
"anchor": "buildchain-dev-warrant-heartbeat"
},
{
"level": 3,
"title": "`buildchain dev warrant observe`",
"anchor": "buildchain-dev-warrant-observe"
},
{
"level": 3,
"title": "`buildchain dev warrant recover`",
"anchor": "buildchain-dev-warrant-recover"
},
{
"level": 3,
"title": "`buildchain dev warrant select`",
"anchor": "buildchain-dev-warrant-select"
},
{
"level": 3,
"title": "`buildchain dev warrant submit`",
"anchor": "buildchain-dev-warrant-submit"
},
{
"level": 2,
"title": "`diagnostics`",
"anchor": "diagnostics"
},
{
"level": 3,
"title": "`buildchain diagnostics`",
"anchor": "buildchain-diagnostics"
},
{
"level": 3,
"title": "`buildchain diagnostics summary`",
"anchor": "buildchain-diagnostics-summary"
},
{
"level": 2,
"title": "`doctor`",
"anchor": "doctor"
},
{
"level": 3,
"title": "`buildchain doctor`",
"anchor": "buildchain-doctor"
},
{
"level": 2,
"title": "`explain`",
"anchor": "explain"
},
{
"level": 3,
"title": "`buildchain explain`",
"anchor": "buildchain-explain"
},
{
"level": 3,
"title": "`buildchain explain artifact`",
"anchor": "buildchain-explain-artifact"
},
{
"level": 3,
"title": "`buildchain explain release`",
"anchor": "buildchain-explain-release"
},
{
"level": 2,
"title": "`facts`",
"anchor": "facts"
},
{
"level": 3,
"title": "`buildchain facts`",
"anchor": "buildchain-facts"
},
{
"level": 3,
"title": "`buildchain facts aggregate`",
"anchor": "buildchain-facts-aggregate"
},
{
"level": 3,
"title": "`buildchain facts module`",
"anchor": "buildchain-facts-module"
},
{
"level": 3,
"title": "`buildchain facts verify`",
"anchor": "buildchain-facts-verify"
},
{
"level": 2,
"title": "`github-governance`",
"anchor": "github-governance"
},
{
"level": 3,
"title": "`buildchain github-governance`",
"anchor": "buildchain-github-governance"
},
{
"level": 3,
"title": "`buildchain github-governance apply`",
"anchor": "buildchain-github-governance-apply"
},
{
"level": 3,
"title": "`buildchain github-governance plan`",
"anchor": "buildchain-github-governance-plan"
},
{
"level": 3,
"title": "`buildchain github-governance protection-policy-plan`",
"anchor": "buildchain-github-governance-protection-policy-plan"
},
{
"level": 3,
"title": "`buildchain github-governance rollback`",
"anchor": "buildchain-github-governance-rollback"
},
{
"level": 3,
"title": "`buildchain github-governance ruleset-policy-plan`",
"anchor": "buildchain-github-governance-ruleset-policy-plan"
},
{
"level": 2,
"title": "`help`",
"anchor": "help"
},
{
"level": 3,
"title": "`buildchain help`",
"anchor": "buildchain-help"
},
{
"level": 2,
"title": "`homebrew`",
"anchor": "homebrew"
},
{
"level": 3,
"title": "`buildchain homebrew`",
"anchor": "buildchain-homebrew"
},
{
"level": 3,
"title": "`buildchain homebrew check`",
"anchor": "buildchain-homebrew-check"
},
{
"level": 3,
"title": "`buildchain homebrew update-formula`",
"anchor": "buildchain-homebrew-update-formula"
},
{
"level": 2,
"title": "`infra-contract`",
"anchor": "infra-contract"
},
{
"level": 3,
"title": "`buildchain infra-contract`",
"anchor": "buildchain-infra-contract"
},
{
"level": 2,
"title": "`init`",
"anchor": "init"
},
{
"level": 3,
"title": "`buildchain init`",
"anchor": "buildchain-init"
},
{
"level": 2,
"title": "`inspect`",
"anchor": "inspect"
},
{
"level": 3,
"title": "`buildchain inspect`",
"anchor": "buildchain-inspect"
},
{
"level": 3,
"title": "`buildchain inspect artifact`",
"anchor": "buildchain-inspect-artifact"
},
{
"level": 3,
"title": "`buildchain inspect release`",
"anchor": "buildchain-inspect-release"
},
{
"level": 2,
"title": "`kfd`",
"anchor": "kfd"
},
{
"level": 3,
"title": "`buildchain kfd`",
"anchor": "buildchain-kfd"
},
{
"level": 3,
"title": "`buildchain kfd 1 gate`",
"anchor": "buildchain-kfd-1-gate"
},
{
"level": 3,
"title": "`buildchain kfd 1 schema`",
"anchor": "buildchain-kfd-1-schema"
},
{
"level": 3,
"title": "`buildchain kfd 1 verify`",
"anchor": "buildchain-kfd-1-verify"
},
{
"level": 3,
"title": "`buildchain kfd 1 witness`",
"anchor": "buildchain-kfd-1-witness"
},
{
"level": 3,
"title": "`buildchain kfd 2 claims`",
"anchor": "buildchain-kfd-2-claims"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims check`",
"anchor": "buildchain-kfd-2-product-claims-check"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims render`",
"anchor": "buildchain-kfd-2-product-claims-render"
},
{
"level": 3,
"title": "`buildchain kfd 2 product-claims write`",
"anchor": "buildchain-kfd-2-product-claims-write"
},
{
"level": 3,
"title": "`buildchain kfd 2 schema`",
"anchor": "buildchain-kfd-2-schema"
},
{
"level": 3,
"title": "`buildchain kfd 2 taxonomy`",
"anchor": "buildchain-kfd-2-taxonomy"
},
{
"level": 3,
"title": "`buildchain kfd 2 trust-assessment`",
"anchor": "buildchain-kfd-2-trust-assessment"
},
{
"level": 3,
"title": "`buildchain kfd 2 trust-claims`",
"anchor": "buildchain-kfd-2-trust-claims"
},
{
"level": 3,
"title": "`buildchain kfd 3`",
"anchor": "buildchain-kfd-3"
},
{
"level": 3,
"title": "`buildchain kfd 3 audit`",
"anchor": "buildchain-kfd-3-audit"
},
{
"level": 3,
"title": "`buildchain kfd 3 detect`",
"anchor": "buildchain-kfd-3-detect"
},
{
"level": 3,
"title": "`buildchain kfd 3 query`",
"anchor": "buildchain-kfd-3-query"
},
{
"level": 3,
"title": "`buildchain kfd 3 register binary`",
"anchor": "buildchain-kfd-3-register-binary"
},
{
"level": 3,
"title": "`buildchain kfd 3 register cli`",
"anchor": "buildchain-kfd-3-register-cli"
},
{
"level": 3,
"title": "`buildchain kfd 3 register documentation`",
"anchor": "buildchain-kfd-3-register-documentation"
},
{
"level": 3,
"title": "`buildchain kfd 3 register node-api`",
"anchor": "buildchain-kfd-3-register-node-api"
},
{
"level": 3,
"title": "`buildchain kfd 3 register python-api`",
"anchor": "buildchain-kfd-3-register-python-api"
},
{
"level": 3,
"title": "`buildchain kfd 3 register site-bundle`",
"anchor": "buildchain-kfd-3-register-site-bundle"
},
{
"level": 3,
"title": "`buildchain kfd 3 witness`",
"anchor": "buildchain-kfd-3-witness"
},
{
"level": 3,
"title": "`buildchain kfd 4 gate`",
"anchor": "buildchain-kfd-4-gate"
},
{
"level": 3,
"title": "`buildchain kfd 4 schema`",
"anchor": "buildchain-kfd-4-schema"
},
{
"level": 3,
"title": "`buildchain kfd 4 verify`",
"anchor": "buildchain-kfd-4-verify"
},
{
"level": 3,
"title": "`buildchain kfd 5 gate`",
"anchor": "buildchain-kfd-5-gate"
},
{
"level": 3,
"title": "`buildchain kfd 5 schema`",
"anchor": "buildchain-kfd-5-schema"
},
{
"level": 3,
"title": "`buildchain kfd 5 verify`",
"anchor": "buildchain-kfd-5-verify"
},
{
"level": 3,
"title": "`buildchain kfd 7 gate`",
"anchor": "buildchain-kfd-7-gate"
},
{
"level": 3,
"title": "`buildchain kfd 7 schema`",
"anchor": "buildchain-kfd-7-schema"
},
{
"level": 3,
"title": "`buildchain kfd 7 verify`",
"anchor": "buildchain-kfd-7-verify"
},
{
"level": 3,
"title": "`buildchain kfd aggregate`",
"anchor": "buildchain-kfd-aggregate"
},
{
"level": 3,
"title": "`buildchain kfd hub explain`",
"anchor": "buildchain-kfd-hub-explain"
},
{
"level": 3,
"title": "`buildchain kfd hub init`",
"anchor": "buildchain-kfd-hub-init"
},
{
"level": 3,
"title": "`buildchain kfd hub inspect`",
"anchor": "buildchain-kfd-hub-inspect"
},
{
"level": 3,
"title": "`buildchain kfd hub test`",
"anchor": "buildchain-kfd-hub-test"
},
{
"level": 3,
"title": "`buildchain kfd migrate-layout`",
"anchor": "buildchain-kfd-migrate-layout"
},
{
"level": 3,
"title": "`buildchain kfd schema list`",
"anchor": "buildchain-kfd-schema-list"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-1`",
"anchor": "buildchain-kfd-schema-show-kfd-1"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-2`",
"anchor": "buildchain-kfd-schema-show-kfd-2"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-3`",
"anchor": "buildchain-kfd-schema-show-kfd-3"
},
{
"level": 3,
"title": "`buildchain kfd schema show kfd-4`",
"anchor": "buildchain-kfd-schema-show-kfd-4"
},
{
"level": 3,
"title": "`buildchain kfd status`",
"anchor": "buildchain-kfd-status"
},
{
"level": 3,
"title": "`buildchain kfd support project`",
"anchor": "buildchain-kfd-support-project"
},
{
"level": 3,
"title": "`buildchain kfd support verify`",
"anchor": "buildchain-kfd-support-verify"
},
{
"level": 3,
"title": "`buildchain kfd upstream check`",
"anchor": "buildchain-kfd-upstream-check"
},
{
"level": 3,
"title": "`buildchain kfd upstream collect`",
"anchor": "buildchain-kfd-upstream-collect"
},
{
"level": 3,
"title": "`buildchain kfd upstream roles`",
"anchor": "buildchain-kfd-upstream-roles"
},
{
"level": 2,
"title": "`layout`",
"anchor": "layout"
},
{
"level": 3,
"title": "`buildchain layout`",
"anchor": "buildchain-layout"
},
{
"level": 2,
"title": "`lifecycle`",
"anchor": "lifecycle"
},
{
"level": 3,
"title": "`buildchain lifecycle`",
"anchor": "buildchain-lifecycle"
},
{
"level": 3,
"title": "`buildchain lifecycle run`",
"anchor": "buildchain-lifecycle-run"
},
{
"level": 2,
"title": "`log`",
"anchor": "log"
},
{
"level": 3,
"title": "`buildchain log`",
"anchor": "buildchain-log"
},
{
"level": 3,
"title": "`buildchain log error`",
"anchor": "buildchain-log-error"
},
{
"level": 3,
"title": "`buildchain log info`",
"anchor": "buildchain-log-info"
},
{
"level": 3,
"title": "`buildchain log summary`",
"anchor": "buildchain-log-summary"
},
{
"level": 3,
"title": "`buildchain log warn`",
"anchor": "buildchain-log-warn"
},
{
"level": 2,
"title": "`mark`",
"anchor": "mark"
},
{
"level": 3,
"title": "`buildchain mark`",
"anchor": "buildchain-mark"
},
{
"level": 2,
"title": "`npm`",
"anchor": "npm"
},
{
"level": 3,
"title": "`buildchain npm`",
"anchor": "buildchain-npm"
},
{
"level": 3,
"title": "`buildchain npm dry-run`",
"anchor": "buildchain-npm-dry-run"
},
{
"level": 2,
"title": "`paper`",
"anchor": "paper"
},
{
"level": 3,
"title": "`buildchain paper`",
"anchor": "buildchain-paper"
},
{
"level": 3,
"title": "`buildchain paper agent verify`",
"anchor": "buildchain-paper-agent-verify"
},
{
"level": 3,
"title": "`buildchain paper alpha`",
"anchor": "buildchain-paper-alpha"
},
{
"level": 3,
"title": "`buildchain paper bootstrap npm`",
"anchor": "buildchain-paper-bootstrap-npm"
},
{
"level": 3,
"title": "`buildchain paper build`",
"anchor": "buildchain-paper-build"
},
{
"level": 3,
"title": "`buildchain paper fleet audit`",
"anchor": "buildchain-paper-fleet-audit"
},
{
"level": 3,
"title": "`buildchain paper fleet update`",
"anchor": "buildchain-paper-fleet-update"
},
{
"level": 3,
"title": "`buildchain paper migrate`",
"anchor": "buildchain-paper-migrate"
},
{
"level": 3,
"title": "`buildchain paper preflight`",
"anchor": "buildchain-paper-preflight"
},
{
"level": 3,
"title": "`buildchain paper resume`",
"anchor": "buildchain-paper-resume"
},
{
"level": 3,
"title": "`buildchain paper scaffold`",
"anchor": "buildchain-paper-scaffold"
},
{
"level": 3,
"title": "`buildchain paper status`",
"anchor": "buildchain-paper-status"
},
{
"level": 3,
"title": "`buildchain paper work start`",
"anchor": "buildchain-paper-work-start"
},
{
"level": 3,
"title": "`buildchain paper work submit`",
"anchor": "buildchain-paper-work-submit"
},
{
"level": 2,
"title": "`portable-cache`",
"anchor": "portable-cache"
},
{
"level": 3,
"title": "`buildchain portable-cache`",
"anchor": "buildchain-portable-cache"
},
{
"level": 3,
"title": "`buildchain portable-cache plan`",
"anchor": "buildchain-portable-cache-plan"
},
{
"level": 3,
"title": "`buildchain portable-cache receipt`",
"anchor": "buildchain-portable-cache-receipt"
},
{
"level": 2,
"title": "`project`",
"anchor": "project"
},
{
"level": 3,
"title": "`buildchain project`",
"anchor": "buildchain-project"
},
{
"level": 3,
"title": "`buildchain project kfx-admission`",
"anchor": "buildchain-project-kfx-admission"
},
{
"level": 2,
"title": "`publication-artifact`",
"anchor": "publication-artifact"
},
{
"level": 3,
"title": "`buildchain publication-artifact`",
"anchor": "buildchain-publication-artifact"
},
{
"level": 3,
"title": "`buildchain publication-artifact manifest`",
"anchor": "buildchain-publication-artifact-manifest"
},
{
"level": 3,
"title": "`buildchain publication-artifact npm-package`",
"anchor": "buildchain-publication-artifact-npm-package"
},
{
"level": 3,
"title": "`buildchain publication-artifact reproducibility`",
"anchor": "buildchain-publication-artifact-reproducibility"
},
{
"level": 2,
"title": "`publish-source`",
"anchor": "publish-source"
},
{
"level": 3,
"title": "`buildchain publish-source`",
"anchor": "buildchain-publish-source"
},
{
"level": 3,
"title": "`buildchain publish-source lock`",
"anchor": "buildchain-publish-source-lock"
},
{
"level": 3,
"title": "`buildchain publish-source manifest`",
"anchor": "buildchain-publish-source-manifest"
},
{
"level": 3,
"title": "`buildchain publish-source validate-anchored-release`",
"anchor": "buildchain-publish-source-validate-anchored-release"
},
{
"level": 3,
"title": "`buildchain publish-source verify-channel-ref`",
"anchor": "buildchain-publish-source-verify-channel-ref"
},
{
"level": 3,
"title": "`buildchain publish-source verify-lock`",
"anchor": "buildchain-publish-source-verify-lock"
},
{
"level": 2,
"title": "`release`",
"anchor": "release"
},
{
"level": 3,
"title": "`buildchain release`",
"anchor": "buildchain-release"
},
{
"level": 3,
"title": "`buildchain release --dry-run`",
"anchor": "buildchain-release-dry-run"
},
{
"level": 3,
"title": "`buildchain release abort`",
"anchor": "buildchain-release-abort"
},
{
"level": 3,
"title": "`buildchain release dry-run`",
"anchor": "buildchain-release-dry-run"
},
{
"level": 3,
"title": "`buildchain release explain`",
"anchor": "buildchain-release-explain"
},
{
"level": 3,
"title": "`buildchain release finalize`",
"anchor": "buildchain-release-finalize"
},
{
"level": 3,
"title": "`buildchain release inspect`",
"anchor": "buildchain-release-inspect"
},
{
"level": 3,
"title": "`buildchain release line open`",
"anchor": "buildchain-release-line-open"
},
{
"level": 3,
"title": "`buildchain release recover`",
"anchor": "buildchain-release-recover"
},
{
"level": 2,
"title": "`release-governance`",
"anchor": "release-governance"
},
{
"level": 3,
"title": "`buildchain release-governance`",
"anchor": "buildchain-release-governance"
},
{
"level": 3,
"title": "`buildchain release-governance reconcile`",
"anchor": "buildchain-release-governance-reconcile"
},
{
"level": 2,
"title": "`release-propagation`",
"anchor": "release-propagation"
},
{
"level": 3,
"title": "`buildchain release-propagation`",
"anchor": "buildchain-release-propagation"
},
{
"level": 3,
"title": "`buildchain release-propagation entry`",
"anchor": "buildchain-release-propagation-entry"
},
{
"level": 3,
"title": "`buildchain release-propagation pickup`",
"anchor": "buildchain-release-propagation-pickup"
},
{
"level": 3,
"title": "`buildchain release-propagation plan`",
"anchor": "buildchain-release-propagation-plan"
},
{
"level": 3,
"title": "`buildchain release-propagation work`",
"anchor": "buildchain-release-propagation-work"
},
{
"level": 3,
"title": "`buildchain release-propagation write-lock`",
"anchor": "buildchain-release-propagation-write-lock"
},
{
"level": 2,
"title": "`release-tail`",
"anchor": "release-tail"
},
{
"level": 3,
"title": "`buildchain release-tail`",
"anchor": "buildchain-release-tail"
},
{
"level": 3,
"title": "`buildchain release-tail compat`",
"anchor": "buildchain-release-tail-compat"
},
{
"level": 3,
"title": "`buildchain release-tail init`",
"anchor": "buildchain-release-tail-init"
},
{
"level": 3,
"title": "`buildchain release-tail plan`",
"anchor": "buildchain-release-tail-plan"
},
{
"level": 3,
"title": "`buildchain release-tail status`",
"anchor": "buildchain-release-tail-status"
},
{
"level": 3,
"title": "`buildchain release-tail verify`",
"anchor": "buildchain-release-tail-verify"
},
{
"level": 2,
"title": "`sample`",
"anchor": "sample"
},
{
"level": 3,
"title": "`buildchain sample`",
"anchor": "buildchain-sample"
},
{
"level": 3,
"title": "`buildchain sample process-tree`",
"anchor": "buildchain-sample-process-tree"
},
{
"level": 2,
"title": "`span`",
"anchor": "span"
},
{
"level": 3,
"title": "`buildchain span`",
"anchor": "buildchain-span"
},
{
"level": 2,
"title": "`transaction`",
"anchor": "transaction"
},
{
"level": 3,
"title": "`buildchain transaction`",
"anchor": "buildchain-transaction"
},
{
"level": 3,
"title": "`buildchain transaction inspect`",
"anchor": "buildchain-transaction-inspect"
},
{
"level": 2,
"title": "`validate`",
"anchor": "validate"
},
{
"level": 3,
"title": "`buildchain validate`",
"anchor": "buildchain-validate"
},
{
"level": 2,
"title": "`verify`",
"anchor": "verify"
},
{
"level": 3,
"title": "`buildchain verify`",
"anchor": "buildchain-verify"
},
{
"level": 3,
"title": "`buildchain verify artifact dir`",
"anchor": "buildchain-verify-artifact-dir"
},
{
"level": 3,
"title": "`buildchain verify artifact file`",
"anchor": "buildchain-verify-artifact-file"
},
{
"level": 3,
"title": "`buildchain verify artifact github-release:...`",
"anchor": "buildchain-verify-artifact-github-release"
},
{
"level": 3,
"title": "`buildchain verify artifact npm:...`",
"anchor": "buildchain-verify-artifact-npm"
},
{
"level": 3,
"title": "`buildchain verify artifact oci:...`",
"anchor": "buildchain-verify-artifact-oci"
},
{
"level": 3,
"title": "`buildchain verify artifact url`",
"anchor": "buildchain-verify-artifact-url"
},
{
"level": 3,
"title": "`buildchain verify artifact-envelope`",
"anchor": "buildchain-verify-artifact-envelope"
},
{
"level": 3,
"title": "`buildchain verify github-artifact-attestation`",
"anchor": "buildchain-verify-github-artifact-attestation"
},
{
"level": 3,
"title": "`buildchain verify infra-contract-evidence-bundle`",
"anchor": "buildchain-verify-infra-contract-evidence-bundle"
},
{
"level": 3,
"title": "`buildchain verify observability-log`",
"anchor": "buildchain-verify-observability-log"
},
{
"level": 3,
"title": "`buildchain verify publication-admission`",
"anchor": "buildchain-verify-publication-admission"
},
{
"level": 3,
"title": "`buildchain verify release-passport`",
"anchor": "buildchain-verify-release-passport"
},
{
"level": 2,
"title": "`version`",
"anchor": "version"
},
{
"level": 3,
"title": "`buildchain version`",
"anchor": "buildchain-version"
},
{
"level": 2,
"title": "`web-surface`",
"anchor": "web-surface"
},
{
"level": 3,
"title": "`buildchain web-surface`",
"anchor": "buildchain-web-surface"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-generated-reference\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: generated\nlast_reviewed: 2026-08-01\nai_provenance:\n model_family: GPT-5\n product: Codex\n generated_at: 2026-08-01\n invisible_context: not asserted\n---\n\n# Buildchain CLI Reference\n\n> Generated from `BUILDCHAIN_USAGE` and the runtime command registry. Do not edit this file by hand.\n\nEvery listed help command is intercepted before dispatch, exits zero, and performs no command side effects.\n\n## `architecture`\n\n### `buildchain architecture`\n\n- Help: `buildchain architecture --help`\n- Canonical id: `architecture`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain architecture\n```\n\n### `buildchain architecture list`\n\n- Help: `buildchain architecture list --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture list [--cwd ] [--json]\n```\n\n### `buildchain architecture qualify`\n\n- Help: `buildchain architecture qualify --help`\n- Canonical id: `architecture`\n- Options: `--authority-revision`, `--candidate-revision`, `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture qualify --authority-revision [--candidate-revision ] [--cwd ] [--json]\n```\n\n### `buildchain architecture show`\n\n- Help: `buildchain architecture show --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture show [--cwd ] [--json]\n```\n\n### `buildchain architecture validate`\n\n- Help: `buildchain architecture validate --help`\n- Canonical id: `architecture`\n- Options: `--cwd`, `--json`\n- Syntax:\n\n```text\nbuildchain architecture validate [--cwd ] [--json]\n```\n\n## `audit`\n\n### `buildchain audit`\n\n- Help: `buildchain audit --help`\n- Canonical id: `audit`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain audit\n```\n\n### `buildchain audit github-governance`\n\n- Help: `buildchain audit github-governance --help`\n- Canonical id: `audit`\n- Options: `--allow-nonqualifying`, `--environment`, `--job`, `--json`, `--npm-trust-json`, `--organization`, `--output`, `--package`, `--provider-audit-json`, `--publisher-mode`, `--repository`, `--require-qualifying`, `--source-sha`, `--workflow`, `--workflow-ref`, `--workflow-repository`\n- Syntax:\n\n```text\nbuildchain audit github-governance [--organization ] [--repository ] [--output ] [--require-qualifying] [--json] [--source-sha ] [--workflow-repository ] [--workflow ] [--workflow-ref ] [--job ] [--environment ] [--package ] [--publisher-mode npm-trusted-publisher|github-token|oidc-role] [--npm-trust-json ] [--provider-audit-json ] [--output ] [--allow-nonqualifying]\n```\n\n### `buildchain audit publication-control-plane`\n\n- Help: `buildchain audit publication-control-plane --help`\n- Canonical id: `audit`\n- Options: `--branch`, `--repository`\n- Syntax:\n\n```text\nbuildchain audit publication-control-plane --repository --branch \n```\n\n## `badges`\n\n### `buildchain badges`\n\n- Help: `buildchain badges --help`\n- Canonical id: `badges`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain badges\n```\n\n### `buildchain badges bundle`\n\n- Help: `buildchain badges bundle --help`\n- Canonical id: `badges-bundle`\n- Options: `--check`, `--claims`, `--cwd`, `--json`, `--readme`, `--write`\n- Syntax:\n\n```text\nbuildchain badges bundle [--cwd ] [--readme ] [--claims ] [--check] [--write] [--json]\n```\n\n### `buildchain badges readme`\n\n- Help: `buildchain badges readme --help`\n- Canonical id: `badges-readme`\n- Options: `--check`, `--cwd`, `--json`, `--readme`, `--write`\n- Syntax:\n\n```text\nbuildchain badges readme [--cwd ] [--readme ] [--check] [--write] [--json]\n```\n\n## `build-contract`\n\n### `buildchain build-contract`\n\n- Help: `buildchain build-contract --help`\n- Canonical id: `build-contract`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain build-contract ...\n```\n\n## `candidate`\n\n### `buildchain candidate`\n\n- Help: `buildchain candidate --help`\n- Canonical id: `candidate`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain candidate\n```\n\n### `buildchain candidate timeline`\n\n- Help: `buildchain candidate timeline --help`\n- Canonical id: `candidate`\n- Options: `--input`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain candidate timeline --input [--output ] [--json]\n```\n\n## `collect`\n\n### `buildchain collect`\n\n- Help: `buildchain collect --help`\n- Canonical id: `collect`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain collect\n```\n\n### `buildchain collect github-release`\n\n- Help: `buildchain collect github-release --help`\n- Canonical id: `collect-github-release`\n- Options: `--anchor-manifest-json`, `--assets-dir`, `--assets-json`, `--base-passport-json`, `--build-facts-json`, `--build-summary-json`, `--dist-tag-evidence-json`, `--github-artifact-attestation-policy-json`, `--impact-json`, `--invariant-passport-cmd`, `--invariant-passport-json`, `--json`, `--kfd-1-witness-json`, `--kfd-2-claim-json`, `--kfd-3-artifact-verify-cmd`, `--kfd-3-artifact-witness-json`, `--kfd-3-prebuild-witness-json`, `--kfd-adopter-manifest-json`, `--kfd-agent-hub-evidence-json`, `--kfd-product-gate-json`, `--kfd-support-matrix-json`, `--output-dir`, `--package-set-json`, `--platform-manifest-json`, `--product-name`, `--publish-evidence-json`, `--publish-json`, `--release-evidence-json`, `--release-extra-json`, `--release-json`, `--repository`, `--require-base-kfd`, `--tag`, `--transaction-json`, `--trusted-publishing-json`\n- Syntax:\n\n```text\nbuildchain collect github-release --tag [--repository ] [--assets-dir ] [--assets-json ] [--release-json ] [--package-set-json ] [--product-name ] [--publish-evidence-json ] [--trusted-publishing-json ] [--transaction-json ] [--anchor-manifest-json ] [--impact-json ] [--build-summary-json ] [--build-facts-json ]... [--platform-manifest-json ]... [--dist-tag-evidence-json ] [--kfd-1-witness-json ]... [--kfd-2-claim-json ]... [--kfd-3-prebuild-witness-json ]... [--kfd-3-artifact-witness-json ]... [--kfd-3-artifact-verify-cmd ] [--kfd-adopter-manifest-json ] [--kfd-support-matrix-json ] [--kfd-product-gate-json ]... [--invariant-passport-json ]... [--invariant-passport-cmd ] [--release-evidence-json ]... [--github-artifact-attestation-policy-json ]... [--kfd-agent-hub-evidence-json ] [--base-passport-json ] [--require-base-kfd] [--release-extra-json ] [--publish-json ] [--output-dir ] [--json]\n```\n\n## `create`\n\n### `buildchain create`\n\n- Help: `buildchain create --help`\n- Canonical id: `create`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain create\n```\n\n### `buildchain create github-artifact-attestation-policy`\n\n- Help: `buildchain create github-artifact-attestation-policy --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create github-artifact-attestation-policy --input-json [--output ] [--json]\n```\n\n### `buildchain create publication-admission`\n\n- Help: `buildchain create publication-admission --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create publication-admission --input-json [--output ] [--json]\n```\n\n### `buildchain create runner-provenance`\n\n- Help: `buildchain create runner-provenance --help`\n- Canonical id: `create`\n- Options: `--input-json`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain create runner-provenance --input-json [--output ] [--json]\n```\n\n## `dev`\n\n### `buildchain dev`\n\n- Help: `buildchain dev --help`\n- Canonical id: `dev`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain dev\n```\n\n### `buildchain dev merge-queue`\n\n- Help: `buildchain dev merge-queue --help`\n- Canonical id: `dev`\n- Options: `--apply`, `--branch`, `--check-response-timeout-minutes`, `--cwd`, `--from-config`, `--max-entries-to-build`, `--repository`, `--workflow`\n- Syntax:\n\n```text\nbuildchain dev merge-queue --repository --branch [--from-config | --workflow ...] [--cwd ] [--check-response-timeout-minutes ] [--max-entries-to-build ] [--apply]\n```\n\n### `buildchain dev pr-admit`\n\n- Help: `buildchain dev pr-admit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--expected-head`, `--json`, `--output`, `--pull-request`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev pr-admit --repository --branch --pull-request --expected-head [--execute] [--output ] [--json]\n```\n\n### `buildchain dev proof classify`\n\n- Help: `buildchain dev proof classify --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof integration`\n\n- Help: `buildchain dev proof integration --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof replay`\n\n- Help: `buildchain dev proof replay --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof source`\n\n- Help: `buildchain dev proof source --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-integration`\n\n- Help: `buildchain dev proof verify-integration --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev proof verify-source`\n\n- Help: `buildchain dev proof verify-source --help`\n- Canonical id: `dev`\n- Options: `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain dev proof [--output ] [--json]\n```\n\n### `buildchain dev warrant cancel-queued`\n\n- Help: `buildchain dev warrant cancel-queued --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant close`\n\n- Help: `buildchain dev warrant close --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant heartbeat`\n\n- Help: `buildchain dev warrant heartbeat --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant observe`\n\n- Help: `buildchain dev warrant observe --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant recover`\n\n- Help: `buildchain dev warrant recover --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant select`\n\n- Help: `buildchain dev warrant select --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n### `buildchain dev warrant submit`\n\n- Help: `buildchain dev warrant submit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev warrant --repository --branch [--execute] [--output ] [--json]\n```\n\n## `diagnostics`\n\n### `buildchain diagnostics`\n\n- Help: `buildchain diagnostics --help`\n- Canonical id: `diagnostics`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain diagnostics\n```\n\n### `buildchain diagnostics summary`\n\n- Help: `buildchain diagnostics summary --help`\n- Canonical id: `diagnostics-summary`\n- Options: `--artifact`, `--json`, `--output`\n- Syntax:\n\n```text\nbuildchain diagnostics summary ... [--artifact ]... [--output ] [--json]\n```\n\n## `doctor`\n\n### `buildchain doctor`\n\n- Help: `buildchain doctor --help`\n- Canonical id: `doctor`\n- Options: `--cwd`, `--json`, `--require-publish-source-lock`\n- Syntax:\n\n```text\nbuildchain doctor [--cwd ] [--require-publish-source-lock] [--json]\n```\n\n## `explain`\n\n### `buildchain explain`\n\n- Help: `buildchain explain --help`\n- Canonical id: `explain`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain explain\n```\n\n### `buildchain explain artifact`\n\n- Help: `buildchain explain artifact --help`\n- Canonical id: `explain-artifact`\n- Options: `--for`, `--json`, `--npm-registry`, `--passport`\n- Syntax:\n\n```text\nbuildchain explain artifact [--passport ] [--npm-registry ] [--for human|agent] [--json]\n```\n\n### `buildchain explain release`\n\n- Help: `buildchain explain release --help`\n- Canonical id: `explain-release`\n- Options: `--for`, `--json`, `--passport`\n- Syntax:\n\n```text\nbuildchain explain release --passport [--for human|agent] [--json]\n```\n\n## `facts`\n\n### `buildchain facts`\n\n- Help: `buildchain facts --help`\n- Canonical id: `facts`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain facts\n```\n\n### `buildchain facts aggregate`\n\n- Help: `buildchain facts aggregate --help`\n- Canonical id: `build-facts`\n- Options: `--artifact`, `--cwd`, `--json`, `--module-fact`, `--output`, `--product`\n- Syntax:\n\n```text\nbuildchain facts aggregate [--cwd ] [--product ] [--module-fact ]... [--artifact ]... [--output ] [--json]\n```\n\n### `buildchain facts module`\n\n- Help: `buildchain facts module --help`\n- Canonical id: `build-facts`\n- Options: `--cwd`, `--json`, `--legacy-kungfu-buildinfo`, `--module`, `--module-root`, `--output`, `--output-path`, `--version-source`\n- Syntax:\n\n```text\nbuildchain facts module [--cwd ] [--module ] [--module-root ] [--version-source ] [--output ] [--output-path ]... [--legacy-kungfu-buildinfo ] [--json]\n```\n\n### `buildchain facts verify`\n\n- Help: `buildchain facts verify --help`\n- Canonical id: `build-facts`\n- Options: `--cwd`, `--fact`, `--json`\n- Syntax:\n\n```text\nbuildchain facts verify [--cwd ] --fact [--json]\n```\n\n## `github-governance`\n\n### `buildchain github-governance`\n\n- Help: `buildchain github-governance --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance\n```\n\n### `buildchain github-governance apply`\n\n- Help: `buildchain github-governance apply --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance ...\n```\n\n### `buildchain github-governance plan`\n\n- Help: `buildchain github-governance plan --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance ...\n```\n\n### `buildchain github-governance protection-policy-plan`\n\n- Help: `buildchain github-governance protection-policy-plan --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance ...\n```\n\n### `buildchain github-governance rollback`\n\n- Help: `buildchain github-governance rollback --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance ...\n```\n\n### `buildchain github-governance ruleset-policy-plan`\n\n- Help: `buildchain github-governance ruleset-policy-plan --help`\n- Canonical id: `github-governance`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain github-governance ...\n```\n\n## `help`\n\n### `buildchain help`\n\n- Help: `buildchain help --help`\n- Canonical id: `help`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain help\n```\n\n## `homebrew`\n\n### `buildchain homebrew`\n\n- Help: `buildchain homebrew --help`\n- Canonical id: `homebrew`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain homebrew\n```\n\n### `buildchain homebrew check`\n\n- Help: `buildchain homebrew check --help`\n- Canonical id: `homebrew-check`\n- Options: `--cwd`, `--json`, `--package`, `--release-passport`\n- Syntax:\n\n```text\nbuildchain homebrew check [--cwd ] [--package ] [--release-passport ] [--json]\n```\n\n### `buildchain homebrew update-formula`\n\n- Help: `buildchain homebrew update-formula --help`\n- Canonical id: `homebrew-update-formula`\n- Options: `--json`, `--package`, `--release-passport`, `--write`\n- Syntax:\n\n```text\nbuildchain homebrew update-formula --package --release-passport [--write] [--json]\n```\n\n## `infra-contract`\n\n### `buildchain infra-contract`\n\n- Help: `buildchain infra-contract --help`\n- Canonical id: `infra-contract`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain infra-contract ...\n```\n\n## `init`\n\n### `buildchain init`\n\n- Help: `buildchain init --help`\n- Canonical id: `init`\n- Options: `--artifact-name`, `--cwd`, `--force`, `--package-manager`, `--runner-preset`, `--type`\n- Syntax:\n\n```text\nbuildchain init [--cwd ] [--type package|native|web-surface|infra-contract|publication-artifact|anchored-package] [--force] [--package-manager pnpm|npm|yarn] [--runner-preset ] [--artifact-name ]\n```\n\n## `inspect`\n\n### `buildchain inspect`\n\n- Help: `buildchain inspect --help`\n- Canonical id: `inspect`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain inspect\n```\n\n### `buildchain inspect artifact`\n\n- Help: `buildchain inspect artifact --help`\n- Canonical id: `inspect-artifact`\n- Options: `--json`, `--npm-registry`, `--passport`\n- Syntax:\n\n```text\nbuildchain inspect artifact [--passport ] [--npm-registry ] [--json]\n```\n\n### `buildchain inspect release`\n\n- Help: `buildchain inspect release --help`\n- Canonical id: `inspect-release`\n- Options: `--json`, `--passport`\n- Syntax:\n\n```text\nbuildchain inspect release --passport [--json]\n```\n\n## `kfd`\n\n### `buildchain kfd`\n\n- Help: `buildchain kfd --help`\n- Canonical id: `kfd`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain kfd ...\n```\n\n### `buildchain kfd 1 gate`\n\n- Help: `buildchain kfd 1 gate --help`\n- Canonical id: `kfd-1-gate`\n- Options: `--artifact-root`, `--cwd`, `--json`, `--output`, `--witness-json`\n- Syntax:\n\n```text\nbuildchain kfd 1 gate --witness-json ... [--cwd ] [--artifact-root ] [--output ] [--json]\n```\n\n### `buildchain kfd 1 schema`\n\n- Help: `buildchain kfd 1 schema --help`\n- Canonical id: `kfd-1-schema`\n- Options: `--json`, `--schema`\n- Syntax:\n\n```text\nbuildchain kfd 1 schema [--schema ] [--json]\n```\n\n### `buildchain kfd 1 verify`\n\n- Help: `buildchain kfd 1 verify --help`\n- Canonical id: `kfd-1-verify`\n- Options: `--gate-json`, `--json`\n- Syntax:\n\n```text\nbuildchain kfd 1 verify --gate-json [--json]\n```\n\n### `buildchain kfd 1 witness`\n\n- Help: `buildchain kfd 1 witness --help`\n- Canonical id: `kfd-1-witness`\n- Options: `--cwd`, `--json`, `--output`, `--source-sha`\n- Syntax:\n\n```text\nbuildchain kfd 1 witness [--cwd ] [--source-sha ] [--output ] [--json]\n```\n\n### `buildchain kfd 2 claims`\n\n- Help: `buildchain kfd 2 claims --help`\n- Canonical id: `kfd-2-claims`\n- Options: `--cwd`, `--json`, `--output-dir`\n- Syntax:\n\n```text\nbuildchain kfd 2 claims [--cwd ] [--output-dir ] [--json]\n```\n\n### `buildchain kfd 2 product-claims check`\n\n- Help: `buildchain kfd 2 product-claims check --help`\n- Canonical id: `kfd-2-product-claims`\n- Options: `--channel`, `--cwd`, `--json`, `--output-dir`, `--registry`, `--source-sha`, `--tag`, `--version`\n- Syntax:\n\n```text\nbuildchain kfd 2 product-claims [--cwd ] [--registry ] [--output-dir ] [--version ] [--channel ] [--tag ] [--source-sha ] [--json]\n```\n\n### `buildchain kfd 2 product-claims render`\n\n- Help: `buildchain kfd 2 product-claims render --help`\n- Canonical id: `kfd-2-product-claims`\n- Options: `--channel`, `--cwd`, `--json`, `--output-dir`, `--registry`, `--source-sha`, `--tag`, `--version`\n- Syntax:\n\n```text\nbuildchain kfd 2 product-claims [--cwd ] [--registry ] [--output-dir ] [--version ] [--channel ] [--tag ] [--source-sha ] [--json]\n```\n\n### `buildchain kfd 2 product-claims write`\n\n- Help: `buildchain kfd 2 product-claims write --help`\n- Canonical id: `kfd-2-product-claims`\n- Options: `--channel`, `--cwd`, `--json`, `--output-dir`, `--registry`, `--source-sha`, `--tag`, `--version`\n- Syntax:\n\n```text\nbuildchain kfd 2 product-claims [--cwd ] [--registry ] [--output-dir ] [--version ] [--channel ] [--tag ] [--source-sha ] [--json]\n```\n\n### `buildchain kfd 2 schema`\n\n- Help: `buildchain kfd 2 schema --help`\n- Canonical id: `kfd-2-schema`\n- Options: `--json`, `--schema`\n- Syntax:\n\n```text\nbuildchain kfd 2 schema [--schema ] [--json]\n```\n\n### `buildchain kfd 2 taxonomy`\n\n- Help: `buildchain kfd 2 taxonomy --help`\n- Canonical id: `kfd-2-taxonomy`\n- Options: `--entry-json`, `--json`, `--kind`\n- Syntax:\n\n```text\nbuildchain kfd 2 taxonomy --entry-json ... [--kind residualRisk|downgradeReason] [--json]\n```\n\n### `buildchain kfd 2 trust-assessment`\n\n- Help: `buildchain kfd 2 trust-assessment --help`\n- Canonical id: `kfd-2-trust-assessment`\n- Options: `--assessment-json`, `--json`\n- Syntax:\n\n```text\nbuildchain kfd 2 trust-assessment [--assessment-json ] [--json]\n```\n\n### `buildchain kfd 2 trust-claims`\n\n- Help: `buildchain kfd 2 trust-claims --help`\n- Canonical id: `kfd-2-trust-claims`\n- Options: `--claims-json`, `--json`\n- Syntax:\n\n```text\nbuildchain kfd 2 trust-claims [--claims-json ] [--json]\n```\n\n### `buildchain kfd 3`\n\n- Help: `buildchain kfd 3 --help`\n- Canonical id: `kfd-3`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain kfd 3 ...\n```\n\n### `buildchain kfd 3 audit`\n\n- Help: `buildchain kfd 3 audit --help`\n- Canonical id: `kfd-3-audit`\n- Options: `--artifact`, `--cwd`, `--json`, `--registry`\n- Syntax:\n\n```text\nbuildchain kfd 3 audit [--cwd ] [--registry ] [--artifact ] [--json]\n```\n\n### `buildchain kfd 3 detect`\n\n- Help: `buildchain kfd 3 detect --help`\n- Canonical id: `kfd-3-detect`\n- Options: `--artifact`, `--cwd`, `--json`, `--kind`\n- Syntax:\n\n```text\nbuildchain kfd 3 detect [--cwd ] [--kind ]... [--artifact ] [--json]\n```\n\n### `buildchain kfd 3 query`\n\n- Help: `buildchain kfd 3 query --help`\n- Canonical id: `kfd-3-query`\n- Options: `--artifact`, `--cwd`, `--json`, `--passport`, `--registry`\n- Syntax:\n\n```text\nbuildchain kfd 3 query [] [--cwd ] [--registry ] [--passport ] [--artifact ] [--json]\n```\n\n### `buildchain kfd 3 register binary`\n\n- Help: `buildchain kfd 3 register binary --help`\n- Canonical id: `kfd-3-register`\n- Options: `--artifact`, `--cwd`, `--json`, `--product`, `--registry`\n- Syntax:\n\n```text\nbuildchain kfd 3 register [--cwd ] [--registry ] [--artifact ] [--product ] [--json]\n```\n\n### `buildchain kfd 3 register cli`\n\n- Help: `buildchain kfd 3 register cli --help`\n- Canonical id: `kfd-3-register`\n- Options: `--artifact`, `--cwd`, `--json`, `--product`, `--registry`\n- Syntax:\n\n```text\nbuildchain kfd 3 register [--cwd ] [--registry ] [--artifact ] [--product