@williamthorsen/release-kit 12.0.0 → 13.1.0

package/docs/editorial-overrides.md

@@ -2,9 +2,9 @@
 
 How to correct a generated changelog entry without rewriting history: where override files live, how they compose, how a key targets items, 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.
+Generated changelogs occasionally need editorial correction: typos, redacted scope, reworded entries, or historical commits whose bodies contain 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 a version that release-kit renders in `CHANGELOG.md` or `.meta/changelog.json` is overwritten on the next release, because release-kit regenerates that version in both artifacts from its entries.
 
-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 or by commit hash and entry position, 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.
+Override files are the supported escape hatch. Add a checked-in JSON file at the conventional path for the scope that it should affect, keyed by commit hash or by commit hash and entry position, 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
 
@@ -14,7 +14,7 @@ Override files are the supported escape hatch. Drop a checked-in JSON file at th
 | 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`).
+Filenames don't have a leading dot, because the `.meta/` directory already provides the visibility property and parallels its sibling artifacts (`changelog.json`, `label-map.json`).
 
 ## Composition: per-key shadowing
 
@@ -22,18 +22,18 @@ 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 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.
+- When the **same key** (string-equal, byte-for-byte) appears in both files, the **workspace entry wins entirely** for that workspace's changelog: release-kit doesn't merge the two entries field by field; the workspace entry replaces the root entry.
 - Non-identical keys that match the same item, such as a root `abc1234` beside a workspace `abc1234:2`, or two prefixes of one commit, do **not** shadow. The run fails with the [overlapping-keys error](#conflicting-keys), which names both keys.
 - 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.
+The project-level changelog applies only the root file. Per-workspace files describe per-workspace editorial intent and don't have any 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.
+- **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
 
@@ -65,7 +65,7 @@ The top-level `$schema` key is optional and names the [published JSON Schema](#p
 | `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: On a title-derived item the field is derived from `body`, so an override that replaces `body` re-derives it, and an item derived from a change-record entry keeps its entry's `migration`. See [The `migration` field](changelogs.md#the-migration-field).
