@mannyc1/ts-release 0.0.2 → 0.0.5

package/ARCHITECTURE.md

@@ -2,19 +2,50 @@
 
 `@mannyc1/ts-release` is library-first and CLI-second.
 
-The package turns release intent into typed data, plans, evidence, and approved operations. The CLI is only an argv, console, and terminal-file adapter over those workflows.
+The package turns release intent into typed data, plans, evidence, and approved operations. The CLI and GitHub Action are adapters over those workflows.
 
-## Module Taxonomy
+## Target Boundary
 
-- `domain/` contains durable schema-backed data models and errors.
+The intended repository shape separates reusable library code from the
+first-party release application:
+
+```text
+src/                 reusable TypeScript release library
+apps/release-ts/     official CLI app, Bun runtime shell, and self-release dogfood
+apps/ts-release-action/
+                     official JavaScript action app and Node runtime shell
+scripts/             repo-wide maintenance gates only
+examples/            reusable release config examples
+```
+
+`src/` contains generic library code only. It may require platform services
+such as `FileSystem`, `Path`, `ReleaseCommandRunner`, `ReleaseHttp`, or
+`HttpClient`, but it must not provide the concrete Bun runtime for the official
+CLI.
+
+`apps/release-ts/` owns argv parsing, terminal output, Bun runtime assembly,
+standalone CLI compilation, and self-release policy/config. A module consumed
+only by the official CLI or self-release dogfood belongs in `apps/release-ts/`
+unless it is made generic and documented as public library API.
+
+`apps/ts-release-action/` owns GitHub Action input parsing, GitHub step-summary
+and output adapters, evidence artifact upload, and the Node runtime assembly
+used by the bundled action. Action code should call public workflow APIs rather
+than reaching into CLI modules.
+
+## Current Module Taxonomy
+
+- `domain/` contains durable schema-backed data models, typed errors, and scalar schemas owned by their semantic domain modules, such as release names in `domain/release`, target IDs in `domain/target`, artifact IDs in `domain/artifact`, operation IDs in `domain/operation`, and evidence IDs in `domain/evidence`.
 - `config/` parses and validates release config into domain values.
 - `planner/` normalizes release intent, builds plans, renders plans, executes operation data through injected services, records evidence, reports status, resumes safe work, and reconciles remote state.
 - `targets/` models ecosystem-specific target semantics and produces operation data. Target modules may describe commands and HTTP checks, but they do not execute them.
 - `host/` defines injectable command and HTTP services plus live or test implementations.
-- `workflows/` contains reusable application workflows over config files, evidence files, and live target/HTTP composition. This is the high-level programmatic surface.
-- `runtime/` contains runtime-specific layer assembly. `runtime/bun` is the Bun composition used by the published executable and maintenance scripts.
-- `cli/` parses command-line flags, calls workflows, prints terminal output, and writes user-requested CLI output files.
-- `scripts/` contains repository maintenance checks. Scripts may use runtime layers, but they are not package library code.
+- `workflows/` contains reusable application workflows over config files, init/scaffolding plans, diagnostics, evidence files, and live target/HTTP composition. This is the high-level programmatic surface.
+- `apps/release-ts/src/runtime/` contains the Bun runtime shell for the official CLI app.
+- `apps/release-ts/src/cli/` parses command-line flags, calls workflows, prints terminal output, and writes user-requested CLI output files.
+- `apps/ts-release-action/src/runtime/` contains the Node runtime shell for the bundled GitHub Action.
+- `apps/ts-release-action/src/` adapts GitHub Action inputs, outputs, step summaries, and artifact uploads to workflow calls.
+- `scripts/` contains repository maintenance checks. Scripts may use app runtime layers, but they are not package library code.
 
 ## Dependency Direction
 
@@ -27,27 +58,36 @@ domain <- config
 domain <- planner <- targets
 domain <- host
 workflows -> config/planner/host/targets
