@williamthorsen/release-kit 10.6.0 → 10.7.0

package/docs/editorial-overrides.md

@@ -0,0 +1,144 @@
+# Editorial overrides
+
+How to correct a generated changelog entry without rewriting history: where override files live, how they compose, what an entry may set, and how to validate the files.
+
+Generated changelogs occasionally need editorial correction — typos, redacted scope, reworded entries, or historical commits whose bodies carry verbatim PR-template scaffolding (`## What`, `## Why`, etc.) that renders as literal text in user-facing release notes. Rewriting git history is not viable, and any in-place edit to `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release because release-kit regenerates both artifacts from scratch.
+
+Override files are the supported escape hatch. Drop a checked-in JSON file at the conventional path for the scope you want to influence, keyed by commit hash, and `release-kit prepare` applies the overrides between `buildChangelogEntries` and serialization. Both `CHANGELOG.md` and `.meta/changelog.json` reflect the post-override view, so downstream consumers (the GitHub Release body, the in-app release-notes page, etc.) see the same content.
+
+## File-location convention
+
+| Scope               | Path                                           | Applies to                                              |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------- |
+| Project (root)      | `.meta/changelog-overrides.json`               | The project changelog and every workspace's changelog   |
+| Workspace           | `packages/<ws>/.meta/changelog-overrides.json` | Only that workspace's changelog                         |
+| Single-package mode | `.meta/changelog-overrides.json`               | The package's changelog (collapses to the project case) |
+
+Filenames have no leading dot — the `.meta/` directory already provides the visibility property and parallels its sibling artifacts (`changelog.json`, `label-map.json`).
+
+## Composition: per-key shadowing
+
+When a workspace's changelog is rendered, both files are consulted:
+
+- The root file's overrides apply globally.
+- The workspace file's overrides apply only to that workspace.
+- When the **same hash key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog — no field-level merge, the workspace entry replaces the root entry.
+- Different prefix strings that happen to resolve to the same commit do **not** shadow; they fall through to the existing ambiguous-prefix error so you can correct your override file.
+- Other keys in the root file still apply for that workspace.
+
+The project-level changelog applies only the root file. Per-workspace files describe per-workspace editorial intent and have no meaning at the aggregated project tier.
+
+## Stale-key warnings
+
+A key that doesn't match any commit gets a stale-reference warning. The warning's scope mirrors the file's scope:
+
+- **Per-workspace files** are warned against their own apply context. A key in `packages/foo/.meta/changelog-overrides.json` that doesn't match any commit in foo's changelog is unambiguously stale and is warned immediately.
+- **Root file** keys are aggregated globally — a root key that matches in any workspace or in the project changelog is non-stale; a root key matched nowhere is warned exactly once after all batches complete.
+
+## File shape
+
+```json
+{
+  "82962311": {
+    "audience": "skip"
+  },
+  "abc1234d": {
+    "body": "Cleaned-up prose without the original PR-template scaffolding."
+  },
+  "ef567890": {
+    "description": "Rewritten headline that fixes the typo",
+    "body": "Optional replacement body."
+  }
+}
+```
+
+Per-entry fields are all optional, but at least one must be present per entry:
+
+| Field         | Type                       | Effect                                                                                                                            |
+| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `audience`    | `'all' \| 'dev' \| 'skip'` | `'skip'` removes the entry entirely. `'all'` and `'dev'` are reserved for a future audience-reclassification feature (see below). |
+| `description` | `string`                   | Replaces the entry's bullet headline. Other fields are preserved.                                                                 |
+| `body`        | `string`                   | Replaces the entry's body (the prose that renders below the bullet). Other fields are preserved.                                  |
+| `breaking`    | `boolean`                  | Toggles the `🚨 **Breaking:** ` marker on the bullet.                                                                             |
+
+There is no `migration` key: the field is derived from `body`, so an override that replaces `body` re-derives it. See [The `migration` field](changelogs.md#the-migration-field).
+
+## Hash-prefix matching
+
+Keys can be either the full 40-character commit SHA or a non-ambiguous prefix. The matcher walks every `ChangelogItem.hash` value present in the entry tree and resolves each override key to its set of matching hashes:
+
+- **Exact prefix match (1 hit)** — the override applies. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
+- **No matches (0 hits)** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues.
+- **Ambiguous prefix (2+ hits)** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+
+Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
+
+## Validation
+
+The override file is validated when `release-kit prepare` loads it. Each error names the offending key so you can locate it in your file:
+
+- Missing file → empty map, no error (the no-op default — projects that do not need overrides skip the file entirely).
+- Malformed JSON → error.
+- Wrong top-level shape (e.g., array, primitive) → error.
+- Unknown fields on an entry → error.
+- Wrong field types (e.g., `description` as a number) → error.
+- An entry with no fields set → error (a copy-paste mistake more often than not).
+- `audience: 'all'` or `audience: 'dev'` → error in the current release: only `'skip'` is supported (see below).
+
+### Standalone validation: `release-kit overrides validate`
+
+For a focused overrides-only health check (locally or as a CI gate), run:
+
+```sh
+pnpm exec release-kit overrides validate
+```
+
+This walks every `.meta/changelog-overrides.json` file across the project tier and per-workspace tier, reporting three classes of finding:
+
+| Class               | Examples                                                                                    | Exit code |
+| ------------------- | ------------------------------------------------------------------------------------------- | --------- |
+| Schema/parse errors | malformed JSON, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
+| Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                | `2`       |
+| Stale-key warnings  | an override key resolves to no commit in its applicable scope                               | `1`       |
+
+Tier-aware stale-key semantics match `release-kit prepare`'s match-set exactly: a workspace-tier key is stale if it does not match in its own workspace's history; a root-tier key is stale only if it matches in **no** scope (no workspace AND not the project release window).
+
+The same logic is also exposed programmatically via the `validateAllChangelogOverrides` function exported from `@williamthorsen/release-kit`, for callers that want to integrate the check into their own tooling.
+
+## Audience semantics: v1 supports `'skip'` only
+
+The on-disk format declares the full `'all' | 'dev' | 'skip'` audience vocabulary so the file format will not need to change when the v2 reclassification feature ships. In the current release, only `'skip'` is supported at runtime; `'all'` and `'dev'` are rejected with an explicit "not yet supported" error.
+
+The eventual v2 behavior will let an override move a single item to a different audience section (e.g., reclassifying a `Documentation` entry as `Internal features` to keep it out of public-facing release notes). v1 deliberately leaves that as a separate change so the override mechanism can ship now and the section-split logic can land additively later.
+
+## Worked example 1: cleaning up scaffolded historical commits (root file)
+
+Suppose a year-old commit `82962311` was authored from a PR template that left `## What` / `## Why` headings in the body, and that commit now appears in your in-app release notes as literal Markdown headings. Add an override at the project tier:
+
+```json
+// .meta/changelog-overrides.json
+{
+  "82962311": {
+    "body": "Add the in-app release-notes page with version-aware navigation."
+  }
+}
+```
+
+On the next `release-kit prepare` run, the matched item's body is replaced before the JSON and Markdown artifacts are written. The original git history is untouched.
+
+## Worked example 2: suppressing a cross-attribution spillover (workspace file)
+
+Release-kit attributes commits to workspaces by file path, so a commit that primarily belongs to one workspace can land in another's changelog if it touched files there. Suppose commit `1ce3d2f` renamed the `audit-deps` package to `v11y-check` (scope `v11y-check`) but also edited `packages/nmr/src/default-scripts.ts` and `packages/nmr/README.md`. The commit correctly appears in `packages/v11y-check/CHANGELOG.md`, but it also spills into `packages/nmr/CHANGELOG.md` where it isn't the right editorial framing.
+
+Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
+
+```json
+// packages/nmr/.meta/changelog-overrides.json
+{
+  "1ce3d2f": {
+    "audience": "skip"
+  }
+}
+```
+
+The commit is now suppressed in nmr's changelog only — it still appears in v11y-check's, where it belongs. A root-tier `'skip'` would have removed it from both, which is the wrong outcome.

