@kungfu-tech/buildchain 4.1.3 → 4.1.4-alpha.0

package/docs/publication-artifacts.md

@@ -1,509 +1,151 @@
-# Publication Artifact Workflow
-
-Buildchain supports `project.type = "publication-artifact"` for repositories
-that produce auditable papers, reports, specifications, or similar publication
-packages. These repositories are artifact producers. They should not be forced
-to become `web-surface` repositories just because a downstream site later
-renders the paper.
-
-The split is:
-
-```text
-paper repo = source, PDF, metadata, source bundle, publication manifest
-papers site = layout, navigation, public web surface, downstream rendering
-```
-
-## Configuration
-
-The paper repository owns `.buildchain/buildchain.toml`:
-
-```toml
-schema = 1
-
-[project]
-type = "publication-artifact"
-name = "paper-observer-declared-timelines"
-
-[publication]
-kind = "paper"
-title = "Observer-Declared Timelines for Real-World Agent Work"
-version = "0.1.0"
-primary_artifact = "_build/main.pdf"
-artifact_paths = ["_build/main.pdf"]
-metadata_paths = ["README.md", "docs/MAP.md"]
-source_paths = ["paper", "README.md", "LICENSE", "Makefile"]
-site_consumers = ["papers.libkungfu.dev"]
-manifest_path = ".buildchain/publication/publication-artifact.json"
-source_bundle_path = ".buildchain/publication/source.tar.gz"
-
-[publication.archive]
-id = "observer-declared-timelines"
-canonical_url = "https://papers.libkungfu.dev/observer-declared-timelines/"
-latest_url = "https://papers.libkungfu.dev/observer-declared-timelines/latest/"
-latest_evidence_url = "https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json"
-immutable_base_url = "https://papers.libkungfu.dev/archive"
-registry_path = ".buildchain/publication/publication-registry.json"
-
-[publication.toolchain]
-type = "latex-docker"
-image = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder"
-digest = "sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8"
-command = "latexmk -pdf -outdir=_build paper/main.tex"
-
-[publish]
-kind = "npm-paper-package"
-package = "@kungfu-tech/paper-observer-declared-timelines"
-auth = "trusted-publishing"
-
-[lifecycle.build]
-command = "make pdf"
-
-[lifecycle.verify]
-command = "make check"
-```
-
-`primary_artifact` is the human-facing publication output, usually a PDF.
-`source_paths` are archived into a source bundle. `metadata_paths` are hashed
-and recorded so a site can consume the paper facts without scraping prose.
-
-`publication.archive` turns the publication into an append-only public archive
-contract:
-
-- `canonical_url` is the stable human reader page.
-- `latest_url` and `latest_evidence_url` are movable aliases for the latest
-  reader page and latest evidence.
-- `immutable_base_url` plus `id` and `publication.version` produce a versioned
-  prefix such as
-  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.
-- `immutable_url_prefix` can be used instead when the repository already owns
-  the full version prefix.
-- `registry_path` records every published version and its manifest, passport,
-  source bundle, primary artifact, URLs, and SHA-256 digests.
-
-Immutable archive prefixes are append-only. Do not run site deployment commands
-with `sync --delete` or equivalent deletion semantics over those prefixes. A
-same-version republish is allowed only when the immutable digest is unchanged;
-if PDF, source bundle, route, metadata, or toolchain evidence changes for an
-existing version, Buildchain fails before the registry is rewritten.
-
-The Buildchain web-surface adapter consumes this boundary from a surface-local
-`manifest.json` whose `archivePolicy.contract` is
-`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive
-root from every owning or parent `sync --delete`, verifies existing object
-digests, uploads only missing immutable files with `--no-overwrite`, and verifies
-them again before mutable site content is synchronized. A current package set
-does not need to rebuild or enumerate every historical version: the protected
-archive root remains outside deletion even when older versions disappear from
-the current artifact.
-
-`publication.toolchain` makes the source-to-PDF transformation part of the
-machine-readable contract. `latex-docker` is the preferred LaTeX profile. The
-Buildchain paper scaffold and reusable workflow default to
-`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the
-digest above. The workflow pulls the declared image by digest and runs the
-declared command in that pinned container. `custom-command` remains available
-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,
-publication manifest, publication passport, optional archive registry, source
-bundle, and declared metadata files.
-
-## Reusable Workflow
-
-Consumer repositories that only need to build and upload paper evidence can
-call the build-only wrapper directly:
-
-```yaml
-jobs:
-  publication:
-    uses: kungfu-systems/buildchain/.github/workflows/public-build-publication.yml@v3
-    with:
-      toolchain-type: config
-      verify-command: make check
-      artifact-name: observer-declared-timelines
-      contract-lock: .buildchain/contract-lock.json
-```
-
-The build-only workflow:
-
-- resolves the Buildchain runtime and checks the floating contract lock before
-  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 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, 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;
-- uploads one GitHub artifact containing the PDF, manifest, passport, optional
-  registry, and source bundle.
-
-It does not publish npm packages, deploy web pages, or create GitHub Releases.
-
-The paper release preset additionally hydrates every prior published package
-registry from the npm registry before generating the current manifest. npm
-package integrity authenticates each downloaded source; Buildchain verifies the
-registry self-digest, merges immutable records, and fails if a cumulative
-registry drops an accepted version or changes immutable route/artifact facts.
-The synthesized package therefore carries complete history even on a clean
-runner. Its cumulative registry and file SHA-256 values are bound into the paper
-release build summary and release passport evidence.
-
-## Paper Release Preset
-
-Paper repositories that publish a versioned npm package should use the
-Buildchain-managed release preset instead of copying npm transaction scripts or
-promotion YAML:
-
-```yaml
-name: Paper Release
-
-on:
-  push:
-    branches:
-      - alpha/v1/v1.0
-      - release/v1/v1.0
-  workflow_dispatch:
-
-jobs:
-  paper-release:
-    uses: kungfu-systems/buildchain/.github/workflows/public-release-paper.yml@v4
-    permissions:
-      actions: read
-      checks: write
-      contents: read
-      id-token: write
-      issues: write
-    with:
-      publisher-workflow-path: .github/workflows/public-release-paper.yml
-      toolchain-type: config
-      verify-command: make check
-      artifact-paths: _build/paper-name.pdf
-      contract-lock: .buildchain/contract-lock.json
-    secrets:
-      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
-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
-bytes. Only the final job receives write and OIDC permissions; it downloads the
-admitted candidate, recomputes the capability binding, and publishes without
-executing consumer build commands. npm binds the OIDC identity to the consumer
-workflow named by `publisher-workflow-path`.
-
-The preset:
-
-- 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;
-- writes the publication manifest, publication passport, optional archive
-  registry, and source bundle;
-- synthesizes an npm package from `[publication]` and `[publish]` declarations
-  under `.buildchain/publication/npm-package`;
-- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes
-  it as `publish-required-artifacts-json`;
-- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the
-  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 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
-  `publication.artifact_paths` alongside the release evidence.
-
-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
-collide with another GitHub Release asset.
-
-For npm Trusted Publishing, register the consumer workflow file that calls this
-preset, for example `.github/workflows/public-release-paper.yml`, against the declared
-package in npm. The trusted publisher is the consumer repository and workflow
-file; the implementation still runs inside Buildchain's reusable workflow.
-
-Standard paper repositories should not carry local copies of
-`packages/core/publication/commands/npm-publish-transaction.mjs`, package-generation scripts, or
-promotion/ref-lock YAML. If the default package shape is insufficient, extend
-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:
+---
+status: draft
+period: ongoing
+theme: paper-consumer
+doc_type: implementation-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-20
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-20
+  visible_context: Schema-2 product compiler, shared caller templates and Paper source scaffold.
+  invisible_context_boundary: No downstream repository migration or hosted Paper release is claimed.
+---
+
+# Paper products
+
+A Paper repository owns its source, build commands, verification commands and
+PDF output. It uses the same two Buildchain caller files as npm and binary
+products. The published pipeline owns delivery, publication and recovery.
+
+## Create or adopt a source tree
+
+For an existing paper with working `make pdf` and `make check` commands:
 
 ```sh