+An override entry doesn't take a `migration` key: On a title-derived item the field is derived from `body`, so an override that replaces `body` re-derives it, and an item derived from a change-record entry keeps its entry's `migration`. See [The `migration` field](changelogs.md#the-migration-field).
 
 ## Keys
 
@@ -76,13 +76,13 @@ A key takes one of two forms. In both, the hash part is lowercase hex and matche
 | `<hash>`     | Every item of the commit                                         |
 | `<hash>:<n>` | The one item derived from the commit's `n`th change-record entry |
 
-`n` counts from 1 over the `entries` of the commit's [change-record block](changelogs.md#change-record-blocks), in the order in which the PR lists them, including entries that yield no item. An item derived from the commit's title has no entry position, so `<hash>:<n>` never matches it. Any other key fails loading.
+`n` counts from 1 over the `entries` of the commit's [change-record block](changelogs.md#change-record-blocks), in the order in which the PR lists them, including entries that don't yield an item. An item derived from the commit's title doesn't have an entry position, so `<hash>:<n>` never matches it. Any other key fails loading.
 
 The hash part can be the full 40-character SHA or a prefix. `prepare` resolves it against the distinct commit hashes in the changelog:
 
-- **One commit** — the override applies to the items that the key targets. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
-- **No commit** — the override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues. An ordinal key whose commit has no item at position `n` is stale in the same way.
-- **Several commits** — the release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
+- **One commit**: The override applies to the items that the key targets. A 7-character prefix is usually unambiguous within a single repo's history; longer prefixes are always safe.
+- **No commit**: The override is treated as a stale reference (probably from a rebase or branch deletion) and prepare reports a warning. The release continues. An ordinal key whose commit doesn't have an item at position `n` is stale in the same way.
+- **Several commits**: The release aborts with an error naming the key and the matching hashes. Lengthen the prefix or use the full SHA.
 
 ### Conflicting keys
 
@@ -104,13 +104,13 @@ Suppose commit `3f0c9a1` merged a PR whose change record lists three entries. It
 
 A bare `"3f0c9a1": { "audience": "skip" }` would skip all three items instead. Adding it beside the keys above fails the run, because it overlaps each of them.
 
-Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and surface on `PrepareResult.warnings`.
+Override application errors abort the run with a non-zero exit; warnings (zero-match keys) are non-fatal and appear in `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:
+The override file is validated when `release-kit prepare` loads it. Each error names the offending key so that the developer can locate it in the file:
 
-- Missing file → empty map, no error (the no-op default — projects that do not need overrides skip the file entirely).
+- Missing file → empty map, no error (the no-op default: Projects that do not need overrides skip the file entirely).
 - Malformed JSON → error.
 - A key that is neither `<hash>` nor `<hash>:<n>` (uppercase hex, non-hex characters, `:0`, a leading zero in `n`) → error.
 - A top-level `$schema` that is not a string → error.
@@ -118,7 +118,7 @@ The override file is validated when `release-kit prepare` loads it. Each error n
 - 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).
+- `audience: 'all'` or `audience: 'dev'` → error in the current release: Only `'skip'` is supported (see below).
 
 Applying the overrides then aborts the run on an ambiguous prefix and on either of the [conflicting-key conditions](#conflicting-keys): a bare key setting `description` or `body` on a commit with several items, and two keys matching the same item.
 
@@ -137,9 +137,9 @@ This walks every `.meta/changelog-overrides.json` file across the project tier a
 | Schema/parse errors | malformed JSON, malformed keys, unknown fields, wrong field types, no-field entries, unsupported `audience` | `2`       |
 | Ambiguous-prefix    | an override key resolves to 2+ commit hashes                                                                | `2`       |
 | Conflicting keys    | a bare key sets `description` or `body` on a commit with several items; two keys match the same item        | `2`       |
-| Stale-key warnings  | an override key resolves to no item in its applicable scope                                                 | `1`       |
+| Stale-key warnings  | an override key doesn't resolve to any item 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).
+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 doesn't match in **any** scope (neither any workspace nor the project release window).
 
 Conflicting keys are found within one file and across the root and workspace files, as `prepare` composes them. An overlap between a root key and a workspace key is reported against the workspace file.
 
@@ -166,13 +166,13 @@ The schema states the key form and the entry fields. It accepts `audience` value
 
 ## 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 on-disk format declares the full `'all' | 'dev' | 'skip'` audience vocabulary so that the file format will not need to change when the v2 reclassification feature is released. 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.
+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 that the override mechanism can be released now and the section-split logic can be added 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:
+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 the project's in-app release notes as literal Markdown headings. Add an override at the project tier:
 
 ```json
 // .meta/changelog-overrides.json
@@ -187,9 +187,9 @@ On the next `release-kit prepare` run, the matched item's body is replaced befor
 
 ## 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.
+Release-kit attributes commits to workspaces by file path, so a commit that primarily belongs to one workspace can appear 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 appears in `packages/nmr/CHANGELOG.md`, where it isn't the right editorial framing.
 
-Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
+Add a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
 
 ```json
 // packages/nmr/.meta/changelog-overrides.json
@@ -200,4 +200,4 @@ Drop a workspace-tier override at `packages/nmr/.meta/changelog-overrides.json`:
 }
 ```
 
-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.
+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

@@ -1,16 +1,16 @@
 # 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`.
+How to declare the repository's labels in `.config/release-kit.config.ts`, how the scaffolded workflow applies them, and where the schema for `.meta/label-map.json` is published.
 
 ## `release-kit sync-labels`
 
-Manage GitHub label definitions via the `repoLabels` block of `.config/release-kit.config.ts`.
+Manages 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.
+`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.
 
 `init` and `generate` accept `--config <path>` to read a config elsewhere; `sync` reads none and rejects the flag. Under `--config`, `init` reads the named file and prints the block for manual paste, and fails when that file does not exist rather than scaffolding one, so its write target stays `.config/release-kit.config.ts`. See [Config file location](configuration.md#config-file-location).
 
-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.
+Every `sync-labels` subcommand refuses to run while the retired `.config/sync-labels.config.ts` is present, so that custom labels cannot be silently dropped mid-migration, and the refusal names what to move and where.
 
 ### Label configuration
 
@@ -29,20 +29,36 @@ export default defineConfig({
 });
 ```
 
-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:
+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.
+1. Presets, in `extends` order: A later preset wins on a shared name.
+2. The `labels` record: An entry adds a label, replaces one that an earlier layer defined, or removes it (`null`). Replacement is wholesale: An entry omitting `description` resolves to a label without a description rather than inheriting the one that an earlier layer supplied.
+
+The `common` preset defines a label for every work type in change-grammar's taxonomy, named by the type's `trackerLabel`, in addition to the labels in its bundled YAML file.
 
 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.
+Overlaps between layers are never errors; order resolves them, and the committed `.github/labels.yaml` diff shows any unexpected change at review. Two misstatements are config errors, because neither is visible in the output diff: a dangling `null`, which removes a name not defined by any preset, and `labels` keys that differ only in case, all but one of which the fold would discard.
+
+### Retiring a label
+
+Mark a label `archived: true` to retire it without losing its history:
+
+```typescript
+labels: {
+  'scope:basic': { color: '00ff96', archived: true }, // retire the scope of a removed package
+},
+```
+
+The sync workflow archives a marked label rather than deleting it. An archived label stays on the issues and pull requests that have it, but it cannot be added to new ones and does not appear in the label picker. Removing the mark unarchives the label on the next sync. Removing the entry instead deletes the label, as the sync deletes every label that `.github/labels.yaml` does not declare, and the label disappears from every issue and pull request that had it.
+
+The mark is set only in the `labels` record, not in a preset. To retire a preset's label, replace it with an entry that restates its color and adds the mark.
 
 ### When labels are applied
 
-The scaffolded workflow carries three triggers:
+The scaffolded workflow declares three triggers:
 
 | Trigger                                                   | Job     | Token           | Effect                            |
 | --------------------------------------------------------- | ------- | --------------- | --------------------------------- |
@@ -50,36 +66,38 @@ The scaffolded workflow carries three triggers:
 | 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.
+Applying on merge closes the window in which a regenerated `.github/labels.yaml` remains unapplied. In that window, a later manual dispatch would apply an unreviewed label set.
+
+The `check` job runs the same sync in dry-run. Its **Label diff** log group lists every create, edit, rename, and deletion that the sync would perform, including deletions of labels that the file does not declare: the destructive edits that 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 `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.
+Its **Archive state** log group lists each label that the sync would archive or unarchive. Archiving runs after the rest of the sync, so a label that the file both adds and marks is created and then archived.
 
-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 two jobs are split because a job's permissions are fixed when the run is created and cannot vary by trigger. The split 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.
+The push trigger filters on the path alone; the `sync` job compares `github.ref_name` against the repository's default branch. The workflow therefore doesn't need a 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.
+GitHub issues a read-only `GITHUB_TOKEN` to pull requests from forks, and by default pauses runs from first-time contributors until a maintainer approves them. Because the dry-run reads labels and writes nothing, the check normally runs once approved. A repo that disables workflows on fork pull requests doesn't get a 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`
+### 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:
+`.meta/label-map.json` is a separate, generic data file that maps commit-prefix scopes and types to GitHub label names. `@williamthorsen/change-grammar` publishes its JSON Schema, 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
+https://github.com/williamthorsen/node-monorepo-tools/raw/change-grammar-v<version>/packages/change-grammar/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",
+  "$schema": "https://github.com/williamthorsen/node-monorepo-tools/raw/change-grammar-v<version>/packages/change-grammar/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.
+Earlier releases published the same schema from release-kit, and URLs under existing `release-kit-v*` tags keep resolving. release-kit does not generate `.meta/label-map.json`; change-grammar's `deriveLabelMap` derives one from the taxonomy and the workspace scopes.

package/docs/project-releases.md

@@ -2,7 +2,7 @@
 
 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.
+Some monorepos release a single combined deliverable, such as a Chrome extension, a CLI binary, or 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';
@@ -19,12 +19,12 @@ 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[]` built from the project's release history (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides.
+- Regenerates the root `./CHANGELOG.md` from the structured `ChangelogEntry[]` built from the project's release history (scoped to the project's `tagPrefix` and the same `paths`) and any matching editorial overrides, keeping the [existing sections](changelogs.md#existing-changelogmd-sections) whose versions those entries lack.
 - 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.
+- Appends the project tag to `tmp/.release-tags` so that `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.
+If the history since the last project tag doesn't contain any commit under `paths`, the project release is silently skipped, as a per-workspace release is.
 
 ## `ProjectConfig`
 
@@ -37,14 +37,14 @@ interface ProjectConfig {
 
 | Field       | Default                 | Description                                                          |
 | ----------- | ----------------------- | -------------------------------------------------------------------- |
-| `paths`     | Contributing-path union | Patterns selecting the commits the project release considers         |
+| `paths`     | Contributing-path union | Patterns selecting the commits that 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.
+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 is a git pathspec, which both the bump and the changelog read. A declared value **replaces** the workspace union rather than extending it: `paths: ['docs/**']` drops every workspace commit from the project release.
+Declare `paths` to choose the window explicitly. Each entry is a git pathspec, which both the bump and the changelog read. 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:
+In a repo whose content lives at the root, commits don't match any `<dir>/**` glob, so the project release would skip every run. Such a repo declares the whole tree:
 
 ```typescript
 const config: ReleaseKitConfig = {
@@ -60,15 +60,15 @@ 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 as no filter at all, which is the inverse of how it reads.
+- `paths`, when declared, must contain at least one non-empty string. An empty array is rejected, because git would read it as the absence of a filter: the inverse of how the array 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.
+- `--dry-run` previews project artifacts alongside workspace artifacts; it doesn't write any files.
+- `--bump=major|minor|patch` propagates to the project release as a level chooser. It does not trigger a release on its own when the window doesn't have any commits or any bump-worthy commits.
+- `--force` runs the project release even when the history since the last project tag doesn't have any commits or any bump-worthy commits. 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 that the run excluded. Run a full `prepare` (without `--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

@@ -4,16 +4,16 @@ How `release-kit publish` and `release-kit create-github-release` choose which p
 
 ## `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.
+Publishes 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.
+`publish` and `create-github-release` operate only on workspaces whose `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 excludes a workspace from publish and announce; it doesn't require any extra release config. 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.
+- **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 are still published.
 
 `release-kit create-github-release` skips unpublishable workspaces with a warning regardless of `--tags`; an all-private tag set is a clean no-op.
 
@@ -25,6 +25,6 @@ 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)).
+Creates 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

@@ -2,7 +2,7 @@
 
 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.
+release-kit publishes two [readyup](https://www.npmjs.com/package/readyup) kits that check a consuming repo against the release that 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 are included in the package, so they check against the installed version rather than whatever a repository ref happens to point at, and a check added in a release becomes available to a repo when it upgrades.
 
 The [README](../README.md#readiness-checks) shows how to name release-kit in the readyup config.
 
@@ -13,6 +13,6 @@ rdy run --from npm:@williamthorsen/release-kit npm-auto-publish  # the npm-auto-
 rdy list --from npm:@williamthorsen/release-kit                  # what release-kit publishes
 ```
 
-`--packages` is the form that survives release-kit publishing further kits.
+`--packages` is the form that keeps working when release-kit publishes 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.
+Because `npm-auto-publish` queries the npm registry for each package's trusted publisher, it needs an npm session elevated by two-factor authentication, and is meant to be invoked deliberately rather than included in 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 are then skipped: the trusted-publisher rows in every case, and `published to npm` when the registry itself is unreachable. Each package's `package.json` checks report throughout, since they don't read a registry.

package/docs/releasing.md

@@ -1,31 +1,41 @@
 # Releasing
 
-How to scaffold the release workflows, what `release-kit prepare` does with its flags, and how the release workflow runs a release.
+How to scaffold the release workflows and keep them up to date, 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.
+Initializes 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`)
+- `.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`)
+
+## `release-kit update-templates`
+
+Updates the scaffolded workflows to the templates of the installed release-kit version, and prints what changed in each file. Run it after upgrading release-kit; `--dry-run` previews the changes without writing them.
+
+The workflows are managed files: release-kit renders them, and a change made by hand is overwritten on the next update. The config files are the repository's own, and the command never reads or writes them.
+
+- It creates a missing workflow that `init` would create.
+- It refreshes `.github/workflows/sync-labels.yaml` only when the file exists, because `sync-labels init` scaffolds it on request.
+- It keeps `publish.yaml`'s provenance setting: When the file does not set `provenance: true`, as in a private repository, the updated file does not either.
 
 ## `release-kit prepare`
 
-Run release preparation with automatic workspace discovery.
+Runs release preparation with automatic workspace discovery.
 
 Workspace names for `--only` match the package directory name (e.g., `arrays`, `release-kit`).
 
 `prepare` reads each target's history once and builds the changelog items of its unreleased commits. The bump is the highest level that those items call for, under [`versionPatterns`](configuration.md#versionpatterns), so the bump and the changelog describe the same release: A `feat` entry in a [change-record block](changelogs.md#change-record-blocks) bumps minor under a `docs:` title, and a breaking item bumps major.
 
-- A commit that yields no item bumps nothing: one without a ticket-ID prefix, one of a type excluded from the changelog (such as `fmt`), and one whose change-record entries are all undeclared or excluded.
-- A `BREAKING CHANGE:` footer raises no major bump. Only a subject's `!` and an entry's `breaking: true` mark an item breaking; on a type whose policy forbids `!`, the footer is reported as a [policy violation](work-types.md#policy-enforcement).
-- A target whose commits yield no item is skipped. The prepare report lists the commits that could not be parsed and the change-record diagnostics, skipped targets included.
+- A commit that doesn't yield an item doesn't bump anything: one without a ticket-ID prefix, one of a type excluded from the changelog (such as `fmt`), and one whose change-record entries are all undeclared or excluded.
+- A `BREAKING CHANGE:` footer doesn't raise a major bump. Only a subject's `!` and an entry's `breaking: true` mark an item breaking; on a type whose policy forbids `!`, the footer is reported as a [policy violation](work-types.md#policy-enforcement).
+- A target whose commits don't yield an item is skipped. The prepare report lists the commits that could not be parsed and the change-record diagnostics, skipped targets included.
 
 `--bump` and `--force` are orthogonal in every mode, single-package included: `--bump` is purely a level chooser; `--force` is purely a release trigger. Examples:
 
@@ -33,16 +43,17 @@ Workspace names for `--only` match the package directory name (e.g., `arrays`, `
 # Release every target at its natural bump level (no flags).
 release-kit prepare
 
-# Force a release even when no commit yields a changelog item; defaults to
-# patch per target, with each target keeping its natural bump if it has one.
+# Force a release even when the commits don't yield any changelog item;
+# defaults to patch per target, with each target keeping its natural bump
+# if it has one.
 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 no commit of a target
-# yields a changelog item, it skips with a "Pass --force..." reason. Otherwise
-# the override applies.
+# --bump=X alone is a level chooser, NOT a trigger. If a target's commits
+# don't yield any changelog item, it skips with a "Pass --force..." reason.
+# Otherwise the override applies.
 release-kit prepare --bump=minor
 ```
 
@@ -50,10 +61,10 @@ release-kit prepare --bump=minor
 
 `--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.
+- `<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.
+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, prepare logs the planned writes and doesn't create any files.
 
 Because preview filenames are versioned, committing them will accumulate files over time. The recommended `.gitignore` entry for monorepos is:
 
@@ -69,7 +80,7 @@ docs/*.v*.md
 
 ### Setting an explicit version with `--set-version`
 
-The `--set-version` flag is a first-class escape hatch for the cases where the derived bump 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 `--set-version` flag is a first-class escape hatch for the cases in which the derived bump produces the wrong version, most notably when 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:
 
@@ -85,17 +96,31 @@ Promoting a pre-1.0 package to 1.0.0 in a monorepo:
 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`.
+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, merge a descriptive release commit (e.g., a `feat!` describing the stable API) before running `prepare`.
+
+### Adopting release-kit in a repo with untagged releases
+
+`prepare` finds a target's previous release by its tag. When a target's current version was released and recorded in its `CHANGELOG.md` or `changelog.json` but never tagged, the unreleased window would extend back to the start of history: The new version would absorb every earlier commit, and its bump would be derived from all of them. `prepare` stops before writing anything instead, under `--force` and `--set-version` too, and names each target, its version, and the tag to create:
+
+```text
+The current version is recorded in the changelog, but its tag is not the previous tag reachable from HEAD:
+  - workspace 'api': 1.2.0 (create tag api-v1.2.0)
+Tag the commit that released each version, then run prepare again.
+```
+
+Tag each named version at the commit that released it, then run `prepare` again. In a monorepo, `prepare` checks the project only after every workspace passes, so a second run can name the project's tag. The check skips a first release, whose version isn't recorded in any changelog, and a workspace that releases only through propagation.
+
+Each new tag closes a release window. When that window's commits yield items, `prepare` renders the tagged version from them, in place of its hand-written section; it keeps every other hand-written version as [Existing `CHANGELOG.md` sections](changelogs.md#existing-changelogmd-sections) describes.
 
 ## 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) |
+| Input   | Type    | Description                                                                                                                                     |
+| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `only`  | string  | Workspaces to release (comma-separated, leave empty for all)                                                                                    |
+| `bump`  | choice  | Bump type: `auto` (default, detects it from commits), `patch`, `minor`, or `major`                                                              |
+| `force` | boolean | Release even when the window doesn't have any commits or any bump-worthy commits (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.