feat: Organize context files and enhance documentation for clarity and structure

ai/context/systems/fid4.md

@@ -0,0 +1,30 @@
+# Fid4
+
+## Role
+
+Fid4 is the main Fidelity consumer iOS app and the most important environment for validating real integration behavior.
+
+---
+
+## Durable Context
+
+- Fid4 is the newer flagship-style app and is heavily SwiftUI-based.
+- Validation in Fid4 often reveals issues that do not appear in XFlowSDK isolation or sample apps.
+- Historical Slack context shows that some tickets were incorrectly scoped until behavior was checked in Fid4 or flagship.
+- Real consumer testing in Fid4 matters for modal presentation, validation messaging, and backend-driven flow behavior.
+
+---
+
+## Validation Implications
+
+- If an issue depends on real flow behavior, do not assume XFlow-only validation is sufficient.
+- When a story touches presentation, entry points, or consumer behavior, check whether Fid4 is required to confirm scope.
+- Build or startup instability in Fid4 can slow validation and should be treated as a practical investigation constraint.
+
+---
+
+## Historical Signals From Slack
+
+- Fid4 was repeatedly referenced as the right place to verify SwiftUI/XFlow bugs before finalizing scope.
+- Historical work included modal-on-modal presentation issues, goal/date validation behavior, and consumer-facing eventing questions.
+- Some XFlow tickets needed rework because the original spike or story had not been validated in flagship/Fid4.

ai/context/systems/ftframeworks.md

@@ -0,0 +1,32 @@
+# FTFrameworks
+
+## Role
+
+FTFrameworks contains consumer-side feature modules such as FTAccountOpen, FTTransfer, and related libraries that mediate how XFlow changes reach Fid4.
+
+---
+
+## Durable Context
+
+- FTFrameworks is often part of the real validation and release chain, not just a downstream detail.
+- Historical Slack context shows pinned FT module versions repeatedly blocking adoption of newer XFlow or XFlowViewMaker changes in Fid4.
+- Changes to XFlow often needed corresponding FTAccountOpen or FTTransfer updates before end-to-end testing was realistic.
+
+---
+
+## Validation And Release Implications
+
+- If Fid4 does not reflect the expected XFlow fix, check FT module versions before concluding the SDK change failed.
+- Version movement can require a chain such as:
+  - XFlowSDK
+  - XFlowViewMaker
+  - FTAccountOpen / FTTransfer
+  - Fid4
+- Test failures or publishing issues in FT modules can delay consumer validation even when the core XFlow change is ready.
+
+---
+
+## Historical Signals From Slack
+
+- FTAccountOpen and FTTransfer were repeatedly mentioned in version bump and release coordination work.
+- Historical messages also tied FTFrameworks to FTAuth and MFA-related stories, showing that dependency understanding matters when sizing or scoping work.

ai/context/systems/index.md

@@ -0,0 +1,23 @@
+# Systems Index
+
+## Core Components
+
+- [fid4.md](./fid4.md)
+  Consumer app and the most important real-world validation environment.
+
+- [xflowsdk.md](./xflowsdk.md)
+  Backend-driven flow engine and the center of most Fidelity behavior analysis.
+
+- [xflowviewmaker.md](./xflowviewmaker.md)
+  Adapter layer historically involved in version bumps, release coupling, and removal evaluation.
+
+- [ftframeworks.md](./ftframeworks.md)
+  Consumer-side feature modules that often mediate whether XFlow changes can be validated in Fid4.
+
+---
+
+## Guidance
+
+- Start with `xflowsdk.md` for backend-driven behavior questions.
+- Start with `fid4.md` or `ftframeworks.md` for consumer validation and release flow questions.
+- Open `xflowviewmaker.md` when the question involves version bumps, transitional architecture, or pipeline friction.

ai/context/systems/xflowsdk.md

@@ -0,0 +1,39 @@
+# XFlowSDK
+
+## Role
+
+XFlowSDK is the backend-driven UI engine that renders Fidelity flows from service-provided configuration.
+
+---
+
+## Durable Context
+
+- XFlow behavior depends on backend rules, entry point, and authentication state.
+- SwiftUI migration work introduced recurring behavior questions that were not just visual; many were contract or lifecycle issues.
+- Historical Slack patterns show recurring topics around:
+  - component type expansion in SwiftUI
+  - Next-button visibility rules
+  - markdown link handling and analytics
+  - modal presentation and dismissal sequencing
+  - consumer-vs-framework ownership boundaries
+
+---
+
+## Debugging Implications
+
+- Do not treat XFlow output as static UI; backend configuration can change the result.
+- When behavior differs across environments, check whether the issue is:
+  - service/configuration driven
+  - auth-state driven
+  - entry-point driven
+  - consumer-integration driven
+- Some apparent XFlow regressions historically turned out to be consumer, pipeline, or environment issues.
+
+---
+
+## Historical Signals From Slack
+
+- SwiftUI behavior repeatedly needed parity work beyond UIKit assumptions.
+- Next-button visibility logic required using the full set of service parameters, not only label text.
+- Modal, delegate, and lifecycle sequencing became recurring themes in pure SwiftUI environments.
+- XFlow work often had to be validated through consumer repositories, not only inside the SDK.

ai/context/systems/xflowviewmaker.md

@@ -0,0 +1,29 @@
+# XFlowViewMaker
+
+## Role
+
+XFlowViewMaker is the adapter layer between XFlowSDK and consuming app/framework integration. It is under evaluation for reduction or removal.
+
+---
+
+## Durable Context
+
+- Historical release work often required bumping XFlowViewMaker alongside XFlowSDK before consumer validation was possible.
+- XFlowViewMaker was a recurring source of coupling between XFlow changes and Fid4 or flagship rollout.
+- Historical Slack evidence shows that version bumps through XFlowViewMaker were often blocked by external pipeline or dependency issues rather than pure feature regressions.
+
+---
+
+## Integration Implications
+
+- When a fix exists in XFlowSDK but is not visible in consumer validation, check whether XFlowViewMaker or downstream pinned versions are blocking adoption.
+- If the issue involves version propagation into Fid4, treat XFlowViewMaker as part of the release path unless direct-consumption work has replaced it.
+- Questions about removing or collapsing the layer should be evaluated against current consumer integration patterns, not just local SDK behavior.
+
+---
+
+## Historical Signals From Slack
+
+- XFlowViewMaker version bumps into flagship frequently surfaced `PreviewMacros.SwiftUI`, Apex, or pipeline compatibility issues.
+- Historical context shows growing pressure to reduce XFlowViewMaker-specific indirection and move toward simpler consumer paths.
+- Slack history also shows that tutorials and release steps around XFlowViewMaker were easy to misunderstand, which made version propagation a repeated risk.