code-foundry 1.20.1 → 1.22.1

package/docs/PERFORMANCE.md

@@ -1,66 +1,74 @@
 # Performance budgets and baselines
 
-Code Foundry measures its source runtime with `bun run performance:check`. The
-check writes `performance-results.json` for CI artifact upload and fails when a
-budget is exceeded. Generated reports are ignored by Git because measurements
-belong to the run that produced them, not the source tree.
+Code Foundry measures its own runtime with `bun run performance:check`. The
+check writes `performance-results.json` for artifact upload and fails when a
+budget is exceeded. Reports are generated-run evidence and are ignored by Git.
 
 ## Enforced budgets
 
-| Metric                              | Budget | Why it is bounded                                    |
-| ----------------------------------- | -----: | ---------------------------------------------------- |
-| CLI help startup p95                | 250 ms | Detect eager imports and startup regressions         |
-| Runtime mode startup p95            | 250 ms | Detect baseline runtime initialization regressions   |
-| Focused runtime tests               |   10 s | Keep the representative runtime contract inexpensive |
-| Format, lint, type-check, and build |   15 s | Bound the local CI feedback loop                     |
-| Runtime dependencies                |      0 | Keep the installed CLI dependency-free               |
-| Development dependencies            |      4 | Prevent unreviewed toolchain growth                  |
-| Packed artifact                     | 255 kB | Bound registry transfer and install cost             |
-| Unpacked artifact                   | 965 kB | Bound installed footprint                            |
-| Packed files                        |    115 | Detect accidental release contents                   |
+| Metric                              |   Budget | Why it is bounded                                    |
+| ----------------------------------- | -------: | ---------------------------------------------------- |
+| CLI help startup p95                |   250 ms | Detect eager imports and startup regressions         |
+| Runtime mode startup p95            |   250 ms | Detect baseline runtime initialization regressions   |
+| Focused runtime tests               |     10 s | Keep the representative runtime contract inexpensive |
+| Format, lint, type-check, and build |     15 s | Bound the local CI feedback loop                     |
+| Runtime dependencies                |        0 | Keep the installed CLI dependency-free               |
+| Development dependencies            |        4 | Prevent unreviewed toolchain growth                  |
+| Packed artifact                     |   260 kB | Bound registry transfer and install cost             |
+| Unpacked artifact                   | 1,000 kB | Bound installed footprint                            |
+| Packed files                        |      115 | Detect accidental release contents                   |
+
+The source-of-truth budgets live in `scripts/performance-check.mjs`. When those
+limits change, update this table and include before/after measurements in the
+same change. The Cloudflare delivery and qualified-publication changes in this release
+moved the measured artifact from 990,481 to 994,555 unpacked bytes (257,384 to
+258,647 packed bytes, with 112 files in both measurements). Draft protection
+configuration, reusable-workflow inputs, documentation, and regression tests
+increased the measured artifact to 998,348 unpacked bytes (259,532 packed bytes,
+with 112 files). The unpacked budget is therefore 1,000 kB; the packed and
+file-count budgets remain unchanged.
 
 The performance workflow disables build-cache reads and writes for this task.