-runtime -> host/workflows/platform layers
-cli -> workflows/runtime boundary
+apps/release-ts runtime -> host/workflows/platform layers
+apps/release-ts cli -> workflows/runtime boundary
+apps/ts-release-action runtime -> host/workflows/platform layers
+apps/ts-release-action action -> workflows/runtime boundary
 ```
 
-`src/index.ts` intentionally stays empty. Public API is the explicit subpath list in `package.json`, checked by `scripts/check-package-exports.ts` and `scripts/check-tree-shaking.ts`.
+`src/index.ts` intentionally stays empty. Public API is the explicit subpath list in `package.json`, checked by `scripts/check-package-exports.ts` and `scripts/check-tree-shaking.ts`. The only workflow aggregate is the opt-in `./workflows` facade.
 
 ## Public Workflow Surface
 
-There is no public `./api` facade. The public workflow modules are named after the work they own:
+There is no public `./api` facade, and the root package export stays empty. The public workflow modules are named after the work they own:
 
+- `./workflows` for the curated opt-in `Config`, `Init`, `Diagnostics`, `Evidence`, and `Live` namespaces.
 - `./workflows/config` for config-file release workflows.
+- `./workflows/init` for data-first scaffolding previews and approved writes.
+- `./workflows/diagnostics` for static config, auth, and CI readiness reports.
 - `./workflows/evidence` for reusable evidence persistence.
 - `./workflows/live` for runtime-neutral live target and HTTP services.
-- `./runtime/bun` for the Bun runtime composition.
 
-Use lower-level `domain/`, `config/`, `planner/`, `host/`, and `targets/` subpaths when a caller needs more control than the workflow modules provide.
+The `./workflows` facade lives at `src/workflows/index.ts` and should only re-export workflow namespaces. Use exact workflow leaf imports for maximum tree-shaking or direct option-class access, and lower-level `domain/`, `config/`, `planner/`, `host/`, and `targets/` subpaths when a caller needs more control than the workflow modules provide.
 
 ## Boundary Rules
 
 - Publish operations are data until execution is explicitly approved.
 - `Effect.run*` belongs at true runtime boundaries.
-- Layers are provided at CLI, runtime, script, and test boundaries.
+- Reusable effectful operations use `Effect.fn`; inline orchestration bodies use `Effect.gen`.
+- Durable models, options, target variants, and typed errors use `Schema.Class`, `Schema.TaggedClass`, and `Schema.TaggedErrorClass`.
+- Layers are provided at CLI, action, runtime, script, application, and test boundaries.
 - Config parsing, evidence persistence, status, resume, reconciliation, and release execution are library workflows, not CLI behavior.
-- Terminal formatting, argv parsing, and `--out` file writing belong in `cli/`.
+- Terminal formatting, argv parsing, and `--out` file writing belong in
+  `apps/release-ts/src/cli/`.
+- GitHub Action input parsing, output names, step summaries, and evidence artifact
+  uploads belong in `apps/ts-release-action/src/`.

package/README.md

@@ -2,20 +2,56 @@
 
 `@mannyc1/ts-release` turns release intent into explicit, inspectable, repeatable publishing operations.
 
+The root package is the reusable TypeScript release library. The official Bun
+CLI app lives in `apps/release-ts`, and the root `cli` script delegates to that
+private first-party app.
+
 The default workflow is plan-first:
 
 ```sh
+bun run cli validate-config --config release.config.json
 bun run cli plan --config release.config.json --format text
 bun run cli run --config release.config.json --execute --approve-irreversible
 ```
 
+On GitHub Actions, the primary CI integration is the JavaScript action:
+
+```yaml
+- uses: mannyc2/ts-release-action@v1
+  with:
+    command: plan
+    config: release.config.json
+    format: markdown
+```
+
+The action calls the TypeScript workflow APIs directly and keeps target-native
+operations visible in the plan. It defaults to `runtime: bundled`; workspace
+runtime mode is deferred until a same-module-graph Node platform setup can be
+required without surprising users. The source currently lives in
+`apps/ts-release-action`.
+
+The action supports the review commands `plan`, `validate-config`, `status`,
+`eligibility`, `doctor`, `check-auth`, and `check-ci`, plus the approved workflow commands
+`validate`, `run`, `resume`, and `reconcile`. Use `upload-evidence: true` when
+an action job should publish collected `.release/evidence` JSON files even after
+a command fails.
+
 The `run` command is the recommended release path: it renders generated files,
 validates every preflight, executes approved publish operations, and verifies
 remote state in order. The primitive commands remain available for review and
 debug flows:
 
 ```sh
