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

ai/context/index.md

@@ -0,0 +1,60 @@
+# Context Index
+
+## Goal
+
+Keep stable Fidelity context organized by domain so the agent can load the right information quickly.
+
+---
+
+## Structure
+
+### `project.md`
+
+High-level overview of the workspace, current Fidelity scope, and where durable context lives.
+
+### `systems/`
+
+Stable context about core product components and how they relate:
+
+- [systems/fid4.md](./systems/fid4.md)
+- [systems/xflowsdk.md](./systems/xflowsdk.md)
+- [systems/xflowviewmaker.md](./systems/xflowviewmaker.md)
+- [systems/ftframeworks.md](./systems/ftframeworks.md)
+
+### `workstreams/`
+
+Durable context about recurring streams of work and investigation:
+
+- [workstreams/rest-migration.md](./workstreams/rest-migration.md)
+- [workstreams/ao-discourse.md](./workstreams/ao-discourse.md)
+- [workstreams/xflow-debugging.md](./workstreams/xflow-debugging.md)
+- [workstreams/xflow-swiftui-migration.md](./workstreams/xflow-swiftui-migration.md)
+- [workstreams/consumer-integration.md](./workstreams/consumer-integration.md)
+
+### `process/`
+
+Rules and expectations for how work should be communicated and maintained:
+
+- [process/communication.md](./process/communication.md)
+- [process/jira-story-rules.md](./process/jira-story-rules.md)
+- [process/context-maintenance.md](./process/context-maintenance.md)
+
+### `people/`
+
+Named people, role mapping, and collaboration context:
+
+- [people/index.md](./people/index.md)
+- [people/manager.md](./people/manager.md)
+
+### `decisions/`
+
+Confirmed technical or product decisions with ongoing impact.
+
+---
+
+## Usage
+
+- Load `project.md` and this index first.
+- Open `systems/` when the question is about architecture, ownership, or integration.
+- Open `workstreams/` when the question is about current priorities, debugging themes, or historical project patterns.
+- Open `process/` when drafting messages, standups, Jira notes, or deciding how to update memory.

ai/context/process/communication.md

@@ -0,0 +1,35 @@
+# Communication Rules
+
+## Goal
+
+Make technical communication precise enough for manager updates, Jira notes, standups, and cross-team messages.
+
+---
+
+## Required Structure
+
+When the format fits, prefer:
+
+1. Context
+2. Observation
+3. Action
+
+---
+
+## Fidelity-Specific Rules
+
+- Always clarify authenticated vs non-authenticated when behavior depends on it.
+- Always separate external issues from regressions.
+- Always state reproducibility and scope.
+- Avoid vague phrasing such as:
+  - "same behavior"
+  - "looks fixed"
+  - "working as expected"
+
+---
+
+## Historical Signals From Slack
+
+- Jeff repeatedly requested polished, explicit wording for PR descriptions, story descriptions, and cross-team messages.
+- Historical Slack threads show that message quality changed how quickly stories were approved or understood.
+- Explicit language mattered most when communicating root cause, ownership boundaries, or whether a report was a confirmed regression.

ai/context/process/context-maintenance.md

@@ -0,0 +1,33 @@
+# Context Maintenance
+
+## Goal
+
+Keep this workspace useful as living memory instead of a pile of disconnected notes.
+
+---
+
+## Stable Rules
+
+- Update canonical context when a durable fact changes.
+- Prefer correcting stale context over appending contradictory notes.
+- Use the smallest correct destination:
+  - `ai/logs/YYYY-MM-DD.md` for daily progress and evolving findings
+  - `ai/state/current.md` for near-term active work
+  - `ai/state/work-items.md` for Jira-linked active work
+  - `ai/context/` for durable project knowledge
+  - `ai/context/people/` for named person context
+
+---
+
+## Ingestion Rules
+
+- Treat Mattermost, Slack history, and direct prompts as potential memory sources.
+- Do not promote failed syncs or tooling errors as project facts.
+- Promote repeated durable patterns from historical archives into stable context when confidence is high.
+- Keep old status-only details archive-only unless they still change current understanding.
+
+---
+
+## Curation Rule
+
+- If a new stable context file is added, keep `project.md` and `index.md` aligned so future sessions can discover it quickly.

ai/context/process/index.md

@@ -0,0 +1,12 @@
+# Process Index
+
+## Stable Process Guides
+
+- [communication.md](./communication.md)
+  How to frame technical updates and external communication.
+
+- [jira-story-rules.md](./jira-story-rules.md)
+  How to create or reference stories with the right scope and precision.
+
+- [context-maintenance.md](./context-maintenance.md)
+  How this workspace should be kept current as living memory.

ai/context/process/jira-story-rules.md

