feat: Update CocoaPods dependency management guidance and index for improved clarity on versioning and release propagation

vault/03-context/ios/cocoapods-dependency-management.md

@@ -0,0 +1,78 @@
+---
+type: guidance
+project: fidelity
+status: active
+updated: 2026-04-17
+tags:
+  - ios
+  - cocoapods
+  - dependencies
+  - fidelity
+---
+# CocoaPods Dependency Management
+
+## Goal
+
+Help the agent reason correctly about CocoaPods behavior, private podspec repos, and release propagation in the Fidelity iOS ecosystem.
+
+---
+
+## Why This Matters Here
+
+- CocoaPods is a core part of how XFlowSDK changes reach XFlowViewMaker, FTFrameworks, and Fid4.
+- Many apparent SDK or consumer issues are actually dependency-resolution or published-podspec issues.
+- The workspace should treat CocoaPods knowledge as part of normal investigation and release reasoning, not as an edge case.
+
+---
+
+## Fidelity-Specific Context
+
+- XFlowSDK releases publish artifacts and podspec updates that downstream consumers adopt through CocoaPods.
+- XFlowViewMaker, FTAccountOpen, FTTransfer, and Fid4 propagation all depend on correct podspec and resolver behavior.
+- The effective dependency constraint can come from the published podspec repo layer, not only from the source repo that developers inspect first.
+- Fid4 currently does not keep `Podfile.lock` in Git, which weakens reproducibility and makes published podspec changes more operationally significant.
+
+---
+
+## Agent Rules
+
+- When a newly published dependency does not resolve in Fid4, check CocoaPods resolution before assuming the code change failed.
+- Distinguish these layers:
+  - source repo podspec or helper code
+  - published private podspec repo
+  - consumer `Podfile`
+  - local/pipeline lockfile state
+- Do not assume FTFrameworks source tells the whole truth about the active dependency graph.
+- Treat private podspec repo edits as high-signal release-path behavior that may explain why local or pipeline resolution differs from expectations.
+- When giving advice, separate:
+  - what fixed the immediate unblock
+  - what is healthy long-term dependency management
+
+---
+
+## CocoaPods Best-Practice Anchors
+
+- CocoaPods podspecs are expected to declare dependency requirements explicitly.
+- CocoaPods documentation recommends the optimistic operator `~>` because it provides version control without being overly restrictive.
+- Overly restrictive dependency requirements can block compatibility.
+- Removing dependency constraints entirely can weaken compatibility guarantees and make transitive resolution less predictable.
+- `pod install` is the normal command after dependency-definition changes; `pod update` is for intentionally updating pod versions.
+- `Podfile.lock` is important for reproducible installs and should normally be committed.
+
+---
+
+## Current Project Caution
+
+- In this project, removing the XFlowViewMaker version reference from published `FTAccountOpen` and `FTTransfer` podspecs unblocked Fid4 resolution.
+- That should be understood as the current operational fix, not automatically as the ideal dependency-management pattern.
+- Because `Podfile.lock` is not committed in Fid4, broad podspec-repo edits can silently change future resolutions more than they should in a healthier CocoaPods setup.
+
+---
+
+## What Good Answers Should Include
+
+- Whether the issue is in source code, published specs, or consumer resolution
+- Whether `pod install`, `pod install --repo-update`, or `pod update` is the appropriate command for the stated goal
+- Whether the current fix improves compatibility or only removes guardrails
+- Whether the result is reproducible or vulnerable to future resolver drift
+- Whether the advice is a short-term unblock or a durable recommendation