chore: add changelog for release notes

.claude/commands/pr.md

@@ -145,6 +145,14 @@ gh pr create --base $base --title "..." --body "..." [--draft]
 - Add `--draft` flag if draft mode selected
 - If actual PR number differs from predicted, rename the saved file
 
+### 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`):
+- Run `git diff $base...HEAD -- CHANGELOG.md` to identify only lines added in this branch (lines prefixed with `+`, excluding the `+++` header line)
+- From those added lines, find entries under `## [Unreleased]` that are missing a `#NUMBER` suffix
+- Append the actual PR number to only 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,12 @@ 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. Check Changelog
+
+Read `CHANGELOG.md` and check whether `## [Unreleased]` has any entries beneath it. Remember the result for Step 3.
+
+**If no entries:** Print `⚠ CHANGELOG.md has no unreleased entries — continuing without changelog update.` and proceed.
+
 ### 3. Create Release Branch & Bump Version
 
 ```bash
@@ -66,6 +72,13 @@ If `{baseRef}` is `master`, pull latest: `git pull origin master`. Skip pull if
 git checkout -b release-{newVersionName}
 ```
 
+**Finalize Changelog (if Step 2c found entries):**
+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 the base is a tag (not master), print:
 ```
 Release branch created from {baseRef}.
@@ -84,6 +97,8 @@ Verify the edit updated exactly 4 occurrences of each (Bitkit Debug/Release + Bi
 
 ```bash
 git add Bitkit.xcodeproj/project.pbxproj
+# Only stage CHANGELOG.md if it was finalized above (i.e. unreleased entries were found in step 2c)
+git add CHANGELOG.md
 git commit -m "chore: version {newVersionName}"
 git push -u origin release-{newVersionName}
 ```
@@ -132,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 App 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 App Store users. Translate the summary into 5 languages.
 
 Create `.ai/` directory if it doesn't exist. Save to `.ai/release-notes-{newVersionName}.md`:
 

.github/pull_request_template.md

@@ -1,3 +1,5 @@
+<!-- Changelog: Add an entry under ## [Unreleased] in CHANGELOG.md for user-facing changes (skip for chores/CI/refactors). -->
+
 ### Description
 
 Please include a summary of changes and which issues are fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

AGENTS.md

@@ -274,6 +274,15 @@ Ensure accessibility modifiers and labels are added to custom components.
 - Use descriptive names: `isLoadingUsers` not `loading`
 - Follow Apple's SwiftUI best practices
 
+### 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)
+
 ## Common Workflows
 
 ### Adding a New Feature

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-ios/compare/v2.1.2...HEAD