+bun run cli schema --out release-config.schema.json
+bun run cli init --template npm-github --package @scope/pkg --repo owner/repo
+bun run cli validate-config --config release.config.json --format text
 bun run cli plan --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
+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
+bun run cli check-intent --config release.config.json --format text
 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
@@ -35,136 +71,117 @@ bun run cli resume --config release.config.json --execute --approve-irreversible
 ```
 
 Resume skips operations with successful matching evidence, reruns safe read-only failures, and blocks failed publish operations until remote state is reconciled manually.
-`eligibility` checks npm and GitHub remote state before the self-release workflow decides whether to run.
+`eligibility` resolves the configured release decision strategy and checks npm and GitHub remote state when a release is intended.
+`check-intent` is a read-only CI gate for the explicit intent-file strategy.
 `reconcile` is separate from resume: it inspects GitHub release state through the API and can publish a matching draft release with explicit `--execute` without republishing immutable npm versions.
 
 The executable is an argv and console adapter over TypeScript workflows. Release workflows are modeled as typed functions first, then exposed through the CLI for terminal and CI usage.
 
 ## Imports
 
-The package intentionally avoids aggregate library barrels. The root `release` export is intentionally empty; import the exact module you need from an explicit subpath.
+The package root export is intentionally empty. For onboarding and application workflow code, import the opt-in workflow facade from `@mannyc1/ts-release/workflows`; for maximum tree-shaking or target-author control, import the exact module you need from an explicit subpath.
 
 ```ts
 import * as Effect from "effect/Effect"
 import { type ReleaseIntent } from "@mannyc1/ts-release/domain/release"
 import { createReleasePlan } from "@mannyc1/ts-release/planner/create-release-plan"
 import { validatePlan } from "@mannyc1/ts-release/planner/executor"
-import { makeBunReleaseWorkflowRuntimeLayer } from "@mannyc1/ts-release/runtime/bun"
 
-const planAndValidate = (intent: ReleaseIntent) =>
-  Effect.gen(function*() {
-    const plan = yield* createReleasePlan(intent)
-    const evidence = yield* validatePlan(plan)
-    return { plan, evidence }
-  }).pipe(
-    Effect.provide(makeBunReleaseWorkflowRuntimeLayer())
-  )
+export const planAndValidate = Effect.fn("docs.planAndValidate")(function*(intent: ReleaseIntent) {
+  const plan = yield* createReleasePlan(intent)
+  const evidence = yield* validatePlan(plan)
+  return { plan, evidence }
+})
 ```
 
-`createReleasePlan` needs a `TargetRegistry` layer. Command execution needs a `ReleaseCommandRunner` layer, while artifact checks and checksum generation use Effect Platform `FileSystem`, `Path`, and `Crypto` services directly. High-level config-file workflows, render writes, and evidence writes also need Effect Platform `FileSystem` and `Path` services. Workflows that verify HTTP evidence, such as `verifyPlan`, `runApprovedReleaseWorkflow`, or direct `VerifyHttpOperation` execution, also need a `ReleaseHttp` layer. `makeBunReleaseWorkflowRuntimeLayer` is the Bun runtime composition used by the published CLI; applications on other runtimes can compose `@mannyc1/ts-release/workflows/live`, `@mannyc1/ts-release/host/platform`, and their platform services at the edge. Tests can import `makeTestReleaseHttpLayer` from `@mannyc1/ts-release/host/http`. Internal Effect imports use deep module paths such as `effect/Effect` and `effect/Layer` to keep bundlers from depending on broad root-package analysis. See `ARCHITECTURE.md` for the module taxonomy.
+`createReleasePlan` needs a `TargetRegistry` layer. Command execution needs a `ReleaseCommandRunner` layer, while artifact checks and checksum generation use Effect Platform `FileSystem`, `Path`, and `Crypto` services directly. High-level config-file workflows, render writes, and evidence writes also need Effect Platform `FileSystem` and `Path` services. Workflows that verify HTTP evidence, such as `verifyPlan`, `runApprovedReleaseWorkflow`, or direct `VerifyHttpOperation` execution, also need a `ReleaseHttp` layer. Applications can compose `@mannyc1/ts-release/workflows` and their platform services at the edge, or use exact lower-level imports from `@mannyc1/ts-release/workflows/live`, `@mannyc1/ts-release/host/platform`, and `@mannyc1/ts-release/host/http`. Tests can import `makeTestReleaseHttpLayer` from `@mannyc1/ts-release/host/http`. Internal Effect imports use deep module paths such as `effect/Effect` and `effect/Layer` to keep bundlers from depending on broad root-package analysis. See `ARCHITECTURE.md` for the module taxonomy.
+
+Reusable operations in docs and examples should use `Effect.fn`; workflow bodies use `Effect.gen`. Durable data, options, tagged target variants, and typed errors use `Schema.Class`, `Schema.TaggedClass`, and `Schema.TaggedErrorClass`, with `.make(...)` for construction. Runtime layers are provided once at CLI, action, script, application, or test boundaries.
 
 ## TypeScript Workflows
 
 Applications can call high-level release workflows without argv arrays or CLI command names:
 
 ```ts
