{
"schemaVersion": 1,
"contract": "kungfu-buildchain-site-page-registry",
"package": "@kungfu-tech/buildchain",
"sourceOfTruth": "npm package @kungfu-tech/buildchain/dist/site/page-registry.json",
"rendererBoundary": {
"contentOwner": "Buildchain",
"rendererOwner": "site repository",
"rule": "Site repositories render these markdown pages and metadata; they do not maintain separate Buildchain product copy."
},
"pageCount": 93,
"categories": [
"action",
"api",
"fixture",
"manual",
"overview"
],
"capabilityGroups": [
"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:25c7c3276f3612a3180c0d3eb6663afb2d6395f007ab937bdccfad4cc76326c1",
"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": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-layered-architecture\ndoc_type: implementation-guide\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Buildchain 4.1 source, architecture registries and local validation.\n invisible_context_boundary: No unpublished release or external consumer qualification is claimed.\n---\n\n# Buildchain\n\nDevelopment: **4.1.0-alpha.0** on `dev/v4/v4.1`. This development version has\nnot been published. See [Code organization](docs/code-organization.md) for the\nworkflow → action → JavaScript/Rust implementation layers.\n\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/self-build-verify.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/self-release-promote.yml)\n[](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-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/governance/incident/report@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\nReusable workflows are the primary consumer API. The generated action registry\nindexes the capability/group/operation hierarchy and marks direct action contracts.\nThe direct consumer integration actions are:\n\n- `actions/build/lifecycle/validate`\n- `actions/build/lifecycle/run`\n- `actions/release/promotion/ref`\n- `actions/governance/incident/report`\n- `actions/release/tail/settle`\n- `actions/release/promotion/candidate`\n\nThree additional release-authority components are also registered and versioned:\n\n- `actions/build/artifact/prepare-attestation`\n- `actions/build/artifact/seal-attestation`\n- `actions/build/credential/macos-island`\n\nSeven shared build components have explicit ownership in\n`architecture/build-orchestration.json`:\n\n- [`actions/build/lifecycle/plan`](actions/build/lifecycle/plan/action.yml)\n- [`actions/build/lifecycle/prepare`](actions/build/lifecycle/prepare/action.yml)\n- [`actions/build/lifecycle/stage`](actions/build/lifecycle/stage/action.yml)\n- [`actions/build/artifact/transfer`](actions/build/artifact/transfer/action.yml)\n- [`actions/build/artifact/sign`](actions/build/artifact/sign/action.yml)\n- [`actions/build/artifact/attest`](actions/build/artifact/attest/action.yml)\n- [`actions/build/artifact/finalize`](actions/build/artifact/finalize/action.yml)\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/.build-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/.build-demo-adapter.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/public-build-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/public-release-promote.yml` for post-merge\n promote-only publication from a PR-stage release candidate, without a second\n heavy build;\n- `.github/workflows/public-release-web.yml` for preview, staging, production, and\n cleanup plans for site/app repositories;\n- `.github/workflows/self-release-promote.yml` for protected release\n promotion and version-state transactions;\n- `.github/workflows/self-build-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/build/lifecycle/validate@v4\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/public-release-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- [v4 declarative release-tail migration](docs/v4-declarative-release-tail-migration.md)\n- [Release governance](docs/release-governance.md)",
"slug": "home"
},
{
"id": "action:build/artifact/prepare-attestation",
"title": "Prepare a GitHub artifact attestation",
"route": "/actions/build/artifact/prepare-attestation",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/artifact/prepare-attestation/README.md",
"digest": "sha256:b3c567926ed486ad6c256c6e86827ec4d002030dbcf2dbe1700e0a9697b1314c",
"headings": [
{
"level": 1,
"title": "Prepare a GitHub artifact attestation",
"anchor": "prepare-a-github-artifact-attestation"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: github-artifact-attestation\ndoc_type: action-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Action metadata and attestation transaction source.\n invisible_context_boundary: No hosted publication qualification is claimed.\n---\n\n# Prepare a GitHub artifact attestation\n\nValidate the exact subject bytes, platform manifest, release Passport and signer policy before calling the external attestation action. The action runs on Node 24 and verifies the selected Buildchain runtime commit.\n\nSupply `runtime-sha`, `subject-path`, `platform-manifest-path`, `release-passport-path` and `policy-json`. The outputs include the verified subject digest, predicate path and `preparation-json` consumed by the sealing action.\n\nUse the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact input/output contract; [`seal-attestation`](../seal-attestation/README.md) verifies the provider result.",
"slug": "build/artifact/prepare-attestation"
},
{
"id": "action:build/artifact/seal-attestation",
"title": "Seal a GitHub artifact attestation",
"route": "/actions/build/artifact/seal-attestation",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/artifact/seal-attestation/README.md",
"digest": "sha256:a1fed088050b41480c3d074dcdf22da83fa3c3b5af168fea0402145db8400b9b",
"headings": [
{
"level": 1,
"title": "Seal a GitHub artifact attestation",
"anchor": "seal-a-github-artifact-attestation"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: github-artifact-attestation\ndoc_type: action-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Action metadata and attestation transaction source.\n invisible_context_boundary: No hosted publication qualification is claimed.\n---\n\n# Seal a GitHub artifact attestation\n\nVerify the external provider result against the preparation record and unchanged subject bytes, then retain the attestation bundle and rooted evidence. The action runs on Node 24 and rechecks the exact selected runtime commit.\n\nSupply `runtime-sha`, `preparation-json`, `bundle-path`, `attestation-id`, `attestation-url` and an explicit read `token`. The outputs identify the retained bundle digest and evidence root. Provider failure or subject drift prevents sealing.\n\nUse the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact contract; [`prepare-attestation`](../prepare-attestation/README.md) owns pre-provider validation.",
"slug": "build/artifact/seal-attestation"
},
{
"id": "action:build/credential/macos-island",
"title": "macOS Credential Island",
"route": "/actions/build/credential/macos-island",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/credential/macos-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.",
"slug": "build/credential/macos-island"
},
{
"id": "action:build/lifecycle/run",
"title": "run-lifecycle",
"route": "/actions/build/lifecycle/run",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/lifecycle/run/README.md",
"digest": "sha256:e9af3a6d3bca4650704228b950b36a9d8e72b323f3c9e427d21ac4a3de8792c8",
"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/build/lifecycle/run@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.",
"slug": "build/lifecycle/run"
},
{
"id": "action:build/lifecycle/validate",
"title": "validate-config",
"route": "/actions/build/lifecycle/validate",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/build/lifecycle/validate/README.md",
"digest": "sha256:14e58dd47b8b617512608e89fd1887b28ef2aa1a545ee89936710a78cfe8d2bd",
"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/build/lifecycle/validate@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.",
"slug": "build/lifecycle/validate"
},
{
"id": "action:governance/incident/report",
"title": "report-buildchain-issue",
"route": "/actions/governance/incident/report",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/governance/incident/report/README.md",
"digest": "sha256:1f5b90a11274f9e5e0bfa73192f007e5604d3c0d8425f7f2bff1088dcbf722ae",
"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/governance/incident/report@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/governance/incident/report@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.",
"slug": "governance/incident/report"
},
{
"id": "action:release/promotion/candidate",
"title": "v4 release-candidate promote action",
"route": "/actions/release/promotion/candidate",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/promotion/candidate/README.md",
"digest": "sha256:b50fc4f13ea9c680142df79c5ab984522cd85893f1ce12f1427e094569329746",
"headings": [
{
"level": 1,
"title": "v4 release-candidate promote action",
"anchor": "v4-release-candidate-promote-action"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: protected-publication-source\ndoc_type: reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-06\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-06\n visible_context: Publication adapter, regression tests, and public GitHub commit metadata.\n invisible_context_boundary: No credentials or private runtime state inspected.\n---\n\n# v4 release-candidate promote action\n\nThis internal action validates a sealed v4 publication qualification receipt, aggregates the Buildchain Release Passport, and executes the fixed four-capability Release Tail Provider Plane. It has no command or shell extension input and is invoked by the v4 branch of the reusable `release-candidate-promote` workflow.\n\nThe protected publication source must match the qualified candidate's exact\nGit tree. An exact commit is accepted directly; a final PR merge may also bind\nthrough identical ordered parents. For repositories requiring linear history,\n`squash-equivalent` requires a protected commit with one parent, a qualified\nmerge candidate with two parents, and the same first parent. GitHub must report\nthe exact PR as merged into the protected commit, and its head must equal the\ncandidate's second parent. Candidate qualification, workflow and repository\nprovenance, and artifact verification remain required before publication.",
"slug": "release/promotion/candidate"
},
{
"id": "action:release/promotion/ref",
"title": "Release promotion adapter",
"route": "/actions/release/promotion/ref",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/promotion/ref/README.md",
"digest": "sha256:5c7ffd4ac03bb13a17d34d453e2957963713f63d7c50b1dab67a69e06dcc26ca",
"headings": [
{
"level": 1,
"title": "Release promotion adapter",
"anchor": "release-promotion-adapter"
},
{
"level": 2,
"title": "Admitted promotion inputs",
"anchor": "admitted-promotion-inputs"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-release-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Current promotion adapters, public workflow and request contract.\n invisible_context_boundary: No external publication or consumer qualification is claimed.\n---\n\n# Release promotion adapter\n\nThe consumer API is\n[public-release-promote.yml](../../../../.github/workflows/public-release-promote.yml).\nIt admits one closed JSON request, qualifies exact source and runtime identities,\napplies the admitted publication plan, and settles provider evidence in separate\npermission boundaries. See the [request contract](../../../../docs/release-promotion-request.md).\n\nThis Node action binds GitHub Actions inputs and outputs to the promotion\ncoordinator. Its implementation lives in\n[packages/core/release/promote-ref](../../../../packages/core/release/promote-ref).\nThe entrypoint contains no business logic; `inputs.js`, `request.js`, `source-lock.js`,\n`outputs.js` and the internal capability modules own their respective operations.\n\nThe canonical channel graph is\n`dev/vX/vX.Y -> alpha/vX/vX.Y -> release/vX/vX.Y`, with\n`publish-gate/major` as the explicit major transition. An exact release tag,\nfloating channel and version-state commit are separate evidence coordinates.\nRetired branch aliases and publisher-selection inputs are not accepted.\n\nOrdinary GitHub Release publication uses the declarative provider adapter.\nComplete-transaction recovery first proves the retained transaction and exact\nprovider assets. A missing asset never permits replacement of an existing asset\nwith a different digest. The full existing asset set is checked before any upload.\n\nVersion-state discovery reads declared TOML settings and package-manager workspace\nmetadata, including nested action packages. Anchored/manual products retain their\nexplicit upstream anchor; semver/auto products prepare the next development version\nthrough the governed next-development transition.\n\nDry-run reports the exact intended effects and performs bounded read-only provider\nlookups. It does not authorize publication. Live publication requires the admitted\nsource lock, runtime identity, candidate evidence, provider policy and protected\nchannel transaction. See [release governance](../../../../docs/release-governance.md)\nand [provider-plane settlement](../../../../docs/release-tail-provider-plane.md).\n\nGenerated JavaScript and the Rust domain WASM are committed under `dist` and must\nmatch the source. Run `pnpm run build` and `pnpm run check` from the repository root.\nThe 4.1 development restructuring itself does not publish an alpha or move a floating tag.\n\n## Admitted promotion inputs\n\nThe workflow's apply node supplies these source-lock and candidate inputs to the\nadapter. This fragment documents the internal action ports; consumer callers use\nthe public request contract linked above.\n\n```yaml\nwith:\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 promote-only-release-candidate: \"true\"\n release-candidate-family-evidence-required: \"true\"\n publish-rematerialize-on-resume: true\n```\n\n`target-ref` remains the channel promotion target. Direct `alpha/*` or `release/*` channel refs\nare not publish source locks. A mismatched source SHA fails before any promotion or publish side effects begin.\nThe exact candidate Passport, family evidence and reconciliation workspace are\nvalidated before provider effects; rematerialization requires the sealed recovery contract.\n\nPassport evidence ports bind product-owned evidence to the resulting release:\n`release-passport-kfd-1-witness-jsons`, `release-passport-kfd-2-claim-jsons`,\n`release-passport-kfd-3-prebuild-witness-jsons`,\n`release-passport-kfd-adopter-manifest-json`,\n`release-passport-kfd-support-matrix-json`, and\n`release-passport-kfd-product-gate-jsons` carry the corresponding KFD evidence.\n`release-passport-evidence-jsons` carries additional evidence documents;\n`release-passport-invariant-passport-command` and\n`release-passport-attachment-command` identify the declared product-owned evidence\noperations. These ports do not replace consumer qualification or provider readback.",
"slug": "release/promotion/ref"
},
{
"id": "action:release/tail/settle",
"title": "Declarative Release Tail",
"route": "/actions/release/tail/settle",
"category": "action",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "actions/release/tail/settle/README.md",
"digest": "sha256:bdc41acd1ead3565f34427a7c996e97df8dcbb6132c4d35afc1e44e150620f71",
"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.\n\nWhen `rehearsal-capsule` is supplied, the same Action switches to the v4\nPublication Rehearsal Capsule boundary. `simulate` and `replay` remain\neffect-disabled. `provider` additionally requires exact capsule-bound\nrehearsal authority, consumes only the capsule-rooted data bindings, and\nrecords every request/readback while still emitting\n`productionAuthority: false` and no Release Passport. See\n[`docs/v4-publication-rehearsal.md`](../../docs/v4-publication-rehearsal.md).",
"slug": "release/tail/settle"
},
{
"id": "api:node-package",
"title": "Buildchain Core",
"route": "/api/node-package",
"category": "api",
"capabilityGroup": "api-cli-reference",
"audience": [
"developer",
"agent"
],
"maturity": "stable",
"sourcePath": "packages/core/README.md",
"digest": "sha256:11d963d9b8f241769d34e45b2fa04831c414fb8ee24e980633f0f1a15669f5b6",
"headings": [
{
"level": 1,
"title": "Buildchain Core",
"anchor": "buildchain-core"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-layered-architecture\ndoc_type: implementation-guide\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-10\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-10\n visible_context: Buildchain 4.1 source, architecture registries and local validation.\n invisible_context_boundary: No unpublished release or external consumer qualification is claimed.\n---\n\n# Buildchain Core\n\nCore contains JavaScript business logic and provider IO, grouped by the closed\ncapabilities in [`architecture/code-layout.json`](../../architecture/code-layout.json).\nSee [Code organization](../../docs/code-organization.md) for the complete layout.\n\nEach capability groups its business transactions, action adapters and supporting\nmodules by responsibility. Action adapters invoke named transaction APIs; they do\nnot dispatch old CLI steps. Command-line handlers live in `cli/`, and executable\ncapability tools in `commands/` delegate to the same core modules. The root `index.js` is the public API aggregation;\nimplementation modules import their actual owner directly.\n\nCore cannot depend on `actions`, `.github/workflows`, `bin`, or repository\n`scripts`. Rust-owned domain decisions are called through the existing WASM/host\nboundary and have no JavaScript fallback.\n\nUse the generated [Node API Reference](../../docs/node-api-reference.md) for\ncurrent package subpaths, symbols and signatures. For example:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI is the adapter for shells and non-JavaScript tools. Core modules can be\nused directly by JavaScript callers. Both paths share the same implementations.",
"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:17b0756d1cc1009144219748b31497a12ebd19e79218a7451b2632be19bc9ba8",
"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-09-11\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/.build-demo-adapter.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/public-build-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/public-build-demo.yml@v4\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/self-build-demo-dogfood.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- prepares the selected execution runtime and checks out the exact consumer source;\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/.build-demo-adapter.yml@v4\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:8d0594d546dff2a33d465ecbc6adc6a3a925d1cd6bed6875cf292f13eebb14b2",
"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 packages/core/providers/commands/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`packages/core/providers/commands/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`packages/core/providers/commands/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 `packages/core/providers/commands/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`packages/core/providers/commands/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:fe01140ac9ff62da7f9c077df538792a588eb1cb609f997eaf1ce56a7965a982",
"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`packages/core/release/commands/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 packages/core/publication/commands/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:bootstrap-recovery",
"title": "Consumer-owned bootstrap recovery",
"route": "/docs/bootstrap-recovery",
"category": "manual",
"capabilityGroup": "getting-started",
"audience": [
"agent"
],
"maturity": "stable",
"sourcePath": "docs/bootstrap-recovery.md",
"digest": "sha256:d8e6670ffd0c7a6c7b6a573dfe8aeaca2a14ef2ff4c9675dd3048b16330c097e",
"headings": [
{
"level": 1,
"title": "Consumer-owned bootstrap recovery",
"anchor": "consumer-owned-bootstrap-recovery"
}
],
"markdown": "---\nstatus: active\nperiod: ongoing\ntheme: bootstrap-recovery-distribution\ndoc_type: manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-09\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-09\n visible_context: Recovery workflows, node implementations, dependency closure generator and isolated consumer tests.\n invisible_context_boundary: No production recovery campaign or external consumer deployment was performed.\n---\n\n# Consumer-owned bootstrap recovery\n\nThe normal entry is `public-ops-bootstrap.yml`. Before depending on it, install\nboth recovery artifacts from the same reviewed Buildchain package into the\nconsumer repository:\n\n| Package source | Consumer destination |\n| --- | --- |\n| `templates/universal-buildchain-bootstrap-recovery.yml` | `.github/workflows/buildchain-bootstrap-recovery.yml` |\n| Contents of `templates/bootstrap-recovery/` | `.buildchain/bootstrap-recovery/` |\n\nCommit both artifacts together. The second directory contains three composite\nnodes, their complete JavaScript dependency closure, a runtime preparation\naction, package identity and a file digest manifest. It must be tracked even\nwhen the consumer otherwise ignores `.buildchain/`. Installing the workflow\nalone is incomplete. Do not substitute files from a different package version.\n\nThe recovery workflow checks out its own defining consumer commit and invokes\nthe prepositioned nodes. Request parsing, independent review and terminal\nreceipt verification start without npm dependencies or a published Buildchain\nworkflow. Candidate code and its dependencies run only after the consumer-owned\nreview boundary admits the exact candidate SHA. Provider execution uses the\nsame candidate engine as the primary route. A failure of GitHub itself remains\nan external availability boundary.\n\nThe recovery package is generated from the current `actions/workflow/`,\n`actions/runtime/` and `packages/core/` implementations. It contains no separate\nrecovery implementation. `pnpm run generate:workflows` regenerates it and its\nadmission roots; the normal repository check rejects distribution drift.\nTests copy only these artifacts into a clean temporary consumer and execute\nrequest admission without the Buildchain checkout or `node_modules`."
},
{
"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:2b7f6d3c8df25cd37fe8028690fc2d9cdce80de873341ef815f800c4ace880db",
"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": "V4 Adopter Delivery",
"anchor": "v4-adopter-delivery"
},
{
"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-09-06\nai_provenance:\n model_family: GPT-6\n product: Codex\n generated_at: 2026-09-06\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 runtime dependency and adds pnpm-backed paper scripts. With v4, build\n and verify callers use `@v4-alpha`; release callers select `@v4-alpha` for\n Alpha and `@v4` for stable releases. Both channel contract locks and their\n distinct resolved source coordinates are bound into provisioning authority.\n Verify callers grant the reusable Check workflow its required read permissions.\n Paper agent guidance resolves next-development scripts from the installed\n Buildchain package and links to the upstream transition ADR.\n Migration reads the other channel from its fetched Git tag. Installed-package\n operators can supply `--stable-buildchain-root` or `--alpha-buildchain-root`\n pointing to the corresponding exact source checkout instead.\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 runtime 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- Installed npm runtimes resolve their source from registry `gitHead`, or from\n the official exact version tag when that field is absent. Missing, malformed,\n duplicate, or unexpected tag results fail closed; floating tags are never\n used as the installed package's source identity.\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 `public-build-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 (`public-release-paper.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 `public-release-paper.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/release/promotion/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## V4 Adopter Delivery\n\n`buildchain adopter-delivery` exposes the public v4 driver gate, exact\nreadback, N-1 bootstrap lineage, and published archive loader. `run` emits a\nrooted non-authoritative readback, `verify` recomputes it, `bootstrap` binds the\nexact v3 authority and v4 base, and `archive` verifies public npm archive bytes\nand package identity. See [`v4-adopter-delivery.md`](v4-adopter-delivery.md).\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/self-release-promote.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 `public-release-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 packages/core/publication/commands/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/self-release-promote.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/self-release-npm-dry-run.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:f9bdeffb0751225c13bf249305c4bfb20d8ab52ca502d0e3d35370b3d2b1e47a",
"headings": [
{
"level": 1,
"title": "Buildchain CLI Reference",
"anchor": "buildchain-cli-reference"
},
{
"level": 2,
"title": "`adopter-delivery`",
"anchor": "adopter-delivery"
},
{
"level": 3,
"title": "`buildchain adopter-delivery`",
"anchor": "buildchain-adopter-delivery"
},
{
"level": 3,
"title": "`buildchain adopter-delivery run`",
"anchor": "buildchain-adopter-delivery-run"
},
{
"level": 3,
"title": "`buildchain adopter-delivery verify`",
"anchor": "buildchain-adopter-delivery-verify"
},
{
"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 authority admit-merge-group`",
"anchor": "buildchain-dev-authority-admit-merge-group"
},
{
"level": 3,
"title": "`buildchain dev authority complete-qualification`",
"anchor": "buildchain-dev-authority-complete-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority heartbeat-landing`",
"anchor": "buildchain-dev-authority-heartbeat-landing"
},
{
"level": 3,
"title": "`buildchain dev authority heartbeat-qualification`",
"anchor": "buildchain-dev-authority-heartbeat-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority lease-landing`",
"anchor": "buildchain-dev-authority-lease-landing"
},
{
"level": 3,
"title": "`buildchain dev authority lease-qualification`",
"anchor": "buildchain-dev-authority-lease-qualification"
},
{
"level": 3,
"title": "`buildchain dev authority migrate`",
"anchor": "buildchain-dev-authority-migrate"
},
{
"level": 3,
"title": "`buildchain dev authority observe`",
"anchor": "buildchain-dev-authority-observe"
},
{
"level": 3,
"title": "`buildchain dev authority recover`",
"anchor": "buildchain-dev-authority-recover"
},
{
"level": 3,
"title": "`buildchain dev authority settle`",
"anchor": "buildchain-dev-authority-settle"
},
{
"level": 3,
"title": "`buildchain dev authority submit`",
"anchor": "buildchain-dev-authority-submit"
},
{
"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 classify-native`",
"anchor": "buildchain-dev-proof-classify-native"
},
{
"level": 3,
"title": "`buildchain dev proof integration`",
"anchor": "buildchain-dev-proof-integration"
},
{
"level": 3,
"title": "`buildchain dev proof native`",
"anchor": "buildchain-dev-proof-native"
},
{
"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-native`",
"anchor": "buildchain-dev-proof-verify-native"
},
{
"level": 3,
"title": "`buildchain dev proof verify-native-reuse`",
"anchor": "buildchain-dev-proof-verify-native-reuse"
},
{
"level": 3,
"title": "`buildchain dev proof verify-source`",
"anchor": "buildchain-dev-proof-verify-source"
},
{
"level": 3,
"title": "`buildchain dev two-phase`",
"anchor": "buildchain-dev-two-phase"
},
{
"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 qualify`",
"anchor": "buildchain-dev-warrant-qualify"
},
{
"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 settle`",
"anchor": "buildchain-dev-warrant-settle"
},
{
"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 compatibility project`",
"anchor": "buildchain-facts-compatibility-project"
},
{
"level": 3,
"title": "`buildchain facts compatibility query`",
"anchor": "buildchain-facts-compatibility-query"
},
{
"level": 3,
"title": "`buildchain facts compatibility query-template`",
"anchor": "buildchain-facts-compatibility-query-template"
},
{
"level": 3,
"title": "`buildchain facts compatibility verify`",
"anchor": "buildchain-facts-compatibility-verify"
},
{
"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": "`next-development`",
"anchor": "next-development"
},
{
"level": 3,
"title": "`buildchain next-development`",
"anchor": "buildchain-next-development"
},
{
"level": 3,
"title": "`buildchain next-development materialize`",
"anchor": "buildchain-next-development-materialize"
},
{
"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 init`",
"anchor": "buildchain-release-tail-init"
},
{
"level": 3,
"title": "`buildchain release-tail plan`",
"anchor": "buildchain-release-tail-plan"
},
{
"level": 3,
"title": "`buildchain release-tail rehearse`",
"anchor": "buildchain-release-tail-rehearse"
},
{
"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": "`tail-reseal`",
"anchor": "tail-reseal"
},
{
"level": 3,
"title": "`buildchain tail-reseal`",
"anchor": "buildchain-tail-reseal"
},
{
"level": 3,
"title": "`buildchain tail-reseal admit`",
"anchor": "buildchain-tail-reseal-admit"
},
{
"level": 3,
"title": "`buildchain tail-reseal plan`",
"anchor": "buildchain-tail-reseal-plan"
},
{
"level": 3,
"title": "`buildchain tail-reseal seal`",
"anchor": "buildchain-tail-reseal-seal"
},
{
"level": 3,
"title": "`buildchain tail-reseal verify-platform`",
"anchor": "buildchain-tail-reseal-verify-platform"
},
{
"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## `adopter-delivery`\n\n### `buildchain adopter-delivery`\n\n- Help: `buildchain adopter-delivery --help`\n- Canonical id: `adopter-delivery`\n- Options: none declared\n- Syntax:\n\n```text\nbuildchain adopter-delivery\n```\n\n### `buildchain adopter-delivery run`\n\n- Help: `buildchain adopter-delivery run --help`\n- Canonical id: `adopter-delivery`\n- Options: `--input`, `--output`\n- Syntax:\n\n```text\nbuildchain adopter-delivery run --input [--output ]\n```\n\n### `buildchain adopter-delivery verify`\n\n- Help: `buildchain adopter-delivery verify --help`\n- Canonical id: `adopter-delivery`\n- Options: `--input`, `--output`, `--readback`\n- Syntax:\n\n```text\nbuildchain adopter-delivery verify --input --readback [--output ]\n```\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: `--adopter-delivery-json`, `--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 ] [--adopter-delivery-json ] [--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 authority admit-merge-group`\n\n- Help: `buildchain dev authority admit-merge-group --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority complete-qualification`\n\n- Help: `buildchain dev authority complete-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority heartbeat-landing`\n\n- Help: `buildchain dev authority heartbeat-landing --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority heartbeat-qualification`\n\n- Help: `buildchain dev authority heartbeat-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority lease-landing`\n\n- Help: `buildchain dev authority lease-landing --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority lease-qualification`\n\n- Help: `buildchain dev authority lease-qualification --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority migrate`\n\n- Help: `buildchain dev authority migrate --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority observe`\n\n- Help: `buildchain dev authority observe --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority recover`\n\n- Help: `buildchain dev authority recover --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority settle`\n\n- Help: `buildchain dev authority settle --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\n```\n\n### `buildchain dev authority submit`\n\n- Help: `buildchain dev authority submit --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--environment-root`, `--execute`, `--json`, `--output`, `--provider-attempt`, `--qualification-domains`, `--repository`\n- Syntax:\n\n```text\nbuildchain dev authority --repository --branch [--environment-root ] [--qualification-domains ] [--provider-attempt ] [--execute] [--output ] [--json]\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 classify-native`\n\n- Help: `buildchain dev proof classify-native --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 native`\n\n- Help: `buildchain dev proof native --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-native`\n\n- Help: `buildchain dev proof verify-native --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-native-reuse`\n\n- Help: `buildchain dev proof verify-native-reuse --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 two-phase`\n\n- Help: `buildchain dev two-phase --help`\n- Canonical id: `dev`\n- Options: `--branch`, `--expected-head`, `--json`, `--native-command`, `--native-proof`, `--output`, `--pull-request`, `--repository`, `--warrant-result`\n- Syntax:\n\n```text\nbuildchain dev two-phase --repository --branch --pull-request --expected-head --warrant-result --native-command [--native-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 qualify`\n\n- Help: `buildchain dev warrant qualify --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 settle`\n\n- Help: `buildchain dev warrant settle --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