-pnpm paper:work:start -- golden-path
-# edit, test, and commit paper source
-pnpm paper:work:submit
+buildchain init --type paper
+buildchain validate --require-lifecycle-stages build,verify
 ```
 
-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:
+To generate a new LaTeX source tree, inspect the plan and then write it:
 
 ```sh
-buildchain paper fleet audit --root /path/to/papers --json
-buildchain paper fleet update --root /path/to/isolated-paper-worktrees --json
+buildchain paper scaffold --name paper-example --title "Example Paper" \
+  --repository example/paper-example --json
+buildchain paper scaffold --name paper-example --title "Example Paper" \
+  --repository example/paper-example --write --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.
+The scaffold contains the paper, bibliography, Makefile, license, product
+manifest, documentation, schema-2 TOML and shared caller pair. It creates no
+repository-side provisioning authority, agent-entry JSON or release controller.
+Existing conflicting files, extra workflows and symlinked write parents stop
+writing before another planned file is created. Repeating an unchanged plan is
+idempotent.
 
-Run a local readiness check without network observations:
+The new Makefile builds LaTeX in a digest-pinned container with networking
+disabled for the build. Running it requires Docker and the referenced image.
+`make check` checks the source files and Git whitespace; add product-specific
+content and PDF checks there as needed. A single successful build is not a
+proof of reproducibility across independent builds.
 