-That makes timing comparisons independent of a warm protected-branch cache and
-prevents benchmark code from populating shared cache entries.
-
-The merged candidate includes the release-integrity verifier, fleet eligibility,
-consumer qualification harness, product-quality profiles, qualified publication
-workflow, and opt-in merge-queue verifier. It measured 248,464 packed bytes,
-947,310 unpacked bytes, and 111 files on Node 24.18.0; the 255 kB, 965 kB, and
-115-file limits retain a small margin while continuing to bound package growth.
-
-## v1.6.1 baseline
-
-Measurements were taken on 2026-09-08 with Node 24.18.0. Process startup used
-30 measured samples after four warmups; before and after samples were
-interleaved on the same host.
-
-| Measurement                |   Before |                   After |   Change |
-| -------------------------- | -------: | ----------------------: | -------: |
-| CLI help median            | 36.11 ms |                29.57 ms |   -18.1% |
-| CLI help p95               | 38.11 ms |                31.56 ms |   -17.2% |
-| Runtime mode median        |        - |                35.94 ms | baseline |
-| Focused runtime tests      |        - |                  2.08 s | baseline |
-| Local CI checks            |        - |                  0.50 s | baseline |
-| Packed / unpacked artifact |        - | 160,114 / 616,887 bytes | baseline |
-| Packed files               |        - |                      74 | baseline |
-
-The startup reduction comes from loading command implementations only after
-argument parsing selects a command. `--help` no longer imports sync, release,
-fleet, doctor, and CI command modules.
-
-The first isolated full hosted audit completed in 3 minutes 2 seconds. Its
-longest jobs were TypeScript CodeQL (66 s), dependency audit (62 s), and unit
-tests (46 s); all other suite jobs completed in 20 seconds or less. Those
-measurements identify the three lanes to optimize before adding more CI fanout.
-
-## Release path
-
-Treat budget changes like source changes: explain the measured reason in a
-pull request, run the complete validation gate, and merge only when the new
-result artifact is available. A Release Please PR then carries the change into
-the next version. Never raise a budget solely to clear CI; include before/after
-measurements and the expected effect on local feedback, hosted runner time,
-package transfer, or installed footprint. The current budget covers the measured
-combined release-integrity, fleet, consumer-qualification, and product-quality
-package footprint described above.
+Timing comparisons therefore do not depend on a warm protected-branch cache, and
+benchmark code cannot populate shared cache entries.
+
+## Package profile
+
+The reusable performance job also supports the opt-in `node-package` profile.
+Configure it in `.github/code-foundry.yml`:
+
+```yaml
+performance: true
+performance_profile: node-package
+performance_budget_file: performance-package-budgets.json
+```
+
+The profile measures cold imports, memory, package size, file counts, and
+production dependency count according to a repository-owned JSON budget file.
+It writes `performance-results/node-package.json`. Every run also writes
+`performance-results/summary.json`, which records repository-owned commands and
+configured performance commands under one stable artifact contract.
+
+## Native Rust test batching
+
+Each Rust test category invokes Cargo once with tracked targets: unit tests use
+`--lib`/`--bin <package>`, while integration, E2E, and smoke tests use repeated
+`--test <target>` arguments. Cargo shares setup without competing processes.
+
+Discovery, category boundaries, fallback behavior, scripts, Python checks, flags,
+and receipts remain unchanged. `--tests` and `--all-targets` stay avoided to
+prevent broader or repeated coverage. Measure cold and warm runs, including
+compilation and cache transfer, before claiming a speedup.
+
+## Changing a budget
+
+Treat budget changes like source changes:
+
+1. capture before/after measurements;
+2. explain the effect on local feedback, runner time, package transfer, or
+   installed footprint;
+3. run the complete validation gate; and
+4. inspect the resulting performance artifact.
+
+Never raise a limit solely to clear CI. Keep network-dependent checks, live
+endpoints, and post-deployment probes in separate repository-owned workflows.

package/docs/PUBLISHING.md

@@ -1,13 +1,21 @@
 # Publishing packages
 
-## npm
+Code Foundry separates versioning, GitHub Releases, and registry publication.
+Choose the release path that matches the repository:
+
+- **Generated consumer caller:** Release Please creates the GitHub Release and
+  the standard `release.yml` job can publish npm when `npm_publish: true`.
+- **Code Foundry itself:** `release_self-ci.yml` qualifies the package, stages
+  the exact archive on an immutable draft release, and delegates final npm
+  publication to `qualified-foundry-publish.yml`.
+
+## npm publication for consumer repositories
 
 Set `npm_publish: true` only when the repository owns an npm package. Configure
-npm trusted publishing for the repository's `release.yml` workflow whenever
-possible. An `NPM_TOKEN` secret is the fallback for registries or repositories
-that cannot use trusted publishing.
+npm trusted publishing for the generated `release.yml` workflow whenever
+possible. Use an `NPM_TOKEN` secret only when trusted publishing is unavailable.
 
