@kungfu-tech/buildchain 2.2.1-alpha.0 → 2.2.1-alpha.1

package/README.md

@@ -1,282 +1,186 @@
-# Kungfu Buildchain
+# Buildchain
 
-Kungfu Buildchain is the v2 source of truth for Kungfu reusable GitHub
-workflows, the minimal Buildchain-native GitHub Actions surface, and release-line
-automation.
+Buildchain Release Passport is a mature product release record for artifacts
+that users or agents depend on.
 
-The repository does more than collect workflow files. Its main job is to make a
-Kungfu release auditable and repeatable: a protected branch merge should produce
-the right version commit, exact release tag, floating channel tag, and next
-alpha line without a maintainer hand-moving refs or repairing package metadata
-after the fact.
+Buildchain by Kungfu uses GitHub as the execution and trust substrate: protected
+refs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted
+Publishing, and machine-readable evidence. Its job is to turn release intent
+into an auditable product record, not to ask a repository to migrate away from
+its existing CI.
 
-## Why This Exists
+The same mechanism releases Buildchain itself.
 
-Kungfu release automation has to solve a few problems at the same time:
+## Install and Verify
 
-- consumers need stable refs such as `v2`, `v2.0`, and `v2.0-alpha`;
-- maintainers need exact immutable refs such as `v2.0.2` and
-  `v2.0.3-alpha.0` for audit and rollback;
-- package manifests must record the same version that the release tag
-  advertises;
-- alpha and release promotion must follow reviewed PRs, not local scripts or
-  manually edited tags;
-- the release toolchain itself must be released by the same governance model
-  that it applies to product repositories.
+For standalone use, install a platform archive from a GitHub Release and verify
+the release passport before trusting the binary:
 
-The older ABV model solved this by treating a GitHub release PR as the release
-intent. Buildchain v2 keeps that semantic contract, but implements it inside a
-modern monorepo with Node 24 actions, pnpm, tsup bundles, committed `dist`
-outputs, reusable workflow tests, package-manager adapters, and a TOML lifecycle
-protocol for non-Node projects.
+```bash
+# Example for Linux x64. Use the archive that matches your platform.
+curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain-x86_64-unknown-linux-gnu.tar.gz
+curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/buildchain.release.json
+curl -LO https://github.com/kungfu-systems/buildchain/releases/download/v2.2.1/artifact-evidence.json
+npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
+tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz
+./buildchain version
+```
 
-## Mental Model
+Release pages publish platform archives, checksums, release passport files, and
+a single evidence bundle:
+
+- `buildchain-x86_64-unknown-linux-gnu.tar.gz`
+- `buildchain-aarch64-apple-darwin.tar.gz`
+- `buildchain-x86_64-pc-windows-msvc.zip`
+- `checksums.txt`
+- `buildchain.release.json`
+- `artifact-evidence.json`
+- `product-mechanism.json`
+- `impact.json`
+- `agent-index.json`
+- `check-report.json`
+- `llms.txt`
+- `buildchain-release-bundle.tar.gz`
+- `buildchain-release-bundle.json`
+
+Loose top-level `buildchain` and `buildchain.exe` assets are intentionally not
+published. The executable lives inside each platform archive, which prevents
+Linux and macOS artifacts from overwriting each other in a merged release lane.
+
+For npm consumers:
 
-Buildchain release automation is branch-driven:
+```bash
+npm install -D @kungfu-tech/buildchain
+npx buildchain version
+npx buildchain doctor --json
+```
 
-| Merge path                              | Meaning                                                | Exact tag        | Floating tags and branches                      |
-| --------------------------------------- | ------------------------------------------------------ | ---------------- | ----------------------------------------------- |
-| `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`    |
-| `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`         |
-| `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`, `release/v(X+1)/v(X+1).0` |
+The npm package exposes the `buildchain` command and importable toolkit APIs:
 
