@mannyc1/ts-release 0.0.7 → 0.2.2

package/README.md

@@ -1,382 +1,336 @@
-# @mannyc1/ts-release
+# ts-release
 
-Portable artifact and package-manager distribution planning for TypeScript projects.
+Automate multi-artifact releases and safely resume partial publication.
 
-`@mannyc1/ts-release` helps you declare the thing you want to distribute, stage
-platform-specific artifacts when needed, and feed those artifacts into
-target-specific package managers, catalogs, release hosts, and install surfaces.
-Publish operations still stay reviewable and approval-gated, but the product
-center is portable distribution data.
+## Release locally
 
-Use it when you need to answer:
-
-- Which binaries, archives, packages, or generated files make up this release?
-- Which package managers or install channels consume each artifact variant?
-- What target-specific files or commands will be generated?
-- Which operations are only rendering data, and which ones publish externally?
-- What evidence proves what was staged, rendered, validated, or executed?
-
-The root package is the reusable TypeScript library. This repo also contains the
-first-party Bun CLI app in `apps/release-ts` and the bundled GitHub Action in
-`apps/ts-release-action`.
-
-## What It Does
-
-`ts-release` models distribution as data:
-
-```text
-release config
-  -> normalized release identity
-  -> artifact recipes and inventory
-  -> installable artifact variants
-  -> target-specific distribution operations
-  -> generated package-manager files
-  -> explicit execution evidence
-  -> verification or reconciliation
-```
-
-The library currently plans, stages, and validates these distribution surfaces:
-
-| Surface | What ts-release models |
-|---|---|
-| npm | package publish, native dry-run validation, provenance, trusted publishing |
-| GitHub Releases | release creation, asset uploads, REST API verification, draft reconciliation |
-| Homebrew taps | generated formula files, macOS artifact variants, and approved tap pushes |
-| PyPI | already-built distributions and platform CLI wrapper wheels published through Twine |
-| Scoop buckets | generated manifest files, Windows binary shims, and approved bucket pushes |
-| Bun executables | optional binary artifact recipe staging before target planning |
-
-It is not a fake universal package manager and does not hide each ecosystem's
-manifest rules. It can stage declared artifacts through adapters, but it does
-not replace full build pipelines, compilers, signing, or installer toolchains.
-The job is to keep shared artifact inventory and target-specific distribution
-data in one typed plan.
-
-## Quick Start
-
-Inside this repository, the CLI script runs the first-party Bun app:
-
-```sh
-bun run cli init --template bun-cli-github --package @scope/pkg --repo owner/repo --github-actions --write
-bun run cli validate-config --config release.config.json
-bun run cli stage-artifacts --config release.config.json --format text
-bun run cli plan --config release.config.json --format text
-bun run cli render --config release.config.json
-```
-
-The first useful path is artifact-first: write or scaffold a config, stage any
-declared artifact recipes, plan the target distribution work, then render
-package-manager files or release metadata. These commands do not publish
-anything unless an execution command receives explicit approval.
-
-To publish through the full ordered workflow, pass both execution approvals:
-
-```sh
-bun run cli run --config release.config.json --execute --approve-irreversible
-```
-
-`run` renders generated files, validates preflights, executes approved publish
-operations, and verifies remote state. The lower-level commands are available
-when you want a manual pause between phases:
+The normal path is one command from a clean Git checkout:
 
 ```sh
-bun run cli render --config release.config.json --execute
-bun run cli validate --config release.config.json
-bun run cli print --config release.config.json
-bun run cli execute --config release.config.json --execute --approve-irreversible
-bun run cli verify --config release.config.json
-```
-
-## GitHub Actions
-
-The bundled action is the intended CI adapter:
-
-```yaml
-- uses: mannyc2/ts-release-action@v1
-  with:
-    command: plan
-    config: release.config.json
-    format: markdown
-    upload-evidence: true
+ts-release release --config release.config.json
 ```
 
-Supported action commands are `plan`, `validate-config`, `doctor`, `check-auth`,
-`check-ci`, `validate`, `run`, and `reconcile`. Artifact recipe staging remains
-owned by the Bun CLI/runtime because the bundled action runs on Node.
+`release` resolves observed package and Git facts, materializes the exact
+verified commit, runs declared local preparation, commits one complete
+`prepared-release/v2` bundle, observes every configured destination, and
+publishes only after a provider-specific decision authorizes that exact
+subject. The command prints the durable prepared reference and correlated
+report. A blocked or uncertain report is preserved and exits nonzero.
 
