---
name: release
description: Bump the app version, update the changelog, and prepare a git tag for release
disable-model-invocation: false
---

# Release

Bump the app version, update the changelog, and prepare a git tag.

## Process

### 1. Determine what changed since the last version

Run `git log` from the last version tag (or all history if no tags exist) and review the
changes. Categorize:

- **Features**: new user-facing capabilities
- **Fixes**: bug fixes
- **Improvements**: performance, UX polish, refactoring that affects behavior
- **Internal**: refactoring, docs, tests, build (don't list individually — summarize if substantial)

### 2. Determine bump type

Read the current version from `package.json`. The project uses **simplified semver during
pre-1.0**:

| Bump | When | Example |
| --- | --- | --- |
| **Minor** (`0.x.0`) | New features, UI changes, behavior changes | `0.1.0` → `0.2.0` |
| **Patch** (`0.x.y`) | Bug fixes, polish, performance, internal | `0.1.0` → `0.1.1` |
| **Major** (`1.0.0`) | Only when declaring public stability (user decision) | — |

Present the categorized changes and your recommended bump type to the user **for confirmation
before proceeding**.

### 3. Update version

Update the `version` field in `package.json`. This is the **single source of truth** — Vite
injects it as `__APP_VERSION__` at build time (shown in the header badge, and in Settings /
the export envelope once those exist).

### 4. Update the changelog

Maintain `docs/CHANGELOG.md`. If it doesn't exist yet, create it with a top-level `# Changelog`
heading. Add a new entry under a month heading:

```markdown
## June 2026

### v0.2.0

- **New feature** — description…

### v0.1.1

- **Bug fix** — description…
```

- Group by feature/change, not by commit.
- Lead with the name in bold, then a dash and description.
- Most important changes first; summarize related commits into coherent items.

### 5. Cross-check user-facing docs

Scan hand-maintained user-facing surfaces against the changes landing in this release and fix
drift **before** the version-bump commit (the CHANGELOG entry is not the place to quietly slip
in doc fixes):

- `README.md` — the status line and any feature claims still accurate?
- Any in-app help / about / onboarding content that exists at release time.

(When narrative content pages are added later, list them here so this net catches accumulated
drift across many changes.)

### 6. Suggest the git tag

After the user stages and commits the version bump, suggest:

```bash
git tag v{version}
git push --tags
```

If/when a deploy pipeline is wired, note here what publishing the tag triggers.

## Rules

- **Never bump the version without user confirmation** on the bump type.
- **Never stage or commit** — the user handles git operations.
- The export-format `version` (the import/export envelope) is **independent** of the app
  version — only bump it when the export schema actually changes.
- Keep commit subjects single-line; no `Co-Authored-By` trailers (the user handles the commit
  regardless).