-After a production release, Buildchain prepares the next alpha source commit for
-the same minor line and moves `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and
-`vX.Y-alpha` to that next prerelease state. This is why a release can leave the
-production channel at `v2.0.2` while the test channel is already at
-`v2.0.3-alpha.0`.
-
-Kungfu treats minor lines as long-running product trains. `v2.0`, `v2.1`, and
-future minor refs can each receive many patch releases such as `v2.0.1234`.
-`v2` points at the selected stable major line, while `v2.0` points at the
-latest production patch for that minor line.
-
-Buildchain opens a new minor line when it adds a new compatible welded surface:
-a reusable workflow contract, public CLI command family, published package
-subpath, evidence protocol, or installable binary distribution shape. The local
-decision log lives in [`docs/versioning.md`](docs/versioning.md).
-
-`publish-gate/major` replaces the old ABV `main` channel. It is deliberately
-not named `main` because it is not the active development trunk. Maintainers use
-the same PR flow as other channel promotions: merging
-`release/v2/v2.0 -> publish-gate/major` means "publish the next major line from
-this production state." The promotion then creates the next major production
-version, for example `v3.0.0`, and prepares `dev/v3/v3.0` plus
-`alpha/v3/v3.0` at `v3.0.1-alpha.0`. The older `major-gate` branch name is only
-a compatibility alias during migration.
-
-Exact tags are always v-prefixed. Use `v2.0.0` and `v2.0.1-alpha.0`; bare tags
-such as `1.0.0` are not maintained as Buildchain release entrypoints.
-
-## Repository Layout
-
-```text
-.github/workflows/        Repository checks, reusable workflows, and release promotion
-actions/                  GitHub Actions implementations, grouped by action
-fixtures/                 Safe fixture repositories or fixture descriptors
-packages/                 Shared libraries, added only when justified
-tests/                    Inventory and contract data used by checks
-docs/                     Governance, migration, architecture, and rollback notes
-scripts/                  Local verification scripts
+```js
+import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
+import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
 ```
 
-## Buildchain v2 Contract
-
-Buildchain v2 ships these active surfaces:
-
-- repository workflows under `.github/workflows`;
-- the public npm package `@kungfu-tech/buildchain` and `buildchain` CLI for
-  initializing and validating new repositories;
-- the active reusable build workflow `.github/workflows/.build.yml`;
-- exactly three GitHub Actions under `actions/<name>`:
-  `validate-config`, `run-lifecycle`, and `promote-buildchain-ref`;
-- action runtime on Node 24;
-- workspace package management with pnpm;
-- action bundling through tsup;
-- committed `dist/index.js` bundles for direct GitHub Actions consumption;
-- package-manager adapters for pnpm, npm, and yarn version-state updates;
-- `buildchain.toml` lifecycle configuration for custom version files and
-  verification commands;
-- `project.type = "web-surface"` configuration for site and app repositories
-  that need preview/staging/production deployment manifests and dry-run deploy
-  plans without package-release version semantics;
-- opt-in anchored/manual version strategy for packages whose version is pinned
-  to an explicit upstream release instead of derived from the Buildchain tag;
-- `actions/validate-config` migration preflight for TOML version-state and
-  lifecycle declarations without running heavyweight builds;
-- `.github/workflows/.build.yml` as the reusable build surface for
-  tri-platform runner presets, custom runner matrices, caller-provided lifecycle
-  commands, trusted event gating, artifact name templates, expected artifact
-  checks, optional digest-pinned Linux job containers, deterministic artifact
-  manifests, publish-gate source locks, resolved release manifests, and
-  aggregate build summaries;
-- `.github/workflows/.web-surface.yml` as the reusable site/app surface for PR
-  preview plans and optional apply, closed-PR preview cleanup apply, push-main
-  staging apply, and explicit production environment gates;
-- `actions/run-lifecycle` for callers that need the same lifecycle/manifest
-  contract inside their own workflows;
-- governance-closed self-promotion through `Buildchain Ref Promotion`.
-- `v2.2` release passport and binary distribution contracts for GitHub Release
-  assets, artifact evidence, impact ledgers, agent indexes, and standalone CLI
-  archives.
-
-Stable consumers should reference actions as:
+The package also ships `dist/site/` as the Buildchain-owned fact source for
+`buildchain.libkungfu.dev`.
 