-The package should define its intended visibility explicitly:
+Declare the package's intended visibility explicitly:
 
 ```json
 {
@@ -22,26 +30,43 @@ publish. The release workflow fails clearly when npm publication is enabled but
 neither trusted publishing nor a token is configured.
 
 After enabling publication, make one controlled release and verify both the
-registry version and the provenance link before treating the repository as
-fully configured.
+registry version and its provenance link before treating the setup as complete.
+
+## Code Foundry's qualified publication
+
+The self-hosted package follows a stricter contract than generated consumer
+callers:
+
+1. Pack the candidate once and qualify that archive across Node 20, 22, and 24.
+2. Create a draft GitHub Release and attach the exact qualified archive plus its
+   qualification receipt.
+3. Publish the immutable GitHub Release after verifying the tag, source commit,
+   archive digest, immutable-release setting, and qualification reports.
+4. Publish the already-qualified archive through the qualified publisher using npm
+   trusted publishing or the optional token fallback.
+
+The final publisher does not rebuild or reinstall the package. It publishes only
+the bytes selected from the same workflow run and attempt. See [Consumer
+qualification](consumer-qualification.md) and [Qualified publication](qualified-publication.md)
+for the complete contract, retries, and recovery rules.
 
 ## GitHub Releases and GitHub Packages
 
-A GitHub Release is release metadata attached to a Git tag. It is independent
-of the npm registry and of GitHub Packages.
+A GitHub Release is metadata attached to a Git tag. It is independent of npm and
+of GitHub Packages.
 
-Publishing to npm does not populate the repository's GitHub Packages section.
-If a repository also needs a GitHub Container Registry or npm-compatible
-GitHub Package, add a repository-owned publishing workflow and credentials;
-that is an optional extension rather than part of the universal baseline.
+Publishing to npm does not populate the repository's GitHub Packages section. If
+a repository also needs GitHub Container Registry or an npm-compatible GitHub
+Package, add a repository-owned publishing workflow and credentials.
 
 ## Provenance and verification
 
 Prefer trusted publishing because it provides short-lived credentials and
 provenance. After a release, verify:
 
-```bash
+```sh
 npm view PACKAGE_NAME version dist-tags
+# Replace VERSION with the published tag.
 gh release view vVERSION
 ```
 

package/docs/README.md

@@ -1,27 +1,42 @@
 # Documentation
 
