@kungfu-tech/buildchain 2.11.1 → 2.11.2-alpha.1

package/dist/site/page-registry.json

@@ -711,7 +711,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/MAP.md",
-      "digest": "sha256:795464d3d84af5698b19a26821dbd16040c258b708e070daaaba6d55e6ad81f7",
+      "digest": "sha256:7e1b72dfc0ad91323156295617e320fee94a644efee54667b017e690fcebf64e",
       "headings": [
         {
           "level": 1,
@@ -739,7 +739,7 @@
           "anchor": "how-this-map-is-maintained"
         }
       ],
-      "markdown": "# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v2 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| 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) |\n| 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) |\n| 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) |\n| 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) |\n| Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| 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) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, and site-consumable manifests? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |\n| How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **v2.1 vs v2.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v2` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
+      "markdown": "# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v2 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| 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) |\n| 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) |\n| 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) |\n| 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) |\n| Floating `@v2` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| 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) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I audit public KFD-2 release trust claims? | [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I keep `@v2` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, and site-consumable manifests? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |\n| How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **v2.1 vs v2.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v2` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
     },
     {
       "id": "manual:migration-inventory",
@@ -902,7 +902,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:f8fa6cf7a5f5aae6b42013e865bbc249c6d7634ab73f017295fbbec680254364",
+      "digest": "sha256:1088128dc3773bfeb6ed0e619eaae3096987e1f02a8eb3f0d0415cf903cfa682",
       "headings": [
         {
           "level": 1,
@@ -930,7 +930,7 @@
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reusable Workflow\n\nConsumer repositories can call the Buildchain wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v2\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nThe wrapper is build-only. It does not publish npm packages, deploy web pages,\nor create GitHub Releases. Release publication can be layered later by a\nrepository-specific governance workflow that attaches the generated manifest\nand passport as release assets.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publish-transaction",
@@ -1501,7 +1501,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/site-bundle-contract.md",
-      "digest": "sha256:6b5bc2ee0f785b16d762f140f14a9163c07caf0d424200c2ececc74f7bb2271c",
+      "digest": "sha256:d67a874b356fbfbee9a5d5ece7021fb52b2848347dc6a14f5562c98570096916",
       "headings": [
         {
           "level": 1,
@@ -1539,7 +1539,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  capability-registry.json\n  cli-registry.json\n  manual-registry.json\n  node-api-registry.json\n  workflow-registry.json\n  public-surface-audit.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`capability-registry.json` is the navigation spine for that page surface. It\ngroups manuals, pages, CLI commands, workflows, actions, Node API exports, and\nKFD claim facts into stable product capability groups. Site repositories should\nrender navigation from this registry first, then use `page-registry.json`,\n`manual-registry.json`, `cli-registry.json`, `node-api-registry.json`, and\n`workflow-registry.json` for the concrete entries inside each group.\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`public-surface-audit.json` is the reverse enumeration report for those\nsurfaces. It enumerates real CLI commands from `bin/buildchain.mjs`, workflow\ninputs, action inputs, site pages, and documentation command references, then\ncompares those sets with `cli-registry.json`, `workflow-registry.json`, and\n`page-registry.json`. Buildchain's self-check fails closed when an enumerable\npublic surface is missing from the generated registries.\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- capability-grouped navigation facts for docs, CLI, Node API, workflows,\n  actions, and KFD claims;\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  publication-registry.json\n  capability-registry.json\n  cli-registry.json\n  manual-registry.json\n  node-api-registry.json\n  workflow-registry.json\n  public-surface-audit.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`capability-registry.json` is the navigation spine for that page surface. It\ngroups manuals, pages, CLI commands, workflows, actions, Node API exports, and\nKFD claim facts into stable product capability groups. Site repositories should\nrender navigation from this registry first, then use `page-registry.json`,\n`manual-registry.json`, `cli-registry.json`, `node-api-registry.json`, and\n`workflow-registry.json` for the concrete entries inside each group.\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`public-surface-audit.json` is the reverse enumeration report for those\nsurfaces. It enumerates real CLI commands from `bin/buildchain.mjs`, workflow\ninputs, action inputs, site pages, and documentation command references, then\ncompares those sets with `cli-registry.json`, `workflow-registry.json`, and\n`page-registry.json`. Buildchain's self-check fails closed when an enumerable\npublic surface is missing from the generated registries.\n`publication-registry.json` is the package-owned publication archive registry\nfor downstream papers surfaces. Site repositories can render latest reader\nroutes, immutable version artifact routes, source bundles, and publication\npassport links from this file instead of keeping their own fixture registry.\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- capability-grouped navigation facts for docs, CLI, Node API, workflows,\n  actions, and KFD claims;\n- complete markdown page registry for public Buildchain docs, action manuals,\n  Node API overview, and fixtures;\n- site manifest;\n- publication archive registry for downstream papers surfaces;\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`publication-registry.json` is the static site-consumption entrypoint for\npublication archive pages. It uses the\n`kungfu-buildchain-publication-release-registry` contract and declares the\nmutable latest/canonical routes separately from append-only immutable version\nprefixes.\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",

package/dist/site/public-surface-audit.json

@@ -2450,7 +2450,7 @@
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "53833f92021caa7cc5feaff5d21f38b0a77317ace11a43795be180d1dec3699f",
     "workflowRegistryDigest": "67572429a83124370b9ffd46f56923aa2b252873c9624ded39a26675fb0ee815",
-    "pageRegistryDigest": "14b3d852445462c23c9c48d786844353a8c3e2764092323fabe60dcab9e39aae"
+    "pageRegistryDigest": "3a041b5802183d5a9559a415645b03f582a1e4808b4ba5713484e6941956d35e"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -0,0 +1,109 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-publication-release-registry",
+  "generatedAt": "2026-07-09T15:39:27.573Z",
+  "publishedAt": "2026-07-09T15:39:27.573Z",
+  "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": "2e87aaee5e94ac19ac676c3999349c55b8253730",
+  "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."
+  },
+  "package": {
+    "name": "@kungfu-tech/buildchain",
+    "version": "2.11.2-alpha.1",
+    "versionSource": "package.json#version"
+  },
+  "sourceKind": "package-site-bundle",
+  "sourceBoundary": {
+    "truthOwner": "@kungfu-tech/buildchain",
+    "siteRole": "rendering, routing, archive preservation checks, and agent discovery",
+    "rule": "Downstream papers sites render this registry; Buildchain owns publication route, latest, immutable artifact, passport, and source bundle facts."
+  },
+  "archivePolicy": {
+    "contract": "kungfu-buildchain-publication-archive-policy",
+    "mutableRouteKinds": [
+      "canonical-reader",
+      "latest",
+      "registry-index"
+    ],
+    "immutableRouteKinds": [
+      "version-artifact",
+      "version-passport",
+      "version-source"
+    ],
+    "deploymentBoundary": "append-only immutable version prefixes",
+    "rule": "A site build may update latest and canonical reader pages, but it must not delete or overwrite files under a declared immutable version prefix."
+  },
+  "publications": [
+    {
+      "id": "publication-archive-fixture",
+      "title": "Publication Archive Fixture",
+      "summary": "A paper-shaped Buildchain package fact proving that site rendering preserves immutable versioned PDF, source, and passport routes while latest pages can move.",
+      "canonicalReader": {
+        "kind": "canonical-reader",
+        "url": "https://kungfu.tech/whitepaper/",
+        "owner": "site-kungfu-tech"
+      },
+      "latest": {
+        "kind": "latest",
+        "version": "0.1.0",
+        "path": "/publication-archive-fixture/latest/"
+      },
+      "immutablePrefixTemplate": "/publication-archive-fixture/v{version}/",
+      "versions": [
+        {
+          "version": "0.1.0",
+          "releasedAt": "2026-07-09T00:00:00.000Z",
+          "immutable": true,
+          "immutablePath": "/publication-archive-fixture/v0.1.0/",
+          "source": {
+            "repository": "https://github.com/kungfu-systems/publication-archive-fixture",
+            "tag": "v0.1.0",
+            "commit": "0000000000000000000000000000000000000000",
+            "bundle": {
+              "path": "source.tar.gz",
+              "sha256": "sha256:e2ca891dbf441f867ed135b21b3556ee5cdcd3ec80038f267a3ecff496c5a38b",
+              "fixtureBodyBase64": "c2l0ZS1saWJrdW5nZnUtZGV2IHB1YmxpY2F0aW9uIGFyY2hpdmUgZml4dHVyZSBzb3VyY2UgYnVuZGxlCnZlcnNpb246IDAuMS4wCg=="
+            }
+          },
+          "passport": {
+            "path": "publication-artifact-passport.json",
+            "sha256": "sha256:ca214e2e17c8d3c01565e507e57d5b440943c762199aa8d9de21995940538cea",
+            "fixtureBodyBase64": "ewogICJjb250cmFjdCI6ICJrdW5nZnUtYnVpbGRjaGFpbi1wdWJsaWNhdGlvbi1hcnRpZmFjdC1wYXNzcG9ydCIsCiAgInB1YmxpY2F0aW9uIjogInB1YmxpY2F0aW9uLWFyY2hpdmUtZml4dHVyZSIsCiAgInZlcnNpb24iOiAiMC4xLjAiLAogICJzdGF0dXMiOiAiZml4dHVyZSIKfQo="
+          },
+          "artifacts": [
+            {
+              "role": "pdf",
+              "path": "main.pdf",
+              "mediaType": "application/pdf",
+              "sha256": "sha256:c1c2020cbdcf0cc339323d2276480a48d9b8d7da9be1d19ab58a0b3c0b7a4fbb",
+              "fixtureBodyBase64": "JVBERi0xLjQKJSBzaXRlLWxpYmt1bmdmdS1kZXYgcHVibGljYXRpb24gYXJjaGl2ZSBmaXh0dXJlCjEgMCBvYmogPDwgL1R5cGUgL0NhdGFsb2cgL1BhZ2VzIDIgMCBSID4+IGVuZG9iagoyIDAgb2JqIDw8IC9UeXBlIC9QYWdlcyAvS2lkcyBbMyAwIFJdIC9Db3VudCAxID4+IGVuZG9iagozIDAgb2JqIDw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgMzAwIDE0NF0gL0NvbnRlbnRzIDQgMCBSID4+IGVuZG9iago0IDAgb2JqIDw8IC9MZW5ndGggNzIgPj4gc3RyZWFtCkJUIC9GMSAxMiBUZiAzNiAxMDAgVGQgKFB1YmxpY2F0aW9uIGFyY2hpdmUgZml4dHVyZSB2MC4xLjApIFRqIEVUCmVuZHN0cmVhbSBlbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmIAp0cmFpbGVyIDw8IC9Sb290IDEgMCBSIC9TaXplIDUgPj4Kc3RhcnR4cmVmCjM2MAolJUVPRgo="
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/site/release-provenance.json

@@ -32,6 +32,7 @@
       "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",
+      "./site/publication-registry.json": "./dist/site/publication-registry.json",
       "./site/page-registry.json": "./dist/site/page-registry.json",
       "./site/capability-registry.json": "./dist/site/capability-registry.json",
       "./site/cli-registry.json": "./dist/site/cli-registry.json",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-09T11:53:37.992Z",
-  "publishedAt": "2026-07-09T11:53:37.992Z",
+  "generatedAt": "2026-07-09T15:39:27.573Z",
+  "publishedAt": "2026-07-09T15:39:27.573Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "eca0282a03517a31383b533e27a7ee09c46a8392",
+  "sourceRevision": "2e87aaee5e94ac19ac676c3999349c55b8253730",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.1",
+    "version": "2.11.2-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:795464d3d84af5698b19a26821dbd16040c258b708e070daaaba6d55e6ad81f7"
+      "digest": "sha256:7e1b72dfc0ad91323156295617e320fee94a644efee54667b017e690fcebf64e"
     },
     {
       "id": "install",
@@ -141,7 +141,7 @@
       "path": "docs/site-bundle-contract.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:6b5bc2ee0f785b16d762f140f14a9163c07caf0d424200c2ececc74f7bb2271c"
+      "digest": "sha256:d67a874b356fbfbee9a5d5ece7021fb52b2848347dc6a14f5562c98570096916"
     },
     {
       "id": "migration-inventory",
@@ -267,6 +267,7 @@
     "release-model.json",
     "artifact-schemas.json",
     "badge-endpoint-registry.json",
+    "publication-registry.json",
     "product-mechanism.json",
     "release-provenance.json",
     "kfd-upstream-aggregate.json",

package/docs/MAP.md

@@ -31,7 +31,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Reusable Build and Lifecycle | `workflow-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |
 | KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |
 | Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |
-| Publication Artifacts | `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
+| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
 | Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |
 | Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |
 | Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md) |
@@ -48,7 +48,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | 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) |
 | GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |
 | release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |
-| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |
+| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |
 | Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |
 | Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |
 | Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |

package/docs/publication-artifacts.md

@@ -176,6 +176,24 @@ without rebuilding old PDFs from the latest npm package or paper source.
 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:
 

package/docs/site-bundle-contract.md

@@ -13,6 +13,7 @@ release mechanics, command registry, workflow registry, or artifact schema.
 dist/site/
   buildchain-site.json
   site-manifest.json
+  publication-registry.json
   capability-registry.json
   cli-registry.json
   manual-registry.json
@@ -65,6 +66,10 @@ inputs, action inputs, site pages, and documentation command references, then
 compares those sets with `cli-registry.json`, `workflow-registry.json`, and
 `page-registry.json`. Buildchain's self-check fails closed when an enumerable
 public surface is missing from the generated registries.
+`publication-registry.json` is the package-owned publication archive registry
+for downstream papers surfaces. Site repositories can render latest reader
+routes, immutable version artifact routes, source bundles, and publication
+passport links from this file instead of keeping their own fixture registry.
 
 ## Timestamp and Reproducibility Policy
 
@@ -138,6 +143,7 @@ The P0 bundle includes:
 - complete markdown page registry for public Buildchain docs, action manuals,
   Node API overview, and fixtures;
 - site manifest;
+- publication archive registry for downstream papers surfaces;
 - CLI command registry;
 - manual registry for packaged agent-facing documentation;
 - Node API registry for public package exports;
@@ -160,6 +166,11 @@ schema metadata without breaking existing consumers.
 release chain model. The site bundle exposes that document and the
 `release-propagation` CLI entry so downstream sites can render the current
 Buildchain-owned propagation contract instead of hand-writing it.
+`publication-registry.json` is the static site-consumption entrypoint for
+publication archive pages. It uses the
+`kungfu-buildchain-publication-release-registry` contract and declares the
+mutable latest/canonical routes separately from append-only immutable version
+prefixes.
 
 ## Rendering Boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.1",
+  "version": "2.11.2-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -35,6 +35,7 @@
     "./buildchain-kfd-claims": "./packages/core/buildchain-kfd-claims.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
+    "./site/publication-registry.json": "./dist/site/publication-registry.json",
     "./site/page-registry.json": "./dist/site/page-registry.json",
     "./site/capability-registry.json": "./dist/site/capability-registry.json",
     "./site/cli-registry.json": "./dist/site/cli-registry.json",

package/packages/core/buildchain-kfd-claims.js

@@ -42,6 +42,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
 const SITE_CONTRACT_FILES = Object.freeze([
   "dist/site/buildchain-site.json",
   "dist/site/site-manifest.json",
+  "dist/site/publication-registry.json",
   "dist/site/page-registry.json",
   "dist/site/capability-registry.json",
   "dist/site/cli-registry.json",
@@ -268,6 +269,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "dist/site/node-api-registry.json",
         "dist/site/page-registry.json",
         "dist/site/capability-registry.json",
+        "dist/site/publication-registry.json",
         "dist/site/buildchain-site.json",
         "dist/site/site-manifest.json",
       ],

package/packages/core/kfd-gate.js

@@ -1,9 +1,10 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { createRequire } from "node:module";
 
-const require = createRequire(import.meta.url);
+import kfdPackageJson from "@kungfu-tech/kfd/package.json" with { type: "json" };
+import kfdStandards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
+import kfdTrustTaxonomySchema from "@kungfu-tech/kfd/schemas/kfd-2/trust-taxonomy.schema.json" with { type: "json" };
 
 export const KFD1_RELEASE_GATE_CONTRACT = "kungfu-buildchain-kfd-1-release-gate";
 export const KFD1_WITNESS_SET_CONTRACT = "kungfu-buildchain-kfd-1-witness-set";
@@ -54,8 +55,21 @@ export function sha256File(filePath) {
   return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
 }
 
+const bundledKfdJsonExports = new Map([
+  ["@kungfu-tech/kfd/package.json", kfdPackageJson],
+  ["@kungfu-tech/kfd/standards.json", kfdStandards],
+  ["@kungfu-tech/kfd/schemas/kfd-2/trust-taxonomy.schema.json", kfdTrustTaxonomySchema],
+]);
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
 function readJsonPackageExport(exportPath) {
-  return JSON.parse(fs.readFileSync(require.resolve(exportPath), "utf8"));
+  if (!bundledKfdJsonExports.has(exportPath)) {
+    throw new Error(`KFD metadata package export is not bundled into Buildchain release gates: ${exportPath}`);
+  }
+  return cloneJson(bundledKfdJsonExports.get(exportPath));
 }
 
 function tryReadJsonPackageExport(exportPath) {

package/scripts/check-inventory.mjs

@@ -298,6 +298,10 @@ if (siteBundle.package?.version !== rootPackage.version) {
 if (siteManifest.package?.version !== rootPackage.version) {
   throw new Error("site-manifest.json package.version must match package.json version");
 }
+const publicationRegistry = JSON.parse(fs.readFileSync(path.join(root, "dist/site/publication-registry.json"), "utf8"));
+if (publicationRegistry.package?.version !== rootPackage.version) {
+  throw new Error("publication-registry.json package.version must match package.json version");
+}
 if (siteBundle.source?.homepageTextSource !== "README.md") {
   throw new Error("buildchain-site.json source.homepageTextSource must be README.md");
 }
@@ -909,7 +913,7 @@ if (!badgeEndpointRegistry.badges?.some((entry) => entry.id === "buildchain-rele
   throw new Error("badge endpoint registry must include Buildchain Release Passport badge");
 }
 
-for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
+for (const siteFile of ["buildchain-site.json", "site-manifest.json", "badge-endpoint-registry.json", "publication-registry.json", "page-registry.json", "capability-registry.json", "cli-registry.json", "manual-registry.json", "node-api-registry.json", "workflow-registry.json", "public-surface-audit.json", "release-model.json", "buildchain-contract.json"]) {
   if (!fs.existsSync(path.join(root, "dist", "site", siteFile))) {
     throw new Error(`site bundle missing ${siteFile}`);
   }