-```yaml
-uses: kungfu-systems/buildchain/actions/<name>@v2
+## Use Buildchain
+
+Bootstrap a repository:
+
+```bash
+npx @kungfu-tech/buildchain init --type package --package-manager pnpm
+npx @kungfu-tech/buildchain validate --require-version-state
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2
 ```
 
-Documented reusable workflows should be referenced as:
+Buildchain supports package and non-package projects through `buildchain.toml`.
+Lifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom
+scripts, or any other command that can run in the repository checkout.
+
+Buildchain's active GitHub Action surface is deliberately small:
+
+- `actions/validate-config`
+- `actions/run-lifecycle`
+- `actions/promote-buildchain-ref`
+
+The active reusable workflow surfaces are:
+
+- `.github/workflows/.build.yml` for deterministic multi-platform build and
+  artifact contracts;
+- `.github/workflows/.web-surface.yml` for preview, staging, production, and
+  cleanup plans for site/app repositories;
+- `.github/workflows/buildchain-ref-promotion.yml` for protected release
+  promotion and version-state transactions;
+- `.github/workflows/binary-distribution.yml` for Buildchain's own release
+  passport proof case.
+
+Stable consumers should reference actions and workflows through floating major
+refs after reviewing the exact release passport:
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v2
+uses: kungfu-systems/buildchain/actions/validate-config@v2
 ```
 
-Repositories can also bootstrap local integration through the CLI:
-
-```bash
-npx @kungfu-tech/buildchain init --type package
-npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.0
-npx @kungfu-tech/buildchain npm dry-run --json
+```yaml
+uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
 ```
 
-Standalone `workflows` and `action-*` repositories are historical rollback
-anchors. Buildchain no longer ships migrated copies of legacy action
-repositories.
-
-Some hidden reusable workflow files from the old `workflows` repository still
-exist in this repository so they can be linted, audited, and made fail-closed
-while consumers migrate. They are not Buildchain-native release or publish
-surfaces unless this README or a dedicated document explicitly names them.
-Modern package, artifact, and publish integrations should use `.build.yml`,
-`buildchain.toml`, lifecycle commands, and publish transaction evidence instead
-of retired legacy action paths.
-
-## Release Governance
-
-Buildchain promotes its own release refs through
-`.github/workflows/buildchain-ref-promotion.yml` and
-`actions/promote-buildchain-ref`.
-
-The important constraints are:
-
-- non-dry-run promotion is not available from manual dispatch;
-- promotion must be backed by a protected same-repository PR channel path;
-- protected channel details must be readable and must enforce protection for
-  administrators;
-- alpha promotion must come from `dev/vX/vX.Y -> alpha/vX/vX.Y`;
-- release promotion must come from `alpha/vX/vX.Y -> release/vX/vX.Y`;
-- major promotion must come from `release/vX/vX.Y -> publish-gate/major`;
-- release promotion must match an existing same-patch alpha tag tree;
-- generated version-state commits must pass the configured verification command
-  before refs move;
-- `BUILDCHAIN_PROMOTION_TOKEN` is the release authority used to move protected
-  refs when repository policy requires it.
-
-Buildchain's top-level `Release - New Version` workflow is intentionally a
-no-op for this repository. Buildchain itself is promoted only by
-`Buildchain Ref Promotion` after `Verify` succeeds. The legacy hidden
-`.release-new-version.yml` file is not the modern publish surface; it remains a
-migration boundary for old consumers and must not be used for new Buildchain v2
-integrations.
-
-Buildchain's npm package is published by the same promotion transaction that
-creates exact v-prefixed release tags. Alpha releases such as
-`v2.0.13-alpha.0` publish to npm with dist-tag `alpha`; stable releases such as
-`v2.0.13` publish with dist-tag `latest`. Floating refs like `v2`, `v2.0`, and
-`v2.0-alpha` never publish npm packages. The old tag-push npm workflow is
-dry-run only; real npm publish happens before public release refs move, using
-the evidence contract in `lifecycle.publish`.
-
-For release-line planning, use the CLI dry-run:
+## Release Model
+
+Buildchain treats a reviewed branch merge as release intent:
+
+| Merge path | Meaning | Exact tag | Floating refs |
+| --- | --- | --- | --- |
+| `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` |
+| `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` |
+| `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 |
+
+Exact tags are immutable. Floating channel tags and branches are machine-updated
+by Buildchain and must remain writable by the release authority.
+
+After a production release, Buildchain prepares the next alpha source commit for
+the same minor line. That keeps production consumers pinned to the production
+passport while development can continue on the next testable patch.
+
+`publish-gate/major` is not an active development trunk. It is a reviewed
+promotion gate used when maintainers decide that the next production release
+should open a new major line.
+
+## Toolkit Observability
+
+Buildchain includes a logging toolkit for release and build steps:
 
 ```bash
-buildchain release --dry-run --target-ref release/v2/v2.0 --sha <verified-sha>
+buildchain mark --event native.configure --phase configure --component cmake
+buildchain span --event native.build --phase build -- cmake --build build
+buildchain log summary --json
+buildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4
 ```
 
