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

ai/context/workstreams/ao-discourse.md

@@ -0,0 +1,33 @@
+# AO And Discourse Issues
+
+## Goal
+
+Handle externally reported issues without misclassifying scope or over-claiming regression.
+
+---
+
+## Stable Patterns
+
+- AO and Discourse reports are often incomplete or partially reproducible.
+- External reports should be treated as external behavior until verified.
+- Many issues only reproduce with authenticated users or in consumer-specific contexts.
+- Some historical reports turned out to be service/configuration issues, environment issues, or existing behavior rather than new regressions.
+
+---
+
+## Investigation Rules
+
+- Always clarify:
+  - authenticated vs non-authenticated
+  - reproducibility
+  - entry point
+  - whether the issue exists in main
+  - whether the behavior is external, existing, or regression
+- Do not use vague comparison phrases like "same behavior" without scope.
+
+---
+
+## Historical Signals From Slack
+
+- Historical reports around button visibility, analytics, slot updates, and consumer validation repeatedly required deeper reproduction work before scoping a fix.
+- Slack history shows multiple examples where the original ticket or report was not enough to define the real root cause.

ai/context/workstreams/consumer-integration.md

@@ -0,0 +1,36 @@
+# Consumer Integration And Release
+
+## Goal
+
+Capture the durable release and validation path between XFlow changes and real consumer behavior.
+
+---
+
+## Stable Patterns
+
+- End-to-end validation often requires more than an SDK change.
+- Historical Slack evidence shows repeated coupling across:
+  - XFlowSDK
+  - XFlowViewMaker
+  - FTFrameworks modules
+  - Fid4 / flagship
+- Version pins, publishing delays, and consumer build issues can block validation even when the original code change is ready.
+
+---
+
+## Investigation Rules
+
+- Before concluding a fix is absent in Fid4, check whether the right version actually propagated downstream.
+- Separate these failure modes:
+  - SDK bug
+  - adapter/version propagation issue
+  - FT module publish/test issue
+  - consumer app setup or pipeline issue
+- Consumer validation constraints should shape story scope and estimates because they can dominate the real effort.
+
+---
+
+## Historical Signals From Slack
+
+- Version bump work repeatedly involved XFlowViewMaker, FTAccountOpen, and FTTransfer.
+- Some rollout problems involved Jenkins, Apex/ApexKit, preview macro compatibility, or secret/token access rather than the product behavior under investigation.

ai/context/workstreams/index.md

@@ -0,0 +1,26 @@
+# Workstreams Index
+
+## Active Durable Workstreams
+
+- [rest-migration.md](./rest-migration.md)
+  GraphQL deprecation and REST rollout constraints.
+
+- [ao-discourse.md](./ao-discourse.md)
+  External issue intake, ambiguity, and authenticated-only reproduction patterns.
+
+- [xflow-debugging.md](./xflow-debugging.md)
+  How to reason about backend-driven flows and dynamic behavior.
+
+- [xflow-swiftui-migration.md](./xflow-swiftui-migration.md)
+  Historical SwiftUI transition themes that still shape XFlow work.
+
+- [consumer-integration.md](./consumer-integration.md)
+  Release and validation coupling across XFlow, XFlowViewMaker, FT modules, and Fid4.
+
+---
+
+## Guidance
+
+- Open `ao-discourse.md` before classifying external bug reports.
+- Open `xflow-debugging.md` for reproduction and investigation framing.
+- Open `consumer-integration.md` when the work depends on release propagation or validation in consumer apps.

ai/context/workstreams/rest-migration.md

@@ -0,0 +1,32 @@
+# REST Migration
+
+## Goal
+
+Deprecate GraphQL and Apollo safely while preserving behavior through REST-backed flows.
+
+---
+
+## Stable Constraints
+
+- REST is behind a feature flag.
+- GraphQL remains the default fallback unless confirmed otherwise.
+- REST should never be assumed active by default.
+- Migration work must preserve behavior parity before removing Apollo-related code.
+
+---
+
+## What Matters In Practice
+
+- Validation must clarify whether the tested path is actually using REST or still falling back to GraphQL.
+- Story scope should distinguish:
+  - transport migration work
+  - feature-flag cleanup
+  - tests and mocks tied to Apollo/GraphQL
+- Communication should avoid implying the migration is complete before the fallback path is removed.
+
+---
+
+## Historical Signals From Slack
+
+- Historical Slack evidence around release and dependency work reinforces that transport or dependency changes often require consumer validation, not just local SDK changes.
+- Some dependency and pipeline issues complicated migration-related rollout even when the technical change itself was understood.

ai/context/workstreams/xflow-debugging.md

@@ -0,0 +1,37 @@
+# XFlow Debugging
+
+## Goal
+
+Debug backend-driven flows without losing track of dynamic dependencies or misclassifying integration behavior.
+
+---
+
+## Stable Patterns
+
+- XFlow screens are backend-driven, so UI can change without local code changes.
+- Reproduction depends on:
+  - entry point
+  - authentication state
+  - backend configuration
+  - consumer integration path
+- Not all entry points are reachable from visible UI; some require exploratory validation.
+
+---
+
+## Investigation Rules
+
+- Confirm the entry point before comparing behavior.
+- Separate service-driven behavior from client regressions.
+- Confirm whether the issue reproduces in:
+  - sample app
+  - XFlow-only environment
+  - Fid4 / flagship
+  - authenticated vs non-authenticated state
+- If a fix appears correct in the SDK but not in consumer validation, inspect the release chain before reopening root cause assumptions.
+
+---
+
+## Historical Signals From Slack
+
+- Historical debugging covered Next-button visibility, markdown modal analytics, modal presentation, slot updates, and SwiftUI lifecycle behavior.
+- Multiple pipeline or dependency problems looked like XFlow issues until the build chain or consumer integration path was inspected more carefully.

ai/context/workstreams/xflow-swiftui-migration.md

@@ -0,0 +1,35 @@
+# XFlow SwiftUI Migration
+
+## Goal
+
+Track the durable behavior patterns introduced while moving XFlow from older assumptions toward a more complete SwiftUI implementation.
+
+---
+
+## Stable Themes
+
+- SwiftUI migration was not just a UI rewrite; it exposed contract, lifecycle, and parity gaps.
+- Historical Slack evidence repeatedly referenced:
+  - component type expansion beyond simple string assumptions
+  - Next-button visibility rules driven by full service parameters
+  - markdown link handling and analytics integration
+  - navigation and modal behavior in pure SwiftUI environments
+  - dismissal delegate lifecycle sequencing
+
+---
+
+## What Matters Now
+
+- When a SwiftUI issue appears, check whether the missing behavior is:
+  - parity with UIKit behavior
+  - an incomplete service contract interpretation
+  - a lifecycle sequencing problem
+  - a consumer presentation constraint in Fid4
+- Do not assume a visual issue is only cosmetic; several historical SwiftUI bugs changed flow behavior materially.
+
+---
+
+## Historical Signals From Slack
+
+- Jeff and Norman repeatedly refined story titles and descriptions around SwiftUI architecture changes, showing that scope wording mattered because the work was often deeper than the first symptom.
+- Historical Slack context also shows that SwiftUI-specific work frequently required cross-team clarification when external dependencies or consumer environments behaved differently.