@releasekit/notes 0.44.1 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  createNotesCommand
4
- } from "./chunk-KTLNPX37.js";
4
+ } from "./chunk-JOA56Y7A.js";
5
5
  import {
6
6
  readPackageVersion
7
- } from "./chunk-VD3TYCTF.js";
7
+ } from "./chunk-EI7LLVJN.js";
8
8
 
9
9
  // src/cli.ts
10
10
  import * as fs from "fs";
package/dist/index.d.ts CHANGED
@@ -11,6 +11,13 @@ declare function loadAuth(): Record<string, string>;
11
11
  declare function saveAuth(provider: string, apiKey: string): void;
12
12
 
13
13
  type ChangelogRefsMode = 'strip' | 'escape' | 'link';
14
+ interface BundledPackage<T> {
15
+ packageName: string;
16
+ /** Set when the package released more than once in the range. */
17
+ firstVersion?: string;
18
+ version: string;
19
+ entries: T[];
20
+ }
14
21
 
15
22
  declare abstract class ReleaseKitError extends Error {
16
23
  abstract readonly code: string;
@@ -41,6 +48,8 @@ interface VersionChangelogEntry {
41
48
  * extraction-error fallback, which isn't a no-change carry.
42
49
  */
43
50
  synthetic?: boolean;
51
+ /** On a `sharedEntries` entry: its commit touched a `sharedPackages` package. Absent for a repo-level entry. */
52
+ sharedPackage?: boolean;
44
53
  }
45
54
  interface VersionPackageChangelog {
46
55
  packageName: string;
@@ -51,6 +60,23 @@ interface VersionPackageChangelog {
51
60
  entries: VersionChangelogEntry[];
52
61
  /** The tag this changelog releases: the package's own, or a sync release's shared one. Absent in older manifests. */
53
62
  tag?: string;
63
+ /**
64
+ * Entries from commits in this changelog's range that touch a `sharedPackages` package and no non-shared package,
65
+ * leaving out commits under this package's own directories. Recorded, possibly empty, by async-mode releases with
66
+ * shared packages; absent otherwise and in older manifests.
67
+ */
68
+ sharedPackageEntries?: VersionChangelogEntry[];
69
+ /** A primary's bundled packages, each with the versions of that package the primary's notes include, oldest first. */
70
+ bundled?: VersionBundledPackage[];
71
+ }
72
+ interface VersionBundledPackage {
73
+ packageName: string;
74
+ versions: string[];
75
+ }
76
+ interface VersionBundledRelease {
77
+ packageName: string;
78
+ version: string;
79
+ entries: VersionChangelogEntry[];
54
80
  }
55
81
  /** `'graduated'`: a prerelease promoted to stable, ignoring any requested bump. `'first-release'`: no prior tag. */
56
82
  type VersionAction = 'first-release' | 'graduated' | 'bumped';
@@ -68,6 +94,11 @@ interface VersionOutput {
68
94
  /** Entries from commits that touch no package outside `sharedPackages`, counting the directories a package
69
95
  * versions through `cargo.paths` / `pub.paths`. */
70
96
  sharedEntries?: VersionChangelogEntry[];
97
+ /**
98
+ * Earlier releases a primary's `bundled` packages made since its previous release, each stored once however many
99
+ * primaries include it. A bundled package's release in this run is its own changelog record.
100
+ */
101
+ bundledReleases?: VersionBundledRelease[];
71
102
  commitMessage?: string;
72
103
  /** Consumer-facing tags from `tagTemplate`. */
73
104
  tags: string[];
@@ -142,6 +173,8 @@ interface ChangelogEntry {
142
173
  originalType?: string;
143
174
  breaking?: boolean;
144
175
  leadIn?: string;
176
+ /** On a project-wide entry: its commit touched a `sharedPackages` package, so every package's notes list it. */
177
+ sharedPackage?: boolean;
145
178
  /** Populated upstream of LLM tasks; never serialised to disk. */
146
179
  context?: {
147
180
  prs: PRContext[];
@@ -156,11 +189,19 @@ interface PackageChangelog {
156
189
  repoUrl: string | null;
157
190
  date: string;
158
191
  entries: ChangelogEntry[];
192
+ sharedPackageEntries?: ChangelogEntry[];
193
+ bundled?: VersionBundledPackage[];
159
194
  }
195
+ type BundledRelease = Omit<VersionBundledRelease, 'entries'> & {
196
+ entries: ChangelogEntry[];
197
+ };
160
198
  type InputSource = 'version';
161
199
  interface ChangelogInput {
162
200
  source: InputSource;
163
201
  packages: PackageChangelog[];
202
+ /** Project-wide entries, from commits that touch no package outside `sharedPackages`. */
203
+ sharedEntries?: ChangelogEntry[];
204
+ bundledReleases?: BundledRelease[];
164
205
  metadata?: {
165
206
  repoUrl?: string;
166
207
  defaultBranch?: string;
@@ -171,7 +212,6 @@ interface EnhancedCategory {
171
212
  entries: ChangelogEntry[];
172
213
  }
173
214
  interface EnhancedData {
174
- entries: ChangelogEntry[];
175
215
  summary?: string;
176
216
  categories?: EnhancedCategory[];
177
217
  releaseNotes?: string;
@@ -186,15 +226,47 @@ interface TemplateContext {
186
226
  compareUrl?: string;
187
227
  enhanced?: EnhancedData;
188
228
  isFirstRelease?: boolean;
229
+ /** Shared-package entries, listed after the version's own. */
230
+ sharedEntries?: ChangelogEntry[];
231
+ /** A primary's bundled packages. Release notes only: the changelog never lists them. */
232
+ bundled?: BundledPackage<ChangelogEntry>[];
233
+ }
234
+ interface TemplateEntry extends ChangelogEntry {
235
+ /** The built-in renderer's line: refs rendered, mentions and comment openers escaped. */
236
+ line: string;
237
+ }
238
+ interface TemplateSection {
239
+ label: string;
240
+ entries: TemplateEntry[];
241
+ }
242
+ /** What a template sees for one version. */
243
+ interface TemplateBundledPackage {
244
+ packageName: string;
245
+ /** Set when the package released more than once since the primary's previous release. */
246
+ firstVersion?: string;
247
+ version: string;
248
+ sections: TemplateSection[];
249
+ }
250
+ interface TemplateVersion extends Omit<TemplateContext, 'entries' | 'enhanced' | 'sharedEntries' | 'bundled'> {
251
+ entries: TemplateEntry[];
252
+ /** LLM categories when `categorize` ran, otherwise commit-type groups. Breaking leads unless `categoryOrder` places it. */
253
+ sections: TemplateSection[];
254
+ /** Shared-package entries in commit-type groups. Empty in a root changelog. */
255
+ shared: TemplateSection[];
256
+ /** A primary's bundled packages, each in commit-type groups. Empty outside release notes. */
257
+ bundled: TemplateBundledPackage[];
258
+ enhanced?: Omit<EnhancedData, 'categories'>;
189
259
  }
190
260
  interface DocumentContext {
191
261
  project: {
192
262
  name: string;
193
263
  repoUrl?: string;
194
264
  };
195
- versions: TemplateContext[];
196
- unreleased?: TemplateContext;
265
+ versions: TemplateVersion[];
266
+ unreleased?: TemplateVersion;
197
267
  compareUrls?: Record<string, string>;
268
+ /** A root changelog's project-wide entries for the run, in commit-type groups. Empty otherwise. */
269
+ shared: TemplateSection[];
198
270
  /** Templates can use this to suppress document-level headings that are redundant
199
271
  * when the content is embedded in a release that already shows the package/version. */
200
272
  perPackage?: boolean;
@@ -232,12 +304,10 @@ interface ScopeConfig {
232
304
  mode?: 'restricted' | 'packages' | 'none' | 'unrestricted';
233
305
  rules?: ScopeRules;
234
306
  }
235
- type UpdateStrategy = 'prepend' | 'regenerate';
236
307
  interface Config {
237
308
  changelog?: false | ChangelogConfig;
238
309
  releaseNotes?: false | ReleaseNotesConfig;
239
310
  monorepo?: MonorepoConfig;
240
- updateStrategy?: UpdateStrategy;
241
311
  }
242
312
  type JSONSchema = Record<string, unknown>;
243
313
  interface CompleteOptions {
@@ -320,6 +390,19 @@ interface ReleaseNotesConfig {
320
390
  declare function loadConfig(projectDir?: string, configFile?: string): Config;
321
391
  declare function getDefaultConfig(): Config;
322
392
 
393
+ interface FormatVersionOptions {
394
+ includePackageName?: boolean;
395
+ /** Order to render LLM-categorised sections. */
396
+ categoryOrder?: string[];
397
+ links?: LinksConfig;
398
+ firstRelease?: FirstReleaseConfig | false;
399
+ refs?: ChangelogRefsMode;
400
+ }
401
+ declare function formatVersion(context: TemplateContext, options?: FormatVersionOptions): string;
402
+ /** `sharedEntries` are listed once, after the versions, under a dated heading of their own. */
403
+ declare function renderMarkdown(contexts: TemplateContext[], options?: FormatVersionOptions, sharedEntries?: ChangelogEntry[]): string;
404
+ declare function writeChangelog(outputPath: string, content: string, dryRun: boolean): void;
405
+
323
406
  declare function createTemplateContext(pkg: PackageChangelog): TemplateContext;
324
407
  interface PipelineResult {
325
408
  /** Per-package rendered markdown keyed by package name. */
@@ -338,6 +421,11 @@ interface PipelineOptions {
338
421
  skipReleaseNotes?: boolean;
339
422
  /** Use during publish from manifest to regenerate only the release notes against an already-bumped tree. */
340
423
  skipChangelogs?: boolean;
424
+ /**
425
+ * Generate release notes only for these packages, and no changelogs. The other packages still count toward the
426
+ * release-notes file layout.
427
+ */
428
+ releaseNotesFor?: string[];
341
429
  }
342
430
  declare function runPipeline(input: ChangelogInput, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
343
431
  declare function processInput(inputJson: string, config: Config, dryRun: boolean, pipelineOptions?: PipelineOptions): Promise<PipelineResult>;
@@ -376,7 +464,7 @@ declare class ConfigError extends NotesError {
376
464
  }
377
465
  declare function getExitCode(error: NotesError): number;
378
466
 
379
- declare function versionOutputToChangelogInput(data: Pick<VersionOutput, 'changelogs'> & Partial<Pick<VersionOutput, 'updates' | 'tags'>>): ChangelogInput;
467
+ declare function versionOutputToChangelogInput(data: Pick<VersionOutput, 'changelogs'> & Partial<Pick<VersionOutput, 'updates' | 'tags' | 'sharedEntries' | 'bundledReleases'>>): ChangelogInput;
380
468
  declare function parseVersionOutput(json: string): ChangelogInput;
381
469
  declare function parseVersionOutputFile(filePath: string): ChangelogInput;
382
470
  declare function parseVersionOutputStdin(): Promise<ChangelogInput>;
@@ -384,13 +472,10 @@ declare function parseVersionOutputStdin(): Promise<ChangelogInput>;
384
472
  interface MonorepoOptions {
385
473
  rootPath: string;
386
474
  packagesPath: string;
387
- mode: 'root' | 'packages' | 'both';
388
475
  fileName?: string;
389
476
  }
390
477
  declare function aggregateToRoot(contexts: TemplateContext[]): TemplateContext;
391
- declare function writeMonorepoChangelogs(contexts: TemplateContext[], options: MonorepoOptions, config: {
392
- updateStrategy?: 'prepend' | 'regenerate';
393
- }, dryRun: boolean, refs?: ChangelogRefsMode): string[];
478
+ declare function writeMonorepoChangelogs(contexts: TemplateContext[], options: MonorepoOptions, render: (contexts: TemplateContext[]) => string, dryRun: boolean): string[];
394
479
  declare function detectMonorepo(cwd: string): {
395
480
  isMonorepo: boolean;
396
481
  packagesPath: string;
@@ -399,17 +484,17 @@ declare function detectMonorepo(cwd: string): {
399
484
  declare function renderJson(contexts: TemplateContext[]): string;
400
485
  declare function writeJson(outputPath: string, contexts: TemplateContext[], dryRun: boolean): void;
401
486
 
402
- interface FormatVersionOptions {
403
- includePackageName?: boolean;
404
- /** Order to render LLM-categorised sections. */
405
- categoryOrder?: string[];
406
- links?: LinksConfig;
407
- firstRelease?: FirstReleaseConfig | false;
408
- refs?: ChangelogRefsMode;
409
- }
410
- declare function formatVersion(context: TemplateContext, options?: FormatVersionOptions): string;
411
- declare function renderMarkdown(contexts: TemplateContext[], options?: FormatVersionOptions): string;
412
- declare function writeMarkdown(outputPath: string, contexts: TemplateContext[], config: Config, dryRun: boolean, options?: FormatVersionOptions): void;
487
+ /** `packageCount` is the release's, not the run's: see `writeVersionedNotes`. */
488
+ declare function nestsReleaseNotes(packageCount: number): boolean;
489
+ /**
490
+ * `nested` MUST reflect whether the *repo* has more than one package - not how many packages are in
491
+ * this run. An independently-versioned monorepo releases one package per pipeline invocation, so a
492
+ * flat path would silently overwrite another package that shares a version number.
493
+ */
494
+ declare function writeVersionedNotes<T extends {
495
+ packageName: string;
496
+ version: string;
497
+ }>(contexts: T[], directory: string, dryRun: boolean, nested: boolean, renderContent: (ctx: T) => string): string[];
413
498
 
414
- export { ConfigError, GitHubError, InputParseError, InputValidationError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput, writeJson, writeMarkdown, writeMonorepoChangelogs };
415
- export type { ChangelogConfig, ChangelogEntry, ChangelogInput, ChangelogType, CompleteOptions, Config, DocumentContext, EnhancedCategory, EnhancedData, FirstReleaseConfig, InputSource, JSONSchema, LLMCategory, LLMConfig, LLMOptions, LLMPromptOverrides, LLMPromptsConfig, LinksConfig, LocationMode, PRContext, PackageChangelog, PipelineOptions, PipelineResult, ReleaseNotesConfig, ReleaseNotesFileConfig, RetryOptions, ScopeConfig, ScopeRules, TemplateConfig, TemplateContext, TemplateEngine, UpdateStrategy };
499
+ export { ConfigError, GitHubError, InputParseError, InputValidationError, LLMError, NotesError, TemplateError, aggregateToRoot, createTemplateContext, detectMonorepo, formatVersion, getDefaultConfig, getExitCode, loadAuth, loadConfig, nestsReleaseNotes, parseVersionOutput, parseVersionOutputFile, parseVersionOutputStdin, processInput, renderJson, renderMarkdown, runPipeline, saveAuth, versionOutputToChangelogInput, writeChangelog, writeJson, writeMonorepoChangelogs, writeVersionedNotes };
500
+ export type { BundledRelease, ChangelogConfig, ChangelogEntry, ChangelogInput, ChangelogType, CompleteOptions, Config, DocumentContext, EnhancedCategory, EnhancedData, FirstReleaseConfig, InputSource, JSONSchema, LLMCategory, LLMConfig, LLMOptions, LLMPromptOverrides, LLMPromptsConfig, LinksConfig, LocationMode, PRContext, PackageChangelog, PipelineOptions, PipelineResult, ReleaseNotesConfig, ReleaseNotesFileConfig, RetryOptions, ScopeConfig, ScopeRules, TemplateBundledPackage, TemplateConfig, TemplateContext, TemplateEngine, TemplateEntry, TemplateSection, TemplateVersion };
package/dist/index.js CHANGED
@@ -12,27 +12,27 @@ import {
12
12
  getExitCode,
13
13
  loadAuth,
14
14
  loadConfig,
15
+ nestsReleaseNotes,
15
16
  parseVersionOutput,
16
17
  parseVersionOutputFile,
17
18
  parseVersionOutputStdin,
18
19
  processInput,
19
20
  runPipeline,
20
21
  saveAuth,
21
- versionOutputToChangelogInput
22
- } from "./chunk-KTLNPX37.js";
22
+ versionOutputToChangelogInput,
23
+ writeVersionedNotes
24
+ } from "./chunk-JOA56Y7A.js";
23
25
  import {
24
26
  aggregateToRoot,
25
- detectMonorepo,
26
- writeMonorepoChangelogs
27
- } from "./chunk-YCULLVSG.js";
28
- import {
29
27
  debug,
28
+ detectMonorepo,
30
29
  formatVersion,
31
30
  info,
32
31
  renderMarkdown,
33
32
  success,
34
- writeMarkdown
35
- } from "./chunk-VD3TYCTF.js";
33
+ writeChangelog,
34
+ writeMonorepoChangelogs
35
+ } from "./chunk-EI7LLVJN.js";
36
36
 
37
37
  // src/output/json.ts
38
38
  import * as fs from "fs";
@@ -86,6 +86,7 @@ export {
86
86
  getExitCode,
87
87
  loadAuth,
88
88
  loadConfig,
89
+ nestsReleaseNotes,
89
90
  parseVersionOutput,
90
91
  parseVersionOutputFile,
91
92
  parseVersionOutputStdin,
@@ -95,7 +96,8 @@ export {
95
96
  runPipeline,
96
97
  saveAuth,
97
98
  versionOutputToChangelogInput,
99
+ writeChangelog,
98
100
  writeJson,
99
- writeMarkdown,
100
- writeMonorepoChangelogs
101
+ writeMonorepoChangelogs,
102
+ writeVersionedNotes
101
103
  };
@@ -1,6 +1,6 @@
1
1
  # LLM Providers
2
2
 
3
- `@releasekit/notes` can use an LLM to enhance changelog entries, generate summaries, or produce prose release notes. All LLM configuration lives under `notes.releaseNotes.llm` in `releasekit.config.json`.
3
+ `@releasekit/notes` can use an LLM to shape release notes: rewrite and group their entries, add a summary, or write prose. `CHANGELOG.md` is always rendered from the commit-derived entries. All LLM configuration lives under `notes.releaseNotes.llm` in `releasekit.config.json`.
4
4
 
5
5
  ## Supported Providers
6
6
 
@@ -32,7 +32,7 @@ Alternatively, set the provider's environment variable (`OPENAI_API_KEY`, `ANTHR
32
32
 
33
33
  ## Provider Setup
34
34
 
35
- Model names change frequently — check your provider's documentation for the current model IDs. As a general guide: **mini/haiku-tier models** are fast and cheap, suitable for most changelog enhancement; **standard/sonnet-tier models** produce higher-quality output and are worth the extra cost for public-facing release notes.
35
+ Model names change frequently — check your provider's documentation for the current model IDs. As a general guide: **mini/haiku-tier models** are fast and cheap, suitable for most release-notes enhancement; **standard/sonnet-tier models** produce higher-quality output and are worth the extra cost for public-facing release notes.
36
36
 
37
37
  ### OpenAI
38
38
 
@@ -128,7 +128,7 @@ Tasks are configured under `llm.tasks`. Multiple tasks can be enabled simultaneo
128
128
 
129
129
  ### `enhance`
130
130
 
131
- Rewrites each changelog entry description to be clearer and more user-facing.
131
+ Rewrites each entry description in the release notes to be clearer and more user-facing.
132
132
 
133
133
  **Input:** `"fix: npe in auth middleware when token is null"`
134
134
  **Output:** `"Fix crash during authentication when no token is provided"`
@@ -143,7 +143,7 @@ Entry descriptions are processed in parallel (default concurrency: `5`). Adjust
143
143
  { "concurrency": 3 }
144
144
  ```
145
145
 
146
- When `enhance` and `categorize` are both enabled, the pipeline runs a single combined `enhanceAndCategorize` call — see [Combined enhance + categorize](#combined-enhance--categorize). The combined call also generates `leadIn` phrases, scope assignments, and breaking flags. These drive scope grouping, breaking change re-routing, and `**leadIn**: description` formatting in the built-in renderer — none of which are available when running `enhance` alone. Routine fixes and bumps receive no `leadIn`.
146
+ When `enhance` and `categorize` are both enabled, the pipeline runs a single combined `enhanceAndCategorize` call — see [Combined enhance + categorize](#combined-enhance--categorize). The combined call also generates `leadIn` phrases, scope assignments, and breaking flags. These drive breaking change re-routing and `**leadIn**: description` formatting in the built-in renderer, neither of which is available when running `enhance` alone. Routine fixes and bumps receive no `leadIn`.
147
147
 
148
148
  ### `summarize`
149
149
 
@@ -155,7 +155,7 @@ Generates a one-paragraph summary of the entire release, added to the template c
155
155
 
156
156
  ### `categorize`
157
157
 
158
- Groups entries into user-friendly categories rather than conventional commit types. The result is available in templates as `enhanced.categories`.
158
+ Groups entries into user-friendly categories rather than conventional commit types. The result is available in release-notes templates as `sections`.
159
159
 
160
160
  ```json
161
161
  { "tasks": { "categorize": true } }
@@ -249,7 +249,7 @@ To customise the prompt for the combined call, use the `enhanceAndCategorize` ke
249
249
  }
250
250
  ```
251
251
 
252
- If you need fully custom output formatting, use the [templates system](./templates.md) instead — it operates on the pipeline result after all LLM tasks have run.
252
+ If you need fully custom output formatting, use the [templates system](./templates.md) instead — release-notes templates get the result after all LLM tasks have run.
253
253
 
254
254
  ---
255
255
 
@@ -260,6 +260,7 @@ The `--llm-*` flags set LLM options without a config file. Every flag is in the
260
260
  ```bash
261
261
  releasekit-notes \
262
262
  --input version-output.json \
263
+ --release-notes-dir release-notes \
263
264
  --llm-provider anthropic \
264
265
  --llm-model claude-haiku-4-5 \
265
266
  --llm-tasks enhance,release-notes
@@ -54,14 +54,12 @@ With `enhance + categorize` enabled, the same commits produce:
54
54
 
55
55
  ### Breaking
56
56
 
57
- - **BREAKING** **API rename**: Rename connect() to initialize()
57
+ - **API rename**: Rename connect() to initialize()
58
58
 
59
59
  ### New
60
60
 
61
- **ipc**:
62
-
63
61
  - **Deeplink testing**: Add deep link support via triggerDeeplink()
64
- - Add mock IPC support
62
+ - **ipc**: Add mock IPC support
65
63
 
66
64
  ### Fixed
67
65
 
@@ -70,6 +68,8 @@ With `enhance + categorize` enabled, the same commits produce:
70
68
 
71
69
  The LLM rewrites descriptions, groups by user intent instead of commit type, generates scannable `leadIn` phrases for notable entries, and routes breaking changes to a dedicated section.
72
70
 
71
+ This applies to release notes only: GitHub release bodies, per-version notes files and the standing PR's notes region. `CHANGELOG.md` always keeps the commit-type form.
72
+
73
73
  ---
74
74
 
75
75
  ## Tasks
@@ -79,11 +79,11 @@ Four tasks are available. Any combination can be enabled simultaneously.
79
79
  | Task | What it does | Output location |
80
80
  |------|-------------|-----------------|
81
81
  | `enhance` | Rewrites entry descriptions to be clear and user-facing | `entries[].description` (replaced in-place) |
82
- | `categorize` | Groups entries into semantic categories | `enhanced.categories` in template context |
82
+ | `categorize` | Groups entries into semantic categories | `sections` in template context |
83
83
  | `summarize` | Generates a 2–3 sentence release summary | `enhanced.summary` in template context |
84
84
  | `releaseNotes` | Writes full prose markdown release notes | `enhanced.releaseNotes` / pipeline result |
85
85
 
86
- **Recommended starting point:** Enable `enhance` and `categorize` together. This is the most impactful combination — rewriting and grouping both happen in a single LLM call, and it also unlocks `leadIn` phrases, scope grouping, and breaking change re-routing in the built-in renderer. Add `summarize` or `releaseNotes` when you want prose output for GitHub releases.
86
+ **Recommended starting point:** Enable `enhance` and `categorize` together. This is the most impactful combination — rewriting and grouping both happen in a single LLM call, and it also unlocks `leadIn` phrases and LLM-flagged breaking changes in the built-in renderer. Add `summarize` or `releaseNotes` when you want prose output for GitHub releases.
87
87
 
88
88
  > **Efficiency tip:** When both `enhance` and `categorize` are enabled, the pipeline makes a **single combined LLM call** (`enhanceAndCategorize`) instead of two sequential calls. This combined path also produces `leadIn` phrases and scope assignments, which are not available when running `enhance` alone.
89
89
 
@@ -91,7 +91,7 @@ Four tasks are available. Any combination can be enabled simultaneously.
91
91
 
92
92
  ## Task: `enhance`
93
93
 
94
- Rewrites each changelog entry description to be clear, concise, and user-focused.
94
+ Rewrites each entry description to be clear, concise, and user-focused.
95
95
 
96
96
  **Input:** `"fix: npe in auth middleware when token is null"`
97
97
  **Output:** `"Fix crash during authentication when no token is provided"`
@@ -108,7 +108,7 @@ Entries are processed in parallel. Control the batch size with `concurrency` (de
108
108
 
109
109
  ## Task: `categorize`
110
110
 
111
- Groups entries into user-friendly categories. The result populates `enhanced.categories` in the template context and drives the built-in markdown renderer's section layout.
111
+ Groups entries into user-friendly categories. The result populates `sections` in the release-notes template context and drives the section layout of the built-in release notes.
112
112
 
113
113
  ### Default categories
114
114
 
@@ -212,13 +212,11 @@ This is more efficient than two sequential calls and produces richer output. Use
212
212
 
213
213
  ## Breaking change handling
214
214
 
215
- Any entry where `breaking: true` is set — whether from the source input or flagged by the LLM during enhancement — is automatically moved to a `Breaking` category by the built-in markdown renderer at render time, regardless of which category the LLM assigned it to. If no `Breaking` category exists, one is created and prepended before all other categories.
215
+ Any entry where `breaking: true` is set — whether from the source input or flagged by the LLM during enhancement — is automatically moved to a `Breaking` category by the built-in markdown renderer at render time, regardless of which category the LLM assigned it to. The `Breaking` category comes first unless `categoryOrder` places it.
216
216
 
217
217
  This happens in the renderer, not during the LLM call, so custom templates receive the raw data and must implement breaking-change handling themselves if needed.
218
218
 
219
- Rendered format:
220
- - With `leadIn`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
221
- - Without `leadIn`: `- **BREAKING** Rename connect() to initialize()`
219
+ The section marks an entry as breaking, so its line has no prefix: `- **API rename**: Rename connect() to initialize()`.
222
220
 
223
221
  ---
224
222
 
@@ -226,36 +224,16 @@ Rendered format:
226
224
 
227
225
  When running the combined `enhanceAndCategorize` task, the LLM generates a `leadIn` phrase for notable entries — a short noun phrase (e.g. `"Streaming API"`, `"Deeplink testing"`) that makes the entry scannable at a glance.
228
226
 
229
- The LLM sets `leadIn` only for entries that introduce a named API, feature, or concept. Routine fixes, dependency bumps, and internal refactors receive `null` and render without a prefix.
227
+ The LLM sets `leadIn` only for entries that introduce a named API, feature, or concept. Routine fixes, dependency bumps, and internal refactors receive `null` and render with just their scope, if any.
230
228
 
231
229
  Rendered format:
232
230
  - With `leadIn`: `- **Deeplink testing**: Add deep link support via triggerDeeplink()`
233
- - Without `leadIn`: `- Add mock IPC support`
234
- - With `leadIn` + `breaking`: `- **BREAKING** **API rename**: Rename connect() to initialize()`
231
+ - Without `leadIn`: `- **ipc**: Add mock IPC support`, or `- Add mock IPC support` with no scope
235
232
 
236
233
  The `leadIn` value is available in templates as `entry.leadIn` (may be `undefined`).
237
234
 
238
235
  ---
239
236
 
240
- ## Scope grouping
241
-
242
- When the built-in markdown renderer encounters a category where **two or more entries share the same scope**, it groups them under a bold scope header instead of repeating the scope on each bullet:
243
-
244
- ```markdown
245
- ### New
246
-
247
- **ipc**:
248
-
249
- - **Deeplink testing**: Add deep link support via triggerDeeplink()
250
- - Add mock IPC support
251
- ```
252
-
253
- A scope that appears on only one entry renders inline: `- **scope**: description`. Entries with no scope render as plain bullets. Both come before the scope groups, so no entry sits under a label it doesn't have.
254
-
255
- Scope is assigned by the LLM (or inherited from the source commit). Control what scopes are valid with the `scopes` config.
256
-
257
- ---
258
-
259
237
  ## Scope validation (`scopes`)
260
238
 
261
239
  Controls how the LLM assigns scopes to entries.
@@ -450,14 +428,12 @@ Note that `links` is a property of `releaseNotes`, not `llm`.
450
428
 
451
429
  ### Breaking
452
430
 
453
- - **BREAKING** **API rename**: Rename connect() to initialize()
431
+ - **API rename**: Rename connect() to initialize()
454
432
 
455
433
  ### New
456
434
 
457
- **ipc**:
458
-
459
435
  - **Deeplink testing**: Add deep link support via triggerDeeplink()
460
- - Add mock IPC support
436
+ - **ipc**: Add mock IPC support
461
437
 
462
438
  ### Fixed
463
439
 
@@ -474,7 +450,7 @@ Note that `links` is a property of `releaseNotes`, not `llm`.
474
450
 
475
451
  **What happened:**
476
452
  - The `refactor!` commit has `breaking: true`, so it was re-routed to `Breaking` regardless of the LLM's original category. The `leadIn` phrase `"API rename"` was generated because it introduces a named API change.
477
- - The two `feat(ipc)` commits share the `ipc` scope, so they're grouped under a `**ipc**:` header. The first gets a `leadIn` (`"Deeplink testing"`); the second is a routine addition and gets none.
453
+ - The first `feat(ipc)` commit gets a `leadIn` (`"Deeplink testing"`), shown in place of its scope; the second is a routine addition and shows its `ipc` scope.
478
454
  - The `fix` commit maps to `Fixed` with no scope or `leadIn` (routine fix).
479
455
  - The `chore` commit maps to `Developer` (internal tooling change).
480
456
  - The static link from `items` is appended under `### Links`.
package/docs/monorepo.md CHANGED
@@ -73,6 +73,47 @@ Custom file name applies to all packages:
73
73
 
74
74
  ---
75
75
 
76
+ ## Project-wide changes
77
+
78
+ Commits that touch no package outside `version.sharedPackages` are project-wide. In async mode (`sync: false`, no `groups`, more than one package in the run):
79
+
80
+ - **Touching a shared package**, such as a bundled core: every released package's changelog, per-version notes file and release body ends with a `### Project-wide changes` block listing the ones since that package's previous release. A shared package's own block leaves out its own commits.
81
+ - **Touching no package**, such as CI or root tooling: only the root changelog lists them.
82
+
83
+ In those releases, the root changelog lists both kinds once per run, after that run's versions:
84
+
85
+ ```markdown
86
+ ## [utils@1.1.0] - 2026-03-15
87
+
88
+ ### Fixed
89
+
90
+ - Memory leak in event handler
91
+
92
+ ## Project-wide changes - 2026-03-15
93
+
94
+ ### Fixed
95
+
96
+ - Pin the bundled zod copy
97
+ ```
98
+
99
+ ---
100
+
101
+ ## Bundled release notes
102
+
103
+ With per-package tags, a releasing package in `version.primaryPackages` gets a section in its release notes and GitHub release body for each of its group-mates and internal dependencies that released changes of their own since the primary's previous release (its previous stable release, if any, for a stable release), in this run or an earlier one. Its internal dependencies are its `dependencies`, `peerDependencies` and cargo path dependencies, followed transitively but not through another primary, which is never bundled.
104
+
105
+ ```markdown
106
+ ### @myorg/utils 1.1.0 → 1.2.0
107
+
108
+ #### Fixed
109
+
110
+ - Memory leak in event handler
111
+ ```
112
+
113
+ Only async and grouped releases bundle, and a primary's first release bundles nothing. Each section groups the package's entries by type, Breaking first. In async mode, `version.sharedPackages` are left out, since their changes are already under Project-wide changes. `CHANGELOG.md` stays per package. `githubRelease.skipPackages` still decides whether a bundled package gets its own release.
114
+
115
+ ---
116
+
76
117
  ## CLI Flags
77
118
 
78
119
  `--changelog-mode` overrides the configured changelog location. Every flag is in the [CLI reference](../../../docs/cli.md#releasekit-notes-generate).