@mannyc1/ts-release 0.0.2 → 0.0.3

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
+
+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, 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,55 @@
 
 `@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
@@ -42,129 +77,109 @@ The executable is an argv and console adapter over TypeScript workflows. Release
 
 ## 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 +215,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,6 +236,8 @@ 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.
 
 Homebrew tap targets model catalog updates as generated files plus an approval-gated push:
@@ -296,6 +314,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 +346,40 @@ 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 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/`:
@@ -327,14 +393,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 +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
@@ -377,13 +448,13 @@ 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` 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
@@ -396,10 +467,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 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
 
@@ -407,6 +478,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 +491,9 @@ the npm target:
     "workflow": "release.yml",
     "packageExists": true,
     "verifyPackageExists": true
-  }
+  },
+  "access": "public",
+  "provenance": true
 }
 ```
 
@@ -433,6 +507,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

package/SPEC.md

@@ -16,6 +16,7 @@ A release is a data flow:
 release intent
   -> normalized release model
   -> target-specific operations
+  -> optional generated files
   -> validation evidence
   -> gated execution
   -> post-publish verification
@@ -26,6 +27,22 @@ The package owns the model and the orchestration. Ecosystem tools remain the sou
 
 For example, npm, PyPI, GitHub Releases, Homebrew taps, OCI registries, app stores, or other targets may each need different commands, credentials, artifacts, and validators. The release package should describe those differences directly instead of hiding them behind one fake universal publish abstraction.
 
+## Current Shape
+
+The root package is the reusable library. It exposes explicit subpaths for domain data, config loading, planners, target adapters, host services, and high-level workflows. The official Bun CLI lives in `apps/release-ts`, and the GitHub Action lives in `apps/ts-release-action`; both are runtime adapters over the same TypeScript workflows.
+
+Current first-party workflows cover:
+
+- config validation and plan rendering
+- data-first init/scaffolding previews with approved writes
+- static doctor/auth/CI diagnostics
+- render, validation, execution, verification, and workflow evidence
+- status reporting from existing evidence
+- conservative resume after interrupted work
+- narrow GitHub release reconciliation without republishing npm versions
+
+Reusable configs live in `templates/`, runnable fixtures live in `examples/`, and publish operations remain data until an execute approval and any irreversible approval are supplied.
+
 ## Design Goals
 
 ### Plan-first
@@ -82,15 +99,19 @@ The library should expose APIs for:
 
 - loading and normalizing config
 - constructing a release plan
+- scaffolding starter configs and CI workflows as proposed files
+- rendering config schemas and validation results
 - rendering target files or generated metadata
 - validating plans and artifacts
+- reporting static auth and CI readiness with confidence levels
 - preparing executable operations
 - running approved operations through an injected host interface
 - recording evidence
 - reporting release status from evidence
 - conservatively resuming safe unfinished work
+- reconciling narrowly modeled remote state without replaying immutable publishes
 
-The CLI should mainly parse arguments, call the library, and format output.
+The CLI and GitHub Action should mainly parse host inputs, call the library, format host-specific output, and persist evidence.
 
 ### Host abstraction without pretending the world is pure
 
@@ -162,14 +183,19 @@ Evidence should survive outside the process as JSON or another stable format. It
 
 The package should make these workflows straightforward:
 
+- initialize a starter config and optional CI workflow from templates
+- validate config JSON and schema shape
 - create a plan from config
 - inspect the plan without executing anything
 - render target-specific files
 - validate artifacts and target readiness
+- report static auth and CI readiness
 - produce evidence artifacts
 - print publish operations
 - execute approved operations
 - verify published state after execution
+- inspect status and resume only safe unfinished work
+- reconcile a matching GitHub draft release without republishing immutable registries
 
 The API should favor explicit functions and typed data over hidden global state.
 
@@ -220,6 +246,8 @@ The rewrite is successful when:
 - irreversible operations require deliberate approval
 - core behavior is covered with deterministic tests
 - a CLI can be rebuilt as a thin adapter over the library
+- a GitHub Action can run the same workflows without embedding CLI behavior
+- starter templates can be checked by the same workflow path as examples
 - adding a new target does not require rewriting the core planner
 
 ## Biases
@@ -243,19 +271,21 @@ Avoid:
 - special cases that only work for one repository shape
 - abstractions that erase important ecosystem differences
 
-## Rewrite Direction
+## Implementation Direction
 
-Start from the data model.
+Continue from the data model.
 
-Define the smallest set of types needed to represent release identity, artifacts, targets, operations, validation results, execution gates, and evidence. Then implement one or two target adapters end to end to prove that the abstractions carry real differences without becoming generic mush.
+Keep the smallest set of types needed to represent release identity, artifacts, targets, operations, validation results, execution gates, and evidence. Add target adapters end to end only when they prove the abstractions carry real differences without becoming generic mush.
 
-The first working version should be narrow but honest:
+The implementation should stay narrow but honest:
 
 1. Load config.
 2. Normalize into a release model.
 3. Generate a serializable plan.
-4. Validate with structured evidence.
-5. Print executable operations.
-6. Execute only when explicitly approved.
+4. Render generated files only through explicit render operations.
+5. Validate with structured evidence.
+6. Print executable operations.
+7. Execute only when explicitly approved.
+8. Verify remote state and report status from evidence.
 
 Everything else should be added only after it has a clear place in that flow.

package/dist/config/schema.d.ts

@@ -1,8 +1,12 @@
 import * as Schema from "effect/Schema";
+import type * as JsonSchema from "effect/JsonSchema";
 import { ReleaseIntent } from "../domain/release.js";
 export type * from "../types/effect-internal.js";
 export declare const DEFAULT_CONFIG_PATH = "release.config.json";
+export declare const RELEASE_CONFIG_SCHEMA_ID = "https://mannyc2.github.io/ts-release/schema/release-config.schema.json";
 export declare const ReleaseConfig: typeof ReleaseIntent;
 export type ReleaseConfig = typeof ReleaseConfig.Type;
 export declare const decodeReleaseConfig: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => import("effect/Effect").Effect<ReleaseIntent, Schema.SchemaError, never>;
+export declare const releaseConfigJsonSchemaDocument: () => JsonSchema.JsonSchema;
+export declare const renderReleaseConfigJsonSchema: () => string;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,mBAAmB,6BAA6B,CAAA;AAEhD,eAAO,MAAM,mBAAmB,wBAAwB,CAAA;AAExD,eAAO,MAAM,aAAa,sBAAgB,CAAA;AAC1C,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD,eAAO,MAAM,mBAAmB,iJAA4C,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,mBAAmB,6BAA6B,CAAA;AAEhD,eAAO,MAAM,mBAAmB,wBAAwB,CAAA;AACxD,eAAO,MAAM,wBAAwB,2EAA2E,CAAA;AAEhH,eAAO,MAAM,aAAa,sBAAgB,CAAA;AAC1C,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD,eAAO,MAAM,mBAAmB,iJAA4C,CAAA;AAE5E,eAAO,MAAM,+BAA+B,QAAO,UAAU,CAAC,UAU7D,CAAA;AAED,eAAO,MAAM,6BAA6B,QAAO,MACkB,CAAA"}