@kungfu-tech/buildchain 2.10.4 → 2.10.5

package/dist/site/release-provenance.json

@@ -17,7 +17,8 @@
       "./diagnostics": "./packages/core/diagnostics.js",
       "./homebrew": "./packages/core/homebrew.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
-      "./kfd-3-surfaces": "./packages/core/kfd3-surface-register.js",
+      "./kfd": "./packages/core/kfd.js",
+      "./buildchain-layout": "./packages/core/buildchain-layout.js",
       "./release-line-bootstrap": "./packages/core/release-line-bootstrap.js",
       "./readme-badges": "./packages/core/readme-badges.js",
       "./public-surface-audit": "./packages/core/public-surface-audit.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-08T12:25:38.748Z",
-  "publishedAt": "2026-07-08T12:25:38.748Z",
+  "generatedAt": "2026-07-08T14:10:07.317Z",
+  "publishedAt": "2026-07-08T14:10:07.317Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "2c2936458d8b1d9af67f4421af00a647de6284bb",
+  "sourceRevision": "4d0eaca9c0b22f057a347838f2526b88355aa397",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.10.4",
+    "version": "2.10.5",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:67a0e6b63a943904eacbf7d26227e3c9ad650d17e8aa937c40b3fdad8f389fdd"
+      "digest": "sha256:b12caa887a325820c591d462ae2c0a4521eda001cb71d3def72e9b55924f892f"
     },
     {
       "id": "install",
@@ -61,7 +61,7 @@
       "path": "docs/install.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:34bc161a26595f95684694d341616e47bfd65b0c51a63225e68a575179636175"
+      "digest": "sha256:2600738a92b5853bc26d4e01211f0c07b8b36a21d4d72ca809bc6032dff5dc5f"
     },
     {
       "id": "release-passport",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:ca764740841b364ff7cfea79b87221d29c09df09fee6d19e78ed4b0b173bfad3"
+      "digest": "sha256:332f058d9a016cc31c709a3447a56dc43ffd0c5e6cdbcd15f9a62f61bb16eb15"
     },
     {
       "id": "release-candidate",
@@ -93,7 +93,7 @@
       "path": "docs/readme-badges.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:ddaf49a7d6e6c11aea8d21d1ba736159897e16207cd74af0044014425faf8a2c"
+      "digest": "sha256:d032ddd27db62bdb21031cbd0673d9ae61af0250c12522fe6106e7aff835fb21"
     },
     {
       "id": "homebrew",
@@ -173,7 +173,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:2f55874feb9acecce1c471b96e07bb9a198a8da93efd0f859d69f353bf9c36a8"
+      "digest": "sha256:b6bc32831d202d5c542d72f6e63322f632014751e7db00862b28fb9ce5318fd3"
     },
     {
       "id": "build-facts",
@@ -189,7 +189,7 @@
       "path": "docs/kfd-support.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:4bb33e408a2129e1534e92bea78d3cc0e4d8f986b0fbb27fe73ae6eae46b9ca3"
+      "digest": "sha256:704efbf7be24d641d8b119737eb33b3e98fea8c55cf434f7f475160809f4e3a4"
     },
     {
       "id": "lifecycle-protocol",
@@ -197,7 +197,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:c76516894cf540da9a6722ba96c475386901ab448ab71ede5850a185f6a716c9"
+      "digest": "sha256:191d706801abe5cea7927042b9cd7989f19cf868e726f8ac5852dff9490aa14f"
     },
     {
       "id": "reusable-build-surface",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a3f979fcede4450dabe5b8d6182395993c9f28559f7176b071a6ff9db565a355"
+      "digest": "sha256:5f56d66ad2798bc46acde3f8091c2e5ccee80412c1b26b70c8197ff9c7f6a406"
     },
     {
       "id": "publish-transaction",
@@ -213,7 +213,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:c3fc5c49180db9167e1cf5bc5ff403e5a21cb55d1ba750bd0cfcd2429ad825b2"
+      "digest": "sha256:2523dd9a81e837918afae30c203349a7b29f00fdf953962a6db360fd95e0c6cb"
     },
     {
       "id": "release-governance",
@@ -253,7 +253,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:58673b84879a219572fe39aa8b4d01cfc34fabf664b3318753d61043821edaff"
+      "digest": "sha256:8d60ee80b1d4af1faa092ff9d7170330b02361d1f479221f73c6dc021aac1e60"
     }
   ],
   "facts": [

package/dist/site/workflow-registry.json

@@ -259,6 +259,7 @@
         "buildchain-contract-lock-path",
         "buildchain-ref",
         "buildchain-repository",
+        "fail-on-release-pr-error",
         "node-version",
         "preview-apply",
         "preview-aws-role-arn",
@@ -273,6 +274,8 @@
         "production-release-head-prefix",
         "production-release-label",
         "production-release-on-main",
+        "production-release-pr-mode",
+        "production-release-pr-token",
         "release-feedback-actor-privacy",
         "staging-apply",
         "staging-aws-role-arn",
@@ -280,7 +283,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 28,
+      "inputCount": 31,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"

package/docs/MAP.md

@@ -38,10 +38,10 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 
 | Capability | Machine-readable entry | Manual entry |
 | --- | --- | --- |
-| Capability-grouped KFD-3 navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
+| Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |
 | KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |
 | KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |
-| KFD-3 surface registration and capability query | `buildchain.kfd3.json`, `dist/site/kfd-claims.json`, `buildchain.release.json` | [`kfd-support.md`](kfd-support.md) |
+| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3-surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
 | Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |

package/docs/cli.md

@@ -90,7 +90,7 @@ floating-ref contract world for a runtime such as `@v2`.
 
 ## Commands
 
-`buildchain init` writes a starter `buildchain.toml` and a reusable workflow
+`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow
 caller at `.github/workflows/build.yml`.
 
 Supported presets:
@@ -111,7 +111,7 @@ The native preset includes an opt-in `[diagnostics.native]` profile with common
 tool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and
 directory lists, or disable it if a repository does not need native diagnostics.
 
-`buildchain validate` parses `buildchain.toml`, checks configured version-state
+`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state
 files, and can require named lifecycle stages:
 
 ```bash
@@ -173,23 +173,57 @@ import {
 assertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));
 ```
 
-`buildchain kfd-3` is the product-facing registration and query entrypoint for
-KFD-3 surfaces. It is separate from Buildchain's self reverse audit: products
-can detect standard public surfaces, register the accepted boundary, audit the
+`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the
+machine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned
+subcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are
+first-class Buildchain surfaces. KFD-4 is schema-only until Buildchain has a
+real verification protocol for it.
+
+`status` reports implemented support and the active repo-owned file layout.
+`migrate-layout` moves legacy root files into `.buildchain/`:
+
+```bash
+buildchain kfd status --json
+buildchain kfd migrate-layout --write
+```
+
+KFD-1 commands generate and validate contract-world release evidence:
+
+```bash
+buildchain kfd 1 schema --json
+buildchain kfd 1 witness --json
+buildchain kfd 1 gate --witness-json kfd-1-witness.json --json
+buildchain kfd 1 verify --gate-json kfd-1-gate.json --json
+```
+
+KFD-2 commands validate trust taxonomy entries and generate Buildchain's public
+claim evidence:
+
+```bash
+buildchain kfd 2 schema --json
+buildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json
+buildchain kfd 2 claims --json
+```
+
+KFD-3 commands are separate from Buildchain's self reverse audit: products can
+detect standard public surfaces, register the accepted boundary, audit the
 current source or artifact tree, generate a release-passport-compatible witness,
 and expose a capability map for agents:
 
 ```bash
-buildchain kfd-3 detect --kind node-api --kind cli --json
-buildchain kfd-3 register node-api --product Buildchain
-buildchain kfd-3 audit --json
-buildchain kfd-3 witness --kind prebuild --output .buildchain/kfd-3/collaboration-interface.prebuild.json
-buildchain kfd-3 query buildchain --json
+buildchain kfd schema list --json
+buildchain kfd schema show kfd-3 --json
+buildchain kfd 3 detect --kind node-api --kind cli --json
+buildchain kfd 3 register node-api --product Buildchain
+buildchain kfd 3 audit --json
+buildchain kfd 3 witness --kind prebuild --output .buildchain/kfd-3/collaboration-interface.prebuild.json
+buildchain kfd 3 query buildchain --json
+buildchain kfd 4 schema --json
 ```
 
-The public Node API is exported from
-`@kungfu-tech/buildchain/kfd-3-surfaces`. See [`kfd-support.md`](kfd-support.md)
-for the detected / declared / enforced model and the agent query flow.
+The public Node API is exported from `@kungfu-tech/buildchain/kfd`. See
+[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model
+and the agent query flow.
 
 Lifecycle runs also write a Buildchain observability JSONL log at
 `.buildchain/logs/events.jsonl` by default. Framework events use
@@ -320,7 +354,7 @@ spend long stretches in low-concurrency compile, archive, link, or cache steps.
 buildchain doctor --json
 ```
 
-It validates `buildchain.toml`, package-manager detection, Git repository state,
+It validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,
 and the reusable workflow caller. For `version.strategy = "anchored"` with
 `version.next = "manual"`, it also embeds the anchored package release contract
 check: anchor manifest readability, configured version files, trusted

package/docs/install.md

@@ -87,7 +87,7 @@ npx @kungfu-tech/buildchain validate --require-version-state
 npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v2/v2.2
 ```
 
-Use `buildchain.toml` to declare lifecycle commands. The commands may use Node
+Use `.buildchain/buildchain.toml` to declare lifecycle commands. The commands may use Node
 package managers or non-Node tools such as pip, Conan, CMake, Make, or project
 scripts.
 

package/docs/kfd-support.md

@@ -9,7 +9,33 @@ facts, not as README prose. The machine-readable sources are:
   workflow, action, site, and documented command surfaces;
 - `buildchain.release.json` for release-specific KFD-1, KFD-2, and KFD-3
   passport results;
-- `buildchain.kfd3.json` for product-owned KFD-3 surface registration.
+- `.buildchain/buildchain.toml` for repository-owned Buildchain configuration;
+- `.buildchain/kfd/kfd-3-surfaces.json` for product-owned KFD-3 surface
+  registration;
+- `.buildchain/contract-lock.json` for accepted floating runtime contracts.
+
+Buildchain still reads the legacy root files `buildchain.toml`,
+`buildchain.contract-lock.json`, and `buildchain.kfd3.json` so existing
+consumers do not break, but new repositories should keep repo-owned Buildchain
+files under `.buildchain/`.
+
+## Unified Namespace
+
+KFD support is exposed through one first-class namespace:
+
+```bash
+buildchain kfd status --json
+buildchain kfd migrate-layout --write
+buildchain kfd schema list --json
+buildchain kfd 1 witness --json
+buildchain kfd 2 claims --json
+buildchain kfd 3 query buildchain --json
+buildchain kfd 4 schema --json
+```
+
+KFD-1, KFD-2, and KFD-3 have concrete Buildchain workflows. KFD-4 is currently
+schema-only in Buildchain: agents can discover and read the KFD-4 schema from
+`@kungfu-tech/kfd`, but Buildchain does not claim KFD-4 verification.
 
 ## KFD-1
 
@@ -22,6 +48,15 @@ For Buildchain itself, the source registry lives in
 `dist/site/kfd-claims.json`. Release promotion binds that registry to exact
 source and artifact hashes in the release passport.
 
+Buildchain exposes KFD-1 through:
+
+```bash
+buildchain kfd 1 schema --json
+buildchain kfd 1 witness --json
+buildchain kfd 1 gate --witness-json kfd-1-witness.json --json
+buildchain kfd 1 verify --gate-json kfd-1-gate.json --json
+```
+
 ## KFD-2
 
 KFD-2 requires public trust claims to be backed by machine-readable evidence.
@@ -38,6 +73,14 @@ Every public claim binds:
 - responsibility state;
 - residual risk.
 
+Buildchain exposes KFD-2 through:
+
+```bash
+buildchain kfd 2 schema --json
+buildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json
+buildchain kfd 2 claims --json
+```
+
 ## KFD-3
 
 KFD-3 closes participant-facing collaboration surfaces over a declared public
@@ -60,7 +103,7 @@ KFD-3 surface registration uses three states.
 | State | Meaning |
 | --- | --- |
 | `detected` | Buildchain found a candidate public surface from package metadata, wheel metadata, CLI bins, binary artifacts, docs, or site bundle facts. |
-| `declared` | The product owner accepted that candidate into `buildchain.kfd3.json`. |
+| `declared` | The product owner accepted that candidate into `.buildchain/kfd/kfd-3-surfaces.json`. |
 | `enforced` | The product has promoted a declared surface to a hard release boundary. Missing enforced surfaces fail release verification. |
 
 Detection does not silently become product intent. `register` is the boundary
@@ -68,31 +111,39 @@ decision. Existing consumers are unaffected until they opt in.
 
 ## CLI
 
+Inspect KFD-owned schema facts:
+
+```bash
+buildchain kfd schema list --json
+buildchain kfd schema show kfd-1 --json
+buildchain kfd 4 schema --json
+```
+
 Detect public surface candidates:
 
 ```bash
-buildchain kfd-3 detect --json
-buildchain kfd-3 detect --kind node-api --kind cli --json
+buildchain kfd 3 detect --json
+buildchain kfd 3 detect --kind node-api --kind cli --json
 ```
 
 Register standard surface classes:
 
 ```bash
-buildchain kfd-3 register node-api --product Buildchain
-buildchain kfd-3 register cli
-buildchain kfd-3 register python-api --artifact dist/wheel-unpacked
+buildchain kfd 3 register node-api --product Buildchain
+buildchain kfd 3 register cli
+buildchain kfd 3 register python-api --artifact dist/wheel-unpacked
 ```
 
 Audit detected, declared, and enforced surfaces:
 
 ```bash
-buildchain kfd-3 audit --json
+buildchain kfd 3 audit --json
 ```
 
 Generate a witness for release passport collection:
 
 ```bash
-buildchain kfd-3 witness \
+buildchain kfd 3 witness \
   --kind prebuild \
   --output .buildchain/kfd-3/collaboration-interface.prebuild.json
 ```
@@ -100,8 +151,8 @@ buildchain kfd-3 witness \
 Query capability facts for agents or downstream sites:
 
 ```bash
-buildchain kfd-3 query buildchain --json
-buildchain kfd-3 query --passport buildchain.release.json --json
+buildchain kfd 3 query buildchain --json
+buildchain kfd 3 query --passport .buildchain/release-passport/buildchain.release.json --json
 ```
 
 ## Node API
@@ -110,16 +161,20 @@ The CLI is a thin wrapper over the public Node API:
 
 ```js
 import {
-  auditKfd3Surfaces,
-  createKfd3SurfaceWitness,
-  detectKfd3Surfaces,
-  queryKfd3Capabilities,
-  registerKfd3Surfaces,
-} from "@kungfu-tech/buildchain/kfd-3-surfaces";
+  kfd1,
+  kfd2,
+  kfd3,
+  kfd4,
+  collectKfdStatus,
+  listKfdSchemas,
+  readKfdSchema,
+} from "@kungfu-tech/buildchain/kfd";
 ```
 
-Agents should prefer `queryKfd3Capabilities()` when deciding whether a product
-capability is usable. The query result connects each capability to:
+Agents should start with `collectKfdStatus()` to learn which standards are
+implemented and where the repository-owned Buildchain files live. For capability
+use decisions, prefer `kfd3.queryCapabilities()`. The query result connects each
+capability to:
 
 - KFD-3 surface identity and state;
 - KFD-1 basis facts such as source and artifact paths or digests;
@@ -146,9 +201,13 @@ the registry over time, but the first boundary is metadata-based.
 
 Buildchain dogfoods this model in two ways:
 
+- `buildchain kfd 1 witness --json` generates Buildchain's own KFD-1 contract
+  world witness;
+- `buildchain kfd 2 claims --json` generates Buildchain's own KFD-2 public
+  claim evidence;
 - `dist/site/kfd-claims.json` declares Buildchain's own KFD-3 collaboration
-  surface;
-- `buildchain kfd-3 query buildchain --json` resolves the packaged
+  interface;
+- `buildchain kfd 3 query buildchain --json` resolves the packaged
   Buildchain capability map from that site fact source.
 
 This lets downstream agents discover Buildchain's supported CLI, Node API,

package/docs/lifecycle-protocol.md

@@ -1,10 +1,15 @@
 # Lifecycle Protocol
 
-Buildchain uses `buildchain.toml` as the v2 repository configuration format.
+Buildchain uses `.buildchain/buildchain.toml` as the v2 repository configuration format.
 The file is optional for simple JavaScript repositories, but it is the preferred
 way to describe release version state and lifecycle commands when a project is
 not a plain pnpm, npm, or yarn workspace.
 
+For compatibility, Buildchain still reads a legacy root `buildchain.toml` when
+`.buildchain/buildchain.toml` is absent. New repositories should use the
+`.buildchain/` layout so all Buildchain-owned local state lives under one
+directory.
+
 Only TOML is supported in v2. YAML, JSON, and JavaScript config files are not
 loaded.
 
@@ -278,7 +283,7 @@ it overrides `lifecycle.verify` for that invocation.
 
 Heavy repositories can validate their Buildchain declaration before they are
 ready to run the real build. `actions/validate-config` checks that
-`buildchain.toml` parses, configured version-state files exist, configured
+`.buildchain/buildchain.toml` parses, configured version-state files exist, configured
 version keys are strings, and required lifecycle stage names are declared.
 For web-surface repositories it also validates `project`, `channels`, `deploy`,
 `retention`, and `security` declarations.

package/docs/publish-transaction.md

@@ -70,7 +70,7 @@ of reusing or overwriting that failed transaction slot.
 
 ## Lifecycle
 
-Repositories declare publish work in `buildchain.toml`:
+Repositories declare publish work in `.buildchain/buildchain.toml`:
 
 ```toml
 [publish]