-```sh
-buildchain paper preflight --offline --json
-buildchain paper status --json
-```
+## Product configuration
 
-Before real npm bootstrap, first inspect the default dry-run result:
+The generated `.buildchain/buildchain.toml` includes a Paper product:
 
-```sh
-buildchain paper bootstrap npm --json
-```
+```toml
+[[products]]
+id = "main"
+type = "paper"
+platforms = ["linux-x64"]
+build = ["make pdf"]
+verify = ["make check"]
 
-Only after reviewing the package, repository, workflow, and dry-run evidence:
+[[products.artifacts]]
+id = "main"
+path = "_build/main.pdf"
+kind = "pdf"
 
-```sh
-buildchain paper bootstrap npm \
-  --execute \
-  --confirm-public-package @kungfu-tech/paper-example \
-  --json
+[[products.targets]]
+provider = "github-release"
+artifacts = ["main"]
 ```
 
-Generate the publication manifest locally or in CI:
-
-```sh
-buildchain publication-artifact manifest --source-sha "$(git rev-parse HEAD)" --json
-```
+This is the product portion of the generated configuration. Keep its schema,
+version, channels and protected-review policy sections as well. Product commands
+may change with the source tree; the two caller files remain identical across
+product types:
 
-Prove the complete candidate from two clean builds:
+- `.github/workflows/buildchain.yml` calls the common normal pipeline.
+- `.github/workflows/buildchain-recover.yml` calls exact-attempt recovery.
 
-```sh
-buildchain publication-artifact reproducibility \
-  --source-sha "$(git rev-parse HEAD)" \
-  --promote \
-  --json
-```
+The source package is private. Its `version` is the product version authority;
+its description and optional homepage retain the paper's title and site URL.
+`--package` optionally sets this source identity and does not add an npm target.
+When adopting a source tree without a versioned package manifest, `init` creates
+`release.json` as the version authority instead.
 
-Generate the npm package contents after the manifest exists:
+## Validate and publish
 
 ```sh
