@mannyc1/ts-release 0.0.1 → 0.0.3

package/ARCHITECTURE.md

@@ -0,0 +1,93 @@
+# Architecture
+
+`@mannyc1/ts-release` is library-first and CLI-second.
+
+The package turns release intent into typed data, plans, evidence, and approved operations. The CLI and GitHub Action are adapters over those workflows.
+
+## Target Boundary
+
+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 and errors.
+- `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, 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
+
+Library modules must not import from `cli/`.
+
+The normal flow is:
+
+```text
+domain <- config
+domain <- planner <- targets
+domain <- host
+workflows -> config/planner/host/targets
+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`. The only workflow aggregate is the opt-in `./workflows` facade.
+
+## Public Workflow Surface
+
+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.
+
+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.
+- 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
+  `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,93 +2,184 @@
 
 `@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`,
+`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 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
+bun run cli eligibility --config release.config.json --format text
+bun run cli reconcile --config release.config.json --execute
 ```
 
 Rendering writes generated target files locally and records `render.json` evidence. `execute` is a lower-level primitive that runs publish operations only. Publishing is blocked unless execution is explicitly approved. Irreversible operations require a second approval flag.
 
+Status and resume commands use existing `.release/evidence` files to report progress and continue conservative unfinished work:
+
+```sh
+bun run cli status --config release.config.json --format text
+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.
+`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 * as Layer from "effect/Layer"
 import { type ReleaseIntent } from "@mannyc1/ts-release/domain/release"
-import { BunReleaseHostLayer } from "@mannyc1/ts-release/host/bun"
 import { createReleasePlan } from "@mannyc1/ts-release/planner/create-release-plan"
 import { validatePlan } from "@mannyc1/ts-release/planner/executor"
-import { LiveTargetRegistryLayer } from "@mannyc1/ts-release/targets/live"
 
-const planAndValidate = (intent: ReleaseIntent) =>
-  Effect.gen(function*() {
-    const plan = yield* createReleasePlan(intent)
-    const evidence = yield* validatePlan(plan)
-    return { plan, evidence }
-  }).pipe(
-    Effect.provide(Layer.mergeAll(BunReleaseHostLayer, LiveTargetRegistryLayer))
-  )
+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. `validatePlan` needs `ReleaseHost` and `TargetRegistry` layers. Workflows that verify HTTP evidence, such as `verifyPlan`, `runApprovedReleaseWorkflow`, or direct `VerifyHttpOperation` execution, also need a `ReleaseHttp` layer. Bun callers can import `LiveReleaseHttpLayer` from `@mannyc1/ts-release/host/http-live` and provide it with a `ReleaseHost` layer plus an Effect HTTP client such as `@effect/platform-bun/BunHttpClient`; 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.
+`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.
 
-## Programmatic CLI
+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.
 
-Applications can run the CLI command path without spawning the executable:
+## 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 {
-  PlanReleaseConfigOptions,
-  planReleaseConfig,
-  ReleaseCliOptions,
-  runReleaseCli
-} from "@mannyc1/ts-release/cli/programmatic"
-
-await Effect.runPromise(
-  runReleaseCli([
-    "plan",
-    "--config",
-    "release.config.json",
-    "--format",
-    "text"
-  ], ReleaseCliOptions.make({ root: "/path/to/release-workspace" }))
+import * as Layer from "effect/Layer"
+import { Config, 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(
+  Config.renderPlan({ root, configPath: "release.config.json", format: "text" }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
 )
 
 const plan = await Effect.runPromise(
-  planReleaseConfig(
-    PlanReleaseConfigOptions.make({
-      root: "/path/to/release-workspace",
-      configPath: "release.config.json"
-    })
+  Config.plan({ root, configPath: "release.config.json" }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const evidence = await Effect.runPromise(
+  Config.run({
+    root,
+    configPath: "release.config.json",
+    execute: true,
+    approveIrreversible: true
+  }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const status = await Effect.runPromise(
+  Config.status({ root, configPath: "release.config.json", format: "json" }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const resumedEvidence = await Effect.runPromise(
+  Config.resume({
+    root,
+    configPath: "release.config.json",
+    execute: true,
+    approveIrreversible: true
+  }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const eligibility = await Effect.runPromise(
+  Config.checkEligibility({
+    root,
+    configPath: "release.config.json"
+  }).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const reconciliationEvidence = await Effect.runPromise(
+  Config.reconcile({
+    root,
+    configPath: "release.config.json",
+    execute: true
+  }).pipe(
+    Effect.provide(RuntimeLayer)
   )
 )
 ```
 
-The helper provides the Bun host and live target registry internally, so callers do not need to import `effect/unstable/cli/Command` or assemble CLI layers by hand.
+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",
@@ -115,8 +206,14 @@ The helper provides the Bun host and live target registry internally, so callers
       "_tag": "NpmRegistryTarget",
       "id": "npm",
       "registry": "https://registry.npmjs.org",
+      "packageName": "@mannyc1/ts-release",
       "packagePath": ".",
-      "tokenEnv": "NPM_TOKEN",
+      "trustedPublishing": {
+        "provider": "github-actions",
+        "workflow": "release.yml",
+        "packageExists": true,
+        "verifyPackageExists": true
+      },
       "access": "public",
       "provenance": true,
       "dryRunSupport": "native",
