@williamthorsen/release-kit 4.8.0 → 5.1.0

package/README.md

@@ -4,6 +4,52 @@ 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.1.0 (2026-04-30)
+
+### Bug fixes
+
+- Make publish's clean-tree safety gate reachable (#311)
+
+  Fixes an issue where `release-kit publish` failed with pnpm's "working tree is dirty" error on a clean tree whenever `releaseNotes.shouldInjectIntoReadme: true` was configured. release-kit injects the release notes into the package README before invoking `pnpm publish`, so pnpm's own working-tree check fired on a tree release-kit had just dirtied — even though the user's tree was clean at command start.
+
+- Make `--set-version` + `project` rejection explicit (#319)
+
+  Improves the error users see when invoking `release-kit prepare --set-version` with a `project` block configured. The combination is still rejected — as before — but now produces a single, project-aware message ("--set-version cannot be combined with a project release…") rather than the previous two-step chain (`--set-version requires --only`, then `--only cannot be combined with a project release` after the user added `--only`).
+
+- Reject `--only` that would strand excluded dependents (#321)
+
+  Fixes a silent footgun in `release-kit prepare --only=...`: an excluded internal dependent with its own changes would be left unreleased with no runtime signal, even though the targeted workspace it depends on was being released. The command now rejects such invocations up front, naming every excluded dependent whose changes would be stranded.
+
+- Order prerelease versions correctly in changelog sort (#334)
+
+  Fixes a latent issue in `@williamthorsen/release-kit` where prerelease version tags (e.g., `1.2.3-alpha`, `1.2.3-rc.1`) were sorted as if their prerelease component were absent, causing them to appear in the wrong position relative to releases sharing the same base version. Changelog entries are now ordered per SemVer §11: prerelease versions precede the corresponding release (`1.2.3-alpha < 1.2.3`), build metadata is ignored for ordering, and entries that fail SemVer validation sort deterministically to the bottom of the list rather than collapsing into mid-list positions.
+
+### Features
+
+- Add `project` block for project-level release stage (#317)
+
+  Adds support for monorepos that ship a single combined deliverable to version, changelog, and release-note the project itself rather than only its constituent workspaces.
+
+- Publish JSON Schema for `.meta/label-map.json` (#325)
+
+  Adds a JSON Schema for `.meta/label-map.json` to release-kit, packaged at `packages/release-kit/schemas/label-map.json` and shipped to npm. Consumers reference it via the stable raw URL pattern `https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json` — the same shape audit-deps already uses.
+
+- Label prepare errors with the failing stage (#326)
+
+  Adds stage attribution to errors thrown during `release-kit prepare`. Errors from per-workspace bumps and changelog generation, the project release stage, and the post-release format command now begin with a stage label that identifies the failing stage and (where relevant) the affected workspace.
+
+- Make `--force` and `--bump` orthogonal (#328)
+
+  Decouples `--force` and `--bump` so each flag has a single responsibility, and unifies skip semantics across the per-workspace and project pipelines.
+
+### Documentation
+
+- Document tag prefix collisions as general rule (#320)
+
+  Documents the strict-prefix tag-prefix collision rule as a general validation rule that applies to every release-kit consumer declaring more than one tag prefix: across active workspaces, declared legacy identities, retired packages, and the optional `project` block. Previously, the rule appeared only inside the `Project releases` validation list.
+<!-- /section:release-notes -->
+
 ## Installation
 
 ```bash
@@ -54,9 +100,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 +119,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 +131,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 +154,152 @@ 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           |
+| `project`         | `ProjectConfig`                  | Opt-in project-level release block. Declaring `project: {}` (even empty) enables a project-release stage in `prepare`         |
 
 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.
+
+`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.
+
+### Tag prefix collisions
+
+Tag prefixes from distinct owners must not be identical or be a strict prefix of one another. An owner is one of:
+
+- An active workspace, comprising its derived `tagPrefix` plus any declared `legacyIdentities[].tagPrefix`. Identities of the same workspace are one owner, so their prefixes are allowed to overlap (this represents the same package across renames).
+- A `retiredPackages[]` entry (one owner per entry).
+- The `project` block, when configured.
+
+release-kit resolves baseline tags via `git describe --match=<prefix>*`, so a strict-prefix overlap between distinct owners would cause that glob to return cross-matches against the wrong owner's history. For example, a project prefix of `v` collides with a workspace prefix of `vue-helpers-v`, since `git describe --match=v*` would return both project tags and `vue-helpers` tags.
+
+The rule is enforced at config load; the resulting error identifies both colliding declarations.
+
+### Project releases
+
+Some monorepos ship a single combined deliverable — a Chrome extension, a CLI binary, a packaged desktop app — for which the per-workspace tags and changelogs alone do not describe what the user actually receives. Declare the optional `project` block to add a project-level release stage that runs alongside the per-workspace pipeline.
+
+```typescript
+import type { ReleaseKitConfig } from '@williamthorsen/release-kit';
+
+const config: ReleaseKitConfig = {
+  // Empty object is enough to opt in. Every non-excluded workspace contributes.
+  project: {},
+};
+
+export default config;
+```
+
+When configured, each `release-kit prepare` run additionally:
+
+- Computes commits since the last project tag (`<tagPrefix><version>`), filtered to the union of every contributing workspace's paths.
+- Bumps the root `package.json`'s `version` field using the same bump-derivation rules as workspaces (or the `--bump=...` override).
+- Regenerates the root `./CHANGELOG.md` via `git-cliff`, scoped to the project's `tagPrefix` and contributing paths.
+- Emits `./.meta/changelog.json` (when `changelogJson.enabled`).
+- With `--with-release-notes`, additionally emits `./docs/RELEASE_NOTES.v<version>.md`.
+- Appends the project tag to `tmp/.release-tags` so `release-kit commit` and `release-kit tag` pick it up alongside per-workspace tags.
+
+If no contributing workspace has commits since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+
+#### `ProjectConfig`
+
+```typescript
+interface ProjectConfig {
+  tagPrefix?: string; // Defaults to 'v'
 }
 ```
 
+| Field       | Default | Description                                                          |
+| ----------- | ------- | -------------------------------------------------------------------- |
+| `tagPrefix` | `'v'`   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+
+Contributing workspaces are implicit: every non-excluded discovered workspace contributes. There is no field to override the contributing set in this initial release; if a future consumer needs to release a workspace as a component but exclude it from the project release, that override can be added then.
+
+Validation rules:
+
+- The root `package.json` must exist and declare a `version` field. release-kit reports an error at config-load time if either is missing.
+- The `project` block is rejected in single-package mode (the implicit "all non-excluded workspaces contribute" rule is meaningless in a single-package repo).
+- Unknown fields inside `project` are rejected.
+
+CLI flag interactions:
+
+- `--dry-run` previews project artifacts alongside workspace artifacts; no files are written.
+- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when there are no commits or no bump-worthy commits.
+- `--force` runs the project release even when no commits or no bump-worthy commits exist since the last project tag. Defaults to patch when `--bump` is not given; combine with `--bump=X` to release at a different level.
+- `--only` is rejected with an error when `project` is configured. `--only` is a surgical, single-workspace operation; combining it with a project release that rolls up every contributing workspace would create ambiguous semantics. To release a single workspace, use a config without a `project` block, or run a full `prepare` (no `--only`) to include the project release.
+- `--set-version` is rejected with an error when `project` is configured. `--set-version` operates on a single workspace, but a project release rolls up every contributing workspace; the two semantics don't compose. To use `--set-version`, run on a config without a `project` block.
+
+`--bump` and `--force` are orthogonal: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
+
+```sh
+# Release every target at its natural bump level (no flags).
+release-kit prepare
+
+# Force a release even when no bump-worthy commits exist; defaults to patch
+# per target, with each target keeping its natural bump if one is derivable.
+release-kit prepare --force
+
+# Force a release at a uniform level across every releasing target.
+release-kit prepare --force --bump=minor
+
+# --bump=X alone is a level chooser, NOT a trigger. If a target has no
+# bump-worthy commits, it skips with a "Pass --force..." reason. If it has
+# bump-worthy commits, the override applies. (Behavioral change from earlier
+# release-kit versions, where --bump=X alone would force a release.)
+release-kit prepare --bump=minor
+```
+
 ### `VersionPatterns`
 
 Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
@@ -140,21 +315,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 +351,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`                    | Release even when no commits or no bump-worthy commits exist since the last tag (defaults to patch; combine with `--bump=X` for a different level) |
+| `--only=name1,name2`         | Only process the named workspaces (monorepo only; rejected when a `project` block is configured)                                                   |
+| `--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
+```
+
+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:
 
-Component names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
+```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 +441,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`)
@@ -207,13 +459,33 @@ Manage GitHub label definitions via config-driven YAML files.
 
 `init` scaffolds `.config/sync-labels.config.ts` with auto-detected workspace scope labels and a `.github/workflows/sync-labels.yaml` caller workflow, then generates `.github/labels.yaml`. `generate` reads the config and writes `.github/labels.yaml`. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
 
+#### Published JSON Schema for `.meta/label-map.json`
+
+release-kit publishes a JSON Schema for `.meta/label-map.json` — a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. The schema lives at `packages/release-kit/schemas/label-map.json` in this repo and is reachable via the stable raw URL:
+
+```
+https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json
+```
+
+Consumers reference it from the top of their `.meta/label-map.json`:
+
+```json
+{
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/release-kit-v<version>/packages/release-kit/schemas/label-map.json",
+  "types": { "feat": "feature", "fix": "fix" },
+  "scopes": { "audit": "scope:audit" }
+}
+```
+
+release-kit publishes the schema only; it does not generate `.meta/label-map.json`. Generation requires commit-prefix knowledge that lives outside release-kit (in agent-conventions tooling), and is owned by those consumers.
+
 ## GitHub Actions workflow
 
 The `init` command scaffolds a release workflow at `.github/workflows/release.yaml` that delegates to a reusable release workflow. The scaffolded workflow accepts these inputs:
 
 | 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 +493,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 +529,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
+
+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
+// .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.
+
+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.
 
-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:
+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 { component } from '@williamthorsen/release-kit';
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
 
-// Accepts the full workspace-relative path
-component('packages/arrays');
+// 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 +588,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 +604,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
+fca70d83414ef35352e152c9e916f24705c93c5556b14c16388a5b791752f075

package/dist/esm/assertCleanWorkingTree.js

@@ -6,7 +6,7 @@ function assertCleanWorkingTree() {
   }).trim();
   if (status.length > 0) {
     throw new Error(
-      "Working tree has uncommitted changes. Commit or stash them before running prepare, or use --no-git-checks to bypass this check."
+      "Working tree has uncommitted changes. Commit or stash them, or use --no-git-checks to bypass this check."
     );
   }
 }