docs: add ArgoCD image-updater multi-source troubleshooting guide

Add comprehensive documentation for resolving ArgoCD image-updater credential
errors with multi-source applications. Documents the solution of using ArgoCD
API write-back method instead of git write-back for applications that use
external Helm charts with local values repositories.

Key learnings:
- Multi-source apps need argocd write-back method not git
- External chart repos don't need write credentials with API method
- Includes step-by-step implementation and verification commands

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -272,4 +272,67 @@ Before migrating any application to ArgoCD:
 4. **Confirm Configuration Persistence**:
    ```bash
    kubectl exec -it deployment/<app-name> -- ls -la /config
-   ```
+   ```
+
+### ArgoCD Image-Updater Multi-Source Application Issues
+
+#### Problem: Credential Errors with Multi-Source Applications
+When using ArgoCD image-updater with multi-source applications (chart from external repo + values from Git), the image-updater may fail with credential errors like:
+```
+Could not update application spec: could not get creds for repo 'https://chart-repository.com': credentials for 'https://chart-repository.com' are not configured in Argo CD settings
+```
+
+#### Root Cause Analysis
+1. **Multi-Source Confusion**: Image-updater tries to write back changes to the chart repository instead of the values repository
+2. **Git Write-Back Limitations**: The `git` write-back method doesn't handle multi-source applications properly
+3. **Repository Credentials**: External chart repositories (like Bananaspliff) don't have write credentials configured
+
+#### Solution: Use ArgoCD API Write-Back Method
+Instead of using `git` write-back method, use the `argocd` API method for multi-source applications:
+
+```yaml
+metadata:
+  annotations:
+    argocd-image-updater.argoproj.io/image-list: app=registry/image:latest
+    argocd-image-updater.argoproj.io/app.update-strategy: digest
+    argocd-image-updater.argoproj.io/write-back-method: argocd  # Use ArgoCD API instead of git
+    argocd-image-updater.argoproj.io/write-back-target: http://git-repo.local/values.git  # Optional: specify target repo
+```
+
+#### Implementation Steps
+1. **Update Image-Updater Configuration**:
+   ```bash
+   kubectl patch configmap argocd-image-updater-config -n argocd --patch '{"data":{"git.user":"argocd-image-updater","git.email":"argocd@turing.lan"}}'
+   ```
+
+2. **Change Application Write-Back Method**:
+   ```bash
+   kubectl patch application <app-name> -n argocd --type='merge' --patch='{"metadata":{"annotations":{"argocd-image-updater.argoproj.io/write-back-method":"argocd"}}}'
+   ```
+
+3. **Restart Image-Updater**:
+   ```bash
+   kubectl rollout restart deployment argocd-image-updater -n argocd
+   ```
+
+#### Verification Commands
+```bash
+# Check image-updater logs for success
+kubectl logs -n argocd deployment/argocd-image-updater --tail=20
+
+# Look for these success indicators:
+# - "Successfully updated the live application spec" 
+# - "Processing results: applications=X images_considered=X images_skipped=0 images_updated=X errors=0"
+
+# Verify applications remain healthy
+argocd app list
+
+# Check that pods are updated with new images
+kubectl get pods -l app=<app-name>
+```
+
+#### Key Learnings
+- **ArgoCD API Method**: Works better than Git write-back for multi-source applications
+- **No Repository Credentials Needed**: ArgoCD API method doesn't require external repository write credentials
+- **Application Spec Updates**: Changes are applied directly to ArgoCD application specs, not Git files
+- **Multi-Source Compatibility**: This approach handles complex application configurations properly