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

vault/03-context/index.md

@@ -1,7 +1,7 @@
 ---
 type: context-index
 project: fidelity
-updated: 2026-04-16
+updated: 2026-04-17
 tags:
   - context
   - map
@@ -36,6 +36,7 @@ Swift and iOS best-practice context for programming questions:
 - [ios/index.md](./ios/index.md)
 - [ios/current-practices.md](./ios/current-practices.md)
 - [ios/project-swift-guidance.md](./ios/project-swift-guidance.md)
+- [ios/cocoapods-dependency-management.md](./ios/cocoapods-dependency-management.md)
 
 ### `workstreams/`
 

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

vault/03-context/ios/index.md

@@ -2,7 +2,7 @@
 type: guidance-index
 project: fidelity
 status: active
-updated: 2026-04-16
+updated: 2026-04-17
 tags:
   - ios
   - fidelity
@@ -23,10 +23,14 @@ Help the agent answer Swift and iOS programming questions with current best prac
 - [project-swift-guidance.md](./project-swift-guidance.md)
   Fidelity-specific guidance for applying Swift/iOS advice in this workspace.
 
+- [cocoapods-dependency-management.md](./cocoapods-dependency-management.md)
+  CocoaPods, private podspec repo, and dependency-resolution guidance for Fidelity release and consumer integration work.
+
 ---
 
 ## Usage
 
 - Use these files before answering Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging questions.
+- Use the CocoaPods guidance whenever the question touches release propagation, podspecs, dependency conflicts, Fid4 resolution, or FTFrameworks consumer updates.
 - When a recommendation depends on current Apple APIs, prefer official Apple or Swift documentation before making strong claims.
 - Keep project constraints visible: XFlow is backend-driven, Fid4 is consumer validation, and REST/GraphQL migration constraints may affect architecture.

vault/03-context/ios/project-swift-guidance.md

@@ -2,7 +2,7 @@
 type: guidance
 project: fidelity
 status: active
-updated: 2026-04-16
+updated: 2026-04-17
 tags:
   - ios
   - fidelity
@@ -20,6 +20,7 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker
 - XFlow is backend-driven; UI behavior may be service/configuration driven, not purely local Swift code.
 - Fid4 is the real consumer validation target for many issues.
 - XFlowViewMaker and FTFrameworks can affect whether a fix is visible in Fid4.
+- CocoaPods and private podspec-repo behavior are part of the real integration surface, not just build tooling details.
 - REST migration constraints still matter; do not assume REST is active by default.
 - Some work happens behind feature flags, especially risky consumer-impact changes.
 
@@ -43,4 +44,5 @@ Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker
 - If the user asks a general Swift question, answer generally but include a Fidelity/XFlow note when relevant.
 - If the user asks about a code change, separate modern best practice from what is safe for the current project.
 - If codebase constraints are unknown, say what must be confirmed: deployment target, Xcode version, module ownership, feature flag path, and consumer validation path.
+- If the work touches dependency propagation, published specs, or consumer upgrade behavior, explicitly include CocoaPods and podspec-repo reasoning instead of treating them as secondary operational noise.
 - For manager-ready explanations, connect the technical recommendation to scope, risk, and validation.

vault/03-context/workstreams/consumer-integration.md

@@ -95,6 +95,10 @@ Capture the durable release and validation path between XFlow changes and real c
 - For the current XFlowViewMaker propagation issue, the practical fix was made in the podspec repo by removing the XFlowViewMaker version reference from both the latest `FTAccountOpen` and `FTTransfer` podspecs.
 - After that podspec-repo PR was merged, `pod install --repo-update` in Fid4 resolved successfully because those podspecs no longer constrained the XFlowViewMaker version.
 - `FTAccountOpen` and `FTTransfer` do not appear to hold a direct XFlowViewMaker version reference in their checked FTFrameworks source podspec files; the effective resolution is managed through the published podspec layer and `ftAdapter` behavior.
+- This appears to be a risky workaround rather than a healthy long-term dependency-management pattern.
+- CocoaPods documentation recommends explicit dependency requirements in podspecs and specifically recommends the optimistic operator `~>` because it gives version control without being overly restrictive.
+- Removing version constraints entirely from published intermediate podspecs weakens compatibility guarantees, makes transitive resolution less predictable, and increases the chance that consumers pick up unvalidated downstream versions.
+- That risk is even higher in this workspace because Fid4 does not keep `Podfile.lock` in Git, so published podspec changes can alter future resolutions without a strong repository-level lockfile trail.
 
 ---