@@ -135,11 +232,13 @@ The helper provides the Bun host and live target registry internally, so callers
     }
   ],
   "strict": true,
-  "evidenceDirectory": ".release/evidence"
+  "evidenceDirectory": ".release/evidence/{version}"
 }
 ```
 
-Paths are release-workspace relative and may not be absolute or contain parent traversal.
+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.
 
 Homebrew tap targets model catalog updates as generated files plus an approval-gated push:
 
@@ -205,49 +304,110 @@ Text plans include the release identity, evidence directory, artifact inventory,
 ```text
 @mannyc1/ts-release@0.1.0
 commit: abc123
-evidence: .release/evidence
+evidence: .release/evidence/0.1.0
 artifacts: 2
 targets: 2
 operations: 9
 
 targets:
   - github [GitHubReleaseTarget] auth=env-token dry-run=simulated strategy=simulated-plan mutability=mutable-release recovery=delete-and-recreate
-  - npm [NpmRegistryTarget] auth=env-token dry-run=native strategy=native-command mutability=immutable recovery=publish-new-version
+  - 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.
 
+## Status and Resume
+
+`status` reads local phase evidence and reports each current operation as pending, passed, failed, blocked, or complete without executing anything. The JSON format is schema-backed for CI or dashboards; the text format is intended for terminal review.
+
+`resume` is intentionally conservative. It skips successful matching evidence, can rerun missing work and failed read-only validation or verification operations, and never reruns a failed publish operation. A failed publish command can still have changed the outside world, so resume blocks until a maintainer reconciles npm, GitHub, or any other remote state manually.
+
+`reconcile` is the narrow remote repair path for GitHub Releases. It reads the GitHub release by tag, blocks on mismatched metadata or assets, skips an already matching published release, and can run `gh release edit <tag> --draft=false` for a matching draft when the target expects a public release. It does not run `npm publish`.
+
 ## Public API
 
-The intentional public API is the explicit subpath list in `package.json`. `release/cli` and `release/cli/command` are public so applications can embed the CLI command, while the executable remains available through the `release` binary.
+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 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. Existing files are not overwritten unless
+`--overwrite` is also passed.
+
+Action-first GitHub templates live under `templates/github-actions/`.
+
+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/`:
 
 - `examples/multi-target`
 - `examples/npm-only`
+- `examples/npm-first-publish`
 - `examples/github-release`
 - `examples/homebrew-tap`
 - `examples/pypi-registry`
 - `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.
+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.
 
 ```json
 {
@@ -258,6 +418,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
@@ -287,20 +448,92 @@ 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 same programmatic CLI command 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` 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.
 
 ```sh
 bun run check:self-release-config
 ```
 
+### Self Release
+
+The local non-publish gates for this package are:
+
+```sh
+bun run check:release
+bun run release:artifacts
+bun run cli plan --config apps/release-ts/release.config.json --format text
+```
+
+`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 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, runs the app CLI with `--config apps/release-ts/release.config.json`, and uploads `.release/evidence/**` for audit.
+
 ### Local Release Auth
 
-Use `.env.example` as the local credential contract. Export `NPM_TOKEN` and `GH_TOKEN`, or copy `.env.example` to `.env` and fill in the tokens locally. `.env` and `.npmrc` are ignored intentionally; keep token values out of commits. `.npmrc.example` shows npm's `${NPM_TOKEN}` interpolation form for local setup.
+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:
+
+```json
+{
+  "packageName": "@mannyc1/ts-release",
+  "trustedPublishing": {
+    "provider": "github-actions",
+    "workflow": "release.yml",
+    "packageExists": true,
+    "verifyPackageExists": true
+  },
+  "access": "public",
+  "provenance": true
+}
+```
+
+Trusted publishing authenticates during `npm publish` with CI OIDC, so
+`ts-release` records that mode in validation evidence instead of running
+`npm whoami`, which does not validate OIDC publishing. Configure npmjs trusted
+publishing for an existing package and use a GitHub-hosted runner with
+`id-token: write`, Node 22.14+ and npm 11.5.1+. The `packageExists` field must be
+`true` as a precondition acknowledgement, not first-publish support. Setting
+`verifyPackageExists` to `true` adds a read-only `npm view <package>` validation
+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
+requires the package to exist before trusted publishing can be configured. For a
+new package, use a temporary token-based npm target with `tokenEnv: "NPM_TOKEN"`
+and no `trustedPublishing` object. After the first version exists on npm,
+configure npm trusted publishing for owner `mannyc2`, repository `ts-release`,
+and workflow filename `release.yml`, then switch the target to
+`trustedPublishing`.
+
+Do not commit token values. Keep `.env.example` and `.npmrc.example` as
+placeholder contracts only.
 
-The first-release GitHub target uses `GH_TOKEN` for both `gh` command authentication and read-only REST API verification. Draft release verification requires authenticated API access. Enable npm provenance for CI-based publishes where the registry can generate provenance.
+The first-release GitHub target uses `GH_TOKEN` for both `gh` command authentication and read-only REST API verification. The release workflow sets up a current Node/npm toolchain for trusted publishing and enables npm provenance for CI-based publishes where the registry can generate provenance.