@kungfu-tech/buildchain 2.8.8-alpha.6 → 2.8.8-alpha.8

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "2.8.8-alpha.6",
+    "version": "2.8.8-alpha.8",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v2",
@@ -193,7 +193,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
+      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
     },
     {
       "contractVersion": 1,
@@ -242,7 +242,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
+      "auditDigest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
     },
     {
       "contractVersion": 1,
@@ -320,7 +320,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:0c6b309846916fd75424c98b812e7089ab5382d833836e81d213ac6d3305e7a2"
+      "auditDigest": "sha256:4455b13cfde44026cc52aad232259d1da861c4e021a8cbe3aa0bd3a19f6b79be"
     },
     {
       "contractVersion": 1,
@@ -342,9 +342,9 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:393f06ac60e0c71254df0bcecde1ed54c1d5f6ecb0a01e87f2d535cb2a90c52c"
+      "auditDigest": "sha256:c3372260cf4d74010c0fa60f69f0816b6ab0d9bf99add0339ce43612c8c827a1"
     }
   ],
   "compatibilityDigest": "sha256:36421b592a782decbfe31a7d8d42d70ce1100a56a2c4f4a0ccc21f0617dc72bf",
-  "contractDigest": "sha256:e7a1f147962d07f6c8242ce3863058ac71ec02c34f5d18da21bd261b9e5158ec"
+  "contractDigest": "sha256:995d2d9ac0cddd99d2eb2074a0faf2379f08f6a3f5556eb3c09184301d3bc9a7"
 }

package/dist/site/buildchain-site.json

