# Release Notes

## Purpose

Use `docs/releases/` as the canonical version-bound release history for `clisbot`.

Release notes answer: what changed in this version, what user or operator impact it has, and which update or validation facts matter later.

Keep user-facing catch-up and install/update docs in [`docs/updates/`](../updates/README.md). Keep manual migration procedures in [`docs/migrations/`](../migrations/README.md).
GitHub Releases and npm notes should stay shorter and link back to the matching release note here.
Release mechanics live in the [`release-clisbot` skill](../../skills/release-clisbot/SKILL.md); [`docs/development/release-process.md`](../development/release-process.md) only points to that canonical workflow.

## File Layout

- [`upcoming.md`](upcoming.md): staging area for work that is expected to become the next public release note
- `vX.Y.Z.md`: one file per shipped version
- [`templates/release-note.md`](templates/release-note.md): the required structure for future version notes

## Writing Rule

Release notes here should optimize for:

- very easy to scan
- clear user impact
- grouped changes by feature area instead of commit-by-commit noise
- plain language first, technical detail second

Use the current feature taxonomy from [`docs/features/feature-tables.md`](../features/feature-tables.md):

- Functional changes: `Channels`, `Auth`, `Agents`, `Runners`, `Control`, `Configuration`, and `DX`
- Non-functional changes: `Stability`, `Security`, `Architecture Conformance`, and `Runtime Benchmarks`

Inside each feature area, use Keep a Changelog verbs when they apply:

- `Added`
- `Changed`
- `Deprecated`
- `Removed`
- `Fixed`
- `Security`

Omit empty feature areas and empty verbs. If one change spans multiple areas, place it under the area with the main user-facing ownership and mention the secondary area in the bullet.

## Release Bundle Rule

For a normal release, update:

1. [`CHANGELOG.md`](../../CHANGELOG.md): short version index only.
2. `docs/releases/vX.Y.Z.md`: canonical version note.
3. `docs/updates/releases/vX.Y.Z-release-guide.md`: only for large releases where users or operators need a 3-5 minute catch-up guide.
4. `docs/updates/update-guide.md`: update the current stable install/update guide when the public update path changes.
5. `docs/migrations/vA.B.C-to-vX.Y.Z.md`: only when config, schema, or runtime update steps require manual operator action beyond install/restart/status.
6. GitHub Release: short summary from the matching git tag, with prerelease=true for beta tags and latest=true only for stable.

Do not duplicate the full release detail across these files. Link between them.

## Beta And Pre-Release Rule

Use beta notes to support testers and operators, not as a second release-history system.

- If a beta is part of an upcoming public release, track it in `upcoming.md` until the release ships.
- When the public release note is cut, summarize meaningful beta history inside that release note under `Pre-Release History`.
- Do not add every beta to `CHANGELOG.md`; keep `CHANGELOG.md` focused on public release targets.
- Create `docs/updates/releases/vX.Y.Z-beta.N-release-guide.md` only when a beta is sent to users/operators and needs a rollout note.
- Create a migration note for a beta only when beta testers need a concrete update or rollback runbook.
- Use the `release-clisbot` skill for beta/stable publish commands and npm dist-tag handling.

## Current Notes

- [Upcoming](upcoming.md)
- [v0.1.53](v0.1.53.md)
- [v0.1.52](v0.1.52.md)
- [v0.1.51](v0.1.51.md)
- [v0.1.50](v0.1.50.md)
- [v0.1.43](v0.1.43.md)
- [v0.1.41](v0.1.41.md)
- [v0.1.39](v0.1.39.md)