ai-release-notes 0.4.0 → 0.5.1

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/README.md CHANGED
@@ -2,7 +2,11 @@
2
2
 
3
3
  Generic AI-powered release notes generator using the [Vercel AI SDK](https://sdk.vercel.ai).
4
4
 
5
- Transform your git changelog into clean, business-readable release notes — with support for OpenAI, Anthropic, Mistral, Google, Ollama, and more.
5
+ Transform your git changelog into clean, business-readable release notes — with support for OpenAI, Anthropic, Mistral, Google, Ollama, and more. Usable as a CLI or as a library.
6
+
7
+ - **generate** — write the notes for a version range, in Markdown and/or HTML, in one or several languages.
8
+ - **promote** — carry a reviewed note to the next environment, word for word.
9
+ - **prompt** — ask about, revise, or merge notes already written, in your own words.
6
10
 
7
11
  **Fully customizable** via configuration: language, instructions, output format, templates, and context files.
8
12
 
@@ -39,31 +43,7 @@ API keys are **never** stored in config files. Only the key for the active provi
39
43
  | Azure OpenAI | `azure` | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` | GPT-4o via Azure | [Get Azure credentials](docs/api-keys.md#azure-openai) |
40
44
  | Ollama | `ollama` | None for local use; optional `OLLAMA_API_KEY` for Ollama Cloud | Local models, including Llama and Mistral | [Set up Ollama](docs/api-keys.md#ollama) |
41
45
 
42
- #### Setting environment variables
43
-
44
- **macOS / Linux:**
45
- ```bash
46
- export OPENAI_API_KEY=sk-...
47
- ```
48
-
49
- **Windows (PowerShell):**
50
- ```powershell
51
- $env:OPENAI_API_KEY="sk-..."
52
- ```
53
-
54
- **Windows (CMD):**
55
- ```cmd
56
- set OPENAI_API_KEY=sk-...
57
- ```
58
-
59
- **`.env` file (with dotenv):**
60
- ```bash
61
- # Install dotenv-cli
62
- npm install -g dotenv-cli
63
-
64
- # Run with env file
65
- dotenv -e .env -- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD
66
- ```
46
+ → [Setting environment variables](docs/api-keys.md#setting-environment-variables) on macOS, Linux, Windows, or from a `.env` file.
67
47
 
68
48
  ### 2. Initialize configuration
69
49
 
@@ -71,465 +51,71 @@ dotenv -e .env -- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env
71
51
  npx ai-release-notes init
72
52
  ```
73
53
 
74
- This creates `.ai-release-notes.yml` in your project root. **No API keys are stored in this file.**
54
+ This creates `.ai-release-notes/.ai-release-notes.yml`. **No API keys are stored in this file.**
55
+ A bare `.ai-release-notes.yml` at the project root, from before this was the
56
+ default, is still found.
75
57
 
76
58
  ### 3. Generate release notes
77
59
 
78
60
  ```bash
79
- # Uses the full Git history through v1.1.0
61
+ # The full Git history through v1.1.0, with the configured provider
80
62
  npx ai-release-notes generate --to v1.1.0 --env PROD
81
63
 
82
- # Uses the default provider (openai) — needs OPENAI_API_KEY
83
- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD
84
-
85
- # Uses Anthropic — needs ANTHROPIC_API_KEY
64
+ # One range, with Anthropic — needs ANTHROPIC_API_KEY
86
65
  npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD --with claude
87
66
 
88
- # Uses Mistral — needs MISTRAL_API_KEY
89
- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD --with mistral
90
- ```
91
-
92
- The command saves files according to your configuration and reports the paths
93
- it updated. To generate notes for the terminal only—without writing release
94
- files or indexes—use `--stdout`. The Markdown is written to standard output;
95
- status and token information go to standard error:
96
-
97
- ```bash
98
- npx ai-release-notes generate --from v1.25.9 --to v1.28.0 --with mistral --env PROD --stdout
99
- ```
100
-
101
- `--dry-run` is different: it shows the prompt without calling the AI provider.
102
- Use `--verbose` to see the instruction source, main language, and configured
103
- translation steps. It reports execution details, not private model reasoning.
104
-
105
- After a generation, the command shows the provider-reported input, output,
106
- and total token counts, together with the number of model calls and elapsed
107
- time. Translated releases include every translation call in these totals.
108
-
109
- ## CLI Options
110
-
111
- | Option | Description |
112
- |--------|-------------|
113
- | `--from <version>` | Previous version tag, or `start` for the full history (default: `start`) |
114
- | `--to <version>` | Current version tag |
115
- | `--env <env>` | **Required.** Environment name (PROD, STAGING, etc.) |
116
- | `--date <date>` | Release date: `now` (default), `tag`, or an ISO date such as `2026-07-20` |
117
- | `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
118
- | `--lang <language>` | Write one configured language only (default: all of them) |
119
- | `--config <path>` | Path to config file |
120
- | `--output <path>` | Output file path (overrides `output.saveTo`) |
121
- | `--to-dir <dir>` | Write the release into this folder (auto-names the file) |
122
- | `--format <markdown\|html>` | Output format (default: `markdown`) |
123
- | `--template <path>` | Custom template file |
124
- | `--changelog-file <path>` | Raw changelog file (skip git) |
125
- | `--context <paths...>` | Context files or directories (mixed) |
126
- | `--dry-run` | Show prompts without calling LLM |
127
- | `-v, --verbose` | Show applied instructions and generation steps |
128
- | `--stdout` | Write generated Markdown to standard output without saving files or indexes |
129
- | `--clipboard` | Copy result to clipboard |
130
-
131
- ### Release date
132
-
133
- Use the current date (the default), the selected `--to` tag's creation date,
134
- or an explicit ISO date:
135
-
136
- ```bash
137
- ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date now
138
- ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date tag
139
- ai-release-notes generate --from v1.25.9 --to v1.28.0 --env PROD --date 2026-07-20
67
+ # Print to the terminal instead of writing release files and indexes
68
+ npx ai-release-notes generate --to v1.1.0 --env PROD --stdout
140
69
  ```
141
70
 
142
- In the library API, pass the same values as `date`.
71
+ Files are saved where your configuration says, and the run reports the paths it
72
+ updated together with the tokens it spent.
143
73
 
144
- ---
74
+ → [Generating release notes](docs/generate.md) — **CLI options**, `--dry-run`, release dates, context files.
145
75
 
146
- ## Promoting a release to the next environment
76
+ ### 4. Promote a release to the next environment
147
77
 
148
- A release note written for QUA has already been read, corrected and agreed on.
149
- When that same release reaches PROD, nothing about it has changed — so
150
- `promote` reuses the files QUA already holds instead of asking a model to write
151
- them again. **Promoting one release builds no prompt and calls no provider**,
152
- which is also why no API key is needed:
78
+ A note written for QUA has already been read and agreed on. Promoting it to PROD
79
+ reuses those files instead of asking a model to write them again — no prompt is
80
+ built, no provider is called, no API key is needed:
153
81
 
154
82
  ```bash
155
83
  # Everything PROD is missing, in one command
156
84
  npx ai-release-notes promote --from-env QUA --to-env PROD
157
85
 
158
86
  # Or one explicit range
159
- npx ai-release-notes promote --from-env QUA --to-env PROD --from start --to v0.23.0
160
- ```
161
-
162
- Each release file names the range it covers, so the files themselves form the
163
- chain — `start → v0.23.0`, `v0.23.0 → v0.24.0`, and so on. Promoting reads that
164
- chain rather than the version numbers, so a project that does not release in
165
- ascending order is followed just as well.
166
-
167
- - **One file covers the range** — it is promoted as it stands, word for word.
168
- - **Several files cover it** — they are merged into the one note that covers
169
- the whole range: sections carrying the same heading become one section,
170
- their scopes become one scope, their lists become one list, and a line two
171
- releases both carry is listed once. Inside a list the newest release's lines
172
- come first, then the ones released before them.
173
- - **A note whose shape cannot be read back** — it is never rewritten to fit.
174
- The notes are kept whole and put one after another instead. Nothing to
175
- choose: a note that does not survive being read and written out unchanged
176
- answers this on its own.
177
-
178
- Every section survives that merge word for word — the reviewed wording is the
179
- whole point. What cannot survive it is the opening: three headings, three dates
180
- and three summaries do not add up to one release note. So the merged note is
181
- given a single opening, and that is the one thing a model is asked for:
182
-
183
- ```text
184
- 🚀 Promoting QUA → PROD: v1.25.7 → v1.28.0
185
- v1.25.7 → v1.26.0
186
- v1.26.0 → v1.27.0
187
- v1.27.0 → v1.28.0
188
- Sections merged word for word; one title and summary written for the range.
189
- ```
190
-
191
- The model is shown the three openings and nothing else, so it cannot reach the
192
- sections, and an answer that comes back carrying sections of its own is
193
- refused.
194
-
195
- When no provider is configured, when the call fails, or when the answer is
196
- refused, the newest release's title and summary stand for the range instead,
197
- with the environment and the version it followed pointed at what was actually
198
- promoted. That is a true opening, only narrower than the range it covers, so
199
- the run says so rather than reading as a success:
200
-
201
- ```text
202
- ⚠️ The v1.28.0 title and summary stand for the whole range: no provider is configured.
87
+ npx ai-release-notes promote --from-env QUA --to-env PROD --from v1.0.0 --to v1.1.0
203
88
  ```
204
89
 
205
- With no `--from`, promotion starts where the target environment already is, so
206
- running it twice does nothing the second time. With no `--to`, it goes to the
207
- newest release the source environment holds. The target environment's output
208
- index is updated exactly as a generation would update it.
90
+ When several releases cover the range they are merged section by section, and a
91
+ model is asked for one thing only: the single opening that covers them all.
209
92
 
210
- ### Where the files are
93
+ → [Promoting a release](docs/promote.md) — **CLI options**, merge rules, environment folders.
211
94
 
212
- Promotion reads and writes the paths `output.saveTo` already describes, so a
213
- layout naming its environment needs nothing else:
95
+ ### 5. Work with existing notes
214
96
 
215
- ```yaml
216
- output:
217
- - format: html
218
- saveTo: ./releases/{env}/release-notes_{from}_{to}.html
219
- ```
220
-
221
- When each environment lives in a folder that the path does not name, point at
222
- the folders instead — their names become the environments:
223
-
224
- ```bash
225
- npx ai-release-notes promote --from-dir ./releases/env1 --to-dir ./releases/env2
226
- ```
227
-
228
- A `saveTo` with neither `{from}` nor `{to}` holds every release in one file
229
- rather than one release per file, so there is nothing to promote from it; those
230
- outputs are reported as skipped.
231
-
232
- ### Promote options
233
-
234
- | Option | Description |
235
- |--------|-------------|
236
- | `--from-env <environment>` | Environment to promote from (default: `--from-dir`'s folder name) |
237
- | `--to-env <environment>` | Environment to promote to (default: `--to-dir`'s folder name) |
238
- | `--from <version>` | Start of the range (default: where the target environment is) |
239
- | `--to <version>` | End of the range (default: the newest release in the source) |
240
- | `--from-dir <dir>` / `--to-dir <dir>` | Read/write the releases in these folders |
241
- | `--pattern <pattern>` | File name inside those folders (default: the configured one) |
242
- | `--with <provider>` | LLM provider used to write the opening of a merged range |
243
- | `--lang <language>` | Promote one language only |
244
- | `--date <date>` | Release date: `now` (default), `tag`, or an ISO date |
245
- | `--config <path>` | Path to config file |
246
- | `--dry-run` | Show what would be promoted without writing anything |
247
- | `-v, --verbose` | Show what was promoted, release by release |
248
- | `--stdout` | Write the promoted notes to the terminal without saving files |
249
-
250
- An HTML release note is read back out of the page it was written into and
251
- rendered into the template again, so the promoted page states its own
252
- environment, versions and date. A page written through a template this cannot
253
- read is copied as it stands, which is the whole point of promoting.
254
-
255
- ---
256
-
257
- ## Asking for a change
258
-
259
- A generated note is rarely wrong so much as not yet right: it repeats a line,
260
- it says more about the build than anyone wants to read, or it drifted from your
261
- own writing rules. Regenerating answers none of that — the changelog has not
262
- changed, so the same note comes back and every correction already made to it is
263
- lost.
264
-
265
- `prompt` opens the notes an environment holds and asks what you would like to
266
- change. You answer in your own words:
97
+ A generated note is rarely wrong so much as not yet right. Regenerating loses
98
+ every correction already made to it, so `prompt` opens an environment as a
99
+ release-note assistant:
267
100
 
268
101
  ```bash
269
- npx ai-release-notes prompt --env PRD --from v1.25.7 --to v1.28.0 --with mistral
102
+ npx ai-release-notes prompt --env PROD
270
103
  ```
271
104
 
272
105
  ```
273
- 📝 2 release notes open for PRD
274
- releases/PRD/release-notes_v1.25.7_v1.26.0.md v1.25.7 → v1.26.0
275
- releases/PRD/release-notes_v1.26.0_v1.28.0.md v1.26.0 → v1.28.0
276
-
277
- 💬 Is there anything you would like to change?
278
- Say it in your own words. Say you are done when you are done.
279
-
280
- › remove the exact duplicate lines
281
- › drop the technical section, I don't want to talk about the docker part
282
- › group everything about "update endpoint logic" under one line
283
- › format them against the project instructions again
284
- › that's it, save them
106
+ 💬 What would you like to know or change?
107
+ › compare the intended audience of the last two notes
108
+ › combine those releases and simplify the introduction
109
+ › save
285
110
  ```
286
111
 
287
- There is nothing to learn first. Every answer is read by a model that works out
288
- what it meant — a change to make, a change to take back, a request to save, or
289
- that you are done — so "put that back", "actually leave it", and "that's all"
290
- all work.
291
-
292
- Without `--from` and `--to`, every release note the environment holds is opened
293
- at once, and each request is applied to all of them.
294
-
295
- - **Nothing is written until you say so.** Each request shows what it changed,
296
- line by line, and the files stay as they were until you ask for them to be
297
- saved.
298
- - **Repeated lines are compared, not rewritten.** Asking for exact duplicates to
299
- go calls no model at all: the lines are compared here, the first of each stays
300
- where you meet it, and a section left empty goes with them.
301
- - **A revision changes what a note says, never which release it is**, so the
302
- release index still describes it and is left alone.
303
-
304
- ### In CI
112
+ Ask arbitrary questions grounded in the open release files, target a particular
113
+ version or language, revise text, or merge a contiguous range into one note.
114
+ Answers are read-only. Every revision, created or deleted file, and release-index
115
+ update stays staged until you ask to save; undo, reset, and dry-run cover merges
116
+ as well. In CI, pass requests as `--ask` instead of answering them.
305
117
 
306
- Pass the requests instead of answering them, and the same session runs with
307
- nothing to type. It saves at the end, and exits non-zero if a request failed:
308
-
309
- ```bash
310
- npx ai-release-notes prompt --env PRD \
311
- --ask "remove exact duplicate lines" \
312
- --ask "drop any line about internal tooling" \
313
- --dry-run
314
- ```
315
-
316
- ### Prompt options
317
-
318
- | Option | Description |
319
- |--------|-------------|
320
- | `--env <environment>` | **Required.** Whose release notes to open |
321
- | `--from <version>` / `--to <version>` | Open only the releases a range covers |
322
- | `--lang <language>` | Open one language only |
323
- | `--with <provider>` | LLM override; see [provider aliases](#1-providers-and-api-keys) |
324
- | `--config <path>` | Path to config file |
325
- | `--ask <request>` | Apply a request with nothing to answer. Repeatable, for CI |
326
- | `--dry-run` | Show what the requests would change without writing anything |
327
- | `-v, --verbose` | Show the provider and instructions the requests are answered with |
328
- | `--stdout` | Write the revised notes to the terminal without saving files (needs `--ask`) |
329
-
330
- An HTML release note is a whole page, so only the note on it is ever sent or
331
- replaced: the page keeps its head, its styles, its footer, and the values the
332
- template filled in when it was generated. A page whose note cannot be told apart
333
- from the page around it is reported and left alone.
334
-
335
- ---
336
-
337
- ## Configuration
338
-
339
- `.ai-release-notes.yml` describes your project and where generated files
340
- belong. Keep API keys in environment variables; they are never stored in the
341
- configuration file.
342
-
343
- The main parts are simple:
344
-
345
- - `projectName` gives the generated notes their product name.
346
- - `provider` chooses the AI provider; `providers` lets you set its model and
347
- generation options.
348
- - `prompt` selects the release languages and where the writing rules come from.
349
- See [Instructions](#instructions).
350
- - `output` lists the Markdown and/or HTML release files to create. Use
351
- `{env}`, `{lang}`, `{from}`, and `{to}` in their names. Missing `--from` and
352
- `--to` become `start` and `end`. A name carrying `{from}` or `{to}` belongs
353
- to a single release, so regenerating it rewrites that file. A name without
354
- either is shared by every release, and each new one is added to it.
355
- - `outputIndex` is optional. It maintains a release summary with links to
356
- every release file. It may be one destination or a list, for example one
357
- Markdown and one HTML summary. Add `{lang}` when each language needs its own
358
- summary. `entryTemplate` sets the shape of one listed release; see
359
- [Index entries](#index-entries). Index templates can place links between those
360
- summaries with `{{languages}}` (or `{{langages}}`). That slot is spent the
361
- first time an index is written: afterwards the switcher is found by the markup
362
- it was rendered as, so a generated page carries a switcher rather than a
363
- marker of ours. A single language shows no switcher at all. The switcher
364
- merges languages from the current prompt with localized index files already
365
- present on disk. An index template is assumed to be written in the first
366
- `prompt.languages` entry, and an index in any other language is translated.
367
-
368
- Custom instruction and summary templates are optional. The generated config
369
- keeps their lines commented until you need them.
370
-
371
- ### Index entries
372
-
373
- One listed release is one template: markup with `{{slot}}` placeholders, and
374
- nothing else. The bundled one lives in
375
- `templates/default-release-summary-entry.md` and `.html`:
376
-
377
- ```html
378
- <section class="release-entry">
379
- <h2>Release {{toVersion}}</h2>
380
- <p><em>{{environment}} · {{date}} · Changes since {{fromVersion}}</em></p>
381
- <p><a href="{{href}}">Read release notes</a></p>
382
- </section>
383
- ```
384
-
385
- The slots are `{{environment}}`, `{{date}}`, `{{fromVersion}}`, `{{toVersion}}`
386
- and `{{href}}`. Everything else is yours to write. Point `entryTemplate` at your
387
- own file to replace it:
388
-
389
- ```yaml
390
- outputIndex:
391
- - format: html
392
- saveTo: ./releases/{env}/{lang}/index.html
393
- template: ./templates/summary.html
394
- entryTemplate: ./templates/entry.html
395
- ```
396
-
397
- The entry template is read from its file on every run and translated together
398
- with the summary template, so an index never carries a copy of it: editing the
399
- file is what changes the shape.
400
-
401
- Each entry stores what the index knows about its release — environment,
402
- versions, date, link — in a comment marker, and the whole list is rendered again
403
- on every run. Edit the entry template, or switch the index to another language,
404
- and the entire history is relabelled at the next release. The list is bounded by
405
- `<!-- ai-release-notes:releases -->` and `<!-- ai-release-notes:/releases -->`;
406
- everything outside those two lines belongs to the summary template.
407
-
408
- An entry that carries no record is kept word for word, below the rendered ones,
409
- since there is nothing to render it from.
410
-
411
- ### The release page
412
-
413
- An HTML release note is rendered inside `templates/default-release-note.html`,
414
- and that file owns every word of the page: its `<title>`, its footer, and its
415
- styles are the template's own. `--template` (or `output[].template`) points at a
416
- file of yours instead. These slots are filled, and anything else is left as
417
- written:
418
-
419
- | Slot | Value |
420
- |------|-------|
421
- | `{{content}}` | The release note itself |
422
- | `{{projectName}}` | `projectName` from the config |
423
- | `{{fromVersion}}` / `{{toVersion}}` | The version range |
424
- | `{{environment}}` | `--env` |
425
- | `{{date}}` | The resolved release date |
426
- | `{{version}}` | The `ai-release-notes` version |
427
-
428
- A page title is a sentence, so it is written in the template's `<title>` rather
429
- than assembled from the versions: there is no `{{title}}` slot.
430
-
431
- ### The first release
432
-
433
- `--from start` — the default — reads the whole history, so there is no previous
434
- version to compare against. The release note says `First release` where a
435
- comparison would go, and the file name still uses `start` for `{from}`.
436
-
437
- For the exact configuration and comments, see the annotated
438
- [example `.ai-release-notes.yml`](examples/.ai-release-notes.yml). The
439
- [examples guide](examples/README.md) then walks through a first run, writing
440
- instructions, templates, and output layouts.
441
-
442
- ---
443
-
444
- ## Instructions
445
-
446
- The release note is written entirely by the model: its title block, its summary,
447
- and its sections all come from the instructions. Built-in instructions apply
448
- until you write your own, so `generate` works with no configuration at all.
449
-
450
- `prompt.instructions` replaces the built-in rules with your own, as inline text
451
- or as a file resolved next to the config:
452
-
453
- ```yaml
454
- prompt:
455
- languages: [en, fr]
456
- instructions:
457
- file: ./.ai-release-instructions.md
458
- ```
459
-
460
- That one file is the whole contract. A localized release goes through two
461
- prompts — the first language is generated from the changelog, the others are
462
- translated from it — and both receive it, so rules that matter only to one of
463
- them, such as a glossary or protected vocabulary, belong in a section of the
464
- same file.
465
-
466
- The prompts themselves can be replaced too. `system` sets the role and goal
467
- that precede the instructions; `user` sets how the release is described to the
468
- model, through these placeholders:
469
-
470
- ```yaml
471
- prompt:
472
- system:
473
- file: ./.ai-release-system.md
474
- user: |
475
- {{projectName}} {{fromVersion}} → {{toVersion}} ({{environment}}, {{date}})
476
-
477
- {{commitCount}} commits:
478
- {{changelog}}
479
- {{context}}
480
- ```
481
-
482
- Whatever the model receives, `--dry-run` prints it without calling a provider,
483
- and `--verbose` reports which instructions were applied.
484
-
485
- Instructions shape the release note; they do not replace it. Every request opens
486
- with a scope guard that no configuration key removes, so `instructions` and
487
- `system` control wording, sections, tone, language, and terminology, but cannot
488
- repurpose the tool into a general-purpose assistant. See
489
- [Security](#security-) for the full trust model.
490
-
491
- ---
492
-
493
- ## Context Files
494
-
495
- Provide additional context to the LLM. Accepts a **mixed array** of files and directories:
496
-
497
- ```bash
498
- npx ai-release-notes generate --from v1.0.0 --to v1.1.0 --env PROD \
499
- --context ./specs/main.md ./docs/models/ ./README.md
500
- ```
501
-
502
- Context is sent to your LLM provider, so a directory scan skips what it should
503
- not upload: credential-shaped files, content matching known key formats, binary
504
- files, and `.git`, `.ssh`, `.aws`, `node_modules` and similar. A file you name
505
- explicitly is always loaded, with a warning when it looks sensitive. Scans stop
506
- at 256 KB per file, 1 MB total, 200 files, and 8 directory levels.
507
-
508
- ---
509
-
510
- ## Security 🔒
511
-
512
- Commit messages come from anyone who can land a commit, and a config file
513
- travels with the repository. Both are treated as untrusted:
514
-
515
- - **Scope guard.** Prepended to every system prompt, including a custom
516
- `prompt.system`, and not removable by configuration.
517
- - **Data boundaries.** The changelog and context go to the model in labelled
518
- blocks, and text imitating a delimiter is rewritten so it cannot break out.
519
- - **Safe rendering.** Raw HTML in a release note is escaped and link targets are
520
- limited to `http`, `https`, `mailto`, and relative paths.
521
- - **Bounded spend.** `git.maxCommits` (default 200) caps one run.
522
- - **Promotion.** `promote` reuses files this tool already wrote, whose markup was
523
- escaped when it was generated; those files are trusted like the rest of your
524
- repository. Merging several of them reaches a provider once, for the opening
525
- alone: the sections are never sent, and the answer is sanitized like any other
526
- model output before it reaches a page.
527
- - **Endpoint checks.** `baseURL` must be `http`/`https`, and a non-local one
528
- warns before any prompt leaves the machine.
529
-
530
- A release note is still model output written from unreviewed input. Review one
531
- before publishing it. Full details and reporting instructions are in
532
- [security.md](security.md).
118
+ → [Talking to your release notes](docs/prompt.md) — questions, merging, **CLI options**, CI mode, HTML pages.
533
119
 
534
120
  ---
535
121
 
@@ -548,106 +134,46 @@ const result = await generate({
548
134
  context: ["./specs/api-v2.md", "./docs/models/"],
549
135
  });
550
136
 
551
- console.log(result.markdown);
552
- console.log(result.html);
137
+ console.log(result.markdown, result.html);
553
138
  ```
554
139
 
555
- `markdownToHtml(markdown, options?)` wraps Markdown in the bundled release-note
556
- template, which supplies the page title and footer:
140
+ `promote(options)` returns the files a promotion would write without writing
141
+ them, and `PromptSession` answers questions or stages revisions and merges
142
+ against notes already on disk, saving only when you say so.
557
143
 
558
- ```typescript
559
- markdownToHtml(markdown, { trustedHtml: true });
560
- ```
561
-
562
- `promote(options)` returns the files a promotion would write, without writing
563
- any of them, so you can review or publish them yourself:
564
-
565
- ```typescript
566
- import { promote } from "ai-release-notes";
567
-
568
- const { files, plan } = await promote({
569
- fromEnvironment: "QUA",
570
- toEnvironment: "PROD",
571
- });
144
+ → [Programmatic API](docs/api.md) — `generate`, `promote`, `PromptSession`, and the steps they are built from.
572
145
 
573
- console.log(plan.segments.map((s) => `${s.fromVersion} → ${s.toVersion}`));
574
- for (const file of files) {
575
- console.log(file.path, "←", file.sources);
576
- }
577
- ```
578
-
579
- `PromptSession` opens the notes an environment holds and applies requests to
580
- them. Nothing reaches the disk until `save`, and `callModel` lets the session
581
- run on a model of your own:
582
-
583
- ```typescript
584
- import { PromptSession } from "ai-release-notes";
146
+ ---
585
147
 
586
- const session = await PromptSession.open({ environment: "PROD" });
148
+ ## Documentation
587
149
 
588
- const { action, instruction } = await session.route("drop the docker line");
589
- const result = action === "dedupe"
590
- ? session.dedupe()
591
- : await session.revise(instruction);
150
+ | Guide | What it covers |
151
+ |-------|----------------|
152
+ | [API keys](docs/api-keys.md) | A key per provider, and where to put it |
153
+ | [Generating release notes](docs/generate.md) | `generate`, CLI options, dates, context files |
154
+ | [Promoting a release](docs/promote.md) | `promote`, merging a range, environment folders |
155
+ | [Talking to your release notes](docs/prompt.md) | `prompt`, questions, revisions, merges, CI mode |
156
+ | [Configuration](docs/configuration.md) | `.ai-release-notes.yml`, output paths, indexes, templates |
157
+ | [Instructions](docs/instructions.md) | What the model is told to write |
158
+ | [Programmatic API](docs/api.md) | Using the package as a library |
159
+ | [CI/CD integration](docs/ci-cd.md) | GitHub Actions, secrets, non-interactive runs |
592
160
 
593
- for (const edit of result.edits) {
594
- console.log(edit.path, edit.changed ? "revised" : edit.skipped ?? "unchanged");
595
- }
161
+ The [example configuration](examples/.ai-release-notes.yml) is annotated, and the
162
+ [examples guide](examples/README.md) walks through a first run.
596
163
 
597
- await session.save();
598
- ```
164
+ ---
599
165
 
600
- Each step is exported on its own when you need only part of it:
601
-
602
- | Function | What it does |
603
- |----------|--------------|
604
- | `discoverReleases(saveTo, values)` | Read a `saveTo` pattern back off disk: which releases exist, and what their paths say about them |
605
- | `formatOutputPath(saveTo, values)` | Fill `{env}`, `{lang}`, `{from}`, `{to}`; anything not supplied stays a placeholder |
606
- | `planPromotion({ available, … })` | Chain release files into the run that carries one version to another |
607
- | `mergeReleaseDocuments(docs, format, opts)` | Merge release notes by section and list; `leadWith: "newest"` puts the last release's lines first |
608
- | `splitReleaseOpening(content, format)` | Cut a note where its first section begins: the title, date and summary on one side, the sections on the other |
609
- | `dedupeReleaseDocument(content, format)` | Drop the lines a note lists twice, and report which they were |
610
- | `parseReleaseDocument` / `serializeReleaseDocument` | A release note as a section tree, and back again |
611
- | `extractReleaseContent(page, template?)` | Read a release note back out of the HTML page it was rendered into |
612
- | `replaceReleaseContent(page, revised, template?)` | Put a revised note back on its page, leaving the page around it standing |
613
- | `sanitizeReleaseHtml(html)` | Reduce model-written markup to what a release note is made of |
614
- | `diffLines(before, after)` | What a revision changed, line by line |
615
- | `updateOutputIndexes(params)` | Add a release to every configured index, creating the ones that do not exist |
166
+ ## Security 🔒
616
167
 
617
- ---
168
+ Commit messages come from anyone who can land a commit, and a config file travels
169
+ with the repository. Both are treated as untrusted: a scope guard no
170
+ configuration key removes opens every system prompt, the changelog and context
171
+ reach the model in labelled blocks, model-written markup is escaped and its link
172
+ targets restricted, and `git.maxCommits` caps what one run can spend.
618
173
 
619
- ## CI/CD Integration
620
-
621
- ### GitHub Actions
622
-
623
- ```yaml
624
- name: Release Notes
625
- on:
626
- push:
627
- tags: ["v*"]
628
-
629
- jobs:
630
- release-notes:
631
- runs-on: ubuntu-latest
632
- steps:
633
- - uses: actions/checkout@v4
634
- with:
635
- fetch-depth: 0
636
-
637
- - run: npm install -g ai-release-notes
638
-
639
- - name: Generate
640
- env:
641
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
642
- run: |
643
- CURRENT=${GITHUB_REF#refs/tags/}
644
- PREVIOUS=$(git describe --tags --abbrev=0 ${CURRENT}^)
645
- ai-release-notes generate --from $PREVIOUS --to $CURRENT --env PROD --output RELEASE_NOTES.md
646
-
647
- - uses: softprops/action-gh-release@v1
648
- with:
649
- body_path: RELEASE_NOTES.md
650
- ```
174
+ A release note is still model output written from unreviewed input. Review one
175
+ before publishing it. Full details and reporting instructions are in
176
+ [security.md](security.md).
651
177
 
652
178
  ---
653
179
 
@@ -662,7 +188,7 @@ This project is governed by the [Code of Conduct](CODE_OF_CONDUCT.md); security
662
188
 
663
189
  ## Community 👥
664
190
 
665
- Love `ai-release-note` ? Give our repo a star ⭐ ⬆️.
191
+ Love `ai-release-notes`? Give our repo a star ⭐ ⬆️.
666
192
 
667
193
  ## License 📄
668
194