package/docs/readme-badges.md

@@ -2,7 +2,7 @@
 
 Buildchain can generate a managed README badge block from repository-owned
 facts. The README keeps only a projection; the source facts remain in
-`buildchain.toml`, package metadata, workflow files, KFD standards metadata,
+`.buildchain/buildchain.toml`, package metadata, workflow files, KFD standards metadata,
 and the repository's own release passport.
 
 The managed block is delimited by:
@@ -107,7 +107,7 @@ so badge drift is detected like any other generated release-facing surface.
 
 ## Configuration
 
-The optional `[badges]` table in `buildchain.toml` declares local facts that
+The optional `[badges]` table in `.buildchain/buildchain.toml` declares local facts that
 cannot be inferred safely:
 
 ```toml

package/docs/release-passport.md

@@ -336,7 +336,7 @@ instead of trusting docs or release notes.
 
 KFD-1 protects release payload surfaces. Floating ref contract locks protect the
 consumer's relationship to Buildchain itself. A consumer can keep
-`buildchain.contract-lock.json` with the Buildchain floating ref it accepted,
+`.buildchain/contract-lock.json` with the Buildchain floating ref it accepted,
 the resolved SHA, the contract digest, and the compatibility policy. Each
 Buildchain run reads the actual contract from the checked-out Buildchain ref
 and compares it before heavy build or publish work begins.

package/docs/reusable-build-surface.md

@@ -169,7 +169,7 @@ workflow path or a temporary explicit workflow ref.
 Stable consumers should use floating major refs such as `@v2`, but a floating
 ref is not blind trust. Each released Buildchain ref carries a package-owned
 runtime contract world in `dist/site/buildchain-contract.json`. Consumers may
-keep a small lock file, `buildchain.contract-lock.json`, recording the
+keep a small lock file, `.buildchain/contract-lock.json`, recording the
 Buildchain ref, resolved SHA, contract digest, compatibility digest, accepted
 major line, and compatibility policy they reviewed.
 
@@ -178,7 +178,7 @@ The reusable build trust gate checks this lock before any heavy matrix job:
 1. resolve the Buildchain runtime ref, for example `v2`, to an immutable SHA;
 2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain
    ref;
-3. read the consumer's `buildchain.contract-lock.json`;
+3. read the consumer's `.buildchain/contract-lock.json`;
 4. compare the accepted contract with the current contract.
 
 SHA drift alone is not a failure. `v2` is expected to advance. Buildchain only
@@ -197,7 +197,7 @@ jobs:
       issues: write
       id-token: write
     with:
-      buildchain-contract-lock-path: buildchain.contract-lock.json
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
       buildchain-contract-compatibility-policy: major-compatible
       buildchain-contract-drift-issue-mode: compatible-and-breaking
 ```
