@kungfu-tech/buildchain 3.0.3-alpha.0 → 3.0.3-alpha.2

package/docs/cli.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-cli
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Buildchain CLI, npm Package, and Toolkit API
 
 Buildchain is published as the public npm package
@@ -76,6 +94,8 @@ import { collectReadmeBadgeFacts } from "@kungfu-tech/buildchain/readme-badges";
 import { verifyReleasePassport } from "@kungfu-tech/buildchain/release-passport";
 import { verifyGitHubArtifactAttestationEvidence } from "@kungfu-tech/buildchain/github-artifact-attestation";
 import { createReleasePropagationPlan } from "@kungfu-tech/buildchain/release-propagation";
+import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain/publication-reproducibility";
+import { collectPaperStatus } from "@kungfu-tech/buildchain/paper";
 import { planReleaseLineBootstrap } from "@kungfu-tech/buildchain/release-line-bootstrap";
 import { collectPublicSurfaceReverseAudit } from "@kungfu-tech/buildchain/public-surface-audit";
 import { createBuildchainLayoutDiscovery } from "@kungfu-tech/buildchain/buildchain-layout";
@@ -101,6 +121,94 @@ with the exact signer/source policy and then verifies the retained bundle,
 predicate, platform manifest, Passport, and Buildchain evidence locally. See
 [`github-artifact-attestation.md`](github-artifact-attestation.md).
 
+### Governed paper lifecycle
+
+`buildchain paper` is the unified operator surface for one paper repository or
+a discovered fleet. Every subcommand returns a versioned JSON contract with
+`--json`:
+
+```bash
+buildchain paper scaffold --package @kungfu-tech/paper-example \
+  --repository kungfu-systems/paper-example
+buildchain paper migrate --json
+buildchain paper work start golden-path --json
+buildchain paper work submit --json
+buildchain paper fleet audit --root ../papers --json
+buildchain paper fleet update --root ../paper-worktrees --json
+buildchain paper preflight --offline --json
+buildchain paper bootstrap npm --json
+buildchain paper build --json
+buildchain paper alpha --json
+buildchain paper status --json
+buildchain paper resume --json
+```
+
+The safety and authority boundary is explicit:
+
+- `scaffold` plans a 14-file, no-overwrite repository shape by default; add
+  `--write` to create only missing files.
+- `migrate` plans the Buildchain-owned authority, workflow, contract lock,
+  version pin, and package control changes needed by an existing paper
+  repository. It pins an exact v3 dependency and adds pnpm-backed paper scripts.
+  Add `--write` only after reviewing exact old and new digests; paper content
+  and publication configuration are never rewritten. Refresh
+  `pnpm-lock.yaml` with `pnpm install --lockfile-only` after a write.
+- `work start` derives the protected development branch from the configured
+  publication semver line and creates a safe local work branch only when the
+  worktree is clean, the sole `origin` is the canonical `kungfu-systems`
+  repository, and local HEAD equals the exact remotely observed development
+  SHA. It never fetches or merges silently.
+- `work submit` accepts only an allowed non-protected work branch that contains
+  the exact remote development commit. It rejects divergent remote work,
+  wrong-base pull requests, dirty trees, forks, and ambiguous remotes; execution
+  uses a normal non-force push and opens or reuses a PR to the derived
+  development branch.
+- `fleet audit` discovers `paper-*` repositories from a root and emits one
+  deterministic audit root over exact runtime, dependency, lockfile, workflow,
+  authority, and repository observations. `fleet update` reuses the migration
+  contract for every discovered repository, remains dry-run by default, and
+  refuses protected or non-work branches.
+- The scaffolded `.buildchain/paper/provisioning-authority.json` binds both
+  caller workflow byte digests, their exact reusable-workflow SHA, the runtime
+  SHA, contract-lock bytes, npm registry and trusted-publisher coordinates, and
+  the repository Actions/generated-write policy under one digest. A floating
+  Buildchain ref cannot change release policy after that authority is accepted.
+- `preflight` separates local readiness from readiness for external mutation.
+  `--offline` skips live GitHub and npm observations without treating them as
+  local failures. Live readiness requires default workflow permissions `read`,
+  Actions pull-request approval disabled, and GitHub App or equivalent narrow
+  generated-write credential metadata.
+- `bootstrap npm` always performs npm pack and publish dry-runs first. A real
+  public bootstrap requires both `--execute` and
+  `--confirm-public-package <exact-name>`, uses only the official npm registry,
+  fixes the bootstrap version at `0.0.0-bootstrap.0`, and returns only npm URLs
+  observed from command output. Success requires public package readback and
+  the exact repository/workflow/environment trusted-publisher binding. For
+  GitHub, the npm coordinate is the workflow filename (`paper-release.yml`),
+  not its `.github/workflows/` repository path.
+- `build` plans the two-clean-build reproducibility proof. Add `--execute` to
+  create and verify the sealed publication bundle.
+- `alpha` plans or opens the protected Alpha pull request; it never merges,
+  publishes, or advances a floating ref.
+- `status` reports only evidence found in the repository or external
+  observations. It never infers a later lifecycle state from an earlier one.
+- `resume` plans or dispatches the repository's thin release workflow; the
+  protected workflow remains the release authority.
+
+The ordered evidence states are `scaffolded`, `governed`, `admitted`,
+`bootstrapped`, `trust-bound`, `content-ready`, `artifact-sealed`,
+`package-published`, `alpha-complete`, `staging-visible`, and
+`production-visible`. A state can be `satisfied`, `not-reached`, `blocked`, or
+`unknown`; consumers must not collapse those distinctions.
+
+The corresponding Node surface is
+`@kungfu-tech/buildchain/paper`. Planning and status functions are read-only;
+`writePaperScaffold()`, `writePaperMigration()`, and
+`writePaperFleetUpdate()` are the bounded local writers. Work plans expose
+separate rechecking executors for local branch creation and normal push, and
+`executePaperNpmBootstrap()` preserves the same confirmation boundary used by
+the CLI.
+
 `buildchain layout` is the stable machine question for repository layout. Tools
 such as Shifu should call it instead of copying `.buildchain/` path constants:
 