-This prints the branch/tag/version-state/governance plan that a channel merge
-would trigger. It is intentionally separate from `buildchain npm dry-run`, which
-only checks package publish shape.
-
-## Documentation
-
-- [Documentation map](docs/MAP.md) routes common user, contributor, release,
-  workflow, and security questions to the right document.
-- [Contributing guide](CONTRIBUTING.md) explains local development, commit
-  rules, and pull request flow.
-- [Security policy](SECURITY.md) explains private vulnerability reporting.
-- [License policy](LICENSE-POLICY.md) explains Apache-2.0 and DCO contribution
-  terms.
-- [Release governance](docs/release-governance.md) explains the design problem,
-  old ABV compatibility, hard constraints, and operational guarantees.
-- [Release flow diagrams](docs/release-flow.md) gives the branch/tag state
-  machine and Mermaid diagrams.
-- [Migration inventory](docs/migration-inventory.md) lists migrated and retired
-  action repositories.
-- [Ownership rules](docs/ownership.md) defines source-of-truth and rollback
-  boundaries.
-- [promote-buildchain-ref](actions/promote-buildchain-ref/README.md) documents
-  the internal promotion action.
-- [Lifecycle protocol](docs/lifecycle-protocol.md) documents `buildchain.toml`
-  for custom version-state files and lifecycle commands.
-- [Reusable build surface](docs/reusable-build-surface.md) documents the build
-  workflow, local runner matrix, artifact contract, and libnode-shaped fixture.
-- [Web-surface deployments](docs/web-surface-deployments.md) documents the
-  preview/staging/production channel ontology, deployment manifest, adapter
-  contract, and dry-run cleanup/deploy plans.
-- [Buildchain CLI and npm package](docs/cli.md) documents the npm package,
-  command-line entrypoint, repository bootstrap flow, and release-only publish
-  gate.
+Every event records a timestamp. `span` records duration. The API form can be
+imported from repository scripts so heavy builds can mark phases from inside
+their own code.
+
+## Site Fact Source
+
+`@kungfu-tech/buildchain` publishes `dist/site/`:
+
+- `buildchain-site.json`
+- `site-manifest.json`
+- `cli-registry.json`
+- `workflow-registry.json`
+- `release-model.json`
+- `artifact-schemas.json`
+- `product-mechanism.json`
+- `release-provenance.json`
+- `agent-index.json`
+
+`buildchain.libkungfu.dev` should render from these package-owned facts, then
+layer presentation around them. The site should not hand-write Buildchain's
+current release mechanics.
 
 ## Local Verification
 
 ```bash
 corepack enable pnpm
 pnpm install --frozen-lockfile
+pnpm run generate:site
 pnpm run check
+npm pack --dry-run --json --registry=https://registry.npmjs.org/
 ```
 