@@ -252,7 +252,7 @@ repository or organization variables named
 private LAN topology out of repository YAML.
 
 Do not read cache URLs or reference paths from PR-controlled files such as
-`buildchain.toml`. These values are trusted workflow inputs or repo/org
+`.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org
 variables. Buildchain does not pass GitHub credentials to cache mirrors or
 reference repositories. If it must fall back to GitHub, the workflow token is
 used only for the GitHub fetch path.
@@ -598,7 +598,7 @@ jobs:
       publish-package-set-order: platforms-first-main-last
       publish-package-main: "@kungfu-tech/libnode"
       release-passport-product-name: Libnode
-      buildchain-contract-lock-path: buildchain.contract-lock.json
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
       buildchain-contract-drift-issue-mode: compatible-and-breaking
 ```
 
@@ -705,7 +705,7 @@ package before all platform artifacts for the same source SHA are available.
 
 ## Command Sources
 
-The workflow runs `buildchain.toml` lifecycle stages by default:
+The workflow runs `.buildchain/buildchain.toml` lifecycle stages by default:
 
 ```toml
 [lifecycle.install]
@@ -870,7 +870,7 @@ the publish gate: pull requests remain non-publishing events.
 `fixtures/libnode-shaped` is the contract fixture. It has:
 
 - `package.json` version state;
-- `buildchain.toml` with `install`, `build`, `verify`, and `publish`;
+- `.buildchain/buildchain.toml` with `install`, `build`, `verify`, and `publish`;
 - cross-platform Node scripts that create small `dist/` outputs;
 - `Build Surface Fixture` workflow coverage.
 

package/docs/web-surface-deployments.md

@@ -22,7 +22,7 @@ This keeps the evidence chain clear:
 
 ## Configuration
 
-`buildchain.toml` is the source of truth. Web-surface projects must declare
+`.buildchain/buildchain.toml` is the source of truth. Web-surface projects must declare
 preview, staging, and production channels plus a deploy adapter for each.
 
 ```toml