-These guides describe the reusable repository baseline in provider-neutral
-terms. They are suitable for copying into another repository and adapting with
-its own names, environments, and deployment details.
-
-## Guides
-
-- [Initialization and synchronization](INITIALIZATION.md)
-- [Configuration reference](CONFIGURATION.md)
-- [Workflow and CI conventions](WORKFLOWS.md)
-- [Release management](RELEASES.md)
-- [Release integrity and build provenance](release-integrity.md)
-- [Publishing packages](PUBLISHING.md)
-- [Caching and remote caching](CACHING.md)
-- [Performance budgets and baselines](PERFORMANCE.md)
-- [Required capabilities and task evidence](required-capabilities.md)
-- [Product quality profiles](product-quality.md)
-- [Agent-facing validation commands](agent-validation.md)
-- [Declarative fleet inventory and staged rollouts](fleet-rollouts.md)
+Code Foundry's documentation is organized by the job you are trying to do. Most
+guides describe the reusable baseline; platform-specific guides call out their
+provider assumptions. Adapt repository names, environments, and deployment
+details before copying any guide elsewhere.
+
+## Start here
+
+- [Initialization and synchronization](INITIALIZATION.md) — install, update, and diagnose a baseline.
+- [Configuration reference](CONFIGURATION.md) — choose workflows, runtimes, validation, and release policy.
+- [Workflow and CI conventions](WORKFLOWS.md) — understand triggers, checks, runners, caching, and branch protection.
+- [Extension points](EXTENSIONS.md) — keep custom workflows and post-release delivery alongside the baseline.
+
+## Validation and quality
+
+- [Agent-facing validation](agent-validation.md) — run local plans and checks with machine-readable evidence.
+- [Required capabilities and task evidence](required-capabilities.md) — require tasks, coverage, and retained receipts.
+- [Performance budgets](PERFORMANCE.md) — maintain runtime, CI, and package-size budgets.
+- [Product quality profiles](product-quality.md) — add acceptance checks for sites, apps, Workers, and packages.
+- [Merge queue validation](merge-queues.md) — validate GitHub merge-group commits.
+
+## Releases and publishing
+
+- [Release management](RELEASES.md) — branch topologies, Release Please, and release permissions.
+- [Publishing packages](PUBLISHING.md) — npm, GitHub Releases, and provenance guidance.
+- [Release integrity and build provenance](release-integrity.md) — immutable releases, verification, and attestations.
+- [Consumer qualification](consumer-qualification.md) — test the packaged release across consumer fixtures.
+- [Qualified publication](qualified-publication.md) — publish the exact qualified Code Foundry archive.
+
+## Fleet and deployment operations
+
+- [Declarative fleet rollouts](fleet-rollouts.md) — inventory, canaries, staged upgrades, and recovery.
+- [Fleet release eligibility](fleet-release-eligibility.md) — require verified release evidence before upgrades.
+- [Verified Cloudflare delivery](cloudflare-delivery.md) — build, verify, canary, and promote Worker versions.
+- [Caching and remote caching](CACHING.md) — configure package, build, and Turborepo caching.
 
 ## Repository-specific documentation
 
-Add project-specific guides, architecture notes, runbooks, and deployment
-instructions to this directory. The Code Foundry initializer preserves `docs/`
-files during synchronization. Prefer clear, task-oriented filenames and link
-new documents from this index when they become part of the supported workflow.
+Add architecture notes, runbooks, and deployment instructions to this directory.
+The initializer preserves `docs/` during synchronization. Link supported guides
+from this index and prefer task-oriented filenames.

package/docs/RELEASES.md

@@ -25,13 +25,17 @@ the `staging` → `main` promotion PR merges with **rebase** (`merge_strategy:
 rebase`), and Release Please version PRs merge with **rebase**
 (`release_merge_strategy: rebase`). In the `direct` topology, feature and fix
 branches squash straight into `main` and Release Please version PRs squash into
-`main` (`release_merge_strategy: squash`). `merge_strategy` is not enforced. Release automation never defaults
-to a merge method and never merges with `--admin`: `staging-release` accepts
-only rebase for release PRs, while `direct` requires squash.
+`main` (`release_merge_strategy: squash`). `sync`, `doctor`, and release
+automation reject any other strategy. Release automation never defaults to a
+merge method and never merges with `--admin`.
 
 The release workflow opens or updates a versioned PR after changes reach
-`main`. Merging that PR updates the changelog, creates the Git tag and GitHub
-Release, and triggers any configured package publication.
+`main`. For generated consumer callers, merging that PR updates the changelog,
+creates the Git tag and GitHub Release, and can trigger npm publication. Code
+Foundry's own caller uses the qualified path: it qualifies the package first,
+creates a draft release, stages the exact qualified archive, then publishes the
+immutable release and package through the verified publisher. See [Qualified
+publication](qualified-publication.md).
 
 For an explicit version, put `Release-As: 2.0.0` in a commit or pull request
 body. Existing `CHANGELOG.md` history remains repository-owned.
@@ -134,7 +138,12 @@ already passed).
 ## Operational checklist
 
 1. Merge tested changes into `main` (direct: feature PRs; staging-release: promote `staging` into `main`).