@@ -1,6 +1,35 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
+  "generatedAt": "2026-07-07T08:53:22.870Z",
+  "publishedAt": "2026-07-07T08:53:22.870Z",
+  "reproducible": true,
+  "timestampPolicy": "ci-injected",
+  "deterministicInputs": [
+    "README.md",
+    "docs/*.md",
+    "actions/*/README.md",
+    "fixtures/*/README.md",
+    "packages/core/README.md",
+    "package.json#exports",
+    "tests/buildchain-inventory.json",
+    "sourceRevision",
+    "sourceDateEpoch",
+    "package content",
+    "declared Buildchain surface manifest contract"
+  ],
+  "sourceDateEpoch": "0",
+  "sourceRevision": "1b06c80878bbd05fcda92b43c9222b47f161fece",
+  "timestampPolicyDetails": {
+    "contract": "kungfu-buildchain-surface-timestamp-policy",
+    "timestampFields": [
+      "generatedAt",
+      "publishedAt"
+    ],
+    "timestampFieldsParticipateInArtifactDigest": true,
+    "artifactDigestScope": "npm package dist/site JSON files",
+    "note": "Human-readable timestamps are separate from reproducibility inputs; do not infer reproducibility from epoch timestamps."
+  },
   "product": {
     "name": "Buildchain",
     "formalName": "Buildchain by Kungfu",
@@ -8,6 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
+    "version": "2.8.8-alpha.8",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -874,7 +904,7 @@
       "route": "/docs/release-passport",
       "category": "manual",
       "sourcePath": "docs/release-passport.md",
-      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333",
+      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094",
       "headings": [
         {
           "level": 1,
@@ -922,7 +952,7 @@
           "anchor": "binary-distribution"
         }
       ],
-      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: exact tag, line, channel, source SHA, target ref, release SHA,\n  release material SHA, publish tooling SHA, and durable release-state ref.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.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/v2.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\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 executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
+      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: exact tag, line, channel, source SHA, target ref, release SHA,\n  release material SHA, publish tooling SHA, and durable release-state ref.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v2.2.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v2.2.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v2.2.0/state.json \\\n  --package-set-json package-set.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/v2.2.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd-2/release-claims.json \\\n  --output-dir .buildchain/release-passport\n```\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v2` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v2` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\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 executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
     },
     {
       "id": "manual:release-propagation",
@@ -1098,7 +1128,7 @@
       "route": "/docs/site-bundle-contract",
       "category": "manual",
       "sourcePath": "docs/site-bundle-contract.md",
-      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa",
+      "digest": "sha256:fa8bdf597ddf87d89629c133318d54f89c5f291d32427189fb3483bc81efc6b7",
       "headings": [
         {
           "level": 1,
@@ -1110,6 +1140,11 @@
           "title": "Files",
           "anchor": "files"
         },
+        {
+          "level": 2,
+          "title": "Timestamp and Reproducibility Policy",
+          "anchor": "timestamp-and-reproducibility-policy"
+        },
         {
           "level": 2,
           "title": "npm Consumption",
@@ -1131,7 +1166,7 @@
           "anchor": "rendering-boundary"
         }
       ],
-      "markdown": "# Site Bundle Contract\n\n`@kungfu-tech/buildchain` publishes `dist/site/` as the package-owned fact\nsource for `buildchain.libkungfu.dev` and other documentation surfaces.\n\nThe website may design navigation, visual hierarchy, examples, and explanatory\ncopy around these facts. It should not hand-write the current Buildchain\nrelease mechanics, command registry, workflow registry, or artifact schema.\n\n## Files\n\n```text\ndist/site/\n  buildchain-site.json\n  site-manifest.json\n  cli-registry.json\n  manual-registry.json\n  node-api-registry.json\n  workflow-registry.json\n  release-model.json\n  artifact-schemas.json\n  buildchain-contract.json\n  kfd-claims.json\n  product-mechanism.json\n  release-provenance.json\n  agent-index.json\n```\n\n`buildchain-site.json` is the top-level bundle entrypoint.\nIt includes a `homepage` object generated from `README.md`, including\n`homepage.sections`, `homepage.displayPlan`, and a\n`homepage.rendererContract` that is implementation metadata rather than\nordinary homepage copy. Site repositories should consume those fields instead\nof parsing `README.md` themselves.\nIt also includes a `pages` collection that mirrors `page-registry.json`, so a\nsite repository can build the full Buildchain public documentation surface from\nthe npm package without scanning the source checkout.\n`page-registry.json` is the complete page fact source: README homepage content,\nall packaged `docs/*.md` manuals, action README files, the Node API package\noverview, and fixture guides.\n`buildchain-contract.json` is the machine-readable Buildchain runtime contract\nworld used by floating-ref contract locks. It records public workflow/action/CLI\nsurfaces, compatibility digests, and audit digests for the files that implement\nthose surfaces.\n`manual-registry.json` enumerates the packaged Markdown manuals with source\ndigests so an agent can find complete operating documentation from the npm\nartifact. `node-api-registry.json` enumerates public Node import surfaces from\n`package.json#exports`, so agents do not have to infer supported APIs from\ninternal paths.\n`kfd-claims.json` is the Buildchain-owned KFD claim registry. It is generated\nfrom `packages/core/buildchain-kfd-claims.js` and enumerates the public release\nclaims plus the KFD-3 collaboration surfaces that Buildchain self-verifies\nduring release promotion.\n\n## npm Consumption\n\n```bash\nnpm install @kungfu-tech/buildchain\n```\n\nThen read files from:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/\n```\n\nPackage exports are also provided for direct JSON-aware consumers:\n\n```js\nimport siteManifest from \"@kungfu-tech/buildchain/site/site-manifest.json\" with { type: \"json\" };\n```\n\n## Generation\n\n```bash\npnpm run generate:site\npnpm run check:site\n```\n\n`check:site` fails when generated files are stale. `pnpm run check` includes\nthis gate, so release candidates cannot publish an out-of-date site bundle.\n\n## Scope\n\nThe P0 bundle includes:\n\n- README-derived homepage fields and display plan;\n- complete markdown page registry for public Buildchain docs, action manuals,\n  Node API overview, and fixtures;\n- site manifest;\n- CLI command registry;\n- manual registry for packaged agent-facing documentation;\n- Node API registry for public package exports;\n- workflow/action registry;\n- release model facts;\n- artifact and evidence schema index;\n- Buildchain runtime contract world for `@v2` floating-ref compatibility checks,\n  KFD-1/KFD-2/KFD-3 release gates, GitHub Release evidence publication, and\n  site-consumption contracts;\n- Buildchain KFD claim registry for release-passport self verification and\n  agent-first public claim discovery;\n- product mechanism manifest;\n- release provenance;\n- agent read order.\n\nFuture minor lines can add examples, recipes, fixture indexes, and richer\nschema metadata without breaking existing consumers.\n\n`release-propagation.md` describes the package-to-package or package-to-site\nrelease chain model. The site bundle exposes that document and the\n`release-propagation` CLI entry so downstream sites can render the current\nBuildchain-owned propagation contract instead of hand-writing it.\n\n## Rendering Boundary\n\nBuildchain owns the homepage wording, section ordering intent, complete\nmarkdown page registry, release model facts, workflow/action registry, CLI\nregistry, manual registry, Node API registry, KFD claim registry, and\nrelease-passport evidence vocabulary. The site owns HTML, CSS, responsive\nlayout, navigation, visual assets, decorative media, markdown-to-HTML rendering,\nand progressive disclosure within the Buildchain-provided\n`homepage.displayPlan` and page metadata.\n\nThe page registry is also part of Buildchain's KFD-3 collaboration-interface\nsurface. Releases declare it as a site-consumption contract, and Buildchain's\nKFD-3 witness generation includes the underlying markdown sources as public\ndocumentation surfaces. If a page is public enough for the site to render, it\nmust be declared and hash-bound in the package-owned site bundle."
+      "markdown": "# Site Bundle Contract\n\n`@kungfu-tech/buildchain` publishes `dist/site/` as the package-owned fact\nsource for `buildchain.libkungfu.dev` and other documentation surfaces.\n\nThe website may design navigation, visual hierarchy, examples, and explanatory\ncopy around these facts. It should not hand-write the current Buildchain\nrelease mechanics, command registry, workflow registry, or artifact schema.\n\n## Files\n\n```text\ndist/site/\n  buildchain-site.json\n  site-manifest.json\n  cli-registry.json\n  manual-registry.json\n  node-api-registry.json\n  workflow-registry.json\n  release-model.json\n  artifact-schemas.json\n  buildchain-contract.json\n  kfd-claims.json\n  product-mechanism.json\n  release-provenance.json\n  agent-index.json\n```\n\n`buildchain-site.json` is the top-level bundle entrypoint.\nIt includes a `homepage` object generated from `README.md`, including\n`homepage.sections`, `homepage.displayPlan`, and a\n`homepage.rendererContract` that is implementation metadata rather than\nordinary homepage copy. Site repositories should consume those fields instead\nof parsing `README.md` themselves.\nIt also includes a `pages` collection that mirrors `page-registry.json`, so a\nsite repository can build the full Buildchain public documentation surface from\nthe npm package without scanning the source checkout.\n`page-registry.json` is the complete page fact source: README homepage content,\nall packaged `docs/*.md` manuals, action README files, the Node API package\noverview, and fixture guides.\n`buildchain-contract.json` is the machine-readable Buildchain runtime contract\nworld used by floating-ref contract locks. It records public workflow/action/CLI\nsurfaces, compatibility digests, and audit digests for the files that implement\nthose surfaces.\n`manual-registry.json` enumerates the packaged Markdown manuals with source\ndigests so an agent can find complete operating documentation from the npm\nartifact. `node-api-registry.json` enumerates public Node import surfaces from\n`package.json#exports`, so agents do not have to infer supported APIs from\ninternal paths.\n`kfd-claims.json` is the Buildchain-owned KFD claim registry. It is generated\nfrom `packages/core/buildchain-kfd-claims.js` and enumerates the public release\nclaims plus the KFD-3 collaboration surfaces that Buildchain self-verifies\nduring release promotion.\n\n## Timestamp and Reproducibility Policy\n\nEvery Buildchain-owned surface manifest uses the same timestamp policy fields:\n\n- `generatedAt`: when the manifest JSON was generated.\n- `publishedAt`: when the surface was published, when known.\n- `reproducible`: whether the manifest declares its reproducibility inputs.\n- `timestampPolicy`: `ci-injected` for release/workflow-generated public\n  artifacts, or `source-date-epoch` for local deterministic source checks.\n- `deterministicInputs`: the source files, revisions, package metadata, and\n  declared Buildchain contracts that determine the manifest bytes.\n- `sourceDateEpoch` / `sourceRevision`: the deterministic time input or source\n  revision used to reproduce the manifest.\n- `timestampPolicyDetails.timestampFieldsParticipateInArtifactDigest`: whether\n  timestamp fields are included in the artifact digest being audited.\n\nThe policy is defined by `@kungfu-tech/buildchain/surface-manifest` and applies\nto the root site bundle, `site-manifest.json`, and web-surface deployment\nmanifests for named surfaces such as KFD, Buildchain, and Core. Site\nrepositories should render these fields; they should not invent their own\nmanifest time semantics.\n\nSource checkouts may use `SOURCE_DATE_EPOCH` for deterministic local checks.\nPublished CI/release artifacts should inject real timestamps with\n`BUILDCHAIN_SITE_GENERATED_AT` / `BUILDCHAIN_SITE_PUBLISHED_AT` or the matching\n`BUILDCHAIN_SURFACE_*` variables, so public manifests do not expose epoch time\nas if it were a real metadata time.\n\nVersion-state branches may already contain a generated manifest for the current\npackage version with `timestampPolicy: ci-injected`. In that case\n`generate-site-bundle.mjs --check` preserves the existing timestamp policy as\nthe deterministic input instead of rewriting public release metadata back to\nepoch time.\n\n## npm Consumption\n\n```bash\nnpm install @kungfu-tech/buildchain\n```\n\nThen read files from:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/\n```\n\nPackage exports are also provided for direct JSON-aware consumers:\n\n```js\nimport siteManifest from \"@kungfu-tech/buildchain/site/site-manifest.json\" with { type: \"json\" };\n```\n\n## Generation\n\n```bash\npnpm run generate:site\npnpm run check:site\n```\n\n`check:site` fails when generated files are stale. `pnpm run check` includes\nthis gate, so release candidates cannot publish an out-of-date site bundle.\n\n## Scope\n\nThe P0 bundle includes:\n\n- README-derived homepage fields and display plan;\n- complete markdown page registry for public Buildchain docs, action manuals,\n  Node API overview, and fixtures;\n- site manifest;\n- CLI command registry;\n- manual registry for packaged agent-facing documentation;\n- Node API registry for public package exports;\n- workflow/action registry;\n- release model facts;\n- artifact and evidence schema index;\n- Buildchain runtime contract world for `@v2` floating-ref compatibility checks,\n  KFD-1/KFD-2/KFD-3 release gates, GitHub Release evidence publication, and\n  site-consumption contracts;\n- Buildchain KFD claim registry for release-passport self verification and\n  agent-first public claim discovery;\n- product mechanism manifest;\n- release provenance;\n- agent read order.\n\nFuture minor lines can add examples, recipes, fixture indexes, and richer\nschema metadata without breaking existing consumers.\n\n`release-propagation.md` describes the package-to-package or package-to-site\nrelease chain model. The site bundle exposes that document and the\n`release-propagation` CLI entry so downstream sites can render the current\nBuildchain-owned propagation contract instead of hand-writing it.\n\n## Rendering Boundary\n\nBuildchain owns the homepage wording, section ordering intent, complete\nmarkdown page registry, release model facts, workflow/action registry, CLI\nregistry, manual registry, Node API registry, KFD claim registry, and\nrelease-passport evidence vocabulary. The site owns HTML, CSS, responsive\nlayout, navigation, visual assets, decorative media, markdown-to-HTML rendering,\nand progressive disclosure within the Buildchain-provided\n`homepage.displayPlan` and page metadata.\n\nThe page registry is also part of Buildchain's KFD-3 collaboration-interface\nsurface. Releases declare it as a site-consumption contract, and Buildchain's\nKFD-3 witness generation includes the underlying markdown sources as public\ndocumentation surfaces. If a page is public enough for the site to render, it\nmust be declared and hash-bound in the package-owned site bundle."
     },
     {
       "id": "manual:toolkit-observability",
@@ -1216,7 +1251,7 @@
       "route": "/docs/web-surface-deployments",
       "category": "manual",
       "sourcePath": "docs/web-surface-deployments.md",
-      "digest": "sha256:61891635707e9ed27b8754b83713db61cf9a7a6bdf65beb6a9ac8aa39356e168",
+      "digest": "sha256:5b374e65dc2740748205db597a7cd9779d71daa1b30ad46e542f95b093e56c98",
       "headings": [
         {
           "level": 1,
@@ -1279,7 +1314,7 @@
           "anchor": "boundaries"
         }
       ],
-      "markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- Production runs when `production-apply` is true and either:\n  - a trusted `workflow_dispatch` passes `production-approved=true`; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
+      "markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"reproducible\": true,\n  \"timestampPolicy\": \"ci-injected\",\n  \"deterministicInputs\": [\n    \"web-surface artifact content\",\n    \"buildchain.toml web-surface channels/deploy/surfaces\",\n    \"sourceSha\",\n    \"artifactHash\",\n    \"deployment channel\",\n    \"deployment alias\"\n  ],\n  \"sourceRevision\": \"...\",\n  \"timestampPolicyDetails\": {\n    \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n    \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n    \"timestampFieldsParticipateInArtifactDigest\": false,\n    \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n  },\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, and every adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nThe health check fetches every surface URL from the apply result and fails\nproduction if a response is unreachable, returns an unexpected status, or still\nsends `x-robots-tag: noindex`. It also verifies that each surface binding\nrecorded a deployment manifest pointer. The production release passport embeds\nthe deploy plan, apply result, production preflight, and health check so a\nreviewer or agent can audit why the production site changed and whether every\ndeclared host was actually covered.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v2`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v2/v2.3/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- Production runs when `production-apply` is true and either:\n  - a trusted `workflow_dispatch` passes `production-approved=true`; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: ${{ github.event_name == 'push' && github.ref_name == 'main' }}\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs or a production apply without `production-approved=true`\non manual dispatch fail immediately instead of spending the build and plan jobs\nfirst.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
     },
     {
       "id": "fixture:infra-contract-aws-cdk-shaped",
@@ -1595,7 +1630,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333"
+      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094"
     },
     {
       "id": "release-propagation",
@@ -1643,7 +1678,7 @@
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa"
+      "digest": "sha256:fa8bdf597ddf87d89629c133318d54f89c5f291d32427189fb3483bc81efc6b7"
     },
     {
       "id": "migration-inventory",
@@ -1739,7 +1774,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:61891635707e9ed27b8754b83713db61cf9a7a6bdf65beb6a9ac8aa39356e168"
+      "digest": "sha256:5b374e65dc2740748205db597a7cd9779d71daa1b30ad46e542f95b093e56c98"
     }
   ],
   "releaseModel": {

package/dist/site/kfd-claims.json

@@ -819,6 +819,18 @@
           "public": true,
           "packageExport": "./release-propagation"
         },
+        {
+          "id": "export:./surface-manifest",
+          "name": "@kungfu-tech/buildchain/surface-manifest",
+          "kind": "package-export",
+          "sourcePath": "packages/core/surface-manifest.js",
+          "evidencePath": "packages/core/surface-manifest.js",
+          "availability": "shipped",
+          "visibility": "public",
+          "participantFacing": true,
+          "public": true,
+          "packageExport": "./surface-manifest"
+        },
         {
           "id": "export:./buildchain-kfd-claims",
           "name": "@kungfu-tech/buildchain/buildchain-kfd-claims",
@@ -1057,6 +1069,6 @@
         "public": true
       }
     ],
-    "publicSurfaceCount": 80
+    "publicSurfaceCount": 81
   }
 }

package/dist/site/manual-registry.json

@@ -23,7 +23,7 @@
       "title": "Release Passport protocol",
       "path": "docs/release-passport.md",
       "plane": "verify",
-      "digest": "sha256:4d69798646adb84c6d193b1f32e7dc50e389db8932e63e9cb71489b6015e0333"
+      "digest": "sha256:56c9000305e9dc23993e6c401568c4063dd496c3586382a44cd44db108a95094"
     },
     {
       "id": "release-propagation",
@@ -65,7 +65,7 @@
       "title": "Site bundle contract",
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
-      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa"
+      "digest": "sha256:fa8bdf597ddf87d89629c133318d54f89c5f291d32427189fb3483bc81efc6b7"
     },
     {
       "id": "migration-inventory",
@@ -149,7 +149,7 @@
       "title": "Web surface deployments",
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
-      "digest": "sha256:61891635707e9ed27b8754b83713db61cf9a7a6bdf65beb6a9ac8aa39356e168"
+      "digest": "sha256:5b374e65dc2740748205db597a7cd9779d71daa1b30ad46e542f95b093e56c98"
     }
   ],
   "requiredAgentManuals": [

package/dist/site/node-api-registry.json

@@ -8,13 +8,13 @@
       "specifier": "@kungfu-tech/buildchain",
       "export": ".",
       "target": "./packages/core/index.js",
-      "digest": "sha256:cfbe85e8fcac0f1c525ed99d9d488898575d9ea21cc7855e454b55df49cd2e0e"
+      "digest": "sha256:5b77fefabfad124ae3a7a68651a1ff54e3c88e71ae542814ca69a927cd867d15"
     },
     {
       "specifier": "@kungfu-tech/buildchain/core",
       "export": "./core",
       "target": "./packages/core/index.js",
-      "digest": "sha256:cfbe85e8fcac0f1c525ed99d9d488898575d9ea21cc7855e454b55df49cd2e0e"
+      "digest": "sha256:5b77fefabfad124ae3a7a68651a1ff54e3c88e71ae542814ca69a927cd867d15"
     },
     {
       "specifier": "@kungfu-tech/buildchain/artifact-passport",
@@ -62,7 +62,7 @@
       "specifier": "@kungfu-tech/buildchain/release-passport",
       "export": "./release-passport",
       "target": "./packages/core/release-passport.js",
-      "digest": "sha256:3476a0837292b81a6efeb7c989dc1ee975b2bd8e8882273fd4eb5f865d330bc1"
+      "digest": "sha256:79520e72824eb0245446f516fe6abe9faab0ec247c6d6cec7ac5fd62ab1f48ee"
     },
     {
       "specifier": "@kungfu-tech/buildchain/release-propagation",
@@ -70,6 +70,12 @@
       "target": "./packages/core/release-propagation.js",
       "digest": "sha256:1960be557e57d738cb242ccf3df9ad41cdf156037648a7ab584905b6629f5840"
     },
+    {
+      "specifier": "@kungfu-tech/buildchain/surface-manifest",
+      "export": "./surface-manifest",
+      "target": "./packages/core/surface-manifest.js",
+      "digest": "sha256:66dbece7b671c69fb0bb69c7818cdedb480b81e627a275c232435ff1fa950351"
+    },
     {
       "specifier": "@kungfu-tech/buildchain/buildchain-kfd-claims",
       "export": "./buildchain-kfd-claims",
@@ -86,7 +92,7 @@
     {
       "id": "site-bundle-contract",
       "path": "docs/site-bundle-contract.md",
-      "digest": "sha256:1977091fc18b816208e7af50a177fd15e114498bfa49041573812405b46585aa"
+      "digest": "sha256:fa8bdf597ddf87d89629c133318d54f89c5f291d32427189fb3483bc81efc6b7"
     }
   ],
   "guidance": "These are the public Node import surfaces shipped by the npm package. Agents should prefer these exports over internal file paths."