-buildchain publication-artifact npm-package --json
-```
-
-Node API:
-
-```js
-import {
-  collectPublicationArtifact,
-  writePublicationArtifact,
-} from "@kungfu-tech/buildchain/publication-artifact";
-
-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
-the reusable workflow. The generated manifest records:
-
-- publication title, kind, authors, and primary artifact;
-- artifact paths, byte sizes, and SHA-256 digests;
-- metadata paths and SHA-256 digests;
-- source SHA, tree SHA, source files, and source bundle digest;
-- publication toolchain type, image, digest, command, invocation mode, and trust
-  classification;
-- timestamp and reproducibility policy;
-- downstream site-consumption hints;
-- optional archive routes for canonical, latest, latest evidence, immutable
-  version prefix, and public artifact URLs.
-
-The companion publication artifact passport records the same source and
-artifact evidence plus an explicit responsibility split. Buildchain proves
-declared files and hashes; it does not peer-review paper claims.
-
-When archive config is present, the registry uses the
-`kungfu-buildchain-publication-artifact-registry` contract. A site repository
-can render latest pages and historical version indexes from that registry
-without rebuilding old PDFs from the latest npm package or paper source.
-
-## Site Consumption
-
-A downstream papers site should treat the publication manifest as the single
-fact source for the artifact. The site owns rendering and navigation; it should
-not reinterpret the paper repository as a web deployment source.
-For registry-level routing, sites should first consume the package-owned
-Buildchain fact source:
-
-```text
-node_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json
-```
-
-or the equivalent package export:
-
-```js
-import registry from "@kungfu-tech/buildchain/site/publication-registry.json" with { type: "json" };
-```
-
-That registry uses the `kungfu-buildchain-publication-release-registry`
-contract. It separates mutable canonical/latest reader routes from immutable
-version prefixes, publication artifacts, source bundles, and passport evidence
-so site repositories can render `/papers/**` without maintaining a parallel
-fixture truth source.
-
-For `paper-observer-declared-timelines`, the expected adoption path is:
-
-```text
-paper repo builds PDF + manifest + source bundle
-paper repo updates publication-registry.json
-papers site consumes publication-artifact.json
-papers site consumes publication-registry.json for history
-site renders paper page and links the PDF/source bundle
+make pdf
+make check
+buildchain validate --require-lifecycle-stages build,verify
+buildchain paper preflight --json
+buildchain paper status --json
 ```
 
-This mirrors web-surface governance without mixing producer and renderer
-responsibilities.
+For schema-2 Paper repositories, preflight and status check local product policy
+and exact caller bytes. They return `localOnly: true` and
+`publication.status: "not-observed"`. They do not contact npm or GitHub accounts,
+and their success does not prove hosted admission, a successful build or a
+published release.
+
+Open a PR on the configured protected channel route to request delivery or
+publication. Supply the common repository permissions and tool-maintained
+runtime locks required by the published entry. Recover a failed operation using
+its exact attempt identifier in the shared recovery workflow. An optional
+repaired runtime applies to that recovery; do not persist it in product callers.
+
+## Existing papers and downstream sites
+
+The former schema-1 npm-paper scaffold used separate product workflows and
+repository-side control records. It is no longer generated for new papers.
+Moving an existing paper to this contract changes its publication target to PDF
+assets in GitHub Releases. Review that target change and downstream consumption
+before migrating an existing repository; `init --force` does not absorb old
+workflows or silently convert their product behavior.
+
+`buildchain paper migrate --json` plans the conversion from a clean committed
+source. It retains declared build/verification commands, moves publication
+metadata into `paper/publication-metadata.json`, and makes the private source
+package's version authoritative. `--write` applies the reviewed changes and
+removes only recognized legacy callers and digest-checked controller files.
+Custom workflows, conflicting version authorities, extra configuration sections,
+and unrepresentable lifecycle settings fail before writing. Runtime locks and
+historical receipts remain byte-identical; channel-root overrides are retired.
+A later source change invalidates the plan. Refresh the dependency lockfile if
+the plan updates an optional local Buildchain CLI dependency.
+
+Keep already published npm versions, original PDF bytes and retained publication
+receipts as historical evidence. A new local configuration does not rewrite or
+requalify those releases. Existing append-only archives retain their immutability
+rules. Sites own rendering, navigation and archive import; they must consume the
+actual selected release and its evidence rather than infer a new npm publication
+from a Paper configuration or successful local check.
+
+## Retired Paper execution commands
+
+The schema-2 Paper interface no longer exposes `paper bootstrap npm`,
+`paper build`, `paper alpha`, or `paper resume`. These commands depended on
+legacy publication configuration and separate workflow wiring. Use the product
+build/verification commands declared in TOML, a legal channel PR to request
+publication, and the generated recovery caller with an exact attempt. The
+generic product reproducibility tools remain available; this change does not
+rewrite published artifacts or historical receipts. Legacy status/preflight
+readers direct users to the migration preview.