-2. Review the generated Release Please PR and changelog.
-3. Merge the release PR with squash in the direct topology (`release_merge_strategy: squash`).
-4. Confirm the GitHub Release and any package publication.
-5. staging-release only: synchronize `staging` with the new `main` release commit.
+2. Review the generated Release Please PR and changelog. A validated
+   `CODE_FOUNDRY_TOKEN` lets the release workflow merge it automatically after
+   required checks; without that token, merge it manually with the configured
+   topology method: squash for `direct`, rebase for `staging-release`.
+3. For a generated consumer caller, confirm the GitHub Release and any package
+   publication.
+4. For Code Foundry itself, confirm qualification, draft staging, immutable
+   publication, and the retained identity receipts.
+5. In `staging-release`, synchronize `staging` with the new `main` release commit.

package/docs/WORKFLOWS.md

@@ -52,6 +52,12 @@ opens those PRs as drafts. Promotion automation listens to `staging` pushes
 automation and default-branch CodeQL listen to `main` pushes.
 Custom deployment, indexing, search, Slither, or other workflows are
 repository-owned extensions and should use the same ready-transition policy.
+Code Foundry's runner-heavy validation, security, qualification, and Cloudflare
+reusable workflows also enforce draft protection at the job boundary. Generated
+callers default to the `draft_protection: true` configuration; set it to `false`
+to run generated gates for drafts. Cloudflare callers use their equivalent
+`draft-protection: false` input. These opt-outs do not remove Draft Guard or
+draft-PR automation; they only allow the protected gates to run for drafts.
 
 ## Billing pause
 
@@ -112,6 +118,11 @@ opt in or out without a code change.
 | Release PR  | Promote `staging` into `main` (staging-release topology only)     |
 | Release     | Release Please, GitHub release, and optional npm publication      |
 
+Generated consumer callers use the standard Release workflow. Code Foundry's
+own `release_self-ci.yml` adds consumer qualification, draft-release staging,
+immutable-release verification, and qualified npm publication; see [Qualified
+publication](qualified-publication.md).
+
 Use concise job names such as `CI / Format`, `Test / Unit`, and
 `CodeQL / Analyze (Python)`. Per-language CodeQL analyzers (Rust shards
 included) and security audits run through a detection-built matrix, so a

package/docs/agent-validation.md

@@ -1,16 +1,17 @@
 # Agent-facing validation commands
 
-The public CLI now exposes a stable plan/check interface using the same discovery,
+The public CLI exposes a stable plan/check interface using the same discovery,
 required-capability policy, ecosystem executor, and task receipts as reusable CI.
 
 ```sh
-code-foundry plan --changed --base origin/main --json
-code-foundry check --tier fast --json
-code-foundry check --tier audit --json
+npx code-foundry plan --changed --base origin/main --json
+npx code-foundry check --tier fast --json
+npx code-foundry check --tier audit --json
 ```
 
 Both commands accept `--target PATH`. Use the Code Foundry version pinned by the
-repository, not an unreviewed floating installation. `plan` executes discovery
+repository, not an unreviewed floating installation; use your package manager's
+local binary when the package is installed as a dependency. `plan` executes discovery
 only: it does not install dependencies, run project checks, modify source files,
 or emit skip-receipt files. Required entrypoints are validated across the complete
 task set, including tasks deferred from the selected local tier.

package/docs/cloudflare-delivery.md

@@ -50,7 +50,11 @@ Wrangler version supporting `WRANGLER_OUTPUT_FILE_PATH` and version-1
 Bun remains the installation path, consistent with the existing deploy workflow.
 
 The repository verification command receives `BASE_URL` and
-`FOUNDRY_DEPLOYMENT_PHASE` (`candidate`, `canary`, or `production`). It must check
+`FOUNDRY_DEPLOYMENT_PHASE` (`candidate`, `canary`, or `production`). Preview
+candidate jobs skip draft pull requests by default. To intentionally deploy
+from drafts, pass `draft-protection: false` in the reusable-workflow call; this
+changes only the CI/deployment gate, not Draft Guard or draft-PR automation. It
+must check
 critical journeys, redirects, assets, and application-specific behavior. The
 built-in smoke probe requires a successful 2xx response and does not follow
 redirects. Deploy credentials are not supplied to verification steps and are
