docs(cli): document bundle upload --auto-bump

apps/docs/src/content/docs/docs/cli/commands.mdx

@@ -173,6 +173,7 @@ Optionally, you can give:
 * `--no-code-check` Ignore checking if notifyAppReady() is called in source code and index present in root folder.
 * `--display-iv-session` Show in the console the IV and session key used to encrypt the update.
 * `--bundle <bundle>` Bundle version number of the bundle to upload.
+* `--auto-bump [level]` Auto-increment from the channel's linked bundle, else the latest remote app version. Level: `major`, `minor` (default), `patch` (alias `fix`), or `metadata`. Bumps until a free name is found (deleted names stay occupied). Cannot be combined with `--bundle`.
 * `--min-update-version <minUpdateVersion>` Minimal version required to update to this version. Used only if the disable auto update is set to metadata in channel.
 * `--auto-min-update-version` Set the min update version based on native packages.
 * `--ignore-metadata-check` Ignores the metadata (node_modules) check when uploading.

apps/docs/src/content/docs/docs/cli/reference/bundle.mdx

@@ -28,6 +28,16 @@ Capgo never inspects external content. Add encryption for trustless security.
 npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production,beta
 ```
 
+Auto-bump the next free semver from the channel (or latest remote app version) when you do not pass `--bundle`. Useful in CI when `package.json` already matches a version Capgo has:
+
+```bash
+npx @capgo/cli@latest bundle upload --channel=production --auto-bump
+npx @capgo/cli@latest bundle upload --auto-bump major
+npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
+npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
+npx @capgo/cli@latest bundle upload --auto-bump metadata
+```
+
 **Options:**
 
 | Param          | Type          | Description          |
@@ -54,6 +64,7 @@ npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel prod
 | **--no-code-check** | <code>boolean</code> | Ignore checking if notifyAppReady() is called in source code and index present in root folder |
 | **--display-iv-session** | <code>boolean</code> | Show in the console the IV and session key used to encrypt the update |
 | **-b** | <code>string</code> | Bundle version number of the bundle to upload |
+| **--auto-bump** | <code>string</code> | Auto-increment from the channel's linked bundle, else the latest remote app version. Level: major, minor (default), patch (alias fix), or metadata. Bumps until a free name is found (deleted names stay occupied). Cannot be combined with --bundle (-b) |
 | **--link** | <code>string</code> | Link to external resource (e.g. GitHub release) |
 | **--comment** | <code>string</code> | Comment about this version, could be a release note, a commit hash, a commit message, etc. |
 | **--min-update-version** | <code>string</code> | Minimal version required to update to this version. Used only if the disable auto update is set to metadata in channel |

apps/docs/src/content/docs/docs/getting-started/cicd-integration.mdx

@@ -148,6 +148,20 @@ This configuration does the following:
 
 Make sure to run semantic-release before building your app so that the updated version from `package.json` is included in your build through the capacitor.config.
 
+### Auto-bump when the local version is already on Capgo
+
+Bundle names must be unique (deleted versions still occupy their name). If CI keeps uploading the same `package.json` version, the upload fails. Prefer bumping `package.json` (for example with semantic-release). When that is not practical, let the CLI pick the next free semver from the channel's linked bundle, or else the latest remote app version:
+
+```bash
+npx @capgo/cli@latest bundle upload --channel=production --auto-bump
+npx @capgo/cli@latest bundle upload --auto-bump major
+npx @capgo/cli@latest bundle upload --auto-bump minor   # default when the flag has no value
+npx @capgo/cli@latest bundle upload --auto-bump patch   # alias: fix
+npx @capgo/cli@latest bundle upload --auto-bump metadata
+```
+
+Do not combine `--auto-bump` with `--bundle` / `-b`. See the [`bundle upload` reference](/docs/cli/reference/bundle/#bundle-upload) for the full option list.
+
 ## Troubleshooting
 
 If you encounter issues with your Capgo CI/CD integration, here are a few things to check:

apps/docs/src/content/docs/docs/live-updates/channels.mdx

@@ -209,6 +209,8 @@ It's important to note that bundles in Capgo are global to your app, not specifi
 
 When versioning your bundles, we recommend using [semantic versioning with Capgo's Semver Tester](/semver_tester/) and pre-release identifiers for channel-specific builds. For example, a beta release might be versioned as `1.2.3-beta.1`.
 
+In CI, if the local version was already uploaded, use `npx @capgo/cli@latest bundle upload --auto-bump` (optionally `major`, `minor`, `patch`/`fix`, or `metadata`) so the CLI bumps from the channel's linked bundle until a free name is found. You cannot combine it with `--bundle`. See [CI/CD Integration](/docs/getting-started/cicd-integration/#auto-bump-when-the-local-version-is-already-on-capgo) and the [CLI reference](/docs/cli/reference/bundle/#bundle-upload).
+
 This approach has several benefits:
 
 - It clearly communicates the relationship between builds. `1.2.3-beta.1` is obviously a pre-release of `1.2.3`.