diff --git a/docs/user/cli-reference.md b/docs/user/cli-reference.md
index 7e9714742..a6e9b2e6d 100644
--- a/docs/user/cli-reference.md
+++ b/docs/user/cli-reference.md
@@ -1590,10 +1590,11 @@ helm push /tmp/aicr-bundle-*.tgz oci://<your-registry>/<path>
 
 # 3. Install — the URL is supplied here, not at bundle time
 #    `--set repoURL` is the PARENT NAMESPACE (no trailing chart name).
-#    The parent Application appends `.Chart.Name` via its `source.chart`
-#    field, and path-based children append it directly into their
-#    rendered `source.repoURL`. Including the chart name in --set
-#    repoURL double-appends it and the children fail to resolve.
+#    The parent Application appends `.Chart.Name` into its OCI
+#    `source.repoURL`, and path-based children append it directly into
+#    their rendered `source.repoURL`. For non-OCI Helm repositories, the
+#    parent uses `source.chart` instead. Including the chart name in
+#    --set repoURL double-appends it and the children fail to resolve.
 helm install aicr-bundle oci://<your-registry>/<path>/aicr-bundle --version <chart-version> \
   -n argocd \
   --set repoURL=oci://<your-registry>/<path> \
@@ -2580,11 +2581,16 @@ aicr --debug bundle -r recipe.yaml
 
 **"failed to load manifest \<path\> for component \<name\>"** — the recipe references a manifest path that does not exist in the current AICR binary's embedded data. This usually means the recipe was generated by an older binary and a referenced manifest has since been removed or relocated. Regenerate the recipe with the current binary (`aicr recipe ...`) and re-bundle. AICR recipes are a point-in-time artifact of the binary that produced them; bundling a stale recipe against a newer binary is not supported.
 
-**`--deployer argocd-helm`: `aicr-stack` or `<component>-pre` / `<component>-post` Application stuck at `Unknown` sync status / "Failed to load target state: ... `<registry>/<path>:<tag>: not found`"** — Argo CD cannot resolve the OCI artifact the parent or path-based child Application points at. Three common causes, in order of likelihood:
+**`--deployer argocd-helm`: `aicr-stack` or `<component>-pre` / `<component>-post` Application stuck at `Unknown` sync status / "Failed to load target state: ... `<registry>/<path>:<tag>: not found`"** — Argo CD cannot resolve the OCI artifact the parent or path-based child Application points at. Common causes:
 
-1. **Chart name doubled in `--set repoURL`.** Under the current contract, `--set repoURL` carries the **parent namespace only** (e.g., `oci://ghcr.io/myorg`). The parent Application appends `.Chart.Name` via its `source.chart` field, and path-based children append it directly into their rendered `source.repoURL`. Passing `--set repoURL=oci://ghcr.io/myorg/aicr-bundle` produces a double-suffixed reference (`.../aicr-bundle/aicr-bundle:<tag>`) that does not exist. Drop the trailing chart segment.
+1. **Chart name doubled in `--set repoURL`.** Under the current contract, `--set repoURL` carries the **parent namespace only** (e.g., `oci://ghcr.io/myorg`). The parent Application appends `.Chart.Name` into its OCI `source.repoURL`, and path-based children append it directly into their rendered `source.repoURL`. For non-OCI Helm repositories, the parent uses `source.chart` instead. Passing `--set repoURL=oci://ghcr.io/myorg/aicr-bundle` produces a double-suffixed reference (`.../aicr-bundle/aicr-bundle:<tag>`) that does not exist. Drop the trailing chart segment.
 2. **Argo CD older than v2.13.** Path-based children rely on Argo CD's generic OCI artifact source type, added in v2.13. Older Argo treats the source as Git and fails to resolve. Check with `kubectl -n argocd get deploy argocd-repo-server -o jsonpath='{.spec.template.spec.containers[0].image}'`. Upgrade Argo, or use `--deployer helm` if Argo upgrade is not an option.
 3. **Tag missing from the registry.** Verify the published artifact exists at the exact tag the parent expects: `oras manifest fetch <registry>/<path>/<chart>:<tag>`. If `aicr bundle` is invoked without a tag (`oci://<registry>/<path>/<chart>` with no `:<tag>` suffix), the CLI version is used as the default — make sure `--set targetRevision=<chart-version>` at install time matches.
+4. **Private registry credentials keyed to a different source URL.** Problem: Argo CD matches repository credentials against the source URL it dereferences.
+
+   Failure case: For this deployer, path-based OCI Applications render full `oci://<registry>/<path>/<chart>` source URLs even though `--set repoURL` is the parent namespace. A Secret keyed only to `<registry>/<path>` or to a scheme-less Helm-OCI URL may let local `helm install` succeed while Argo's repo-server still returns 401.
+
+   Solution: Key the Argo CD repository credential to the rendered `oci://.../<chart>` prefix, or to a broader matching prefix allowed by your cluster's credential policy, such as `oci://<registry>/` or `oci://<registry>/<path>/`.
 
 ## External Data Directory