package/docs/labels.md

@@ -0,0 +1,83 @@
+# Labels
+
+How to declare the repository's labels in `.config/release-kit.config.ts`, how the scaffolded workflow applies them, and the published schema for `.meta/label-map.json`.
+
+## `release-kit sync-labels`
+
+Manage GitHub label definitions via the `repoLabels` block of `.config/release-kit.config.ts`.
+
+`init` scaffolds the `.github/workflows/sync-labels.yaml` caller workflow and seeds a `repoLabels` block with scope labels discovered from workspaces and declared `retiredPackages`. When `.config/release-kit.config.ts` does not exist, `init` writes it; when it does, `init` prints the block for manual paste — a hand-authored config is never rewritten. `generate` resolves the block and writes `.github/labels.yaml`; with `--check` it regenerates in memory and exits non-zero if the committed file is stale or missing, writing nothing. `sync` triggers the workflow remotely — it requires the `gh` CLI and an existing workflow file.
+
+Every `sync-labels` subcommand refuses to run while the retired `.config/sync-labels.config.ts` is present, so custom labels cannot be silently dropped mid-migration, and the refusal names what to move and where.
+
+### Label configuration
+
+```typescript
+import { defineConfig } from '@williamthorsen/release-kit/config';
+
+export default defineConfig({
+  repoLabels: {
+    extends: ['common'],
+    labels: {
+      'scope:my-package': { color: '00ff96' }, // add, with no description
+      bug: { color: 'b60205', description: 'Something broken' }, // replace the preset's `bug`
+      wontfix: null, // remove the preset's `wontfix`
+    },
+  },
+});
+```
+
+The block declares the repository's label registry — the set of labels defined on the GitHub repo, distinct from labels applied to PRs and issues. Resolution is an ordered fold with last-writer-wins:
+
+1. Presets, in `extends` order — a later preset wins on a shared name.
+2. The `labels` record — an entry adds a label, replaces one an earlier layer defined, or removes it (`null`). Replacement is wholesale: an entry omitting `description` resolves to no description rather than inheriting the one an earlier layer supplied.
+
+Names match case-insensitively, as GitHub matches them: `Bug` in the `labels` record replaces a preset's `bug`, and `Bug: null` removes it. A label takes the spelling of the last layer to write it.
+
+`description` is optional throughout, in a preset as in the `labels` record, and `sync-labels init` generates none for a scope label. The generated file spells an absent description `''` because `github-label-sync` reads an omitted description as "leave the label's current one alone"; the empty form clears it.
+
+Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff is where an unexpected change surfaces at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name that no preset defines, and `labels` keys that differ only in case, all but one of which the fold would discard.
+
+### When labels are applied
+
+The scaffolded workflow carries three triggers:
+
+| Trigger                                                   | Job     | Token           | Effect                            |
+| --------------------------------------------------------- | ------- | --------------- | --------------------------------- |
+| Push to the default branch touching `.github/labels.yaml` | `sync`  | `issues: write` | Applies the labels                |
+| Manual dispatch (`release-kit sync-labels sync`)          | `sync`  | `issues: write` | Applies the labels                |
+| Pull request touching `.github/labels.yaml`               | `check` | `issues: read`  | Logs the diff without applying it |
+
+Applying on merge closes the window in which a regenerated `.github/labels.yaml` sits unapplied — a window in which a later manual dispatch would apply a label set nobody reviewed.
+
+The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion the sync would perform, including deletions of labels the file does not declare — the destructive edits a diff of `.github/labels.yaml` alone cannot show, because a label created by hand or by another workflow is absent from the file both before and after. Read that log; the check reports success whether or not the diff is destructive, so a green check is not evidence that nothing will be deleted.
+
+The two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split is what keeps a write-scoped token out of pull-request runs.
+
+The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore needs no per-repo edit whatever that branch is named — and a push touching `.github/labels.yaml` on any other branch produces a run whose jobs all skip.
+
+Manual dispatch is not a preview. It matches the `sync` job, so it applies the labels, deletions included; only the pull-request path runs in dry-run.
+
+### Dry-run checks on fork pull requests
+
+GitHub issues a read-only `GITHUB_TOKEN` to pull requests from forks, and by default holds runs from first-time contributors until a maintainer approves them. The dry-run reads labels and writes nothing, so the check normally runs once approved. A repo that disables workflows on fork pull requests gets no check at all; to preview such a change, push the branch to the base repo and open the pull request from there.
+
+### 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.