-Publishing still needs explicit approval:
+npm authentication is always explicit. A GitHub-hosted npm and GitHub release
+can use this authored configuration:
 
-```yaml
-- uses: mannyc2/ts-release-action@v1
-  with:
-    command: run
-    config: release.config.json
-    execute: "true"
-    approve-irreversible: "true"
-    upload-evidence: true
+```json
+{
+  "project": { "repository": "owner/repo" },
+  "versionFrom": "manifest",
+  "npmPackage": { "path": "." },
+  "publish": {
+    "npm": {
+      "authentication": {
+        "strategy": "trusted-publishing",
+        "attestation": {
+          "provider": "github-actions",
+          "runner": "github-hosted",
+          "repository": "owner/repo",
+          "workflow": "release.yml",
+          "workflowRef": "refs/heads/main",
+          "allowedAction": "npm-publish-direct"
+        }
+      }
+    },
+    "github": {}
+  }
+}
 ```
 
-For npm trusted publishing, configure npmjs for the GitHub repository and
-workflow, grant `id-token: write`, and keep `trustedPublishing` in the npm
-target. Trusted publishing uses OIDC during `npm publish`; it does not use
-`NPM_TOKEN`.
-
-For PyPI trusted publishing, configure a pending or existing PyPI Trusted
-Publisher for the GitHub repository, workflow, and release environment, then
-keep `trustedPublishing` in the PyPI target. Twine uses OIDC during
-`twine upload`; it does not require `TWINE_USERNAME` or `TWINE_PASSWORD` in CI.
-
-## Config
-
-A release config declares identity, artifacts, target policy, and evidence
-location.
+`workflow` and `workflowRef` are local host-admission constraints, not claims
+about fields exposed by npm's trusted-publisher configuration. They must name
+the workflow that actually invokes publication: use `release.yml` with the
+automatic template and `reviewed-release.yml` with the reviewed template. The
+host must observe that exact repository/path/ref on a GitHub-hosted runner
+before it reads either OIDC request value. Public npm metadata reads are always
+anonymous; private or custom-registry authenticated reads are unsupported
+until configured with a distinct read credential.
+
+The resolver fills package name, version, tag, commit, and repository only
+when observed facts agree with authored intent. For a non-OIDC host, use
+`{ "strategy": "token", "credential": "NPM_TOKEN" }` instead. The value of
+that environment variable remains host-owned and never enters configuration,
+prepared bytes, reports, or logs.
+
+Prebuilt Python distributions can be published to the closed `pypi` or
+`testpypi` destination. Each named artifact must be a valid wheel or gzip
+sdist whose filename and embedded metadata agree with the configured project
+and version:
 
 ```json
 {
-  "$schema": "https://mannyc2.github.io/ts-release/schema/release-config.schema.json",
-  "identity": {
-    "_tag": "PackageManifestReleaseIdentitySource",
-    "packagePath": "package.json",
-    "commit": "HEAD",
-    "tagTemplate": "v{version}"
-  },
+  "project": { "name": "fixture", "version": "1.0.0", "tag": "v1.0.0" },
   "artifacts": [
-    {
-      "id": "package",
-      "path": ".",
-      "format": "directory",
-      "consumers": ["npm"]
-    }
+    { "id": "wheel", "path": "dist/fixture-1.0.0-py3-none-any.whl", "format": "file" }
   ],
-  "targets": [
-    {
-      "_tag": "NpmRegistryTarget",
-      "id": "npm",
-      "registry": "https://registry.npmjs.org",
-      "packageName": "@scope/pkg",
-      "packagePath": ".",
-      "trustedPublishing": {
-        "provider": "github-actions",
-        "workflow": "release.yml",
-        "packageExists": true,
-        "verifyPackageExists": true
-      },
-      "access": "public",
-      "provenance": true,
-      "dryRunSupport": "native",
-      "mutability": "immutable",
-      "recovery": "publish-new-version"
+  "publish": {
+    "pypi": {
+      "artifacts": ["wheel"],
+      "repository": "pypi",
+      "authentication": {
+        "strategy": "token",
+        "credential": "PYPI_TOKEN",
+        "scope": "project"
+      }
     }
-  ],
-  "strict": true,
-  "evidenceDirectory": ".release/evidence/{version}"
+  }
 }
 ```
 
-Useful config commands:
+PyPI token upload additionally requires the host to install a shared,
+durable terminal `PublicationClaimStore`; runner-local files and memory do not
+satisfy that contract. The stock CLI and Action deliberately fail closed
+without one. Library hosts can pass it to `makeNodeReleaseLayer`,
+`makeBunReleaseLayer`, or `makeCustomReleaseLayer`. The token is projected as
+PyPI Basic authentication only inside the authorized HTTP sink. PyPI trusted
+publishing is represented as an external, host-owned
+`pypa/gh-action-pypi-publish@release/v1` path; the stock coordinator neither
+exchanges its OIDC token nor claims to recover that external upload.
+
+With the canonical GitHub origin or package repository configured, `init` can
+discover the exact owner/repository coordinate and write this explicit shape:
 
 ```sh
-bun run cli schema --out release-config.schema.json
-bun run cli validate-config --config release.config.json --format text
-bun run cli plan --config release.config.json --format summary
-bun run cli explain npm:npm-publish --config release.config.json
+ts-release init --preset bun-npm-github
 ```
 
-Paths are release-workspace relative. Artifact paths can interpolate
-`{version}`, `{name}`, and `{normalizedName}`. Evidence directories can
-interpolate `{version}`.
+It refuses to guess when no repository coordinate is observable and strictly
+inspects the exact generated configuration before writing it.
 
-## Artifact Variants
+## Automatic GitHub Actions release
 
-Artifact recipes can produce installable variants for different operating
-systems and architectures. Bun executable recipes derive variant metadata from
-their compile target, so the release plan can carry facts such as `linux`/`x64`
-or `windows`/`x64` before any package-manager adapter consumes the artifact.
+The default workflow is one job and one Action invocation. Copy the exact
+[automatic workflow template](templates/github-actions/release.yml). It is
+manual-only and requires `candidate_sha` to equal the current commit on
+`refs/heads/main` before the job can reach checkout. Its
+mutation job grants `contents: write` for the same-repository tag, release, and
+assets, `id-token: write` for npm trusted publishing, and `actions: read` for
+prepared-artifact recovery. It installs the publisher boundary explicitly,
+uses the job-scoped `GITHUB_TOKEN`, and uploads the redacted report as a
+recovery artifact.
 
-```json
-{
-  "id": "cli-linux-x64",
-  "target": "bun-linux-x64-baseline",
-  "path": "artifacts/pkg-{version}-linux-x64",
-  "consumers": ["github"]
-}
-```
-
-The planned artifact inventory for that output includes an executable artifact
-with a variant like:
-
-```json
-{
-  "os": "linux",
-  "arch": "x64",
-  "libc": "glibc",
-  "targetTriple": "bun-linux-x64-baseline"
-}
+```yaml
+- id: release
+  uses: mannyc2/ts-release/apps/ts-release-action@v0.2.2
+  env:
+    GITHUB_TOKEN: ${{ github.token }}
+  with:
+    command: ${{ inputs.prepared_ref == '' && 'release' || 'publish' }}
+    config: ${{ inputs.prepared_ref == '' && 'release.config.json' || '' }}
+    prepared: ${{ inputs.prepared_ref }}
 ```
 
-Direct artifact declarations can also include `variant` when an artifact was
-built outside `ts-release`. Homebrew formulas can consume macOS `darwin` x64
-and arm64 variants from one target, and Scoop manifests can derive a stable shim
-from a Windows executable variant. Future package-manager adapters should follow
-that pattern instead of guessing platform support from filenames.
-
-## Diagnostics
-
-Static diagnostics help catch missing auth and unsafe workflow setup before an
-approved run:
+Leave `prepared_ref` empty for a fresh release. To resume after durable
+preparation, dispatch the same candidate with the exact emitted
+`prepared:gha:` reference; the job selects `publish`, loads and verifies the
+original bundle, and does not rebuild.
+
+`v0.2.2` is the immutable monorepo-subpath coordinate intended for this
+candidate. Packaging and release certification must stop unless that tag is
+created from the exact certified result commit before consumers can see a
+README that names it. A floating Action branch is never an alternative.
+
+## Optional environment-gated publication
+
+When a host policy requires a protected environment, use the
+[two-job workflow template](templates/github-actions/reviewed-release.yml).
+Copy its paired
+[reviewed configuration](templates/npm-github/reviewed-release.config.json)
+to the repository root with the same filename; the workflow loads that exact
+file.
+Its prepare job has read-only repository authority and no OIDC permission. It
+uploads one complete prepared bundle and passes only its content-addressed
+hosted reference. The environment-gated publish job installs the publisher
+toolchain, receives mutation permissions, reloads and verifies the bundle, and
+then observes destinations before any write. The environment gate remains a workflow
+fact; it is not release-engine identity or data.
+
+The reviewed configuration attests `workflow: "reviewed-release.yml"` and
+`workflowRef: "refs/heads/main"`. Keep the workflow filename and dispatch it
+from that ref with `candidate_sha` equal to the current commit, or deliberately
+update both constraints. Reusing an automatic configuration that attests
+`release.yml` fails before OIDC acquisition. Recover a failed reviewed
+publication by rerunning the publish job in the same workflow run, not by
+preparing again.
+
+## Prepare without publication
+
+Use the split local path for build-only work or when bytes must cross an
+explicit host boundary:
 
 ```sh
-bun run cli doctor --config release.config.json --format text
-bun run cli check-auth --config release.config.json --target npm --format text
-bun run cli check-ci --config release.config.json --workflow .github/workflows/release.yml --format markdown
+prepared_ref="$(ts-release prepare --config release.config.json)"
+ts-release inspect "$prepared_ref"
 ```
 
-Diagnostics report confidence levels instead of pretending local checks can
-prove provider-side setup. For example, npm trusted publishing can only be fully
-confirmed inside the configured GitHub Actions environment.
+The value is a path-free `prepared:local:sha256-…` reference resolved against
+the selected content-addressed store. `--store` selects another local store;
+the reference itself never embeds a filesystem path. Publication accepts only
+a complete reference and never rebuilds from source as a fallback.
+
+Local extension work uses two primitives. `CommandCheck` is a pass/fail gate.
+`CommandArtifact` generates or transforms declared regular-file bytes. Data
+flow uses declared input and output IDs. Generic preparation children receive
+no authored host environment values, and the runner may retain only `PATH` as
+argv execution plumbing. Trusted commands are not a sandbox or a generic
+remote-effect mechanism.
 
-## Programmatic API
+## Observe and recover
 
-Install the library and provide platform services at your application boundary:
+Observation is read-only:
 
 ```sh
-bun add @mannyc1/ts-release effect@beta @effect/platform-bun@beta
+ts-release observe "$prepared_ref"
 ```
 
-High-level workflows are available from the opt-in workflow facade:
+To resume a partial or response-lost release, publish the same reference:
 
-```ts
-import * as BunHttpClient from "@effect/platform-bun/BunHttpClient"
-import * as BunServices from "@effect/platform-bun/BunServices"
-import * as Effect from "effect/Effect"
-import * as Layer from "effect/Layer"
-import { Distribution, Live } from "@mannyc1/ts-release/workflows"
-
-const root = "/path/to/release-workspace"
-const RuntimeLayer = Live.makeLayer({ root }).pipe(
-  Layer.provideMerge(BunServices.layer),
-  Layer.provideMerge(BunHttpClient.layer)
-)
-
-const textPlan = await Effect.runPromise(
-  Distribution.renderPlan({ root, configPath: "release.config.json", format: "text" }).pipe(
-    Effect.provide(RuntimeLayer)
-  )
-)
-
-const evidence = await Effect.runPromise(
-  Distribution.run({
-    root,
-    configPath: "release.config.json",
-    execute: true,
-    approveIrreversible: true
-  }).pipe(Effect.provide(RuntimeLayer))
-)
-
-console.log(textPlan)
-console.log(evidence.schemaVersion)
+```sh
+ts-release publish "$prepared_ref"
 ```
 
-Use `@mannyc1/ts-release/workflows` for the curated `Distribution`, `Config`,
-`Init`, `Diagnostics`, `Evidence`, and `Live` namespaces. The `Distribution`
-namespace is the artifact-first facade; `Config` keeps the lower-level
-config-file workflow names. Use exact subpaths such as
-`@mannyc1/ts-release/workflows/distribution` or lower-level `domain/`,
-`planner/`, `targets/`, and `host/` modules when you need tighter control or
-maximum tree-shaking.
+Every attempt verifies the manifest and blobs, then reobserves every subject.
+Equivalent subjects are skipped. Conflict and pre-mutation uncertainty stop
+without mutation. A post-dispatch unknown outcome stays uncertain until a new
+exact observation converges. Publication is not an atomic transaction, so a
+release may partially succeed and there is no universal rollback.
 
-The package root export is intentionally empty. Public API is the explicit
-subpath list in `package.json`.
+## Provider-specific correction
 
-## Templates And Examples
-
-Config templates live in `templates/`:
-
-- `npm-only`
-- `npm-github`
-- `bun-cli-github`
-- `multi-target-homebrew`
-- `multi-target-scoop`
-
-Runnable fixtures live in `examples/` and are checked through the same workflow
-path as user configs.
+Correction is deliberately separate from ordinary publication:
 
 ```sh
-bun run build
-cd examples/multi-target
-bun ../../apps/release-ts/src/cli/main.ts plan --config release.config.json --format text
+ts-release correct "$prepared_ref" correction.json
 ```
 
-Templates with `artifactRecipes` need an explicit staging step before target
-planning expects the generated files to exist:
+The command binds authored intent to the exact prepared provider subject. npm
+and GitHub Release corrections remain canonical external operator proposals.
+Catalog Git installs one conditional `forward-catalog-state` correction: it
+requires a SemVer-newer replacement and changes both the consumer formula or
+manifest and its managed-state record against the exact observed branch
+generation. Deletion, arbitrary inverse operations, and announcements are not
+release destinations.
+
+## Capability and platform boundary
+
+A source checkout or accepted field is not support evidence. The generated
+capability inventory must join each supported row to its strict decoder,
+default-layer entrypoint, exact observation semantics, and vertical test, and
+the release-candidate matrix must exercise every claimed execution host.
+
+| Axis | Kernel candidate boundary |
+| --- | --- |
+| Local preparation | Bun compilation, prebuilt imports, command checks/artifacts, archives, and checksums are retained; final support requires the generated capability and clean-candidate gates to agree. |
+| Remote publication | npm, prebuilt PyPI distributions, GitHub Releases, and typed Homebrew/Scoop catalog Git delivery are installed. npm uses explicit trusted-publishing or token authentication; PyPI token writes require a host-supplied shared terminal claim store, and its trusted-publishing strategy is external-host-owned. |
+| Correction | npm and GitHub authored proposals are exact-bound; PyPI yanking is observation-only; catalog Git installs exact paired SemVer-forward correction. |
+| Execution hosts | Linux is the only installed execution host. The checked-in Action is a native Node 24 launcher around a workflow-installed, pinned Bun runtime. macOS and Windows are not ts-release execution hosts. |
+| Artifact targets | The Bun builder advertises Linux and macOS x64/arm64 targets. macOS binaries are cross-compiled artifacts, not host-execution evidence. The self-release does not distribute a Windows ts-release binary. |
+| Native tools | Linux preparation requires an external Bun executable and `libseccomp.so.2`; network-denied commands record both identities. WSL, when used, is Linux. A standalone CLI binary is not a self-contained replacement for these tools. |
+
+Installed Node consumers must satisfy the package engine
+`^22.22.2 || ^24.15.0 || >=26.0.0`; Bun consumers require Bun 1.3.14 or newer.
+The checked-in Action uses GitHub's native Node 24 Action handler so the runner
+can inject its Actions-artifact transport credentials. Its tiny checked-in
+launcher passes no credentials to the Bun 1.3.14 runtime preloader, then runs
+the checked-in `dist/index.js` through the workflow-installed Bun runtime.
+Preparation stays in Bun, while every Actions-artifact upload or download is
+delegated to the checked-in Node 24 bridge so the official artifact client runs
+on its native stream implementation. The Action does not change the Node
+engine of the installed library or CLI package.
+
+The current source tree is not a release certificate. A published support
+claim exists only after the clean-candidate evidence records all required
+gates green; skipped live facts remain `UNVERIFIED`.
+
+## Extension jobs and exclusions
+
+The kernel translates extension requests to the owner that can enforce them:
+
+| User job | Owner |
+| --- | --- |
+| Tests, policy checks, generated notes, and agent bundles | `CommandCheck` or declared `CommandArtifact` bytes |
+| npm, prebuilt PyPI, GitHub Release, and catalog Git remote verification/publication | Installed provider modules; PyPI token mutation also requires the shared terminal claim boundary |
+| Environment protection or human authorization | External workflow host |
+| Downstream announcements | External workflow step after a complete report |
+
+Homebrew and Scoop rendering/delivery use typed renderers and an exact paired
+Git Data subject; arbitrary whole-file catalog templating remains excluded.
+Wrapper wheels remain excluded from the prebuilt PyPI slice unless an explicit product decision reopens them. PyPI
+support is contract-tested but has not been live-write-dogfooded in this wave.
+Custom library applications may compose full provider subjects through the
+[`provider-sdk`](https://github.com/mannyc2/ts-release/blob/main/docs/native-extensions.md)
+subpath. The stock CLI and Action
+do not discover packages or treat generic hooks as remote publishers.
+
+## Library API
+
+The Promise API uses the same lifecycle as the CLI and Action:
 
-```sh
-bun run cli stage-artifacts --config release.config.json --format text
-```
-
-## Evidence
-
-Validation, rendering, execution, reconciliation, and verification write JSON
-evidence bundles. Primitive commands write named files such as
-`validation.json`; the full `run` workflow writes `evidence.json`.
-
-```json
-{
-  "schemaVersion": "release-evidence/v1",
-  "releaseName": "release",
-  "releaseVersion": "0.1.0",
-  "records": [
-    {
-      "id": "npm:npm-pack-dry-run:command",
-      "operationId": "npm:npm-pack-dry-run",
-      "phase": "validation",
-      "targetId": "npm",
-      "risk": "read-only",
-      "status": "passed",
-      "severity": "info",
-      "message": "npm pack dry run passed.",
-      "startedAt": "2026-01-01T00:00:00.000Z",
-      "endedAt": "2026-01-01T00:00:00.100Z",
-      "durationMillis": 100,
-      "command": "npm pack --dry-run --json",
-      "exitCode": 0
-    }
-  ]
+```ts
+import {
+  defineRelease,
+  encodeCompletePreparedReleaseRef,
+  makeReleaseApi
+} from "@mannyc1/ts-release"
+import { NodeReleaseLayer } from "@mannyc1/ts-release/node"
+
+const config = defineRelease({
+  project: { repository: "owner/repo" },
+  versionFrom: "manifest" as const,
+  npmPackage: { path: "." },
+  publish: {
+    npm: {
+      authentication: {
+        strategy: "trusted-publishing" as const,
+        attestation: {
+          provider: "github-actions" as const,
+          runner: "github-hosted" as const,
+          repository: "owner/repo",
+          workflow: "release.yml",
+          workflowRef: "refs/heads/main",
+          allowedAction: "npm-publish-direct" as const
+        }
+      }
+    },
+    github: {}
+  }
+})
+
+const api = makeReleaseApi(NodeReleaseLayer)
+try {
+  const result = await api.release({ config, workspace: process.cwd() })
+  console.log(encodeCompletePreparedReleaseRef(result.prepared))
+  console.log(result.report.status)
+} finally {
+  await api.dispose()
 }
 ```
 
-Failed commands preserve partial evidence when possible. Non-strict mode records
-missing validators as visible skipped evidence instead of silently dropping them.
-
-## Reconciliation
-
-`reconcile` is a narrow repair path for GitHub Releases. It reads the release by
-tag, blocks on mismatched metadata or assets, skips an already matching
-published release, and can publish a matching draft with `--execute`.
-
-It does not replay immutable registry publishes:
-
-```sh
-bun run cli reconcile --config release.config.json --execute
-```
-
-## Repository Checks
-
-Use Bun for package management, scripts, and tests:
+The public operations are `inspect`, `prepare`, `observe`, `publish`,
+`release`, and `correct`. Public inputs contain neither credential values nor
+prepared paths. The derived graph is ephemeral; the verified prepared
+manifest and blobs are the durable cross-process boundary.
 
-```sh
-bun run check:release
-bun run check:examples
-bun run check:readme
-```
+## Agent bundles and development
 
-Real-tool integration checks are opt-in:
+The single tracked agent source owner is `apps/ts-release-agents`. Generated
+Codex and Claude layouts are ignored build output and are captured by the
+self-release as declared `CommandArtifact` outputs. No root marketplace tree
+is a second canonical owner.
 
 ```sh
-bun run test:integration:tools
-RELEASE_INTEGRATION_GITHUB=1 bun run test:integration:tools
+bun install --frozen-lockfile
+bun run check:portable
+bun test
 ```
 
-See `ARCHITECTURE.md` for module boundaries, `SPEC.md` for the design contract,
-`templates/README.md` for starter configs, and `examples/README.md` for runnable
-fixtures.
+The durable model is documented in [ARCHITECTURE.md](ARCHITECTURE.md), and the
+precise public contract is in [SPEC.md](SPEC.md). Both files are included with the npm
+package; this README does not rely on an unpackaged relative document.