@@ -165,14 +165,14 @@ jobs:
   web:
     uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v2
     with:
-      buildchain-contract-lock-path: buildchain.contract-lock.json
+      buildchain-contract-lock-path: .buildchain/contract-lock.json
       buildchain-contract-compatibility-policy: major-compatible
       buildchain-contract-drift-issue-mode: compatible-and-breaking
       build-command: pnpm build
       artifact-path: dist
 ```
 
-The caller repository commits `buildchain.contract-lock.json` after reviewing an
+The caller repository commits `.buildchain/contract-lock.json` after reviewing an
 accepted Buildchain runtime SHA and contract digest. The reusable workflow then
 resolves the floating runtime to an immutable SHA, checks the lock before the
 caller build command, and applies these rules:
@@ -657,6 +657,14 @@ When enabled, Buildchain owns the full release apply state machine:
   release-intent commit, carries `production-release-label`, and includes the
   staging URLs, source SHA, artifact hash, and staging release-passport artifact
   link in the PR body.
+- Production release PR handoff is permission-aware. Staging apply and staging
+  health remain successful even when the repository or organization has
+  GitHub Actions workflow permissions set to read-only. In that case Buildchain
+  records `release-pr-status=permission-denied`, uploads the release PR handoff
+  summary/body plus staging release passport artifacts, and writes an exact
+  manual `gh pr create` command to the step summary. Set
+  `fail-on-release-pr-error=true` only when PR creation failure should fail the
+  whole workflow.
 - Release pull requests that match the configured production gate get a
   Buildchain review comment with the staging URL and production target, so the
   operator can verify staging from the PR page and use merge as the approval
@@ -702,10 +710,29 @@ jobs:
       production-release-label: buildchain-release
       production-release-head-prefix: release/
       production-release-branch-channel: production
+      production-release-pr-mode: auto
       production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions
       production-environment: production
 ```
 