package/docs/project-releases.md

@@ -0,0 +1,74 @@
+# Project releases
+
+How to add a project-level release to a monorepo, what the `project` block accepts, and how that release interacts with `prepare`'s flags.
+
+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/config';
+
+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 `paths` (by default, 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` from the structured `ChangelogEntry[]` produced by `git-cliff --context` (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
+- 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 commit under `paths` has landed since the last project tag, the project release is silently skipped — same behavior as a per-workspace skip.
+
+## `ProjectConfig`
+
+```typescript
+interface ProjectConfig {
+  paths?: string[]; // Defaults to the union of every contributing workspace's paths
+  tagPrefix?: string; // Defaults to 'v'
+}
+```
+
+| Field       | Default                 | Description                                                          |
+| ----------- | ----------------------- | -------------------------------------------------------------------- |
+| `paths`     | Contributing-path union | Patterns selecting the commits the project release considers         |
+| `tagPrefix` | `'v'`                   | Prefix for project tags. The full tag is `${tagPrefix}${newVersion}` |
+
+By default the contributing workspaces are implicit: every non-excluded discovered workspace contributes its `<dir>/**` glob, and the project release considers commits under their union.
+
+Declare `paths` to choose the window yourself. Each entry reaches two matchers: `git log` as a pathspec, and `git-cliff --include-path` as a glob. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
+
+A repo whose content lives at the root — where no commit matches any `<dir>/**` glob, so the project release would skip every run — declares the whole tree:
+
+```typescript
+const config: ReleaseKitConfig = {
+  project: { paths: ['**'] },
+};
+```
+
+`'**'` is the whole-tree pattern, matching root-level files, dotfiles, and nested paths alike.
+
+Terminate a directory scope with `/**`. The two matchers agree on `'aws/**'` but diverge on a bare `'aws'`, which git reads as the whole subtree and git-cliff matches against nothing; `'.'` is the same trap for the repo root. A release under such an entry finds commits, bumps the version, and writes the tag, while its changelog gains no entry for them — and nothing reports an error.
+
+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 package's own release already covers the whole repo, so a project tier would only duplicate it).
+- `paths`, when declared, must hold at least one non-empty string. An empty array is rejected: it reaches git and git-cliff as no filter at all, which is the inverse of how it reads.
+- 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` narrows the run to the named workspaces and skips the project release, which is reported as a warning. The project release rolls up every contributing workspace, and `--only` changes which workspaces those are, so rolling up a narrowed set would release a project version covering work the run excluded. 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.
+
+How `--bump` and `--force` combine for every target is in [Releasing](releasing.md#release-kit-prepare).

package/docs/publishing.md

@@ -0,0 +1,30 @@
+# Publishing
+
+How `release-kit publish` and `release-kit create-github-release` choose which packages to publish and which tags get a GitHub Release.
+
+## `release-kit publish`
+
+Publish packages that have release tags on HEAD. The publish workflow's reusable workflow `publish.reusable.yaml` invokes this command in CI.
+
+### Publishability filter
+
+`publish` and `create-github-release` operate only on workspaces where `package.json#private` is absent or `false`. A workspace marked `private: true` is "versioned but not published": it can still be tagged by `release-kit tag` and get a `CHANGELOG.md` entry, but it is skipped by both `release-kit publish` (no registry publish) and `release-kit create-github-release` (no GitHub Release). `private: true` alone routes a workspace out of publish and announce — no extra release config is required. Other commands ignore this filter and operate on private workspaces unchanged.
+
+An unpublishable tag is always skipped cleanly, never fatal. For `release-kit publish`, whether the skip is announced depends on how the tag was resolved:
+
+- **Without `--tags`** (implicit resolution): unpublishable tags on HEAD are silently filtered. The pre-publish listing shows only the publishable subset. If the filter empties the set, `release-kit publish` prints `Nothing to publish.` and exits 0.
+- **With `--tags`** (explicit naming): each named tag pointing at an unpublishable workspace is skipped with a warning, and any publishable tags named in the same command still publish.
+
+`release-kit create-github-release` skips unpublishable workspaces with a warning regardless of `--tags`; an all-private tag set is a clean no-op.
+
+Example warning when an explicit tag is unpublishable:
+
+```
+Skipping basic-v1.0.0 (packages/basic): package.json#private is true.
+```
+
+## `release-kit create-github-release`
+
+Create GitHub Releases from `changelog.json` for tags on HEAD. Independent of `npm publish`: invoking this command creates Releases for publishable packages whether or not they were published to a registry. Private workspaces are skipped (see [Publishability filter](#publishability-filter)).
+
+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.

package/docs/readiness-checks.md

@@ -0,0 +1,18 @@
+# Readiness checks
+
+What release-kit's two readyup kits check, how to run each, and what `npm-auto-publish` needs from the npm session.
+
+release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits that check a consuming repo against the release it has installed: the `default` kit covers release-kit's own setup — workflows matching the current templates, config free of removed fields, sync-labels wiring — and `npm-auto-publish` covers a repo's OIDC-based npm publishing setup. Both ship inside the package, so they check against the version you installed rather than whatever a repository ref happens to point at, and a check added in a release reaches your repo on upgrade.
+
+The [README](../README.md#readiness-checks) shows how to name release-kit in the readyup config.
+
+```bash
+rdy run --packages                                               # every kit each listed package publishes
+rdy run --from npm:@williamthorsen/release-kit                   # the default kit alone
+rdy run --from npm:@williamthorsen/release-kit npm-auto-publish  # the npm-auto-publish kit
+rdy list --from npm:@williamthorsen/release-kit                  # what release-kit publishes
+```
+
+`--packages` is the form that survives release-kit publishing further kits.
+
+`npm-auto-publish` queries the npm registry for each package's trusted publisher, so it needs an npm session elevated by two-factor authentication, and is meant to be invoked deliberately rather than swept up by an unattended run. A session that cannot answer those queries, whether it is missing a login, missing the elevation, or facing an unreachable registry, is reported once by the `npm session can answer trust queries` gate. The rows that would repeat the failed query then stand down: the trusted-publisher rows in every case, and `published to npm` where the registry itself is unreachable. Each package's `package.json` checks report throughout, since they read no registry.

package/docs/releasing.md

@@ -0,0 +1,108 @@
+# Releasing
+
+How to scaffold the release workflows, what `release-kit prepare` does with its flags, and how the release workflow runs a release.
+
+The [README](../README.md#quick-start) shows the first run.
+
+## `release-kit init`
+
+Initialize release-kit in the current repository. By default, scaffolds only the GitHub Actions workflow files. Use `--with-config` to also scaffold configuration files.
+
+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`)
+
+## `release-kit prepare`
+
+Run release preparation with automatic workspace discovery.
+
+Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
+
+`--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.
+release-kit prepare --bump=minor
+```
+
+### 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`, prepare reports 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:
+
+```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`.
+
+## 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  | Workspaces to release (comma-separated, leave empty for all)                                                                |
+| `bump`  | choice  | Override bump type: `patch`, `minor`, `major` (empty = auto-detect)                                                         |
+| `force` | boolean | Release even when no commits or no bump-worthy commits exist (defaults to patch; combine with `bump` for a different level) |
+
+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`, `--bump`, and `--force` flags, check for changes, read tags from `tmp/.release-tags`, then commit, tag, and push.
+
+### Triggering a release
+
+```sh
+# All workspaces
+gh workflow run release.yaml
+
+# Specific workspace(s)
+gh workflow run release.yaml -f only=arrays
+gh workflow run release.yaml -f only=arrays,strings -f bump=minor
+```
+
+Or use the GitHub UI: Actions > Release > Run workflow.

package/docs/work-types.md

@@ -0,0 +1,121 @@
+# Work types and tiers
+
+The taxonomy against which release-kit parses commits: its tiers, the breaking-change policy, section markers, customization, and the commands that compare it with its upstream.
+
+The canonical taxonomy lives in `packages/release-kit/src/work-types.json` and is split into three tiers that drive section rendering and audience classification.
+
+| Tier     | Key         | Header                    | Aliases       | `!` policy   |
+| -------- | ----------- | ------------------------- | ------------- | ------------ |
+| public   | `feat`      | 🎉 Features               | `feature`     | optional     |
+| public   | `drop`      | 🪦 Removed                |               | **required** |
+| public   | `deprecate` | 🗑️ Deprecated             |               | forbidden    |
+| public   | `fix`       | 🐛 Bug fixes              | `bugfix`      | forbidden    |
+| public   | `sec`       | 🔒 Security               | `security`    | optional     |
+| public   | `perf`      | ⚡ Performance            | `performance` | forbidden    |
+| internal | `internal`  | 🏗️ Internal features      | `utility`     | forbidden    |
+| internal | `refactor`  | ♻️ Refactoring            |               | forbidden    |
+| internal | `tests`     | 🧪 Tests                  | `test`        | forbidden    |
+| process  | `tooling`   | ⚙️ Tooling                |               | forbidden    |
+| process  | `ci`        | 👷 CI                     |               | forbidden    |
+| process  | `deps`      | 📦 Dependencies           | `dep`         | forbidden    |
+| process  | `ai`        | 🤖 Agentic support        |               | forbidden    |
+| process  | `docs`      | 📚 Documentation          | `doc`         | forbidden    |
+| process  | `fmt`       | (excluded from changelog) |               | forbidden    |
+
+## Tier semantics
+
+- **`public`** — visible to all audiences. `public`-tier sections appear in both public release notes and dev changelogs.
+- **`internal`** — dev-only. `internal`-tier sections appear in dev changelogs but not in public-facing release notes.
+- **`process`** — dev-only. Same audience treatment as `internal`.
+
+Section render order is **tier order (`public` → `internal` → `process`), then row order within tier**. The bundled `cliff.toml.template` encodes this order via hidden `<!-- NN -->` HTML-comment prefixes on each parser's `group` value; tera's `group_by` filter sorts groups lexicographically (now monotonic by row number), and the body template's `striptags` filter erases the prefix from rendered headings.
+
+## `utility` alias
+
+`utility:` is a backward-compat alias for `internal:`. Both forms parse to the same canonical type, route to the same `🏗️ Internal features` section, and are subject to the same `!` policy.
+
+## `!` (breaking change) policy
+
+Each work-type carries a `breakingPolicy` value:
+
+- `optional` (`feat`, `sec`) — `!` is allowed; both `type:` and `type!:` parse cleanly.
+- `forbidden` (most types) — `!` is a policy violation. The premise: types like `internal!`, `perf!`, `fix!` are contradictory; an internal change cannot break a consumer contract, a pure perf change preserves the contract, and a bug-fix is by definition not a contract change.
+- `required` (`drop`) — bare `drop:` is a policy violation; only `drop!:` is accepted. The premise: removing a feature always breaks consumers; the `!` form makes that explicit.
+
+### Two-tier policy enforcement
+
+The `!` policy operates at two distinct levels with different semantics:
+
+- **Write-time** (commit-msg hook) — strict rejection. Policy violations are blocked at the gate where the author can act on them immediately. _Hook-based enforcement is tracked separately and is not yet shipped._
+- **Release-time** (`parseCommitMessage`) — tolerant warn-and-continue. Commits already in the log cannot be rewritten, so a policy-violating commit is parsed using its canonical type with `breaking: false` (the `!` is dropped from the parse) and a `onPolicyViolation` callback fires. Callers (`decideRelease` etc.) can collect these warnings and surface them in the release report. A single legacy `internal!` in a year-old log does not block releases.
+
+A `BREAKING CHANGE:` body footer on a `forbidden`-policy type triggers the same warning path as the prefix `!` does — the spirit of the policy is "internal/perf/etc. cannot be breaking", which must apply to both surfaces.
+
+The release-prepare orchestrators (`releasePrepare`, `releasePrepareMono`, `releasePrepareProject`) apply `DEFAULT_BREAKING_POLICIES` automatically. Violations encountered while parsing each workspace's or project's commit window are collected onto the corresponding result's `policyViolations` field and rendered under the section in the prepare report:
+
+```
+arrays
+  Found 1 commits since arrays-v1.0.0
+  ⚠️  1 policy violation:
+      · def5678 'internal!: refactor cache' — type 'internal' at prefix surface
+  Bumping versions (patch)...
+  📦 1.0.0 → 1.0.1 (patch)
+```
+
+To customize, set `breakingPolicies` in `release-kit.config.ts` — provide a partial map to override individual types, or `{}` to disable enforcement entirely (the parser falls back to `'optional'` for any missing type). Violations remain warnings, never failures.
+
+## `🚨 **Breaking:**` bullet marker
+
+Items whose commit subject carries the `!` prefix (e.g. `feat!`, `drop!`, `feat(api)!`) are rendered with a `🚨 **Breaking:** ` prefix on the bullet:
+
+```markdown
+- 🚨 **Breaking:** Drop legacy /v1 endpoint
+```
+
+Only the prefix `!` triggers this marker. A `BREAKING CHANGE:` body footer on its own does **not** retroactively mark a changelog item as breaking — the changelog signal is tied to the commit-prefix policy. This avoids surprise breaking-marker appearances for older commits written under earlier conventions.
+
+The emoji and label of this marker are sourced from the `markers.breaking` entry in `work-types.json` (see [Section markers](#section-markers)) so consumers that render their own breaking-changes section draw from the same SSOT.
+
+## Section markers
+
+Alongside `tiers` and `types`, `work-types.json` exposes a top-level `markers` object for cross-cutting section markers — visual indicators that aren't tied to a specific work type. Today the canonical entry is `breaking`; additional keys (e.g., security advisories, migration notices) can be added without a schema change.
+
+```jsonc
+{
+  "markers": {
+    "breaking": { "emoji": "🚨", "label": "Breaking" },
+  },
+}
+```
+
+Entries store plain text only — the SSOT is format-agnostic, so consumers apply their own emphasis (Markdown bold, ANSI escape, HTML `<strong>`) when constructing the rendered form. release-kit's own renderer constructs the per-bullet prefix as `${emoji} **${label}:** ` from this entry.
+
+## `fmt`
+
+`fmt:` commits are recognized by `parseCommitMessage` (they contribute to a patch bump) but `fmt` carries `excludedFromChangelog: true`. The bundled `cliff.toml.template` skips `fmt:` commits at the parser level, so they never appear in `CHANGELOG.md`, `changelog.json`, or release notes. The label and emoji are present in `work-types.json` for schema parity with the codeassembly upstream but never render.
+
+## Custom work types
+
+Work types from your config are merged with these defaults by key — your entries override or extend, they don't replace the full set. 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 derived from the `internal` and `process` tiers (excluding `fmt`). Override via `changelogJson.devOnlySections` in your config; matching is decorator-tolerant, so a bare-name override like `['Internal features']` keeps working against the emoji-prefixed and prefix-decorated default titles.
+
+## `release-kit work-types`
+
+Manage the canonical work-types taxonomy used by changelog and release-notes generation.
+
+The check is non-blocking initially: until codeassembly publishes its `work-types.json`, the upstream URL returns 404 and `check` exits 0 with a warning. CI flip to a blocking check is tracked as a follow-up once the upstream ships.
+
+These commands are also exposed as `nmr work-types:check` / `nmr work-types:sync` from any package directory.
+
+### Authenticated fetches
+
+When the upstream codeassembly repo is private, both `check` and `sync` need a GitHub token to fetch the canonical `work-types.json`. Set `GITHUB_TOKEN` in the environment and the commands send `Authorization: Bearer <token>` automatically; without it, requests are unauthenticated and a private upstream will return 404.
+
+```sh
+# Source from `gh auth` for local runs:
+export GITHUB_TOKEN=$(gh auth token)
+pnpm exec release-kit work-types check
+```
+
+The token needs `contents: read` on the codeassembly repo (fine-grained PAT scope) or the equivalent classic-PAT scope. A token without sufficient scope still produces a 404 — same response as a missing upstream — so a misconfigured token degrades to the transitional-warning path rather than failing loudly. CI wiring against private upstream is deferred until either codeassembly is publicly readable or a cross-repo PAT is provisioned as a workflow secret.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/release-kit",
-  "version": "10.6.0",
+  "version": "10.7.0",
   "description": "Version-bumping and changelog-generation toolkit for release workflows",
   "keywords": [
     "changelog",
@@ -45,11 +45,13 @@
     "bin",
     "cliff.toml.template",
     "dist/*",
+    "docs",
+    "!docs/*.v*.md",
     "presets/**",
     "schemas/**"
   ],
   "dependencies": {
-    "@williamthorsen/nmr-core": "0.11.0",
+    "@williamthorsen/nmr-core": "0.11.1",
     "@williamthorsen/toolbelt.errors": "0.7.0",
     "glob": "13.0.6",
     "json-stringify-pretty-compact": "4.0.0",
@@ -62,8 +64,9 @@
     "@williamthorsen/toolbelt.filesystem": "0.8.3",
     "@williamthorsen/toolbelt.testing": "0.5.1",
     "@williamthorsen/toolbelt.vitest": "0.9.0",
-    "readyup": "0.35.0",
-    "smol-toml": "1.8.0"
+    "readyup": "0.36.0",
+    "smol-toml": "1.8.0",
+    "vitest": "4.1.11"
   },
   "engines": {
     "node": ">=24"

package/dist/esm/readCurrentVersion.d.ts

@@ -1,2 +0,0 @@
-/** Read the `version` field from a package.json file. Returns undefined if the file can't be read or parsed. */
-export declare function readCurrentVersion(filePath: string): string | undefined;