-`pnpm run check` validates inventory data, lints all root workflows including
-hidden reusable workflows, and rebuilds every action bundle.
-
-## Lifecycle Configuration
-
-Projects can add `buildchain.toml` to declare release version state and
-lifecycle commands. Buildchain v2 supports TOML only. The promotion action uses
-configured version files to create source version commits, then runs
-`lifecycle.verify` before moving release refs. Repositories that publish
-external artifacts can also declare `lifecycle.publish`; with publish
-transactions enabled, Buildchain requires machine-readable evidence before exact
-release tags and floating channel refs move.
-
-Web-surface projects can also declare `project.type = "web-surface"` with
-preview, staging, and production channels. Those projects get deployment
-manifests and dry-run deploy/cleanup plans, but they are not forced into package
-version lines or anchored release semantics.
-
-## Safety Defaults
-
-- Lab workflows are manual by default.
-- Publishing is disabled unless explicitly enabled by a production release
-  workflow. Reusable builds expose `publish-channel`, `publish-allowed`, and
-  `publish-reason` so callers can gate publish jobs on a reviewed channel ref
-  instead of inferring publish eligibility from ad hoc branch checks.
-- Publish gate branches are resolved to a source SHA before checkout. Builds,
-  verification, artifact manifests, and summaries use that locked SHA; publish
-  jobs must re-check the branch tip before external side effects.
-- Publish transactions are keyed by repository, version, source SHA, and target
-  ref rather than run id. Reruns may resume missing artifacts, accept matching
-  existing artifacts, and fail closed on conflicting material until an explicit
-  repair override is used.
-- Fork pull requests must not reach secrets or self-hosted runners.
-- Candidate refs are expected to come from `kungfu-systems/*`.
-- Self-hosted runner validation is available only through the manual
-  `Self-hosted Runner Smoke` workflow.
-
 ## Read Next
 
+- [Install and verify](docs/install.md)
 - [Documentation map](docs/MAP.md)
+- [Product mechanism](docs/product-mechanism.md)
+- [Release Passport and binary distribution](docs/release-passport.md)
+- [Binary distribution details](docs/binary-distribution.md)
+- [Toolkit observability](docs/toolkit-observability.md)
+- [Site bundle contract](docs/site-bundle-contract.md)
 - [Lifecycle protocol](docs/lifecycle-protocol.md)
-- [Publish transaction](docs/publish-transaction.md)
 - [Reusable build surface](docs/reusable-build-surface.md)
+- [Publish transaction](docs/publish-transaction.md)
+- [Release governance](docs/release-governance.md)

package/dist/site/agent-index.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-site-agent-index",
+  "readOrder": [
+    "site-manifest.json",
+    "product-mechanism.json",
+    "release-model.json",
+    "cli-registry.json",
+    "workflow-registry.json",
+    "artifact-schemas.json"
+  ],
+  "instruction": "Use this bundle as the package-owned fact source for Buildchain pages. Do not infer current release mechanics from prose alone."
+}