+`production-release-pr-mode` controls the post-staging handoff:
+
+| Mode | Behavior |
+| --- | --- |
+| `auto` | Generate release PR facts, create/update the empty release-intent branch and PR, and label it when token permissions allow. This is the default. |
+| `summary-only` | Generate and upload release PR facts, body, passport evidence, and manual command, but do not call the GitHub PR API. |
+| `disabled` | Record a disabled handoff and skip release PR API calls. |
+
+Automatic release PR creation normally uses the workflow `github.token`. If the
+consumer repository cannot enable "GitHub Actions can create and approve pull
+requests" globally, pass a narrower GitHub App token or PAT through
+`production-release-pr-token`:
+
+```yaml
+with:
+  production-release-pr-token: ${{ secrets.BUILDCHAIN_RELEASE_PR_TOKEN }}
+```
+
 The merge button becomes the production approval only for a PR that carries the
 release label and comes from the configured source-branch prefix. Ordinary pull
 requests merged into `main` deploy staging and open a release-intent PR; merging
@@ -722,7 +749,9 @@ Callers must grant `id-token: write` for OIDC role assumption. Preview comments
 need `pull-requests: write`. Automatic release PR creation also needs
 `contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can
 create the release branch, write the empty release-intent commit, open or update
-the PR, and apply the release label. The AWS roles remain caller-owned and
+the PR, and apply the release label. If these permissions are unavailable,
+Buildchain degrades the release handoff instead of marking a successful staging
+deployment as failed, unless `fail-on-release-pr-error=true`. The AWS roles remain caller-owned and
 should be scoped by channel: preview can mutate only preview resources, staging
 can mutate only staging resources, and production can mutate only production
 resources.