@@ -0,0 +1,30 @@
+# Jira Story Rules
+
+## Goal
+
+Keep Jira updates precise enough that the story reflects the real problem and remains easy to reference later.
+
+---
+
+## Stable Rules
+
+- Preserve Jira ID and explicit title whenever available.
+- Prefer story wording that describes the real contract or behavior gap, not only the first symptom.
+- Include authenticated-state or environment qualifiers when they materially affect scope.
+- Validate consumer behavior before finalizing scope when the issue depends on Fid4 or flagship.
+
+---
+
+## Story-Creation Guidance
+
+- Create or refine the story after the reproduction path is understood well enough to avoid mis-scoping.
+- Include points and scope only after the work has been framed clearly.
+- If the issue crosses SDK, adapter, FT modules, and consumer app boundaries, the story should say so.
+- If a bug is external or not yet confirmed as regression, avoid writing the ticket as if the root cause is already proven.
+
+---
+
+## Historical Signals From Slack
+
+- Historical Slack threads repeatedly show Jeff refining titles and descriptions before stories were created or shared.
+- Several story discussions centered on making the wording reflect deeper SwiftUI, lifecycle, or integration issues rather than surface symptoms alone.

ai/context/project.md

@@ -17,81 +17,47 @@ The product work happens outside this repository, usually from another machine.
 
 ---
 
-## Current Priorities
+## Stable Context Map
 
-### REST migration
+- Core systems live under:
+  - `ai/context/systems/`
+- Durable workstreams live under:
+  - `ai/context/workstreams/`
+- Stable communication and maintenance rules live under:
+  - `ai/context/process/`
+- Named people and role mapping live under:
+  - `ai/context/people/`
 
-- REST is behind a feature flag
-- GraphQL is still the default fallback
-- REST should never be assumed active unless confirmed
-- Migration must preserve behavior while Apollo is deprecated safely
-
-### Discourse and AO issues
-
-- External reports are often incomplete
-- Many reported issues are not confirmed regressions
-- Some issues reproduce only with authenticated users
-
-### Flow debugging
-
-- XFlow behavior changes based on backend configuration
-- Entry point affects what the user sees
-- Authentication state affects reproducibility
-
-### Testing complexity
-
-- Around 15 entry points have been identified at code level
-- Not all entry points are reachable from visible UI
-- Validation often requires exploratory testing
-
-## Historical Slack patterns
-
-- XFlow SwiftUI migration discussions repeatedly covered Next-button visibility, markdown modal presentation, and custom nav pin/unpin behavior
-- Some historical pipeline failures were traced to Apex/ApexKit or Swift preview macro support in the consuming pipeline, not just XFlow itself
-- Jeff often requested explicit, polished wording for PR descriptions and cross-team messages
-- Historical discussions also surfaced recurring uncertainty around XFlow ownership boundaries versus consumer-app responsibility
-- Cross-team dependency issues sometimes involved security, token access, or external pipeline configuration rather than only iOS code changes
-- Historical AO and consumer bugs often turned out to be service/configuration issues, incomplete reproduction reports, or consuming-app integration issues rather than XFlow regressions
-- Historical integration work repeatedly involved XFlowViewMaker, FTBusiness, FTFrameworks, and Fid4 release/version coupling, especially when validating fixes in real consumer flows
+The Slack archive has already been curated into those files so the agent does not need to rediscover the same patterns from raw history every session.
 
 ---
 
-## How This Workspace Is Used
+## Current Priorities
+
+- REST migration is replacing GraphQL over time, but REST is still behind a feature flag
+- AO and Discourse issues require careful classification because many are incomplete, external, or auth-dependent
+- XFlow debugging remains dynamic because behavior changes by entry point, authentication state, backend configuration, and consumer integration
+- Consumer validation often depends on Fid4, FT modules, and version propagation, not just SDK behavior
+
+---
+
+## Workspace Use
 
 This machine is used to:
 
 - maintain current project context
 - record findings from work performed elsewhere
-- capture Mattermost communication that changes understanding
+- capture communication that changes technical understanding
 - prepare polished updates for the current manager or stakeholder
 - generate standups with better context coverage
 
-This means logs must capture both technical findings and communication context.
+This means the context files should hold durable engineering knowledge, while `ai/logs/` and `ai/state/` hold the moving day-to-day view.
 
 ---
 
-## People Context
+## First Files To Read
 
-- The current manager role is mapped in `ai/context/people/manager.md`
-- The active people roster lives in `ai/context/people/index.md`
-- Repeatedly relevant named people should have individual files under `ai/context/people/`
-
----
-
-## Communication Expectations
-
-All important updates should clarify:
-
-- whether the flow is authenticated or non-authenticated
-- whether the issue is reproducible
-- whether the report is external behavior or regression
-- whether behavior is present in main
-- what action is needed next
-
-Avoid phrases that hide scope, such as:
-
-- "same behavior"
-- "looks fixed"
-- "working as expected"
-
-Use explicit framing instead.
+- `ai/context/index.md`
+- `ai/context/workstreams/index.md`
+- `ai/context/process/communication.md`
+- `ai/context/people/index.md`

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.

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.