@@ -85,7 +89,10 @@ and new production workflows active.
 Outputs include preview URL, exact version ID, source SHA, declared build-tree
 SHA-256 digest, Cloudflare deployment ID, and GitHub application deployment ID.
 Explicit application deployment records receive in-progress and success/failure
-statuses, in addition to GitHub's environment-job records. Sanitized candidate and
+statuses, in addition to GitHub's environment-job records. For pull requests,
+the deployment record is associated with `github.event.pull_request.head.sha`,
+not GitHub Actions' merge commit, so GitHub can display the preview in the PR's
+Deployments section. Direct pushes use `github.sha`. Sanitized candidate and
 production JSON evidence is uploaded even on failure. Binding values, API bodies,
 and credentials are not copied into those reports. Forced runner termination may
 prevent final status steps; the GitHub job still reflects cancellation/failure.
@@ -164,13 +171,18 @@ the deployment API intentionally changes version routing only.
 
 ## Legacy workflow hardening
 
-`cloudflare-deploy.yml` now uses real job environments, non-cancelling concurrency,
+`cloudflare-deploy.yml` uses real job environments, non-cancelling concurrency,
 structured Wrangler output, exact/local Wrangler selection, reusable outputs, and
-in-progress/failure deployment records. Its legacy-compatible default remains
-`latest`; callers should prefer `local` or an exact version for reproducibility. A
-production URL can be supplied with `deployment-url` when API output contains only
-route patterns. It is still a **direct, unverified deployment**; adopt
-`cloudflare-delivery.yml` for candidate verification and guarded promotion.
+in-progress/failure deployment records. Its preview deployment records use the
+pull request head SHA when called from a PR, so completed previews appear in that
+PR's Deployments section; direct pushes use the workflow SHA. Its compatibility
+default remains `latest`; callers should prefer `local` or an exact version for
+reproducibility. A production URL can be supplied with `deployment-url` when API
+output contains only route patterns. It is still a **direct, unverified deployment**;
+adopt `cloudflare-delivery.yml` for candidate verification and
+guarded promotion. Consumers pinned to an older Code Foundry release must update
+their reusable workflow reference; existing deployments are not retroactively
+re-associated with the PR head commit.
 
 ## References and testing
 

package/docs/consumer-qualification.md

@@ -5,8 +5,9 @@ Release-candidate compatibility checks against the distributable package.
 **Status:** Opt-in reusable workflow; required by Code Foundry's own release caller.
 **Scope:** Package installation, CLI initialization/synchronization, generated workflow contracts.
 
-`consumer-qualification.yml` packs the checked-out candidate once, shares that archive across all supported
-Node majors using an artifact scoped to the same workflow run **and attempt**, installs it offline with lifecycle scripts disabled,
+`consumer-qualification.yml` packs the checked-out candidate once, shares that
+archive across Node 20, 22, and 24 using an artifact scoped to the same workflow
+run **and attempt**, and installs it offline with lifecycle scripts disabled,
 and executes its public CLI from the installed package. The harness does not
 import the source checkout's initializer as a substitute for package testing.
 
@@ -39,13 +40,14 @@ member. Reports are evidence, not signatures or a substitute for release identit
 verification.
 
 The self release caller cannot start Release Please or npm publication until all
-qualification jobs and the aggregate `Gate` succeed. An explicit `release-while-paused` dispatch is passed
-through to the reusable workflow; ordinary calls remain blocked by the billing pause.
-Consumer-generated release callers do not inherit this Code Foundry-specific
-qualification job. This does not yet guarantee that its legacy publishing job uses
-this same archive; the verified-publication workflow handles that separate
-requirement. No branch protections, repository settings, credentials, or consumer
-runtimes are changed by this feature.
+qualification jobs and the aggregate `Gate` succeed. An explicit
+`release-while-paused` dispatch is passed through to the reusable workflow;
+ordinary calls remain blocked by the billing pause. Consumer-generated release
+callers do not inherit this Code Foundry-specific qualification job. Code
+Foundry's self caller passes the qualified archive to the verified publication
+workflow, which independently rechecks the same bytes before publishing. No
+branch protections, repository settings, credentials, or consumer runtimes are
+changed by this workflow.
 
 ## Verified handoff and reruns
 