@@ -249,9 +357,9 @@ branch action, and initial version before any GitHub mutation happens:
 
 ```bash
 buildchain release line open \
-  --major 2 \
-  --minor 10 \
-  --source-ref release/v2/v2.9 \
+  --major 3 \
+  --minor 1 \
+  --source-ref release/v3/v3.0 \
   --json
 ```
 
@@ -264,9 +372,9 @@ reconciliation succeeds, and opens the first dev-to-alpha channel PR:
 
 ```bash
 buildchain release line open \
-  --major 2 \
-  --minor 10 \
-  --source-ref release/v2/v2.9 \
+  --major 3 \
+  --minor 1 \
+  --source-ref release/v3/v3.0 \
   --write \
   --json
 ```
@@ -284,7 +392,9 @@ import {
   assertPublicSurfaceReverseAudit,
 } from "@kungfu-tech/buildchain/public-surface-audit";
 
-assertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));
+assertPublicSurfaceReverseAudit(
+  collectPublicSurfaceReverseAudit({ root: process.cwd() }),
+);
 ```
 
 `buildchain kfd` is the product-facing KFD namespace. Schema commands expose the
@@ -398,7 +508,10 @@ The event protocol is JSONL and is also available from the SDK:
 ```js
 import { createBuildchainLogger } from "@kungfu-tech/buildchain/logging";
 
-const logger = createBuildchainLogger({ source: "user", component: "native-build" });
+const logger = createBuildchainLogger({
+  source: "user",
+  component: "native-build",
+});
 logger.mark("configure.ready", { phase: "configure" });
 ```
 
@@ -530,6 +643,24 @@ buildchain publication-artifact manifest \
   --json
 ```
 
+Run the fail-closed clean-room gate before Alpha or release admission:
+
+```bash
+buildchain publication-artifact reproducibility \
+  --source-sha "$(git rev-parse HEAD)" \
+  --promote \
+  --json
+```
+
+The command checks two independent clones of the exact commit, isolates caches,
+derives `SOURCE_DATE_EPOCH` from Git, and compares every declared artifact,
+source bundle, publication evidence file, npm package file, and actual npm
+tarball. It writes
+`.buildchain/publication/reproducibility-receipt.json`. Only a byte-identical
+build using the digest-pinned `latex-docker` toolchain is qualifying.
+`--allow-unpinned-toolchain` exists for local diagnostics and never changes the
+receipt's `qualifying` field.
+
 Generate the Buildchain-owned npm paper package contents from declared
 publication facts:
 