package/dist/site/artifact-schemas.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-artifact-schema-index",
+  "releasePassport": [
+    "buildchain.release.json",
+    "artifact-evidence.json",
+    "product-mechanism.json",
+    "impact.json",
+    "agent-index.json",
+    "check-report.json",
+    "llms.txt",
+    "buildchain-release-bundle.json",
+    "buildchain-release-bundle.tar.gz"
+  ],
+  "site": [
+    "buildchain-site.json",
+    "site-manifest.json",
+    "cli-registry.json",
+    "workflow-registry.json",
+    "release-model.json",
+    "artifact-schemas.json",
+    "product-mechanism.json",
+    "release-provenance.json",
+    "agent-index.json"
+  ]
+}

package/dist/site/buildchain-site.json

@@ -0,0 +1,150 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-site-bundle",
+  "product": {
+    "name": "Buildchain",
+    "formalName": "Buildchain by Kungfu",
+    "category": "Buildchain Release Passport"
+  },
+  "package": {
+    "name": "@kungfu-tech/buildchain",
+    "versionSource": "package.json#version"
+  },
+  "sourceOfTruth": "npm package @kungfu-tech/buildchain/dist/site",
+  "humanFirst": true,
+  "agentFirst": true,
+  "entrypoints": [
+    "cli-registry.json",
+    "workflow-registry.json",
+    "release-model.json",
+    "artifact-schemas.json",
+    "product-mechanism.json",
+    "release-provenance.json",
+    "agent-index.json",
+    "site-manifest.json"
+  ],
+  "docs": [
+    {
+      "id": "install",
+      "title": "Install and verify Buildchain",
+      "path": "docs/install.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "release-passport",
+      "title": "Release Passport protocol",
+      "path": "docs/release-passport.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "binary-distribution",
+      "title": "Binary distribution contract",
+      "path": "docs/binary-distribution.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "toolkit-observability",
+      "title": "Toolkit observability",
+      "path": "docs/toolkit-observability.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "site-bundle-contract",
+      "title": "Site bundle contract",
+      "path": "docs/site-bundle-contract.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "product-mechanism",
+      "title": "Product mechanism",
+      "path": "docs/product-mechanism.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "cli",
+      "title": "CLI and npm package",
+      "path": "docs/cli.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "lifecycle-protocol",
+      "title": "Lifecycle protocol",
+      "path": "docs/lifecycle-protocol.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "reusable-build-surface",
+      "title": "Reusable build surface",
+      "path": "docs/reusable-build-surface.md",
+      "plane": "use",
+      "exists": true
+    },
+    {
+      "id": "publish-transaction",
+      "title": "Publish transaction",
+      "path": "docs/publish-transaction.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "release-governance",
+      "title": "Release governance",
+      "path": "docs/release-governance.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "release-flow",
+      "title": "Release flow",
+      "path": "docs/release-flow.md",
+      "plane": "verify",
+      "exists": true
+    },
+    {
+      "id": "versioning",
+      "title": "Versioning",
+      "path": "docs/versioning.md",
+      "plane": "why",
+      "exists": true
+    },
+    {
+      "id": "web-surface-deployments",
+      "title": "Web surface deployments",
+      "path": "docs/web-surface-deployments.md",
+      "plane": "use",
+      "exists": true
+    }
+  ],
+  "releaseModel": {
+    "schemaVersion": 1,
+    "contract": "kungfu-buildchain-release-model",
+    "exactTags": "v-prefixed exact tags are immutable release records.",
+    "floatingTags": "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
+    "channelBranches": [
+      "dev/vX/vX.Y",
+      "alpha/vX/vX.Y",
+      "release/vX/vX.Y",
+      "publish-gate/major"
+    ],
+    "releasePassport": {
+      "entrypoint": "buildchain.release.json",
+      "bundle": "buildchain-release-bundle.tar.gz",
+      "contract": "kungfu-buildchain-release-passport"
+    },
+    "npm": {
+      "package": "@kungfu-tech/buildchain",
+      "command": "./bin/buildchain.mjs",
+      "versionSource": "package.json#version",
+      "alphaDistTag": "alpha",
+      "stableDistTag": "latest"
+    }
+  }
+}