@williamthorsen/release-kit 4.8.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,72 @@
 
 All notable changes to this project will be documented in this file.
 
+## [release-kit-v5.0.0] - 2026-04-23
+
+### Bug fixes
+
+- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+
+  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+
+### Features
+
+- Improve release-notes rendering quality (#261)
+
+  Improves the quality of release notes and CHANGELOG entries generated by release-kit. Release notes sections are now ordered by work-type priority (bug fixes first, then features, then internal), and each bullet now includes the commit body text for context that a one-line title cannot provide. Refactoring commits are now excluded from the release notes.
+
+- Scaffold release-notes injection and check markers (#267)
+
+  Adds release-notes injection to the configs scaffolded by `release-kit init`, so newly-onboarded consumers get the feature without having to discover or toggle the flag. The release-kit readyup kit gains a check that warns when a consumer's README is missing the marker pair where injected notes should land — without those markers, injection silently prepends to the top of the file, pushing the README's title below the notes.
+
+- Split GitHub Release creation into its own workflow (#272)
+
+  Splits GitHub Release creation out of release-kit publish into a dedicated release-kit create-github-release CLI command and a matching reusable GitHub Actions workflow. Consumers that do not publish to npm can now create Releases independently, and the contents: write permission required to create a Release no longer leaks into the publish path.
+
+- Replace --only with --tags on release-kit publish and push (#273)
+
+  `release-kit publish` and `release-kit push` now filter by full tag name via `--tags=<tag1,tag2>` instead of workspace directory name via `--only=<dir>`, matching the shape already used by `create-github-release`. Callers pass the tag they care about (e.g., `core-v1.3.0`) directly, with no translation step back to the publishing workspace's directory name. The reusable workflow gains an optional `tags:` input, and the internal `publish.yaml` caller now passes `tags: ${{ github.ref_name }}`, making the publish scope explicit rather than relying on the single-tag fetch default of `actions/checkout@v6`.
+
+- Apply pre-1.0 bump rule and add --set-version CLI escape hatch (#274)
+
+  Fixes an issue where a `feat!` commit on a pre-1.0 package would accidentally promote it to `1.0.0`. At pre-1.0 (`0.y.z`), a `'major'` release type now collapses to a minor bump. Adds a validated `--set-version <semver>` CLI flag on `release-kit prepare` that bypasses commit-derived bump logic and writes a specific version.
+
+- Scaffold audit.yaml workflow from audit-deps init (#277)
+
+  Adds GitHub Actions workflow scaffolding to `audit-deps init`. Running the command now writes both `.config/audit-deps.config.json` and `.github/workflows/audit.yaml` in the target repo, so that consumers no longer have to copy the canonical caller workflow by hand from this repo. The workflow content is shipped as a bundled template that ships to npm, and the repo's own workflow is kept byte-identical to that template via a consistency test — the canonical workflow cannot silently drift from what is published.
+
+- Add migrate-tag-prefixes.sh migration tool (#282)
+
+  Adds a one-shot migration tool, `migrate-tag-prefixes.sh`, shipped inside the release-kit package. The tool creates additive annotated-tag aliases under release-kit's new unscoped-package-name prefix that point at the same commits as the previous directory-basename tags, bridging the gap so post-migration `getCommitsSinceTarget` calls can resolve prior releases.
+
+- Add legacyTagPrefixes config field (#289)
+
+  Replaces the v4 → v5 tag-prefix migration mechanism (tag aliasing via `migrate-tag-prefixes.sh`) with a declarative `legacyTagPrefixes` config field. release-kit now searches for both legacy and modern prefixes when generating changelogs.
+
+  Adds a companion `release-kit show-tag-prefixes` CLI command that renders a per-workspace table of derived and declared legacy prefixes, flags cross-workspace collisions, and surfaces undeclared candidate prefixes with a copy-pasteable config snippet. `release-kit prepare` gains a one-line hint pointing operators to `show-tag-prefixes` when a workspace has no baseline tag but the repo contains candidate-shaped tags.
+
+- Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
+
+  Replaces the per-workspace `legacyTagPrefixes: string[]` field with `legacyIdentities: LegacyIdentity[]`, a structured array of complete `(name, tagPrefix)` historical snapshots. Each legacy identity is now a self-consistent record of what a workspace used to be called and how its tags used to be prefixed, so a workspace that has been renamed (npm name change, tag-prefix change, or both) carries one entry per prior identity.
+
+- Add `retiredPackages` repo-level config field (#299)
+
+  Adds support for declaring packages that once lived in this repo but have been extracted or removed, so their historical tag prefixes (e.g., `preflight-v*` from the extracted `readyup` project) no longer surface as "Undeclared tag prefixes" in `release-kit show-tag-prefixes`. Declared retired packages are acknowledged as real history but never consulted for baseline lookup or changelog attribution — they complement `workspaces[].legacyIdentities`, which is used when a workspace still exists under a new identity.
+
+- Add release-notes preview generator to `release-kit prepare` (#302)
+
+  Adds the ability to generate release notes when running `release-kit prepare`. The `--with-release-notes` option enables the generation of per-workspace preview files so authors can verify release-note injection before publishing. Injected release notes are also now prefixed with a `## Release notes — v{version} ({date})` heading to add missing context to the README.
+
+### Refactoring
+
+- Rename `component` to `workspace` in config API and internals (#296)
+
+  Renames release-kit's per-workspace vocabulary from "component" to "workspace" throughout the public API, internal types, validation messages, CLI help, init templates, and documentation. Behavior is unchanged; only identifiers, error-message strings, scaffolded template text, and prose have been changed.
+
+- Rename `node-monorepo-core` to `nmr-core` (#304)
+
+  Renames the shared-utilities package from `@williamthorsen/node-monorepo-core` to `@williamthorsen/nmr-core`, aligning it with the repository's `nmr-*` naming convention. The package's functionality and version are unchanged; only the published name differs.
+
 ## [release-kit-v4.8.0] - 2026-04-17
 
 ### Bug fixes
@@ -241,10 +307,6 @@ All notable changes to this project will be documented in this file.
 
 ### Features
 
-- Migrate release-kit from toolbelt (#18)
-
-  Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
-
 - Slim down release workflow by removing unnecessary pnpm install (#21)
 
   Make release-kit self-contained by invoking git-cliff via `npx --yes` instead of requiring it on PATH, and by appending modified file paths to the format command so lightweight formatters like `npx prettier --write` work without a full `pnpm install`. Update init templates, README, and consuming repo config/workflow to reference workflow v3.
@@ -267,4 +329,12 @@ All notable changes to this project will be documented in this file.
 
   Addresses five code quality issues and a test coverage gap identified during the release-kit migration (#5). Extracts a duplicated `isRecord` type guard into a shared module, eliminates a double-read in `bumpAllVersions`, improves error handling in `usesPnpm` by replacing a silent catch with a structured error boundary, removes an unreachable `'feature'` pattern from version defaults, and adds an integration test for scaffold template path resolution.
 
+## [release-kit-v1.0.1] - 2026-03-14
+
+### Features
+
+- Migrate release-kit from toolbelt (#18)
+
+  Migrates the complete `@williamthorsen/release-kit` package (v1.0.1) from `williamthorsen/toolbelt` into `packages/release-kit/`, adds shebang preservation to the shared esbuild plugin for CLI binaries, and sets up dogfooding infrastructure so this monorepo uses release-kit for its own releases.
+
 <!-- generated by git-cliff -->

package/README.md

@@ -4,6 +4,64 @@ Version-bumping and changelog-generation toolkit for release workflows.
 
 Provides a self-contained CLI that auto-discovers workspaces from `pnpm-workspace.yaml`, parses conventional commits, determines version bumps, updates `package.json` files, and generates changelogs with `git-cliff`.
 
+<!-- section:release-notes -->
+## Release notes — v5.0.0 (2026-04-23)
+
+### Bug fixes
+
+- Derive monorepo tag prefix from unscoped `package.json` name (#278)
+
+  Fixes a long-standing mismatch between a monorepo workspace's directory basename and its publishable package identity.
+
+### Features
+
+- Improve release-notes rendering quality (#261)
+
+  Improves the quality of release notes and CHANGELOG entries generated by release-kit. Release notes sections are now ordered by work-type priority (bug fixes first, then features, then internal), and each bullet now includes the commit body text for context that a one-line title cannot provide. Refactoring commits are now excluded from the release notes.
+
+- Scaffold release-notes injection and check markers (#267)
+
+  Adds release-notes injection to the configs scaffolded by `release-kit init`, so newly-onboarded consumers get the feature without having to discover or toggle the flag. The release-kit readyup kit gains a check that warns when a consumer's README is missing the marker pair where injected notes should land — without those markers, injection silently prepends to the top of the file, pushing the README's title below the notes.
+
+- Split GitHub Release creation into its own workflow (#272)
+
+  Splits GitHub Release creation out of release-kit publish into a dedicated release-kit create-github-release CLI command and a matching reusable GitHub Actions workflow. Consumers that do not publish to npm can now create Releases independently, and the contents: write permission required to create a Release no longer leaks into the publish path.
+
+- Replace --only with --tags on release-kit publish and push (#273)
+
+  `release-kit publish` and `release-kit push` now filter by full tag name via `--tags=<tag1,tag2>` instead of workspace directory name via `--only=<dir>`, matching the shape already used by `create-github-release`. Callers pass the tag they care about (e.g., `core-v1.3.0`) directly, with no translation step back to the publishing workspace's directory name. The reusable workflow gains an optional `tags:` input, and the internal `publish.yaml` caller now passes `tags: ${{ github.ref_name }}`, making the publish scope explicit rather than relying on the single-tag fetch default of `actions/checkout@v6`.
+
+- Apply pre-1.0 bump rule and add --set-version CLI escape hatch (#274)
+
+  Fixes an issue where a `feat!` commit on a pre-1.0 package would accidentally promote it to `1.0.0`. At pre-1.0 (`0.y.z`), a `'major'` release type now collapses to a minor bump. Adds a validated `--set-version <semver>` CLI flag on `release-kit prepare` that bypasses commit-derived bump logic and writes a specific version.
+
+- Scaffold audit.yaml workflow from audit-deps init (#277)
+
+  Adds GitHub Actions workflow scaffolding to `audit-deps init`. Running the command now writes both `.config/audit-deps.config.json` and `.github/workflows/audit.yaml` in the target repo, so that consumers no longer have to copy the canonical caller workflow by hand from this repo. The workflow content is shipped as a bundled template that ships to npm, and the repo's own workflow is kept byte-identical to that template via a consistency test — the canonical workflow cannot silently drift from what is published.
+
+- Add migrate-tag-prefixes.sh migration tool (#282)
+
+  Adds a one-shot migration tool, `migrate-tag-prefixes.sh`, shipped inside the release-kit package. The tool creates additive annotated-tag aliases under release-kit's new unscoped-package-name prefix that point at the same commits as the previous directory-basename tags, bridging the gap so post-migration `getCommitsSinceTarget` calls can resolve prior releases.
+
+- Add legacyTagPrefixes config field (#289)
+
+  Replaces the v4 → v5 tag-prefix migration mechanism (tag aliasing via `migrate-tag-prefixes.sh`) with a declarative `legacyTagPrefixes` config field. release-kit now searches for both legacy and modern prefixes when generating changelogs.
+
+  Adds a companion `release-kit show-tag-prefixes` CLI command that renders a per-workspace table of derived and declared legacy prefixes, flags cross-workspace collisions, and surfaces undeclared candidate prefixes with a copy-pasteable config snippet. `release-kit prepare` gains a one-line hint pointing operators to `show-tag-prefixes` when a workspace has no baseline tag but the repo contains candidate-shaped tags.
+
+- Replace `legacyTagPrefixes` with `legacyIdentities` (#297)
+
+  Replaces the per-workspace `legacyTagPrefixes: string[]` field with `legacyIdentities: LegacyIdentity[]`, a structured array of complete `(name, tagPrefix)` historical snapshots. Each legacy identity is now a self-consistent record of what a workspace used to be called and how its tags used to be prefixed, so a workspace that has been renamed (npm name change, tag-prefix change, or both) carries one entry per prior identity.
+
+- Add `retiredPackages` repo-level config field (#299)
+
+  Adds support for declaring packages that once lived in this repo but have been extracted or removed, so their historical tag prefixes (e.g., `preflight-v*` from the extracted `readyup` project) no longer surface as "Undeclared tag prefixes" in `release-kit show-tag-prefixes`. Declared retired packages are acknowledged as real history but never consulted for baseline lookup or changelog attribution — they complement `workspaces[].legacyIdentities`, which is used when a workspace still exists under a new identity.
+
+- Add release-notes preview generator to `release-kit prepare` (#302)
+
+  Adds the ability to generate release notes when running `release-kit prepare`. The `--with-release-notes` option enables the generation of per-workspace preview files so authors can verify release-note injection before publishing.  Injected release notes are also now prefixed with a `## Release notes — v{version} ({date})` heading to add missing context to the README.
+<!-- /section:release-notes -->
+
 ## Installation
 
 ```bash
@@ -54,9 +112,9 @@ That's it for most repos. The CLI auto-discovers workspaces and applies sensible
 
 ## How it works
 
-1. **Workspace discovery**: reads `pnpm-workspace.yaml` and resolves its `packages` globs to find workspace directories. Each directory containing a `package.json` becomes a component. If no workspace file is found, the repo is treated as a single-package project.
+1. **Workspace discovery**: reads `pnpm-workspace.yaml` and resolves its `packages` globs to find workspace directories. Each directory containing a `package.json` becomes a workspace. If no workspace file is found, the repo is treated as a single-package project.
 2. **Config loading**: loads `.config/release-kit.config.ts` (if present) via [jiti](https://github.com/unjs/jiti) and merges it with discovered defaults.
-3. **Commit analysis**: for each component, finds commits since the last version tag, parses them for type and scope, and determines the appropriate version bump.
+3. **Commit analysis**: for each workspace, finds commits since the last version tag, parses them for type and scope, and determines the appropriate version bump.
 4. **Version bump + changelog**: bumps `package.json` versions and generates changelogs via `git-cliff`.
 5. **Release tags file**: writes computed tags to `tmp/.release-tags` for the release workflow to read when tagging and pushing.
 
@@ -73,7 +131,7 @@ scope|type!: description       # scoped breaking change
 type(scope)!: description      # conventional scoped breaking change
 ```
 
-The `scope|type:` format scopes a commit to a specific component in a monorepo. Use `scopeAliases` in your config to map shorthand names to canonical scope names.
+The `scope|type:` format scopes a commit to a specific workspace in a monorepo. Use `scopeAliases` in your config to map shorthand names to canonical scope names.
 
 ## Configuration
 
@@ -85,8 +143,8 @@ Configuration is optional. The CLI works out of the box by auto-discovering work
 import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
 
 const config: ReleaseKitConfig = {
-  // Exclude a component from release processing
-  components: [{ dir: 'internal-tools', shouldExclude: true }],
+  // Exclude a workspace from release processing
+  workspaces: [{ dir: 'internal-tools', shouldExclude: true }],
 
   // Run a formatter after changelog generation (modified file paths are appended as arguments)
   formatCommand: 'npx prettier --write',
@@ -108,23 +166,66 @@ The config file supports both `export default config` and `export const config =
 | Field             | Type                             | Description                                                                                                                   |
 | ----------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | `cliffConfigPath` | `string`                         | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template |
-| `components`      | `ComponentOverride[]`            | Override or exclude discovered components (matched by `dir`)                                                                  |
+| `workspaces`      | `WorkspaceOverride[]`            | Override or exclude discovered workspaces (matched by `dir`)                                                                  |
 | `formatCommand`   | `string`                         | Shell command to run after changelog generation; modified file paths are appended as arguments                                |
 | `versionPatterns` | `VersionPatterns`                | Rules for which commit types trigger major/minor bumps                                                                        |
 | `scopeAliases`    | `Record<string, string>`         | Maps shorthand scope names to canonical names in commits                                                                      |
 | `workTypes`       | `Record<string, WorkTypeConfig>` | Work type definitions, merged with defaults by key                                                                            |
+| `retiredPackages` | `RetiredPackage[]`               | Packages that once lived in this repo but have been extracted or removed; suppresses undeclared-tag-prefix warnings           |
 
 All fields are optional.
 
-### `ComponentOverride`
+### `WorkspaceOverride`
 
 ```typescript
-interface ComponentOverride {
+interface WorkspaceOverride {
   dir: string; // Package directory name (e.g., 'arrays')
   shouldExclude?: boolean; // If true, exclude from release processing
+  legacyIdentities?: LegacyIdentity[]; // Prior `(name, tagPrefix)` identities for this workspace
+}
+
+interface LegacyIdentity {
+  name: string; // Full scoped npm name at the time (e.g., '@scope/pkg')
+  tagPrefix: string; // Tag prefix under which historical tags were published (e.g., 'core-v')
 }
 ```
 
+`legacyIdentities` captures prior identities of a workspace as complete `(name, tagPrefix)` snapshots. The union of the current `tagPrefix` and each identity's `tagPrefix` is consulted when release-kit searches for the most recent baseline tag and when generating changelogs. Use it when a workspace's historical tags were published under a different npm name, a different tag prefix, or both — typically across a package rename. Both fields are required per identity: each entry must be a complete historical snapshot that stays valid regardless of subsequent renames. Run `release-kit show-tag-prefixes` to detect undeclared candidates and produce a paste-ready config snippet. Listing the current identity (full `(name, tagPrefix)` match) is rejected as a no-op duplicate; an identity whose `tagPrefix` matches the current but whose `name` differs is valid and documents a prior rename that reused the same tag shape. If the workspace no longer exists in this repo at all (the package was extracted or removed), use [`retiredPackages`](#retiredpackage) instead.
+
+### `RetiredPackage`
+
+```typescript
+interface RetiredPackage {
+  name: string; // Final scoped npm name while the package lived in this repo
+  tagPrefix: string; // Tag prefix under which the package's historical tags were published
+  successor?: string; // Optional successor package name (e.g., 'readyup')
+}
+```
+
+`retiredPackages` is the repo-level complement to `legacyIdentities`. Use `legacyIdentities` when the workspace still exists in this repo under a new identity; use `retiredPackages` when no workspace for this package exists in this repo anymore — the package was extracted to another repo or removed outright. Retired entries are inert: release-kit never consults them for baseline lookup or changelog attribution. Their declared `tagPrefix` values are recognized as historical, so `show-tag-prefixes` stops flagging them under "Undeclared tag prefixes."
+
+Worked example — `preflight` was extracted from this monorepo and continues as the standalone `readyup` project. Its tags stay in this repo as historical anchors:
+
+```typescript
+import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
+
+const config: ReleaseKitConfig = {
+  retiredPackages: [{ name: '@scope/preflight', tagPrefix: 'preflight-v', successor: 'readyup' }],
+};
+
+export default config;
+```
+
+Validation rules:
+
+- `name` and `tagPrefix` are required per entry and must be non-empty strings.
+- `successor` is optional; if present, it must be a non-empty string.
+- Full-tuple `(name, tagPrefix)` duplicates within `retiredPackages` are rejected.
+- Two entries sharing the same `tagPrefix` but different `name`s are accepted — this documents a package renamed within the repo before being retired.
+- A `tagPrefix` that collides with an active workspace's derived prefix or any declared `workspaces[].legacyIdentities[].tagPrefix` is rejected. A retired prefix cannot also be current or legacy.
+
+`show-tag-prefixes` currently does not render a dedicated "Retired packages" section (deferred). Declaring a retired entry is verifiable by confirming that its `tagPrefix` stops appearing under "Undeclared tag prefixes" in the `show-tag-prefixes` output.
+
 ### `VersionPatterns`
 
 Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
@@ -140,21 +241,29 @@ Default: `{ major: ['!'], minor: ['feat'] }`
 
 ### Default work types
 
-| Key        | Header        | Aliases   |
-| ---------- | ------------- | --------- |
-| `fix`      | Bug fixes     | `bugfix`  |
-| `feat`     | Features      | `feature` |
-| `internal` | Internal      |           |
-| `refactor` | Refactoring   |           |
-| `tests`    | Tests         | `test`    |
-| `tooling`  | Tooling       |           |
-| `ci`       | CI            |           |
-| `deps`     | Dependencies  | `dep`     |
-| `docs`     | Documentation | `doc`     |
-| `fmt`      | Formatting    |           |
+| Key         | Header          | Aliases       |
+| ----------- | --------------- | ------------- |
+| `fix`       | Bug fixes       | `bugfix`      |
+| `deprecate` | Deprecated      |               |
+| `feat`      | Features        | `feature`     |
+| `internal`  | Internal        |               |
+| `perf`      | Performance     | `performance` |
+| `refactor`  | Refactoring     |               |
+| `sec`       | Security        | `security`    |
+| `tests`     | Tests           | `test`        |
+| `tooling`   | Tooling         |               |
+| `ci`        | CI              |               |
+| `deps`      | Dependencies    | `dep`         |
+| `docs`      | Documentation   | `doc`         |
+| `ai`        | Agentic support |               |
+| `fmt`       | (skipped)       |               |
 
 Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set.
 
+`fmt:` commits are recognized for version-bump determination (they contribute to a patch bump) but are skipped by the bundled `cliff.toml.template`, so they do not appear in `CHANGELOG.md` or release notes.
+
+Release-notes sections are rendered in the declaration order of the merged work-types record, with any unknown titles trailing the known ones. The default `devOnlySections` (excluded from public release notes but still written to `CHANGELOG.md`) are: `Agentic support`, `CI`, `Dependencies`, `Internal`, `Refactoring`, `Tests`, `Tooling`. Override via `changelogJson.devOnlySections` in your config.
+
 ## CLI reference
 
 ### Global options
@@ -168,15 +277,82 @@ Work types from your config are merged with these defaults by key — your entri
 
 Run release preparation with automatic workspace discovery.
 
-| Flag                         | Description                                                      |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `--dry-run`                  | Preview changes without writing files                            |
-| `--bump=major\|minor\|patch` | Override the bump type for all components                        |
-| `--force`                    | Bypass the "no commits since last tag" check (requires `--bump`) |
-| `--only=name1,name2`         | Only process the named components (monorepo only)                |
-| `--help`, `-h`               | Show help                                                        |
+| Flag                         | Description                                                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `--dry-run`                  | Preview changes without writing files                                                                        |
+| `--bump=major\|minor\|patch` | Override the bump type for all workspaces                                                                    |
+| `--set-version=X.Y.Z`        | Set an explicit canonical semver version; bypasses commit-derived bumps. Requires `--only` in monorepo mode. |
+| `--force`                    | Bypass the "no commits since last tag" check (requires `--bump`)                                             |
+| `--only=name1,name2`         | Only process the named workspaces (monorepo only)                                                            |
+| `--with-release-notes`       | Write per-workspace release-notes previews under `{workspacePath}/docs/`                                     |
+| `--help`, `-h`               | Show help                                                                                                    |
+
+Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
+
+#### Previewing release notes with `--with-release-notes`
+
+`--with-release-notes` writes two versioned files per workspace after each workspace's `changelog.json` is produced:
+
+- `{workspacePath}/docs/README.v{version}.md` — the workspace `README.md` with release notes injected at the `<!-- section:release-notes -->` marker.
+- `{workspacePath}/docs/RELEASE_NOTES.v{version}.md` — the standalone release notes for this version.
+
+The publish-time inject-and-revert lifecycle is unchanged; previews are additive, deterministic, and safe to regenerate. When `changelogJson.enabled` is `false`, the flag logs a warning and skips preview generation. In dry-run mode, planned writes are logged and no files are created.
+
+Because preview filenames are versioned, committing them will accumulate files over time. The recommended `.gitignore` entry for monorepos is:
+
+```gitignore
+packages/*/docs/*.v*.md
+```
 
-Component names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
+For single-package repos:
+
+```gitignore
+docs/*.v*.md
+```
+
+#### Setting an explicit version with `--set-version`
+
+The `--set-version` flag is a first-class escape hatch for the cases where commit-derived bump logic produces the wrong version — most notably, promoting a pre-1.0 package to 1.0.0. Pre-1.0 packages collapse a `feat!` breaking change to a minor bump (matching semantic-release's `initialMajor: false` and release-please's `bump-minor-pre-major`), so a deliberate promotion to 1.0.0 must be requested explicitly.
+
+The flag validates that:
+
+- The value is canonical `N.N.N` semver (pre-release suffixes are rejected).
+- The target is strictly greater than the current version (numeric comparison on each component).
+- In monorepo mode, `--only` is set and resolves to exactly one workspace.
+
+`--set-version` is mutually exclusive with `--bump` and `--force`. The rest of the pipeline (changelog generation, tag creation, commit summary, propagation to dependents) runs unchanged, so dependents receive a propagated patch bump triggered by the overridden version.
+
+Promoting a pre-1.0 package to 1.0.0 in a monorepo:
+
+```sh
+release-kit prepare --only arrays --set-version 1.0.0
+```
+
+An empty changelog section is expected for a bare promotion, because the changelog is generated from commits since the last tag. To include a narrative entry, land a descriptive release commit (e.g., a `feat!` describing the stable API) before running `prepare`.
+
+### `release-kit create-github-release`
+
+Create GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: invoking this command creates Releases regardless of whether the matching package was published.
+
+| Flag                   | Description                                                               |
+| ---------------------- | ------------------------------------------------------------------------- |
+| `--dry-run`            | Preview without creating releases                                         |
+| `--tags=tag1,tag2,...` | Only create releases for the named tags (comma-separated, full tag names) |
+| `--help`, `-h`         | Show help                                                                 |
+
+When `--tags` is omitted, every release tag pointing at HEAD is processed. The CLI requires the `gh` CLI on `PATH` and `contents: write` permission. The bundled `create-github-release.reusable.yaml` GitHub Actions workflow runs this command in CI.
+
+### `release-kit show-tag-prefixes`
+
+Print a per-workspace table of derived tag prefixes, tag counts, and declared legacy prefixes. Also surfaces any release-shaped tag prefix in the repo that is neither a derived prefix nor declared via `legacyIdentities`, along with a copy-pasteable `workspaces: [...]` config snippet. The snippet uses a `TODO-fill-in-legacy-npm-name` placeholder for each identity's `name`; replace it with the package's prior npm name before pasting.
+
+| Flag           | Description |
+| -------------- | ----------- |
+| `--help`, `-h` | Show help   |
+
+Exits `0` when every workspace derives a prefix and there are no cross-workspace collisions; exits `1` on any derivation failure or collision. Undeclared candidates do not affect the exit code — they surface as a warning via the `legacy tag prefixes are declared` readyup check.
+
+In single-package mode, prints a single row with `workspacePath = .` and `derivedPrefix = v`; legacy entries and undeclared-candidate scanning are not applicable.
 
 ### `release-kit init`
 
@@ -191,6 +367,8 @@ Initialize release-kit in the current repository. By default, scaffolds only the
 
 Scaffolded files:
 
+- `.github/workflows/create-github-release.yaml` — workflow that creates a GitHub Release on tag push, independent of npm publish
+- `.github/workflows/publish.yaml` — workflow that delegates to a reusable publish workflow
 - `.github/workflows/release.yaml` — workflow that delegates to a reusable release workflow
 - `.config/release-kit.config.ts` — starter config with commented-out customization examples (with `--with-config`)
 - `.config/git-cliff.toml` — copied from the bundled template (with `--with-config`)
@@ -213,7 +391,7 @@ The `init` command scaffolds a release workflow at `.github/workflows/release.ya
 
 | Input  | Type   | Description                                                         |
 | ------ | ------ | ------------------------------------------------------------------- |
-| `only` | string | Components to release (comma-separated, leave empty for all)        |
+| `only` | string | Workspaces to release (comma-separated, leave empty for all)        |
 | `bump` | choice | Override bump type: `patch`, `minor`, `major` (empty = auto-detect) |
 
 For repos that need a self-contained workflow instead of the reusable one, the scaffolded file can be expanded. The key steps are: checkout with full history (`fetch-depth: 0`), run `release-kit prepare` with optional `--only` and `--bump` flags, check for changes, read tags from `tmp/.release-tags`, then commit, tag, and push.
@@ -221,10 +399,10 @@ For repos that need a self-contained workflow instead of the reusable one, the s
 ### Triggering a release
 
 ```sh
-# All components
+# All workspaces
 gh workflow run release.yaml
 
-# Specific component(s)
+# Specific workspace(s)
 gh workflow run release.yaml -f only=arrays
 gh workflow run release.yaml -f only=arrays,strings -f bump=minor
 ```
@@ -257,25 +435,57 @@ This package shells out to two external tools:
 - **`git`** — must be available on `PATH`. Used to find tags and retrieve commit history.
 - **`git-cliff`** — automatically downloaded and cached via `npx` on first invocation. No need to install it as a dev dependency.
 
-## Using `component()` for manual configuration
+## Upgrading from v4 to v5
 
-If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `component()` helper creates a `ComponentConfig` from a workspace-relative path:
+Release-kit v5 derives each workspace's tag prefix from its unscoped `package.json` `name`, so a package at `packages/core` with `"name": "@scope/nmr-core"` uses tags like `nmr-core-v1.3.0`. Repos that previously tagged under the directory basename (e.g., `core-v1.3.0`) do not need to rewrite history — declare the prior identity in `legacyIdentities` so release-kit recognizes historical tags under both the new and old prefixes.
+
+Minimal worked example for a repo whose pre-v5 tags were `core-v0.2.7` and whose npm name has not changed:
 
 ```typescript
-import { component } from '@williamthorsen/release-kit';
+// .config/release-kit.config.ts
+import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
+
+const config: ReleaseKitConfig = {
+  workspaces: [
+    {
+      dir: 'core',
+      legacyIdentities: [{ name: '@scope/nmr-core', tagPrefix: 'core-v' }],
+    },
+  ],
+};
+
+export default config;
+```
+
+Each `legacyIdentity` is a complete `(name, tagPrefix)` snapshot of the workspace at an earlier point. In the common case — the tag-derivation rule changed but the npm name did not — the identity's `name` equals the current `name`. If an earlier publish used a different npm name, use that prior name here.
 
-// Accepts the full workspace-relative path
-component('packages/arrays');
+Verify with `release-kit show-tag-prefixes` — it prints the derived prefix per workspace, tag counts under each declared legacy prefix, and any undeclared release-shaped prefixes it finds in the repo (with a copy-pasteable config snippet that includes a `TODO-fill-in-legacy-npm-name` placeholder to replace with the prior npm name). After declaring, `release-kit prepare` consults the union of the current and legacy tag prefixes when searching for the most recent baseline tag, and changelog generation matches tags under either prefix.
+
+See the `legacyIdentities` entry in the [`WorkspaceOverride`](#workspaceoverride) section for the config shape.
+
+## Using `deriveWorkspaceConfig()` for manual configuration
+
+If you need to build a `MonorepoReleaseConfig` manually (e.g., for the legacy script-based approach), the exported `deriveWorkspaceConfig()` helper creates a `WorkspaceConfig` from a workspace-relative path. It reads the workspace's `package.json` to derive the tag prefix from the package name:
+
+```typescript
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+// packages/arrays/package.json contains `"name": "@scope/arrays"`
+deriveWorkspaceConfig('packages/arrays');
 // => {
 //   dir: 'arrays',
+//   name: '@scope/arrays',
 //   tagPrefix: 'arrays-v',
+//   workspacePath: 'packages/arrays',
 //   packageFiles: ['packages/arrays/package.json'],
 //   changelogPaths: ['packages/arrays'],
 //   paths: ['packages/arrays/**'],
 // }
 ```
 
-The `dir` field is derived from `path.basename()`, so `packages/arrays` and `libs/arrays` both produce `dir: 'arrays'`. The `tagPrefix` is always `${dir}-v` — it cannot be customized.
+`dir` is the basename of the workspace path and is the stable internal identifier used by `--only`, `WorkspaceOverride.dir`, and the dependency graph. `tagPrefix` is derived from the unscoped `package.json` `name` — any leading `@scope/` is stripped — so tags reflect the package identity rather than the directory layout. For example, a workspace at `packages/core` with `"name": "@williamthorsen/nmr-core"` produces `tagPrefix: 'nmr-core-v'`, yielding tags like `nmr-core-v1.3.0`.
+
+The workspace's `package.json` must declare a non-empty `name` field; `deriveWorkspaceConfig()` throws otherwise. If two workspaces produce the same `tagPrefix` (because their unscoped names collide), `mergeMonorepoConfig()` throws and names the colliding workspaces so you can rename one.
 
 ## Legacy script-based approach
 
@@ -284,10 +494,10 @@ The CLI-driven approach is recommended for new setups. The script-based approach
 ```typescript
 // .github/scripts/release.config.ts
 import type { MonorepoReleaseConfig } from '@williamthorsen/release-kit';
-import { component } from '@williamthorsen/release-kit';
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
 
 export const config: MonorepoReleaseConfig = {
-  components: [component('packages/arrays'), component('packages/strings')],
+  workspaces: [deriveWorkspaceConfig('packages/arrays'), deriveWorkspaceConfig('packages/strings')],
   formatCommand: 'npx prettier --write',
 };
 ```
@@ -300,10 +510,70 @@ import { config } from './release.config.ts';
 runReleasePrepare(config);
 ```
 
-The key difference: the script-based approach requires manually listing every component, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
+The key difference: the script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
 
 ## Breaking changes
 
+### `resolveReleaseTags` takes workspaces; `WorkspaceConfig` requires `workspacePath`
+
+Tag resolution is now driven by workspace records rather than a caller-supplied directory map, so `resolveReleaseTags` can report both the workspace `dir` and its `workspacePath` for every resolved tag.
+
+- `resolveReleaseTags` signature changed from `(workspaceMap?: Map<string, string>)` to `(workspaces?: readonly WorkspaceConfig[])`.
+- `WorkspaceConfig` gained a required `workspacePath: string` field.
+
+Replace direct `Map`-based calls with `deriveWorkspaceConfig()`, which now populates `workspacePath` for you:
+
+```diff
+-import { resolveReleaseTags } from '@williamthorsen/release-kit';
+-
+-const workspaceMap = new Map([['core', 'packages/core']]);
+-resolveReleaseTags(workspaceMap);
++import { deriveWorkspaceConfig, resolveReleaseTags } from '@williamthorsen/release-kit';
++
++resolveReleaseTags([deriveWorkspaceConfig('packages/core')]);
+```
+
+If you construct `WorkspaceConfig` objects directly, add `workspacePath` alongside the other required fields.
+
+### `release-kit publish` and `release-kit push` replace `--only` with `--tags`
+
+The `--only=<dir>` flag on `release-kit publish` and `release-kit push` has been removed. Both commands now filter by full tag name via `--tags=<tag1>[,<tag2>...]`, matching `release-kit create-github-release`. Passing `--only=...` after upgrading produces an `Unknown option: --only` error.
+
+Local usage mapping:
+
+```diff
+-release-kit publish --only=core
++release-kit publish --tags=core-v1.3.0
+
+-release-kit push --only=core,cli
++release-kit push --tags=core-v1.3.0,cli-v0.5.0
+```
+
+Omitting `--tags` preserves the previous behavior of operating on every release tag at HEAD. The reusable workflow `publish.reusable.yaml` also accepts an optional `tags:` input, and the scaffolded `publish.yaml` now passes `tags: ${{ github.ref_name }}` so the publish scope is explicit rather than relying on `actions/checkout@v6`'s fetch default. Existing callers that do not set `tags:` continue to work unchanged.
+
+### GitHub Release creation moved to its own command and workflow
+
+`release-kit publish` no longer creates GitHub Releases as a side effect, and the `releaseNotes.shouldCreateGithubRelease` config field has been removed. Adoption is now signaled by installing the dedicated `create-github-release.reusable.yaml` workflow.
+
+If you previously set the field, remove it from `.config/release-kit.config.ts`. The new caller template (scaffolded by `release-kit init`) looks like this:
+
+```yaml
+name: Create GitHub Release
+on:
+  push:
+    tags:
+      - '*-v[0-9]*.[0-9]*.[0-9]*'
+permissions:
+  contents: write
+jobs:
+  create-github-release:
+    uses: williamthorsen/node-monorepo-tools/.github/workflows/create-github-release.reusable.yaml@workflow/create-github-release-v1
+    with:
+      tag: ${{ github.ref_name }}
+```
+
+The CLI command was renamed from `release-kit github-release` to `release-kit create-github-release`, and its filter flag changed from `--only=<package-name>` to `--tags=<full-tag-name>[,...]`.
+
 ### v1.1.0: `formatCommand` receives file paths as trailing arguments
 
 Previously, `formatCommand` was executed as-is (e.g., `pnpm run fmt` would run without arguments). Now, the paths of all modified files (package.json files and changelogs) are appended as trailing arguments.

package/cliff.toml.template

@@ -61,6 +61,7 @@ commit_preprocessors = []
 commit_parsers = [
   { message = "^release:", skip = true },
   { message = "^Merge", skip = true },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ai(!)?:", group = "Agentic support" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?bugfix(!)?:", group = "Bug fixes" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?ci(!)?:", group = "CI" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?deprecate(!)?:", group = "Deprecated" },
@@ -69,7 +70,7 @@ commit_parsers = [
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feat(!)?:", group = "Features" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?feature(!)?:", group = "Features" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fix(!)?:", group = "Bug fixes" },
-  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fmt(!)?:", group = "Formatting" },
+  { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?fmt(!)?:", skip = true },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?internal(!)?:", group = "Internal" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?perf(!)?:", group = "Performance" },
   { message = "^(\\#\\d+([.\\-]\\d+)?|\\#\\#|[A-Z]+-\\d+)\\s+([\\w-]+\\|)?performance(!)?:", group = "Performance" },

package/dist/esm/.cache

@@ -1 +1 @@
-d6a6d71f34f00ba31c3dca3b32657832693ff9c12de118fafa96fc3554835ecc
+4493cd8b695da653fc9ae7a81c0916cc0cb92c9acf3d560433b18cdd74f945a4