+import * as BunHttpClient from "@effect/platform-bun/BunHttpClient"
+import * as BunServices from "@effect/platform-bun/BunServices"
 import * as Effect from "effect/Effect"
-import { makeBunReleaseWorkflowRuntimeLayer } from "@mannyc1/ts-release/runtime/bun"
-import {
-  PlanReleaseConfigOptions,
-  ReleaseExecutionOptions,
-  ReleaseEligibilityConfigOptions,
-  ReleaseReconcileConfigOptions,
-  ReleaseResumeConfigOptions,
-  ReleaseStatusOptions,
-  checkReleaseConfigEligibility,
-  reconcileReleaseConfig,
-  planReleaseConfig,
-  renderReleaseConfigPlan,
-  resumeReleaseConfig,
-  runReleaseConfig,
-  statusReleaseConfig
-} from "@mannyc1/ts-release/workflows/config"
+import * as Layer from "effect/Layer"
+import { Config, Live } from "@mannyc1/ts-release/workflows"
 
 const root = "/path/to/release-workspace"
-const RuntimeLayer = makeBunReleaseWorkflowRuntimeLayer({ root })
+const RuntimeLayer = Live.makeLayer({ root }).pipe(
+  Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(BunHttpClient.layer)
+)
 
 const textPlan = await Effect.runPromise(
-  renderReleaseConfigPlan(
-    PlanReleaseConfigOptions.make({ root, configPath: "release.config.json", format: "text" })
-  ).pipe(Effect.provide(RuntimeLayer))
+  Config.renderPlan({ root, configPath: "release.config.json", format: "text" }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
 )
 
 const plan = await Effect.runPromise(
-  planReleaseConfig(PlanReleaseConfigOptions.make({ root, configPath: "release.config.json" })).pipe(
+  Config.plan({ root, configPath: "release.config.json" }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 
 const evidence = await Effect.runPromise(
-  runReleaseConfig(
-    ReleaseExecutionOptions.make({
-      root,
-      configPath: "release.config.json",
-      execute: true,
-      approveIrreversible: true
-    })
-  ).pipe(
+  Config.run({
+    root,
+    configPath: "release.config.json",
+    execute: true,
+    approveIrreversible: true
+  }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 
 const status = await Effect.runPromise(
-  statusReleaseConfig(
-    ReleaseStatusOptions.make({ root, configPath: "release.config.json", format: "json" })
-  ).pipe(
+  Config.status({ root, configPath: "release.config.json", format: "json" }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 
 const resumedEvidence = await Effect.runPromise(
-  resumeReleaseConfig(
-    ReleaseResumeConfigOptions.make({
-      root,
-      configPath: "release.config.json",
-      execute: true,
-      approveIrreversible: true
-    })
-  ).pipe(
+  Config.resume({
+    root,
+    configPath: "release.config.json",
+    execute: true,
+    approveIrreversible: true
+  }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 
 const eligibility = await Effect.runPromise(
-  checkReleaseConfigEligibility(
-    ReleaseEligibilityConfigOptions.make({
-      root,
-      configPath: "release.config.json"
-    })
-  ).pipe(
+  Config.checkEligibility({
+    root,
+    configPath: "release.config.json"
+  }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 
 const reconciliationEvidence = await Effect.runPromise(
-  reconcileReleaseConfig(
-    ReleaseReconcileConfigOptions.make({
-      root,
-      configPath: "release.config.json",
-      execute: true
-    })
-  ).pipe(
+  Config.reconcile({
+    root,
+    configPath: "release.config.json",
+    execute: true
+  }).pipe(
     Effect.provide(RuntimeLayer)
   )
 )
 ```
 
-Use `@mannyc1/ts-release/workflows/config` for high-level config-file workflows, `@mannyc1/ts-release/workflows/evidence` for reusable evidence persistence, and `@mannyc1/ts-release/workflows/live` for the live target/HTTP layer. Bun callers can use `@mannyc1/ts-release/runtime/bun` for the same runtime layer used by the published binary. Node callers can provide Node platform services and a Node HTTP client instead. Use explicit lower-level planner, config, target, host, and domain subpaths when an application needs finer control over planning, execution, or test layers.
+Use `@mannyc1/ts-release/workflows` for the curated `Config`, `Init`, `Diagnostics`, `Evidence`, and `Live` namespaces. Exact leaf imports such as `@mannyc1/ts-release/workflows/config`, `@mannyc1/ts-release/workflows/init`, `@mannyc1/ts-release/workflows/diagnostics`, `@mannyc1/ts-release/workflows/evidence`, and `@mannyc1/ts-release/workflows/live` remain stable and are preferred when an application needs maximum tree-shaking or direct access to option classes. Applications provide platform services at the edge, such as `FileSystem`, `Path`, `HttpClient`, and command execution. Use explicit lower-level planner, config, target, host, and domain subpaths when an application needs finer control over planning, execution, or test layers.
 
 ## Example Config
 
 ```json
 {
+  "$schema": "https://mannyc2.github.io/ts-release/schema/release-config.schema.json",
   "identity": {
     "name": "@mannyc1/ts-release",
     "version": "0.1.0",
@@ -200,6 +217,7 @@ Use `@mannyc1/ts-release/workflows/config` for high-level config-file workflows,
         "verifyPackageExists": true
       },
       "access": "public",
+      "provenance": true,
       "dryRunSupport": "native",
       "mutability": "immutable",
       "recovery": "publish-new-version"
@@ -220,7 +238,62 @@ Use `@mannyc1/ts-release/workflows/config` for high-level config-file workflows,
 }
 ```
 
+The optional `$schema` key powers editor completion and does not change release behavior. Print the derived schema with `bun run cli schema`, and use `bun run cli validate-config` to check JSON syntax and release config shape without running target validators.
+
 Paths are release-workspace relative and may not be absolute or contain parent traversal. `evidenceDirectory` may include the literal `{version}` placeholder, which is resolved during planning so each release version can use its own evidence directory.
+Artifact paths may use `{version}`, `{name}`, and `{normalizedName}`. `normalizedName` removes a leading npm scope marker and replaces `/` with `-`, matching generated self-release artifact names such as `mannyc1-ts-release-0.1.0.tgz`.
+
+## Release Strategies
+
+Release identity and release decisions are strategy-backed data. Target adapters still receive a concrete release identity and still produce reviewable, approval-gated operations.
+
+| Strategy | Good for | Source of truth |
+|---|---|---|
+| Static config | audited/manual release identity | release config |
+| Package manifest | npm/package releases with one version source | `package.json` |
+| Git tag | tag-triggered release workflows | current Git tag |
+| Conventional commits | automated SemVer from commit messages | commits since the latest matching tag |
+| Intent files | reviewed release intent in PRs | `.release/intents/*.json` |
+
+Static identity remains supported:
+
+```json
+{
+  "identity": {
+    "name": "@scope/pkg",
+    "version": "0.1.0",
+    "commit": "abc123",
+    "tag": "v0.1.0"
+  }
+}
+```
+
+For npm-style packages, prefer manifest-derived identity to avoid repeating versions in release config:
+
+```json
+{
+  "identity": {
+    "_tag": "PackageManifestReleaseIdentitySource",
+    "packagePath": "package.json",
+    "commit": "HEAD",
+    "tagTemplate": "v{version}"
+  }
+}
+```
+
+Decision strategies are opt-in through `releaseDecision`. The default `RemoteStateReleaseDecision` uses the resolved identity, then checks npm and GitHub state. Git tag and conventional commit strategies can return `skipped` without error when no release input is present. Intent files are small JSON documents in `.release/intents`:
+
+```json
+{
+  "$schema": "https://mannyc2.github.io/ts-release/schema/release-intent.schema.json",
+  "package": "@scope/pkg",
+  "release": "patch",
+  "summary": "Explain the user-visible change.",
+  "empty": false
+}
+```
+
+This is a first-party intent-file format, not full Changesets compatibility. Publish operations remain plan data until explicit execution approval, regardless of which strategy chose the intended version.
 
 Homebrew tap targets model catalog updates as generated files plus an approval-gated push:
 
@@ -296,6 +369,24 @@ targets:
   - npm [NpmRegistryTarget] auth=trusted-publishing runs-in=ci provider=github-actions workflow=release.yml required-permission=id-token:write package-prerequisite=exists dry-run=native strategy=native-command mutability=immutable recovery=publish-new-version
 ```
 
+Summary plans provide a compact human first pass over risk, execution gates, target auth setup, and gated operation IDs:
+
+```sh
+bun run cli plan --config release.config.json --format summary
+```
+
+Markdown plans are intended for CI artifacts and PR review:
+
+```sh
+bun run cli plan --config release.config.json --format markdown > release-plan.md
+```
+
+Use `explain` when one operation needs a focused review without executing anything:
+
+```sh
+bun run cli explain npm:npm-publish --config release.config.json
+```
+
 JSON plans include the same data in a stable, CI-artifact-friendly shape, including `targetCapabilities`.
 
 GitHub release verification uses the GitHub REST API to check the release tag, title, draft flag, prerelease flag, and each uploaded artifact name.
@@ -310,10 +401,46 @@ GitHub release verification uses the GitHub REST API to check the release tag, t
 
 ## Public API
 
-The intentional public API is the explicit subpath list in `package.json`. The npm package exposes the `release` executable through `bin`; programmatic callers should import high-level workflows from `@mannyc1/ts-release/workflows/config` or use the explicit lower-level planner/config/target/status subpaths for finer control. `release/cli` and `release/cli/command` remain public for applications that need to embed the CLI command adapter.
+The intentional public API is the explicit subpath list in `package.json`. The root package export remains empty. Programmatic callers can use the opt-in `@mannyc1/ts-release/workflows` facade for happy-path workflow APIs, or exact leaf subpaths such as `@mannyc1/ts-release/workflows/config`, `@mannyc1/ts-release/workflows/init`, and `@mannyc1/ts-release/workflows/diagnostics` for maximum tree-shaking and direct option-class access. Lower-level planner/config/target/status subpaths remain available for finer control. The official CLI command adapter lives in the private `apps/release-ts` app rather than the reusable root package API.
 
 The package export checker fails if a new export is added without being added to the intentional API list.
 
+## Templates
+
+Copyable starter configs live in `templates/`. They are authoring starting
+points with placeholder package, repository, tap, and bucket names. Runnable
+fixtures live in `examples/`.
+
+Config templates are intentionally narrow:
+
+- `npm-only` for an existing npm package using GitHub Actions trusted publishing.
+- `npm-github` for npm plus GitHub Releases.
+- `multi-target-homebrew` for npm, GitHub Releases, and a Homebrew tap.
+- `multi-target-scoop` for npm, GitHub Releases, and a Scoop bucket.
+
+```sh
+bun run cli init --template npm-github --package @scope/pkg --repo owner/repo
+bun run cli init --template npm-github --package @scope/pkg --repo owner/repo --write
+bun run cli init --template npm-github --package @scope/pkg --repo owner/repo --github-actions --package-manager npm --write
+bun run cli plan --config release.config.json --format text
+```
+
+The npm templates enable provenance and set `verifyPackageExists: true`, which
+adds a read-only `npm view <package>` validation before trusted publishing.
+Add `--github-actions` to include the action-first trusted-publishing workflow
+template in the preview or write set. Workflow scaffolding supports
+`--package-manager bun|npm|pnpm|yarn`, plus single-line `--install-command` and
+`--build-command` overrides. Those commands are CI setup steps, not release
+target policy; publish operations still come from the `ts-release` plan.
+Existing files are not overwritten unless `--overwrite` is also passed.
+
+Action-first GitHub templates live under `templates/github-actions/`. The
+checked-in templates use npm setup by default, while this repository's own
+self-release workflow uses the Bun preset.
+
+Use `doctor`, `check-auth`, and `check-ci` after writing a template to inspect
+static readiness before any publish operation is approved.
+
 ## Examples
 
 Runnable example configs live in `examples/`:
@@ -327,14 +454,18 @@ Runnable example configs live in `examples/`:
 - `examples/scoop-bucket`
 - `examples/non-strict-skips`
 
-`examples/multi-target` demonstrates one release coordinated across a release host, a package registry, and an installer catalog. Build the package first, then plan an example from its directory:
+`examples/multi-target` demonstrates one release coordinated across GitHub Releases, npm, and a Homebrew tap. The focused fixtures cover PyPI, Scoop, npm-only trusted publishing, token-based first npm publish, GitHub-only releases, and non-strict skipped validators. Build the package first, then plan an example from its directory:
 
 ```sh
 bun run build
 cd examples/multi-target
-bun ../../dist/cli/main.js plan --config release.config.json --format text
+bun ../../apps/release-ts/src/cli/main.ts plan --config release.config.json --format text
 ```
 
+Trusted-publishing npm examples use provenance and `verifyPackageExists`. The
+`npm-first-publish` example intentionally stays token-based because npm trusted
+publishing can only be configured after the package already exists.
+
 ## Evidence
 
 Render, validation, execution, and verification evidence is written as JSON bundles. Failed commands still preserve partial evidence before the command failure is returned. Use `evidenceDirectory` such as `.release/evidence/{version}` when older local evidence should not collide with the current release version.
@@ -348,6 +479,7 @@ Render, validation, execution, and verification evidence is written as JSON bund
     {
       "id": "npm:npm-pack-dry-run:command",
       "operationId": "npm:npm-pack-dry-run",
+      "operationFingerprint": "{\"_tag\":\"ValidateCommandOperation\",\"id\":\"npm:npm-pack-dry-run\",\"targetId\":\"npm\",\"approval\":{\"requiresExecute\":false,\"requiresIrreversibleApproval\":false},\"command\":{\"executable\":\"npm\",\"args\":[\"pack\",\"--dry-run\",\"--json\"],\"requiredEnv\":[],\"redactedEnv\":[]}}",
       "status": "passed",
       "severity": "info",
       "exitCode": 0
@@ -366,7 +498,9 @@ Normal verification stays deterministic and does not require live external servi
 bun run check:release
 ```
 
-CI runs the portable package checks on Linux, macOS, and Windows. The Ubuntu release-readiness lane also runs the self-release config guard.
+CI runs the portable package checks on Linux, macOS, and Windows. The release
+gate runs the self-release config guard, the static self-release CI diagnostic,
+and then the portable checks.
 
 Real-tool integration checks are opt-in:
 
@@ -377,16 +511,17 @@ RELEASE_INTEGRATION_GITHUB=1 bun run test:integration:tools
 
 The first command validates npm adapter operations against the real `npm` CLI. The second also validates GitHub adapter readiness checks against the real `gh` CLI and requires `gh auth status` to succeed. GitHub release creation itself has no native dry-run; release validation is simulated from the deterministic plan before publish and verified against GitHub only after publish.
 
-Example configs are checked through the TypeScript workflow path:
+Example configs and templates are checked through the TypeScript workflow path:
 
 ```sh
 bun run check:examples
 ```
 
-This repository also includes a first release config at `release.config.json` that targets both npm and GitHub for the scoped `@mannyc1/ts-release` package. The self-release config must pass `bun run check:self-release-config` before release checks proceed. Its `identity.commit` may be the explicit current short commit, or `HEAD` as a stored-config convenience. Generated plans resolve `HEAD` to the current short commit, and the self-release guard requires a committed Git checkout with clean tracked files.
+This repository also includes a self-release config at `apps/release-ts/release.config.json` that targets both npm and GitHub for the scoped `@mannyc1/ts-release` package. The app-owned self-release scripts live under `apps/release-ts/scripts`, with root package scripts delegating to them. The self-release config must pass `bun run check:self-release-config`, and the workflow must pass `bun run check:self-release-ci`, before portable release checks proceed. It derives name and version from the root `package.json`, uses `{version}` artifact templates, and keeps `identity.commit` as `HEAD` for stored-config convenience. Generated plans resolve `HEAD` to the current short commit, and the self-release guard requires a committed Git checkout with clean tracked files.
 
 ```sh
 bun run check:self-release-config
+bun run check:self-release-ci
 ```
 
 ### Self Release
@@ -396,10 +531,10 @@ The local non-publish gates for this package are:
 ```sh
 bun run check:release
 bun run release:artifacts
-bun dist/cli/main.js plan --config release.config.json --format text
+bun run cli plan --config apps/release-ts/release.config.json --format text
 ```
 
-`release:artifacts` writes ignored files under `.release/artifacts`: the npm package tarball and standalone CLI executables for Linux, macOS, and Windows. GitHub Actions runs the approved release workflow on protected `main` when the package version has not already been published. The workflow uses npm trusted publishing with GitHub Actions OIDC instead of an npm token, and uploads `.release/evidence/**` for audit.
+`release:artifacts` delegates to `apps/release-ts/scripts/build-release-artifacts.ts` and writes ignored files under `.release/artifacts`: the npm package tarball and standalone CLI executables for Linux, macOS, and Windows. GitHub Actions runs on protected `main` and checks release eligibility before the full release gate. When `should_release` is true, the plan job runs `check:release`, builds artifacts, records a Markdown release plan, uploads evidence, and does not execute release operations. The protected `execute` job uses the reviewed `.release/artifacts` download, grants `contents: write` and `id-token: write`, and runs approved execution with npm trusted publishing OIDC instead of an npm token.
 
 ### Local Release Auth
 
@@ -407,6 +542,7 @@ Use `.env.example` as the local credential contract. Export `GH_TOKEN`, or copy
 `.env.example` to `.env` and fill in token values locally. `.env` and `.npmrc`
 are ignored intentionally; keep token values out of commits. `.npmrc.example`
 shows npm's `${NPM_TOKEN}` interpolation form for token-based npm targets.
+`TWINE_USERNAME` and `TWINE_PASSWORD` are only needed for PyPI/Twine examples.
 
 For npmjs releases from GitHub Actions, prefer structured `trustedPublishing` on
 the npm target:
@@ -419,7 +555,9 @@ the npm target:
     "workflow": "release.yml",
     "packageExists": true,
     "verifyPackageExists": true
-  }
+  },
+  "access": "public",
+  "provenance": true
 }
 ```
 
@@ -433,6 +571,22 @@ publishing for an existing package and use a GitHub-hosted runner with
 check. Trusted publishing does not use `NPM_TOKEN` for `npm publish`; token-based
 npm targets may still use `.npmrc.example` and `NPM_TOKEN`.
 
+Diagnostics stay static by default and report confidence instead of pretending
+local checks prove provider setup:
+
+```sh
+bun run cli check-auth --config release.config.json --format text
+bun run cli check-ci --config release.config.json --workflow .github/workflows/release.yml --format markdown
+bun run cli doctor --config release.config.json --format json
+```
+
+The reusable GitHub Actions trusted-publishing workflow template lives at
+`templates/github-actions/trusted-publishing.yml`. It uses
+`mannyc2/ts-release-action@v1` to record a Markdown plan, uploads review
+artifacts, and requires a protected `release` environment before running
+approved execution. npm trusted publishing uses OIDC, not `NPM_TOKEN`;
+`GH_TOKEN` is for GitHub Releases and API verification.
+
 ### First npm Publish Bootstrap
 
 Trusted publishing is the preferred steady state for GitHub Actions, but npm