docs: add mandatory version bump rule to AGENTS.md, GEMINI.md, and CLAUDE.md

AGENTS.md

@@ -17,8 +17,15 @@ This document provides essential architectural context, operational rules, workf
    - Create atomic branches named `feat/<feature-name>`, `fix/<bug-name>`, or `perf/<improvement-name>` directly from `custom`.
    - Test and verify changes locally.
    - Commit atomic changes with clear Conventional Commit messages (`feat:`, `fix:`, `refactor:`, `chore:`).
+   - **Bump app version** (`version-name` and `version-code` in `gradle/libs.versions.toml`) before merging into `custom`.
    - Merge back into `custom` and push both the feature branch and `custom` to `origin`.
-3. **Submodule Synchronization**:
+3. **Always Bump Version Before Merging into `custom` (MANDATORY)**:
+   - Every push to `custom` triggers the automated CI/CD release workflow (`.github/workflows/custom-build-release.yml`), creating a public release tagged as `v${VERSION}`.
+   - To avoid release tag collisions and ensure the in-app auto-updater (`VersionManager.kt`) notifies users of new builds, **always increment** the version numbers in `gradle/libs.versions.toml`:
+     - `version-name` (e.g. `2.3.2` -> `2.3.3`)
+     - `version-code` (e.g. `62` -> `63`)
+   - Never merge into `custom` with an already-released version number.
+4. **Submodule Synchronization**:
    - If a change requires edits inside `core/`, work on an atomic branch inside `core` derived from its `custom` branch.
    - Commit and push to `muriloscolari/core:custom` FIRST.
    - Only then stage and commit the updated `core` submodule commit pointer in the root `SimpMusic` repository.

CLAUDE.md

@@ -20,6 +20,17 @@
 - **Architecture**: Clean Architecture + MVVM
 - **Build system**: Gradle (Kotlin DSL)
 
+## 🏷️ Release Versioning & Git Workflow Rule (MANDATORY)
+
+- **Base Integration Branch**: **`custom`** (never commit directly to `main` or `dev`).
+- **Feature/Fix Branches**: Always branch off `custom` (e.g. `feat/<name>`, `fix/<name>`, `chore/<name>`).
+- **ALWAYS Bump App Version Before Merging to `custom`**:
+  - Every push to `custom` triggers `.github/workflows/custom-build-release.yml`, which automatically builds and publishes a GitHub Release tagged as `v${VERSION}`.
+  - To prevent release collisions and ensure the in-app auto-updater (`VersionManager.kt`) notifies users of new builds, the AI agent **MUST** increment the version in `gradle/libs.versions.toml` before merging any branch into `custom`:
+    - `version-name` (e.g. `2.3.2` -> `2.3.3`)
+    - `version-code` (e.g. `62` -> `63`)
+  - **Never merge into `custom` with an already-released version number.**
+
 ## 🏗️ Architecture
 
 ### Clean Architecture Layers

composeApp/src/commonTest/kotlin/com/maxrave/simpmusic/utils/VersionManagerTest.kt

@@ -13,6 +13,8 @@ class VersionManagerTest {
         assertTrue(isNewerRelease(current = "2.3.0", tag = "v2.3.1", commitHash = "", isWindows = true))
         assertTrue(isNewerRelease(current = "2.3.1", tag = "v2.3.2", commitHash = "", isWindows = false))
         assertTrue(isNewerRelease(current = "2.3.1", tag = "v2.3.2", commitHash = "", isWindows = true))
+        assertTrue(isNewerRelease(current = "2.3.2", tag = "v2.3.3", commitHash = "", isWindows = false))
+        assertTrue(isNewerRelease(current = "2.3.2", tag = "v2.3.3", commitHash = "", isWindows = true))
     }
 
     @Test

gradle/libs.versions.toml

@@ -1,7 +1,7 @@
 [versions]
 # App version
-version-name = "2.3.2"
-version-code = "62"
+version-name = "2.3.3"
+version-code = "63"
 
 android = "9.4.1"
 kotlin = "2.4.20"