chore: add changelog for release notes

.claude/commands/pr.md

@@ -186,6 +186,13 @@ gh pr create --base $base --title "..." --body "..." [--draft]
   - Instruct the user to drag-and-drop each media file into the Preview section via the GitHub web UI
   - Note: GitHub does not support programmatic media upload to PR bodies
 
+### 8b. Backfill Changelog PR Number
+
+If the PR was created (not dry run) and `CHANGELOG.md` was modified in the branch (`git diff $base...HEAD --name-only | grep CHANGELOG.md`):
+- Read `CHANGELOG.md` and scan `## [Unreleased]` entries for lines missing a `#NUMBER` suffix
+- Append the actual PR number to those entries, e.g. `- Add foo` becomes `- Add foo #123`
+- If any entries were updated, create a new commit with message `chore: backfill changelog pr number` and push
+
 ### 9. Output Summary
 
 **If PR created:**

.claude/commands/release.md

@@ -53,6 +53,19 @@ If "Previous tag": ask `"Which tag?"` with a text input (default: `v{oldVersionN
 
 If "master" or if the release is minor/major: `{baseRef} = master`.
 
+### 2c. Finalize Changelog
+
+Read `CHANGELOG.md` and check whether `## [Unreleased]` has any entries beneath it.
+
+**If entries exist:**
+1. Replace `## [Unreleased]` with `## [{newVersionName}] - {YYYY-MM-DD}` (today's date)
+2. Insert a fresh empty `## [Unreleased]` section above the new version heading
+3. Update the compare link references at the bottom of the file:
+   - Change `[Unreleased]` link to compare from `v{newVersionName}...HEAD`
+   - Add a new `[{newVersionName}]` link comparing `v{oldVersionName}...v{newVersionName}`
+
+**If no entries:** Print `⚠ CHANGELOG.md has no unreleased entries — continuing without changelog update.` and proceed.
+
 ### 3. Create Release Branch & Bump Version
 
 ```bash
@@ -79,10 +92,13 @@ Edit `app/build.gradle.kts`:
 
 ```bash
 git add app/build.gradle.kts
+# Only stage CHANGELOG.md if step 2c modified it (i.e. unreleased entries were found)
 git commit -m "chore: version {newVersionName}"
 git push -u origin release-{newVersionName}
 ```
 
+If step 2c updated `CHANGELOG.md`, also `git add CHANGELOG.md` before the commit.
+
 ### 4. Create Version Bump PR
 
 Read `.github/pull_request_template.md` for structure. Create PR:
@@ -131,13 +147,13 @@ gh release create v{newVersionName} \
 
 ### 6. Generate Store Release Notes
 
-Fetch the auto-generated release notes from the draft release:
+Read the `## [{newVersionName}]` section from `CHANGELOG.md` as the primary source for release content. If that section is empty or was not created in Step 2c, fall back to fetching auto-generated release notes:
 
 ```bash
 gh release view v{newVersionName} --json body --jq .body
 ```
 
-Using those notes as context, write a concise user-facing summary of the release (2-3 sentences max, no commit hashes or PR numbers, written for end users not developers). Focus on new features and important bug fixes. Omit chores, maintenance, refactoring, CI changes, and test coverage improvements — these are not relevant to Play Store users. Translate the summary into 5 languages.
+Using the changelog entries (or auto-generated notes as fallback) as context, write a concise user-facing summary of the release (2-3 sentences max, no commit hashes or PR numbers, written for end users not developers). Focus on new features and important bug fixes. Omit chores, maintenance, refactoring, CI changes, and test coverage improvements — these are not relevant to Play Store users. Translate the summary into 5 languages.
 
 Create `.ai/` directory if it doesn't exist. Save to `.ai/release-notes-{newVersionName}.md`:
 

.cursor/rules/rules.main.mdc

@@ -62,6 +62,16 @@ alwaysApply: true
 
 ---
 
+## Changelog rules:
+- add an entry under `## [Unreleased]` in `CHANGELOG.md` for `feat:` and `fix:` PRs; skip for `chore:`, `ci:`, `refactor:`, `test:`, `docs:` unless the change is user-facing
+- use standard Keep a Changelog categories: `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`, `### Security`
+- append `#PR_NUMBER` at the end of each changelog entry when the PR number is known
+- place new entries at the top of their category section (newest first)
+- never modify released version sections — only edit `## [Unreleased]`
+- create category headings on demand (don't add empty stubs)
+
+---
+
 ## Rules for Android Unit tests and Instrumentation tests:
 - run unit tests for specific files like this: `./gradlew :app:testDevDebugUnitTest --tests "to.bitkit.repositories.LightningRepoTest"`
 - write unit tests in the same style and using same libraries as: `CurrencyRepoTest`, `LightningRepoTest`, `WalletRepoTest`

.github/pull_request_template.md

@@ -1,4 +1,5 @@
 <!-- Closes | Fixes | Resolves #ISSUE_ID -->
+<!-- Changelog: Add an entry under ## [Unreleased] in CHANGELOG.md for user-facing changes (skip for chores/CI/refactors). -->
 <!-- Brief summary of the PR changes, linking to the related resources (issue/design/bug/etc) if applicable. -->
 
 ### Description

AGENTS.md

@@ -237,6 +237,15 @@ suspend fun getData(): Result<Data> = withContext(Dispatchers.IO) {
 - ALWAYS use `.toImmutableList()`, `.toImmutableMap()`, `.toImmutableSet()` when producing collections for UI state
 - ALWAYS use `persistentListOf()`, `persistentMapOf()`, `persistentSetOf()` for default values in UiState fields
 
+### Changelog
+
+- ALWAYS add an entry under `## [Unreleased]` in `CHANGELOG.md` for `feat:` and `fix:` PRs; skip for `chore:`, `ci:`, `refactor:`, `test:`, `docs:` unless the change is user-facing
+- USE standard Keep a Changelog categories: `### Added`, `### Changed`, `### Deprecated`, `### Removed`, `### Fixed`, `### Security`
+- ALWAYS append `#PR_NUMBER` at the end of each changelog entry when the PR number is known
+- ALWAYS place new entries at the top of their category section (newest first)
+- NEVER modify released version sections — only edit `## [Unreleased]`
+- ALWAYS create category headings on demand (don't add empty stubs)
+
 ### Device Debugging (adb)
 
 - App IDs per flavor: `to.bitkit.dev` (dev/regtest), `to.bitkit.tnet` (testnet), `to.bitkit` (mainnet)

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/synonymdev/bitkit-android/compare/v2.1.2...HEAD