package/docs/fleet-release-eligibility.md

@@ -2,14 +2,12 @@
 
 Require a verified, qualified runtime before any fleet upgrade mutates repositories.
 
-**Dependency:** Installed release-integrity verifier (#537).
-**Activation:** Consumer-owned `.code-foundry-release-policy.json` at the fleet root.
+**Activation:** Add a consumer-owned `.code-foundry-release-policy.json` at the
+fleet root.
 
-The public `upgradeFleet` entrypoint now applies an optional release eligibility
-guard before delegating to the unchanged legacy/manifest rollout implementation.
-The implementation was moved verbatim to `fleet-core.mjs`; discovery exports and
-existing callers retain their interface. No policy file means existing behavior.
-A malformed or symlinked policy is an error, not an opt-out. Dry runs use the same
+The public fleet upgrade command applies an optional release-eligibility guard
+before it mutates repositories. No policy file means existing fleet behavior. A
+malformed or symlinked policy is an error, not an opt-out. Dry runs use the same
 guard, and `--force` cannot bypass source identity or qualification.
 
 ```json
@@ -30,8 +28,8 @@ This is a shape example, not a completed fleet policy. Populate canonical reposi
 identity, actual workflow path, and exact job names from the qualified release
 caller's Actions API results. Include the publication job when successful registry
 publication is required before adoption. Require every relevant job: a workflow's
-aggregate success alone can conceal skipped jobs. The qualification gate in #544
-and verified publisher in #547 provide the producer side of this policy.
+aggregate success alone can conceal skipped jobs. The producer-side qualification
+and verified-publication workflows provide the evidence this policy consumes.
 
 Keep the policy alongside the **consumer workspace's** fleet inventory. Do not put
 private repository names, local layouts, or deployment credentials into this
@@ -69,12 +67,13 @@ First release and validate the qualification/verification producer and confirm
 real workflow/job identities. Then opt a consumer workspace into this policy and
 exercise `fleet upgrade --dry-run --root <fleet-root> --source <clean-release-checkout>`.
 When `--source` is omitted, the installed package is used and an enabled policy
-will reject it unless that installation is itself a clean Git checkout. Older mutable
-releases or unavailable permissions should fail; do not weaken the policy just to
-make an old release eligible. No real fleet inventory is fabricated by this PR.
+will reject it unless that installation is itself a clean Git checkout. Older
+mutable releases or unavailable permissions should fail; do not weaken the policy
+just to make an old release eligible. No real fleet inventory is created by the
+eligibility guard.
 
 The focused suite verifies guard ordering and failure propagation with GitHub/CLI
 fixtures. Live authenticated verification, exact production job naming, and the
-full existing fleet-engine suite must pass before activation. The original fleet
-engine's Git blob is retained byte-for-byte; the source move still needs full
-repository import/type-check/packaging validation in CI.
+full fleet-engine suite should pass before activation. The guard is not a
+substitute for repository import, type-check, packaging, or deployment
+validation.

package/docs/fleet-rollouts.md

@@ -54,9 +54,9 @@ Adopt those requirements in consumer repositories before requiring them here.
 ## Commands
 
 ```sh
-code-foundry fleet status --root /path/to/fleet
-code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --dry-run
-code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --create-pr
+npx code-foundry fleet status --root /path/to/fleet
+npx code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --dry-run
+npx code-foundry fleet upgrade --root /path/to/fleet --source /path/to/release-checkout --create-pr
 ```
 
 Use `--source` to provide the clean Code Foundry release checkout used for the

package/docs/merge-queues.md

@@ -2,25 +2,25 @@
 
 Opt-in validation of the combined commit produced by GitHub's merge queue.
 
-**Activation:** `merge_queue: true` in the consumer's `.github/code-foundry.yml`, followed by normal sync.
-**Required check:** Existing canonical `Validation / Gate`.
+**Activation:** Set `merge_queue: true` in the consumer's
+`.github/code-foundry.yml`, then run `sync`.
+**Required check:** The canonical `Validation / Gate` aggregate check.
 
 The synchronizer adds `.github/workflows/validation-merge-queue.yml` only when
-explicitly enabled. The ordinary PR readiness workflow is unchanged: this feature
-does not turn draft pushes into CI, mark PRs ready, enqueue PRs, or change release
-behavior. Queue events receive the full audit even when staging PRs normally use
-fast validation. Release Please branch detection is deliberately not reused for
-a merge group containing several PRs; the group's combined tree is audited, not
-treated as a generated version-only diff.
+explicitly enabled. Queue validation does not turn draft pushes into CI, mark
+pull requests ready, enqueue pull requests, or change release behavior. Queue
+events receive the full audit even when staging pull requests normally use fast
+validation. Release Please branch detection is not reused for a merge group
+containing several pull requests; the combined tree is audited as submitted.
 
 ```yaml
 merge_queue: true
 ```
 
-Normal `code-foundry sync` updates the generated queue caller alongside the other
-runtime pins. Explicit fleet runtime overrides are honored. The installed runtime
-must contain this feature, and queues require an exact commit or released version
-pin rather than a moving branch. Direct topology enables main; staging-release
+Normal `npx code-foundry sync` updates the generated queue caller alongside the
+other runtime pins. Explicit fleet runtime overrides are honored. The installed
+runtime must contain this feature, and queues require an exact commit or released
+version pin rather than a moving branch. Direct topology enables main; staging-release
 enables main and staging. Existing runner choices, Rust CodeQL sharding, and an
 explicit `codeql: false` policy select the same appropriate validation orchestrator
 as ordinary PRs. No CodeQL policy or runtime default is relaxed.
@@ -60,8 +60,7 @@ Setting `merge_queue: false` or removing the key removes only a caller bearing t
 exact Foundry management marker. A custom file at that path is preserved when
 disabled; enabling over it fails before synchronization writes, even with force.
 Symlinked workflow paths are rejected. Dry runs report changes without creating,
-updating, or deleting the caller. The original synchronizer is retained verbatim
-in `sync-core.mjs`; its public exports are preserved through the thin wrapper.
+updating, or deleting the caller.
 
 Disable the repository's queue rule before removing its required queue workflow.
 Otherwise queued PRs will correctly wait for checks that no longer run.
@@ -74,16 +73,17 @@ configure required checks. Register the aggregate check, not PR-only mode or
 readiness checks that have no merge-group equivalent. An existing rule requiring
 individual checks needs those exact contexts reviewed as well. Do not enable the
 queue rule before the workflow is merged and a disposable queue exercise passes.
-No repository rule, branch protection, secret, merge setting, or queue is changed
-by this PR.
+Enabling this workflow does not change repository rules, branch protection,
+secrets, merge settings, or the queue itself.
 
 Focused tests cover event identity and rejection, generated audit wiring,
 configured CodeQL policy, pin evolution, idempotence, dry runs, and ownership
-preservation. They do not establish a live merge-group run or full sync integration.
-Before readiness, run the existing complete sync/fleet tests, locked formatter,
-linter, TypeScript and package budgets, and Actionlint against rendered callers
-and their pinned/local reusable workflow contracts. Exercise two queued PRs and
-one deliberately failing check in an eligible disposable repository.
+preservation. They do not establish a live merge-group run or full sync
+integration. Before enabling the queue rule, run the complete sync/fleet tests,
+locked formatter, linter, type check, package budgets, and Actionlint against
+rendered callers and their pinned/local reusable workflow contracts. Exercise two
+queued pull requests and one deliberately failing check in an eligible
+disposable repository.
 
 References: [GitHub merge-queue CI configuration](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue),
 [merge-group event](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group).