@@ -629,7 +760,7 @@ buildchain collect github-release \
   --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \
   --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \
   --kfd-3-artifact-verify-cmd "kungfu agent verify --json" \
-  --release-extra-json '{"channel":"release","targetRef":"release/v2/v2.3"}' \
+  --release-extra-json '{"channel":"release","targetRef":"release/v3/v3.0"}' \
   --output-dir .buildchain/release-passport
 ```
 
@@ -880,9 +1011,9 @@ Buildchain's own npm package is published from
 `.github/workflows/buildchain-ref-promotion.yml`, inside the same publish
 transaction that promotes release refs:
 
-- `v2.0.13-alpha.0` publishes to npm with dist-tag `alpha`.
-- `v2.0.13` publishes to npm with dist-tag `latest`.
-- moving refs such as `v2`, `v2.0`, and `v2.0-alpha` do not match the publish
+- `v3.0.3-alpha.0` publishes to npm with dist-tag `alpha`.
+- `v3.0.2` publishes to npm with dist-tag `latest`.
+- moving refs such as `v3`, `v3.0`, and `v3.0-alpha` do not match the publish
   workflow and do not publish.
 
 The promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.

package/docs/consumer-issue-reporting.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-consumer-issue-reporting
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Consumer Issue Reporting
 
 Buildchain ships a first-class issue reporting surface for consumer workflows.
@@ -73,7 +91,7 @@ const result = await reportBuildchainIssue({
   token: process.env.BUILDCHAIN_ISSUE_TOKEN,
   summary: "Native artifact manifest is incomplete",
   failureCode: "native-manifest-incomplete",
-  buildchainRef: "v2",
+  buildchainRef: "v3",
   diagnosticsPath: ".buildchain/artifacts/diagnostics.json",
 });
 ```

package/docs/github-governance-authority.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-07-30
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -234,7 +234,7 @@ branch; unrelated rules and conditions are preserved in place.
 ```bash
 buildchain github-governance ruleset-policy-plan \
   --repository kungfu-systems/buildchain \
-  --branch alpha/v2/v2.14 \
+  --branch alpha/v3/v3.0 \
   --ruleset-id 19518955 \
   --snapshot-output ruleset-rollback.json \
   --plan-output ruleset-rollout.json

package/docs/lifecycle-protocol.md

@@ -1,6 +1,24 @@
+---
+status: active
+period: ongoing
+theme: buildchain-lifecycle-protocol
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Lifecycle Protocol
 
-Buildchain uses `.buildchain/buildchain.toml` as the v2 repository configuration format.
+Buildchain uses `.buildchain/buildchain.toml` as the v3 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.
@@ -10,7 +28,7 @@ For compatibility, Buildchain still reads a legacy root `buildchain.toml` when
 `.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
+Only TOML is supported in v3. YAML, JSON, and JavaScript config files are not
 loaded.
 
 ## Minimal File

package/docs/migration-inventory.md

@@ -1,9 +1,28 @@
+---
+status: historical
+period: 2026-07
+theme: buildchain-v2-migration-inventory
+doc_type: migration-inventory
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Buildchain v2 Migration Inventory
 
-This inventory records the buildchain v2 action surface. Buildchain v2 is the
-monorepo source of truth for active Kungfu repository workflows, the active
-reusable build workflow, and the three GitHub Actions that are still part of
-Buildchain's reusable contract.
+This historical inventory records the Buildchain v2 consolidation boundary.
+Buildchain v3 is now the active monorepo source of truth for Kungfu repository
+workflows, reusable build workflows, and Buildchain-native actions. The v2
+names below preserve the migration decisions that v3 inherited; they are not a
+current runtime baseline.
 Standalone `workflows` and `action-*` repositories are historical rollback
 anchors, not active Buildchain migration targets.
 
@@ -111,7 +130,7 @@ older standalone action repository.
 | `actions/run-lifecycle` | lifecycle command execution and deterministic artifact manifest generation |
 | `actions/validate-config` | `buildchain.toml` version-state and lifecycle preflight without executing lifecycle commands |
 
