@williamthorsen/release-kit 10.6.0 → 10.7.0

package/dist/esm/bin/release-kit.js

@@ -35,8 +35,9 @@ Commands:
   work-types       Check for or sync work-type taxonomy drift against the upstream canonical
 
 Options:
-  --dry-run     Preview changes without writing files
-  --help, -h    Show this help message
+  --dry-run        Preview changes without writing files
+  --help, -h       Show this help message
+  --version, -V    Show the version number
 `);
 }
 function showSyncLabelsHelp() {
@@ -95,7 +96,7 @@ function showInitHelp() {
 Usage: release-kit init [options]
 
 Initialize release-kit in the current repository.
-By default, scaffolds only the GitHub Actions workflow file.
+By default, scaffolds only the GitHub Actions workflow files.
 
 Options:
   --with-config   Also scaffold .config/release-kit.config.ts and .config/git-cliff.toml

package/dist/esm/buildDependencyGraph.d.ts

@@ -1,10 +1,12 @@
 import type { WorkspaceConfig } from './types.js';
-/** Reverse adjacency map from package names to their workspace dependents. */
+/** Identities, current versions, and `workspace:` dependency edges of the workspaces' packages. */
 export interface DependencyGraph {
     /** Resolve a package name to its workspace `dir`. */
     packageNameToDir: Map<string, string>;
     /** Resolve a workspace `dir` to its package name (inverse of `packageNameToDir`). */
     dirToPackageName: Map<string, string>;
+    /** Resolve a workspace `dir` to its current version; absent when its `package.json` has no string `version`. */
+    dirToVersion: Map<string, string>;
     /** Map a package name to the workspaces that depend on it. */
     dependentsOf: Map<string, WorkspaceConfig[]>;
     /**
@@ -14,11 +16,10 @@ export interface DependencyGraph {
     dependenciesOf: Map<string, Set<string>>;
 }
 /**
- * Build a reverse dependency graph from the workspaces' `package.json` files.
+ * Builds the dependency graph from the workspaces' `package.json` files.
  *
  * Reads each workspace's primary `package.json` (first entry in `packageFiles`) to discover
- * `workspace:` references in `dependencies` and `peerDependencies`. Returns a map from each
- * package name to the workspaces that depend on it, enabling upward traversal from a bumped
- * package to all its dependents.
+ * `workspace:` references in `dependencies` and `peerDependencies`, and to record its current
+ * version.
  */
 export declare function buildDependencyGraph(workspaces: readonly WorkspaceConfig[]): DependencyGraph;

package/dist/esm/buildDependencyGraph.js

@@ -6,6 +6,7 @@ function isPackageJsonSubset(value) {
 export function buildDependencyGraph(workspaces) {
     const packageNameToDir = new Map();
     const dirToPackageName = new Map();
+    const dirToVersion = new Map();
     const dependentsOf = new Map();
     const dependenciesOf = new Map();
     const workspacePackages = new Map();
@@ -16,6 +17,9 @@ export function buildDependencyGraph(workspaces) {
         }
         const pkg = readPackageJsonSubset(primaryPackageFile);
         workspacePackages.set(workspace, pkg);
+        if (typeof pkg.version === 'string') {
+            dirToVersion.set(workspace.dir, pkg.version);
+        }
         if (pkg.name === undefined) {
             continue;
         }
@@ -44,7 +48,7 @@ export function buildDependencyGraph(workspaces) {
             }
         }
     }
-    return { packageNameToDir, dirToPackageName, dependentsOf, dependenciesOf };
+    return { packageNameToDir, dirToPackageName, dirToVersion, dependentsOf, dependenciesOf };
 }
 function readPackageJsonSubset(filePath) {
     let content;

package/dist/esm/init/scaffold.js

@@ -1,22 +1,30 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { findPackageRoot, writeFileWithCheck } from '@williamthorsen/nmr-core';
 import { describeError } from '@williamthorsen/toolbelt.errors';
 import { createGithubReleaseWorkflow, publishWorkflow, releaseConfigScript, releaseWorkflow } from "./templates.js";
 export function copyCliffTemplate(dryRun, overwrite) {
     const destPath = '.config/git-cliff.toml';
-    const root = findPackageRoot(import.meta.url);
-    const templatePath = resolve(root, 'cliff.toml.template');
-    if (!existsSync(templatePath)) {
-        return { filePath: destPath, outcome: 'failed', error: `Could not find bundled template at ${templatePath}` };
+    let root;
+    try {
+        root = findPackageRoot(import.meta.url);
+    }
+    catch (error) {
+        const message = describeError(error);
+        return { filePath: destPath, outcome: 'failed', error: `Failed to resolve package root: ${message}` };
     }
+    const templatePath = resolve(root, 'cliff.toml.template');
     let content;
     try {
         content = readFileSync(templatePath, 'utf8');
     }
     catch (error) {
         const message = describeError(error);
-        return { filePath: destPath, outcome: 'failed', error: `Failed to read template ${templatePath}: ${message}` };
+        return {
+            filePath: destPath,
+            outcome: 'failed',
+            error: `Failed to read bundled template at ${templatePath}: ${message}`,
+        };
     }
     return writeFileWithCheck(destPath, content, { dryRun, overwrite });
 }

package/dist/esm/planVersionBump.d.ts

@@ -16,6 +16,7 @@ export interface VersionBumpPlan {
 export declare function planVersionBump(packageFiles: readonly string[], releaseType: ReleaseType): VersionBumpPlan;
 /**
  * Computes an explicit version assignment for a workspace's package files without writing them,
- * bypassing commit-derived bump logic. Backs the `--set-version` flag.
+ * bypassing commit-derived bump logic. Backs the `--set-version` flag, and so rejects a
+ * `newVersion` that is not greater than the current version.
  */
 export declare function planVersionSet(packageFiles: readonly string[], newVersion: string): VersionBumpPlan;

package/dist/esm/planVersionBump.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { chainError } from '@williamthorsen/toolbelt.errors/candidate';
 import { bumpVersion } from "./bumpVersion.js";
+import { isForwardVersion } from "./compareVersions.js";
 function isPackageJson(value) {
     return typeof value === 'object' && value !== null && 'version' in value && typeof value.version === 'string';
 }
@@ -13,6 +14,9 @@ export function planVersionBump(packageFiles, releaseType) {
 export function planVersionSet(packageFiles, newVersion) {
     const { firstFile, firstPkg } = readPrimaryPackage(packageFiles);
     const currentVersion = firstPkg.version;
+    if (!isForwardVersion(currentVersion, newVersion)) {
+        throw new Error(`--set-version ${newVersion} is not greater than current version ${currentVersion}`);
+    }
     return { currentVersion, newVersion, writes: renderVersionWrites(packageFiles, firstFile, firstPkg, newVersion) };
 }
 function readPrimaryPackage(packageFiles) {

package/dist/esm/propagateBumps.d.ts

@@ -12,8 +12,6 @@ export interface ReleaseEntry {
      */
     newVersionOverride?: string;
 }
-/** Map from workspace `dir` to its current version string (read from package.json). */
-export type CurrentVersions = Map<string, string>;
 /**
  * Walk upward through the dependency graph via BFS, adding `patch` bumps for dependents
  * not already in the release set with a higher bump.
@@ -21,4 +19,4 @@ export type CurrentVersions = Map<string, string>;
  * Returns the full release set (direct + propagated). Direct entries that also have a
  * propagated dependency get `propagatedFrom` metadata without changing their bump type.
  */
-export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph, currentVersions: CurrentVersions): Map<string, ReleaseEntry>;
+export declare function propagateBumps(directBumps: Map<string, ReleaseEntry>, graph: DependencyGraph): Map<string, ReleaseEntry>;

package/dist/esm/propagateBumps.js

@@ -1,5 +1,5 @@
 import { bumpVersion } from "./bumpVersion.js";
-export function propagateBumps(directBumps, graph, currentVersions) {
+export function propagateBumps(directBumps, graph) {
     const result = new Map();
     for (const [dir, entry] of directBumps) {
         result.set(dir, { ...entry });
@@ -19,7 +19,7 @@ export function propagateBumps(directBumps, graph, currentVersions) {
         if (packageName === undefined) {
             continue;
         }
-        const currentVersion = currentVersions.get(dir);
+        const currentVersion = graph.dirToVersion.get(dir);
         const entry = result.get(dir);
         if (currentVersion === undefined || entry === undefined) {
             continue;

package/dist/esm/releasePrepare.js

@@ -5,7 +5,6 @@ import { buildReleaseSummary } from "./buildReleaseSummary.js";
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyChangelogOverrides, formatStaleOverrideKeyWarning, loadOverridesForScopes, } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
-import { isForwardVersion } from "./compareVersions.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { determineBumpFromCommits } from "./determineBumpFromCommits.js";
 import { getCommitsSinceTarget } from "./getCommitsSinceTarget.js";
@@ -13,7 +12,6 @@ import { hasPrettierConfig } from "./hasPrettierConfig.js";
 import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
-import { readCurrentVersion } from "./readCurrentVersion.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
 export function releasePrepare(config, options) {
@@ -34,17 +32,6 @@ export function releasePrepare(config, options) {
     const collector = createPolicyViolationCollector();
     let bump;
     if (setVersion !== undefined) {
-        const primaryPackageFile = config.packageFiles[0];
-        if (primaryPackageFile === undefined) {
-            throw new Error('No package files specified');
-        }
-        const currentVersion = readCurrentVersion(primaryPackageFile);
-        if (currentVersion === undefined) {
-            throw new Error(`Cannot validate --set-version: failed to read current version from ${primaryPackageFile}`);
-        }
-        if (!isForwardVersion(currentVersion, setVersion)) {
-            throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
-        }
         bump = planVersionSet(config.packageFiles, setVersion);
     }
     else {

package/dist/esm/releasePrepareMono.js

@@ -8,7 +8,6 @@ import { buildSyntheticChangelogEntry } from "./buildSyntheticChangelogEntry.js"
 import { mergeChangelogEntriesWithDisk, renderChangelogJson, resolveChangelogJsonPath } from "./changelogJsonFile.js";
 import { applyWorkspaceOverrides, createOverrideContext, formatStaleOverrideKeyWarning, } from "./changelogOverrides.js";
 import { createPolicyViolationCollector } from "./collectPolicyViolations.js";
-import { isForwardVersion } from "./compareVersions.js";
 import { decideRelease } from "./decideRelease.js";
 import { DEFAULT_BREAKING_POLICIES, DEFAULT_VERSION_PATTERNS, DEFAULT_WORK_TYPES } from "./defaults.js";
 import { detectUndeclaredTagPrefixes } from "./detectUndeclaredTagPrefixes.js";
@@ -19,7 +18,6 @@ import { resolveWorkTypes } from "./loadConfig.js";
 import { planReleaseNotesPreviews } from "./planReleaseNotesPreviews.js";
 import { planVersionBump, planVersionSet } from "./planVersionBump.js";
 import { propagateBumps } from "./propagateBumps.js";
-import { readCurrentVersion } from "./readCurrentVersion.js";
 import { releasePrepareProject } from "./releasePrepareProject.js";
 import { renderChangelogMarkdown } from "./renderChangelogMarkdown.js";
 import { deriveSectionOrder } from "./resolveReleaseNotesConfig.js";
@@ -32,7 +30,7 @@ export function releasePrepareMono(config, options) {
     }
     const sectionOrder = deriveSectionOrder(resolveWorkTypes(config.workTypes));
     const overrideContext = createOverrideContext(config.workspaces);
-    const { directBumps, directResults, skippedResults, currentVersions } = determineDirectBumps(config, options);
+    const { directBumps, directResults, skippedResults } = determineDirectBumps(config, options);
     const previousTags = new Map();
     for (const result of directResults.values()) {
         previousTags.set(result.workspace.dir, result.tag);
@@ -41,7 +39,7 @@ export function releasePrepareMono(config, options) {
         previousTags.set(skipped.workspace.dir, skipped.tag);
     }
     const graph = buildDependencyGraph(config.workspaces);
-    const fullReleaseSet = propagateBumps(directBumps, graph, currentVersions);
+    const fullReleaseSet = propagateBumps(directBumps, graph);
     const { sorted: sortedDirs, cyclicDirs } = topologicalSort(fullReleaseSet, graph);
     if (cyclicDirs.length > 0) {
         warnings.push(`Circular workspace dependencies detected among: ${cyclicDirs.join(', ')}. ` +
@@ -119,7 +117,6 @@ function determineDirectBumps(config, options) {
     const directBumps = new Map();
     const directResults = new Map();
     const skippedResults = [];
-    const currentVersions = new Map();
     const hintState = { emitted: false };
     const knownPrefixes = config.workspaces.flatMap(getAllTagPrefixes);
     for (const workspace of config.workspaces) {
@@ -130,21 +127,7 @@ function determineDirectBumps(config, options) {
         if (tag === undefined) {
             maybeEmitBaselineHint(workspace, knownPrefixes, hintState);
         }
-        const primaryPackageFile = workspace.packageFiles[0];
-        if (primaryPackageFile !== undefined) {
-            const currentVersion = tryStage(stageLabel, () => readCurrentVersion(primaryPackageFile));
-            if (currentVersion !== undefined) {
-                currentVersions.set(workspace.dir, currentVersion);
-            }
-        }
         if (setVersion !== undefined) {
-            const currentVersion = currentVersions.get(workspace.dir);
-            if (currentVersion === undefined) {
-                throw new Error(`Cannot validate --set-version: failed to read current version from ${primaryPackageFile ?? '(no package file)'}`);
-            }
-            if (!isForwardVersion(currentVersion, setVersion)) {
-                throw new Error(`--set-version ${setVersion} is not greater than current version ${currentVersion}`);
-            }
             directBumps.set(workspace.dir, { releaseType: 'patch', newVersionOverride: setVersion });
             directResults.set(workspace.dir, {
                 workspace,
@@ -199,7 +182,7 @@ function determineDirectBumps(config, options) {
             bumpOverride,
         });
     }
-    return { directBumps, directResults, skippedResults, currentVersions };
+    return { directBumps, directResults, skippedResults };
 }
 function collectSkippedWorkspaces(skippedResults, fullReleaseSet) {
     const workspaces = [];

package/dist/esm/sync-labels/resolveLabels.d.ts

@@ -5,9 +5,11 @@ import type { LabelDefinition } from './types.js';
  *
  * Resolution is an ordered fold with last-writer-wins: presets are loaded in `extends` order (a later preset replaces
  * an earlier preset's label of the same name), then the `labels` record is applied: An entry adds a label, replaces
- * one an earlier layer defined, or removes it (`null`). Replacement is wholesale, so an entry omitting `description`
+ * one an earlier layer defined, or removes it (`null`). Names match case-insensitively, as GitHub matches them, and the
+ * replacing layer's spelling becomes the label's name. Replacement is wholesale, so an entry omitting `description`
  * drops the one an earlier layer supplied rather than inheriting it.
- * Throws only on a dangling `null`: a removal naming a label no preset defined, which is a stale reference that
- * would otherwise produce no output diff to review.
+ * Throws on two misstatements that would otherwise leave no trace in the output diff: keys in the `labels` record that
+ * differ only in case, all but one of which the fold would discard, and a dangling `null`, a removal naming a label that
+ * no preset defined.
  */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];

package/dist/esm/sync-labels/resolveLabels.js

@@ -1,22 +1,28 @@
 import { loadPreset } from "./presets.js";
 export function resolveLabels(config) {
+    const labelEntries = Object.entries(config.labels ?? {});
+    const caseVariantGroups = findCaseVariantGroups(labelEntries.map(([name]) => name));
+    if (caseVariantGroups.length > 0) {
+        const groupList = caseVariantGroups.map((group) => group.map((name) => `'${name}'`).join(' and ')).join('; ');
+        throw new Error(`Keys in 'labels' differ only in case, which GitHub treats as the same label: ${groupList}. Keep one entry per label.`);
+    }
     const resolved = new Map();
     const presetNames = config.extends ?? [];
     for (const presetName of presetNames) {
         for (const label of loadPreset(presetName)) {
-            resolved.set(label.name, label);
+            resolved.set(toLabelKey(label.name), label);
         }
     }
-    const labelEntries = Object.entries(config.labels ?? {});
     for (const [name, spec] of labelEntries) {
+        const key = toLabelKey(name);
         if (spec === null) {
-            if (!resolved.has(name)) {
+            if (!resolved.has(key)) {
                 throw new Error(`Label '${name}' is set to null (remove), but no preset in 'extends' defines it. Fix the name or delete the entry.`);
             }
-            resolved.delete(name);
+            resolved.delete(key);
         }
         else {
-            resolved.set(name, {
+            resolved.set(key, {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
@@ -25,6 +31,15 @@ export function resolveLabels(config) {
     }
     return sortLabels(resolved.values().toArray());
 }
+function findCaseVariantGroups(names) {
+    return Map.groupBy(names, toLabelKey)
+        .values()
+        .filter((group) => group.length > 1)
+        .toArray();
+}
 function sortLabels(labels) {
-    return [...labels].sort((a, b) => a.name.localeCompare(b.name));
+    return labels.toSorted((a, b) => a.name.localeCompare(b.name));
+}
+function toLabelKey(name) {
+    return name.toLowerCase();
 }

package/dist/esm/types.d.ts

@@ -388,8 +388,10 @@ export type LabelSpec = z.infer<typeof labelSpecSchema>;
  * the GitHub repo, distinct from labels applied to PRs and issues).
  *
  * Resolution is an ordered fold with last-writer-wins: presets in `extends` order, then the `labels` record,
- * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`).
- * A `null` naming a label no earlier layer defined is a resolve-time error (`resolveLabels`), not a schema error.
+ * where an entry adds a label, replaces one an earlier layer defined, or removes it (`null`). Names match
+ * case-insensitively, as GitHub matches them, and the replacing layer's spelling wins.
+ * Two misstatements are resolve-time errors (`resolveLabels`), not schema errors: `labels` keys that differ only in
+ * case, and a `null` naming a label that no earlier layer defined.
  */
 export declare const repoLabelsSchema: z.ZodObject<{
     extends: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/esm/validateConfig.js

@@ -31,7 +31,7 @@ function preprocessDeprecatedKeys(raw) {
     const errors = [];
     const cleaned = { ...raw };
     if (isRecord(cleaned['releaseNotes']) && Object.hasOwn(cleaned['releaseNotes'], 'shouldCreateGithubRelease')) {
-        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow. Remove this field from your config; see README for the updated workflow.');
+        errors.push('releaseNotes.shouldCreateGithubRelease is no longer supported. Adoption is now signaled by installing the create-github-release workflow, which `release-kit init` scaffolds. Remove this field from your config.');
         const releaseNotesCopy = { ...cleaned['releaseNotes'] };
         delete releaseNotesCopy['shouldCreateGithubRelease'];
         cleaned['releaseNotes'] = releaseNotesCopy;

package/docs/api.md

@@ -0,0 +1,73 @@
+# Programmatic API
+
+How to build a release config by hand with `deriveWorkspaceConfig()`, the script-based approach that predates the CLI, and the workspace records that `resolveReleaseTags` takes.
+
+## 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/**'],
+// }
+```
+
+`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
+
+The CLI-driven approach is recommended for new setups. The script-based approach (using `runReleasePrepare` with a manually maintained config) is still supported for backward compatibility.
+
+```typescript
+// .github/scripts/release.config.ts
+import type { MonorepoReleaseConfig } from '@williamthorsen/release-kit';
+import { deriveWorkspaceConfig } from '@williamthorsen/release-kit';
+
+export const config: MonorepoReleaseConfig = {
+  workspaces: [deriveWorkspaceConfig('packages/arrays'), deriveWorkspaceConfig('packages/strings')],
+  formatCommand: 'npx prettier --write',
+};
+```
+
+```typescript
+// .github/scripts/release-prepare.ts
+import { runReleasePrepare } from '@williamthorsen/release-kit';
+import { config } from './release.config.ts';
+
+runReleasePrepare(config);
+```
+
+The key difference: the script-based approach requires manually listing every workspace, while the CLI auto-discovers them from `pnpm-workspace.yaml`.
+
+## `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.

package/docs/changelogs.md

@@ -0,0 +1,70 @@
+# Changelogs
+
+What reaches a published tarball, what each `.meta/changelog.json` item contains, how the git-cliff config is resolved, and how release notes reach a README.
+
+Neither `CHANGELOG.md` nor `.meta/changelog.json` reaches a published tarball on its own. npm stopped including `CHANGELOG` automatically in npm 7, so a package that declares a `files` field ships a changelog only where that field names `CHANGELOG.md` and `.meta/changelog.json`. release-kit's readyup kit reports a publishable workspace whose `files` field omits either.
+
+## `changelog.json` item schema
+
+Each item under a section in `.meta/changelog.json` carries one required field and four optional ones:
+
+| Field         | Type      | Meaning                                                                                                                                        |
+| ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description` | `string`  | The bullet headline, taken from the commit subject with the ticket ID and type prefix stripped.                                                |
+| `body`        | `string`  | The commit body, with trailing trailer metadata stripped.                                                                                      |
+| `breaking`    | `boolean` | Present and `true` where the commit subject carried the `!` prefix. See [`!` (breaking change) policy](work-types.md#-breaking-change-policy). |
+| `migration`   | `string`  | The migration step for a consumer. See below.                                                                                                  |
+| `hash`        | `string`  | The full commit SHA, and the key on which an override entry matches. Absent on synthetic propagation entries.                                  |
+
+Every optional field is omitted rather than emitted as `null`, so a consumer tests for presence.
+
+### The `migration` field
+
+A commit body states a migration step as a paragraph opening with the literal label `Migration:`. Where one is present, `migration` carries that paragraph with the label stripped:
+
+```jsonc
+{
+  "description": "Rename the workspace field",
+  "body": "Renames `name` to `id`.\n\nMigration: Change any uses of `name` to `id`.",
+  "migration": "Change any uses of `name` to `id`.",
+}
+```
+
+Three properties are worth knowing:
+
+- **It is independent of `breaking`.** A `fix` cannot carry `!` under the default breaking policy, and a `fix` that tightens validation still imposes a migration. Filter on `migration` to find every step; filter on `breaking` to find every breaking change.
+- **`body` keeps the paragraph.** The field is an extraction, not a move, so `CHANGELOG.md` and `.meta/changelog.json` go on agreeing.
+- **It is derived, not authored.** `migration` is not a field an override file can set (see [File shape](editorial-overrides.md#file-shape)); it is re-derived from whatever `body` an override installs, and cleared where that body carries no labeled paragraph. To change the migration text, override `body`.
+
+The label match is exact: `migration:` and `**Migration:**` are not recognized.
+
+## cliff.toml setup
+
+The package includes a bundled `cliff.toml.template` that is used automatically when no custom config is found. The resolution order:
+
+| Priority | Path                          | Notes                                           |
+| -------- | ----------------------------- | ----------------------------------------------- |
+| 1        | `cliffConfigPath` in config   | Explicit path, returned without existence check |
+| 2        | `.config/git-cliff.toml`      | Project-level override                          |
+| 3        | `cliff.toml`                  | Repo root fallback                              |
+| 4        | Bundled `cliff.toml.template` | Automatic fallback                              |
+
+The bundled template provides a generic git-cliff configuration that:
+
+- Strips issue-ticket prefixes matching `^[A-Z]+-\d+\s+` (e.g., `TOOL-123 `, `AFG-456 `)
+- Handles both `type: description` and `workspace|type: description` commit formats
+- Groups commits by work type via `[git].commit_parsers`
+
+The body template is intentionally empty: release-kit reads cliff's `--context` JSON output and renders `CHANGELOG.md` in-process via `renderChangelogMarkdown` (see [How it works](../README.md#how-it-works) for the rationale). The `[git].commit_parsers` section remains load-bearing for `--context` group assignment.
+
+To customize, scaffold a local copy with `release-kit init --with-config` and edit `.config/git-cliff.toml`. Edit only the `[git]` section — body-template changes have no effect.
+
+## Release-notes injection
+
+With `releaseNotes.shouldInjectIntoReadme` set to `true`, `release-kit publish` writes each package's release notes into its `README.md` for the duration of the publish, then restores the file. The notes are the all-audience sections of the released version's entry in `.meta/changelog.json`, under a `## Release notes — v<version> (<date>)` heading, and they replace whatever lies between the marker pair:
+
+```markdown
+<!-- section:release-notes --><!-- /section:release-notes -->
+```
+
+A README without the marker pair receives the notes at its top, above its title, and release-kit's readyup kit reports a README that lacks the markers. Injection is skipped with a warning when `changelogJson.enabled` is `false`, when the version has no entry, or when the entry has no all-audience content. `release-kit prepare --with-release-notes` writes the same injected README as a [preview](releasing.md#previewing-release-notes-with---with-release-notes).

package/docs/configuration.md

@@ -0,0 +1,105 @@
+# Configuration
+
+The fields of `.config/release-kit.config.ts`, how a workspace declares its prior identities or a retired package, the rule against colliding tag prefixes, and the patterns that decide a bump.
+
+A minimal config file is in the [README](../README.md#configuration).
+
+## `ReleaseKitConfig` reference
+
+| Field              | Type                                                      | Description                                                                                                                                                                                   |
+| ------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cliffConfigPath`  | `string`                                                  | Explicit path to cliff config. If omitted, resolved automatically: `.config/git-cliff.toml` → `cliff.toml` → bundled template                                                                 |
+| `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                                                                                                                                            |
+| `breakingPolicies` | `Record<string, 'forbidden' \| 'optional' \| 'required'>` | Per-type `!`-policy lookup. Defaults to `DEFAULT_BREAKING_POLICIES`. Replaces the default entirely when provided. Set to `{}` to disable enforcement                                          |
+| `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`                                                                         |
+| `repoLabels`       | `RepoLabelsConfig`                                        | Declares the repository's label registry for `sync-labels`; see [Label configuration](labels.md#label-configuration)                                                                          |
+| `changelogJson`    | `ChangelogJsonConfig`                                     | Controls `.meta/changelog.json`: `enabled` (default `true`), `outputPath` (default `'.meta/changelog.json'`), and `devOnlySections`; see [Custom work types](work-types.md#custom-work-types) |
+| `releaseNotes`     | `ReleaseNotesConfig`                                      | `shouldInjectIntoReadme` (default `false`) injects release notes into each package's README while it publishes; see [Release-notes injection](changelogs.md#release-notes-injection)          |
+
+All fields are optional.
+
+## `WorkspaceOverride`
+
+```typescript
+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 { defineConfig } from '@williamthorsen/release-kit/config';
+
+export default defineConfig({
+  retiredPackages: [{ name: '@scope/preflight', tagPrefix: 'preflight-v', successor: 'readyup' }],
+});
+```
+
+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.
+
+## `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.
+
+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.
+
+## `VersionPatterns`
+
+Defines which commit types trigger major or minor bumps. Any recognized type not listed defaults to a patch bump.
+
+```typescript
+interface VersionPatterns {
+  major: string[]; // Patterns triggering a major bump ('!' = any breaking change)
+  minor: string[]; // Commit types triggering a minor bump
+}
+```
+
+Default: `{ major: ['!'], minor: ['feat'] }`