Merge pull request #357 from keboola/devin/PSGO-1086-1759383894-document-cleanup-rename-conflicts

PSGO-1086: Document --cleanup-rename-conflicts flag for pull command

Author: Matovidlo

cli/commands/sync/pull/index.md

@@ -30,6 +30,14 @@ If your local state is invalid, the command will fail unless you use the `--forc
 `--force`
 : Ignore invalid local state
 
+`--cleanup-rename-conflicts`
+: Enable cleanup mode for handling rename conflicts. When configurations are renamed in the UI (e.g., in a chain like A→B, C→A), this option removes conflicting destinations to allow the rename to proceed. **Only use this for UI-only workflows** where changes are made exclusively in the Keboola UI and synced down. This option is not needed for normal Git-based development workflows.
+
+<div class="clearfix"></div><div class="alert alert-warning" role="alert" markdown="1">
+<strong>Warning:</strong><br>
+When using `--cleanup-rename-conflicts`, conflicting files that block renames will be permanently removed from your local directory. These files cannot be recovered unless they exist in the remote Keboola project. Only use this option when you have no uncommitted local changes and are purely syncing UI modifications.
+</div>
+
 [Global Options](/cli/commands/#global-options)
 
 ## Examples

cli/devops-use-cases/index.md

@@ -160,3 +160,44 @@ that can be deployed as a [Data App](https://help.keboola.com/components/data-ap
 This application includes GitHub actions that allow you to manage this scenario. It is expected that users will modify this flow to their needs.
 
 To learn about the full use case, please refer to [this blog post](https://www.keboola.com/blog/keboola-dev-prod-lifecycle-via-git), where we describe the workflow in depth.
+
+## UI-Only Sync Workflow
+
+When working in a purely UI-based workflow where all changes are made in the Keboola user interface and no local development occurs in the Git repository, you may encounter rename conflicts during pull operations.
+
+### Rename Conflicts
+
+Rename conflicts occur when configurations are renamed in a chain. For example:
+- Configuration A is renamed to B in the UI
+- Configuration C is renamed to A in the UI
+
+When pulling these changes, the standard `kbc pull` command will fail because it tries to rename C to A, but A still exists (it hasn't been renamed to B yet in the local operation order).
+
+### Using --cleanup-rename-conflicts
+
+For UI-only workflows, use the `--cleanup-rename-conflicts` flag:
+
+```shell
+kbc pull --cleanup-rename-conflicts
+```
+
+This flag enables cleanup mode, which:
+1. Detects when a rename destination already exists
+2. Removes the conflicting destination
+3. Proceeds with the rename operation
+
+This is safe for UI-only workflows because there are no uncommitted local changes that could be lost.
+
+<div class="clearfix"></div><div class="alert alert-warning" role="alert" markdown="1">
+<strong>Important:</strong><br>
+Only use `--cleanup-rename-conflicts` when you are working in a purely UI-based workflow with no local development. Files removed during cleanup cannot be recovered unless they exist in the remote Keboola project. If you make local changes to configurations outside of the UI, do not use this flag as it may permanently delete your uncommitted work.
+</div>
+
+### When NOT to Use This Flag
+
+Do **not** use `--cleanup-rename-conflicts` if:
+- You are making local changes to configurations in your Git repository
+- You are following a Git-based development workflow
+- You have uncommitted local modifications
+
+For Git-based development workflows, standard `kbc pull` and `kbc push` operations handle renames correctly without requiring cleanup mode.