-## Stable v2 Refs
+## Current v3 Refs
 
 - Actions: `kungfu-systems/buildchain/actions/<name>@v3`
 - Reusable workflows: `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`

package/docs/ownership.md

@@ -1,8 +1,26 @@
+---
+status: active
+period: ongoing
+theme: buildchain-ownership-and-migration
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Ownership And Migration Rules
 
 ## Source Of Truth
 
-Buildchain v2 workflow and action design lands in this repository. Standalone
+Buildchain v3 workflow and action design lands in this repository. Standalone
 `workflows` and `action-*` repositories are historical rollback anchors.
 Buildchain only ships the native action surface required for config validation,
 lifecycle execution, and release ref promotion.

package/docs/publication-artifacts.md

@@ -106,6 +106,37 @@ for compatibility, but the passport records it as lower trust because
 Buildchain can record the command boundary without proving the compiler or
 LaTeX distribution digest.
 
+## Reproducibility Gate
+
+Alpha and release admission require
+`.buildchain/publication/reproducibility-receipt.json`. Buildchain creates the
+receipt by cloning the exact checked-out Git commit into two independent local
+repositories, assigning each build a separate home and npm cache, and deriving
+`SOURCE_DATE_EPOCH` from the source commit. A pinned `latex-docker` build runs
+with UTC, `C.UTF-8`, no build-time network, and the exact image digest declared
+in `[publication.toolchain]`.
+
+Each clean build independently creates the PDF set, source bundle, publication
+manifest and passport, append-only registry, synthesized npm package directory,
+and an actual npm tarball. After qualification, Buildchain copies the first
+qualifying tarball into the promoted publication candidate instead of deleting
+it with the temporary clean build. The receipt compares exact bytes and records:
+
+- source repository, commit, tree, and `SOURCE_DATE_EPOCH`;
+- toolchain image, digest, command, and toolchain identity root;
+- every artifact and evidence path with byte size and SHA-256;
+- npm tarball SHA-256, SHA-1 shasum, and `sha512` integrity;
+- per-build output-set roots and the first differing field or artifact.
+
+The gate is fail-closed. A build-only `custom-command` run can diagnose byte
+drift and promote its byte-identical local output with
+`--allow-unpinned-toolchain`, but it is never a qualifying publication receipt.
+Any workflow that prepares a publishable paper package accepts only a
+digest-pinned toolchain and promotes the first clean build into the publication
+candidate only after both builds are byte-identical. The receipt remains
+outside the npm tarball to avoid a circular digest; it binds the tarball bytes
+from the surrounding sealed publication evidence.
+
 `publish.kind = "npm-paper-package"` declares that Buildchain, not the consumer
 repository, owns the standard paper npm package shape and release transaction
 mechanics. `publish.package` is the public npm package that contains the PDF,
@@ -134,14 +165,18 @@ The build-only workflow:
   any paper build runs;
 - resolves the declared publication toolchain from `[publication.toolchain]` or
   workflow inputs;
+- hydrates authenticated registry history before building so both clean
+  candidates include the same append-only history;
 - for `latex-docker`, pulls the pinned build-images LaTeX builder digest and
-  runs the declared command in the container;
+  runs two independent clean builds with the reproducibility policy above;
 - for `custom-command`, runs the declared command and records the lower-trust
-  boundary in the passport;
+  boundary in the passport, but refuses publication qualification;
 - runs the verify command;
 - creates a source bundle from `publication.source_paths`;
 - writes `.buildchain/publication/publication-artifact.json`;
 - writes `.buildchain/publication/publication-artifact-passport.json`;
+- writes a qualifying
+  `.buildchain/publication/reproducibility-receipt.json`;
 - when `[publication.archive]` is configured, writes
   `.buildchain/publication/publication-registry.json` and verifies same-version
   immutability;
@@ -174,36 +209,36 @@ on:
       - alpha/v1/v1.0
       - release/v1/v1.0
   workflow_dispatch:
-    inputs:
-      buildchain-ref:
-        description: "Temporary Buildchain runtime ref"
-        required: false
-        default: ""
 
 jobs:
   paper-release:
-    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>
     permissions:
       actions: read
       checks: write
-      contents: write
+      contents: read
       id-token: write
       issues: write
     with:
-      buildchain-ref: ${{ inputs.buildchain-ref || '' }}
+      buildchain-ref: <exact-buildchain-sha>
       publisher-workflow-path: .github/workflows/paper-release.yml
       toolchain-type: config
       verify-command: make check
       artifact-paths: _build/paper-name.pdf
       buildchain-contract-lock-path: .buildchain/contract-lock.json
     secrets:
-      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+      BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}
+      BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}
+      BUILDCHAIN_GENERATED_WRITE_TOKEN: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}
 ```
 
-The sealed preset does not use a long-lived token for npm publication. It may
-accept an optional `BUILDCHAIN_PROMOTION_TOKEN` only for machine-generated
-version-state updates on protected channel branches; npm publication remains
-bound to GitHub OIDC trusted publishing. The preset builds and packages the
+The sealed preset does not use a long-lived token for npm publication. It
+prefers a repository-scoped GitHub App installation token for generated
+repository writes and accepts `BUILDCHAIN_GENERATED_WRITE_TOKEN` as an
+equivalent narrow compatibility authority. The deprecated
+`BUILDCHAIN_PROMOTION_TOKEN` name remains accepted for existing consumers, but
+there is no `github.token` fallback for generated writes. npm publication
+remains bound to GitHub OIDC trusted publishing. The preset builds and packages the
 paper in a read-only job, then a credential-free authority job downloads that
 exact candidate, audits the external control plane, and seals a capability over
 the source tree, Buildchain runtime, controller receipt, PDF, and npm package
@@ -214,8 +249,9 @@ workflow named by `publisher-workflow-path`.
 
 The preset:
 
-- resolves the floating Buildchain runtime once and binds the exact SHA into the
-  publication candidate and authority capability;
+- uses the exact Buildchain SHA admitted by the provisioning authority and
+  binds it into the caller bytes, contract lock, publication candidate, and
+  authority capability;
 - builds the PDF through the declared pinned LaTeX Docker toolchain or custom
   command in a read-only job;
 - verifies the paper repository;
@@ -229,7 +265,13 @@ The preset:
   channel commit and requires `promote-buildchain-ref` to verify that lock
   before any publish side effect;
 - verifies the complete candidate again after authority and publishes the
-  package through npm Trusted Publishing without rebuilding it;
+  package through npm Trusted Publishing without rebuilding or repacking it;
+- writes a typed sealed-bundle manifest that binds the candidate root, exact
+  npm tarball, every GitHub Release asset, durable storage path, and resume
+  command;
+- persists the complete binary bundle to the transaction's durable release-state
+  ref before npm receives credentials, allowing an empty runner to restore and
+  verify the same bytes after interruption;
 - writes Buildchain release/passport evidence; and
 - creates or updates the exact-version GitHub Release by default, uploading
   every file declared by `publication.primary_artifact` and
@@ -239,6 +281,17 @@ Consumers can opt out of the GitHub Release with `github-release: false`, but
 the default is on so downstream release propagation can observe
 `release.published` without hand-written `gh release` steps.
 
+The transaction exposes a stable publication progression:
+
+```text
+prepared -> sealed -> package-published -> alpha-complete
+```
+
+Stable publication ends at `release-complete`. If a run stops after npm but
+before GitHub Release completion, the next run starts from
+`package-published`, restores the sealed PDF and companion assets, and finishes
+the release without invoking the paper build or `npm pack` again.
+
 Declared publication artifacts are resolved from the generated publication
 manifest rather than repeated in consumer workflow YAML. Publication fails
 before upload if a declared artifact is missing or if its basename would
@@ -256,12 +309,119 @@ Buildchain rather than forking the mechanics into each paper repository.
 
 ## CLI And Node API
 
+### Unified paper operator surface
+
+The `buildchain paper` command family assembles the existing publication
+primitives into a resumable operator flow:
+
+```text
+scaffold/new or migrate/existing -> preflight -> bootstrap npm -> build -> alpha -> status -> resume
+```
+
+Each command emits a typed JSON envelope with `--json`. Dry-run is the default
+for every external mutation. `scaffold --write` is limited to no-overwrite
+local file creation. `migrate --write` is limited to the Buildchain-owned
+contract lock, version pin, thin workflows, and provisioning authority; paper
+content and publication configuration are preserved. `bootstrap npm --execute`, `alpha --execute`, and
+`resume --execute` cross external authority boundaries and therefore require
+explicit execution.
+
+The evidence model is intentionally non-inferential:
+
+| State                | Required evidence                                        |
+| -------------------- | -------------------------------------------------------- |
+| `scaffolded`         | Complete managed scaffold inventory                      |
+| `governed`           | Compatible Buildchain contract lock                      |
+| `admitted`           | Repository admission receipt                             |
+| `bootstrapped`       | Successful public npm bootstrap receipt or registry fact |
+| `trust-bound`        | Trusted publisher binding receipt                        |
+| `content-ready`      | Declared source paths present                            |
+| `artifact-sealed`    | Verified sealed publication bundle                       |
+| `package-published`  | Exact package version visible in npm                     |
+| `alpha-complete`     | Protected Alpha PR completion evidence                   |
+| `staging-visible`    | Staging route evidence                                   |
+| `production-visible` | Production route evidence                                |
+
+`paper status` reports `satisfied`, `not-reached`, `blocked`, or `unknown` for
+each state. It does not promote a state merely because a prior state is
+complete. This makes a later `paper resume` safe: the command dispatches the
+thin repository release workflow, while the workflow re-verifies durable
+evidence and remains the publication authority.
+
+Operationally, responsibility remains split:
+
+- the paper repository owns content, declared metadata, and its thin
+  build/release workflow;
+- Buildchain owns scaffold shape, evidence contracts, reproducibility, sealed
+  bundle mechanics, npm transaction mechanics, and resumption planning;
+- GitHub branch protection and trusted publishing own authority transitions;
+- the papers site consumes publication evidence and owns reader-facing
+  rendering.
+
+Daily work begins and ends through the repository-pinned v3 CLI:
+
+```sh
+pnpm paper:work:start -- golden-path
+# edit, test, and commit paper source
+pnpm paper:work:submit
+```
+
+The start plan derives `dev/vN/vN.M` from `publication.version` and requires
+local HEAD to equal the exact canonical remote development SHA. The submit plan
+allows only a non-protected work branch containing that SHA, a clean committed
+tree, a normal fast-forward push, and a pull request back to the same derived
+development branch. Neither command force-pushes, guesses a fork target, or
+silently fetches and merges stale state.
+
+Maintainers can inspect a sibling fleet without per-repository command copies:
+
+```sh
+buildchain paper fleet audit --root /path/to/papers --json
+buildchain paper fleet update --root /path/to/isolated-paper-worktrees --json
+```
+
+Fleet update is dry-run first and accepts only isolated work branches. Its
+typed plan carries exact-old and expected-new digests for the same owned
+surfaces as `paper migrate`; `--write` also refreshes each pnpm lockfile. It
+never rewrites paper content or publication configuration.
+
+Run a local readiness check without network observations:
+
+```sh
+buildchain paper preflight --offline --json
+buildchain paper status --json
+```
+
+Before real npm bootstrap, first inspect the default dry-run result:
+
+```sh
+buildchain paper bootstrap npm --json
+```
+
+Only after reviewing the package, repository, workflow, and dry-run evidence:
+
+```sh
+buildchain paper bootstrap npm \
+  --execute \
+  --confirm-public-package @kungfu-tech/paper-example \
+  --json
+```
+
 Generate the publication manifest locally or in CI:
 
 ```sh
 buildchain publication-artifact manifest --source-sha "$(git rev-parse HEAD)" --json
 ```
 
+Prove the complete candidate from two clean builds:
+
+```sh
+buildchain publication-artifact reproducibility \
+  --source-sha "$(git rev-parse HEAD)" \
+  --promote \
+  --json
+```
+
 Generate the npm package contents after the manifest exists:
 
 ```sh
@@ -280,6 +440,13 @@ import {
   collectPublicationPackageFacts,
   preparePublicationNpmPackage,
 } from "@kungfu-tech/buildchain/publication-package";
+
+import { verifyPublicationReproducibility } from "@kungfu-tech/buildchain/publication-reproducibility";
+
+import {
+  createPublicationSealedBundle,
+  verifyPublicationSealedBundle,
+} from "@kungfu-tech/buildchain/publication-sealed-bundle";
 ```
 
 `writePublicationArtifact()` is the single implementation used by the CLI and