Add daily logs and templates for Fidelity project

- Created daily log entries for April 13-16, 2026, capturing standup contexts, Mattermost syncs, and ongoing work items.
- Established a daily logs index for easy navigation of daily entries.
- Introduced templates for daily notes, decisions, meeting notes, people, systems, and work items to standardize documentation.
- Developed maps for AI workspace core, current work, Fidelity domain, and work items to enhance workspace navigation.
- Implemented base configurations for daily notes, decisions, people, systems, work items, and workstreams to streamline data management.
- Added a placeholder for attachments to facilitate file organization.

vault/03-context/index.md

@@ -0,0 +1,78 @@
+---
+type: context-index
+project: fidelity
+updated: 2026-04-16
+tags:
+  - context
+  - map
+---
+# 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)
+
+### `ios/`
+
+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)
+
+### `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)
+- [workstreams/flow-page-references.md](./workstreams/flow-page-references.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 `ios/` when the question is about Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging.
+- 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.

vault/03-context/ios/current-practices.md

@@ -0,0 +1,71 @@
+---
+type: guidance
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - ios
+  - fidelity
+---
+# Current iOS And Swift Practices
+
+## Goal
+
+Keep Swift/iOS answers modern without turning the workspace into stale API documentation.
+
+---
+
+## Currentness Rule
+
+For version-sensitive recommendations, verify against official sources before presenting as current best practice.
+
+Prefer:
+
+- Apple Developer Documentation
+- Swift.org / docs.swift.org
+- official WWDC materials when API behavior or migration guidance matters
+
+Avoid relying only on memory for:
+
+- newest SwiftUI APIs
+- Observation / data-flow migration guidance
+- Swift Testing availability or migration advice
+- Swift concurrency behavior
+- Xcode or iOS version-specific recommendations
+
+---
+
+## Stable Defaults
+
+- Prefer simple, testable Swift over clever abstractions.
+- Prefer structured concurrency over ad-hoc callback or detached-task patterns when the deployment target and codebase support it.
+- Keep UI state changes on the main actor.
+- Avoid recommending new APIs until deployment target and project constraints are known.
+- For SwiftUI, separate pure view composition from side effects and navigation/workflow coordination.
+- For testing, use the framework already adopted by the codebase unless the user explicitly asks about migration.
+
+---
+
+## Testing Guidance
+
+- Apple positions Swift Testing as a modern option for unit tests in Xcode 16 and later.
+- XCTest remains relevant, especially for UI tests, performance tests, and existing test suites.
+- Do not recommend wholesale migration from XCTest unless the project constraints support it.
+
+---
+
+## SwiftUI Guidance
+
+- Observation can be adopted incrementally; do not assume a project can immediately replace all `ObservableObject` usage.
+- In SwiftUI code review, focus on data ownership, lifecycle, invalidation scope, navigation boundaries, and side effects.
+- Avoid introducing `@StateObject`, `@ObservedObject`, `@State`, or `@Observable` recommendations without first identifying ownership and deployment constraints.
+
+---
+
+## Source Anchors
+
+- SwiftUI documentation: `https://developer.apple.com/documentation/swiftui`
+- Observation migration: `https://developer.apple.com/documentation/swiftui/migrating-from-the-observable-object-protocol-to-the-observable-macro`
+- Swift Testing: `https://developer.apple.com/documentation/testing`
+- XCTest: `https://developer.apple.com/documentation/xctest`
+- Swift language: `https://developer.apple.com/swift/`

vault/03-context/ios/index.md

@@ -0,0 +1,32 @@
+---
+type: guidance-index
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - ios
+  - fidelity
+---
+# iOS And Swift Context
+
+## Goal
+
+Help the agent answer Swift and iOS programming questions with current best practices while still respecting Fidelity/XFlow project constraints.
+
+---
+
+## Files
+
+- [current-practices.md](./current-practices.md)
+  Rules for staying current with Apple and Swift best practices.
+
+- [project-swift-guidance.md](./project-swift-guidance.md)
+  Fidelity-specific guidance for applying Swift/iOS advice in this workspace.
+
+---
+
+## Usage
+
+- Use these files before answering Swift, SwiftUI, iOS architecture, testing, concurrency, or debugging questions.
+- 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

@@ -0,0 +1,46 @@
+---
+type: guidance
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - ios
+  - fidelity
+---
+# Project Swift Guidance
+
+## Goal
+
+Apply Swift/iOS advice in a way that fits Fidelity's XFlow, Fid4, XFlowViewMaker, and FTFrameworks environment.
+
+---
+
+## Fidelity-Specific Constraints
+
+- 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.
+- REST migration constraints still matter; do not assume REST is active by default.
+- Some work happens behind feature flags, especially risky consumer-impact changes.
+
+---
+
+## SwiftUI / XFlow Priorities
+
+- Treat modal presentation, dismissal sequencing, and lifecycle boundaries as high-risk areas.
+- Be careful when removing UIKit bridges such as `UIHostingController`; preserve consumer behavior and rollout safety.
+- When discussing SwiftUI architecture, include how the change affects:
+  - backend-driven flow rendering
+  - consumer app integration
+  - feature flags
+  - validation in Fid4
+  - UIKit/SwiftUI parity
+
+---
+
+## Answering Rules
+
+- 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.
+- For manager-ready explanations, connect the technical recommendation to scope, risk, and validation.

vault/03-context/process/agent-memory-rules.md

@@ -0,0 +1,182 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags: [process, memory, agent]
+---
+
+# Agent Memory Rules
+
+## Goal
+
+Make workspace memory maintenance part of the agent's normal job, not a separate optional workflow.
+
+---
+
+## Default Agent Behavior
+
+For any meaningful prompt, the agent should decide whether the interaction changes project memory.
+
+This applies to:
+
+- direct user prompts
+- Mattermost sync results
+- translated notes
+- standup generation
+- manager-update drafting
+- debugging discussions
+- corrections to previous understanding
+
+The agent should not wait for a separate promotion command when the right update is already clear.
+
+---
+
+## What Counts As Memory-Worthy
+
+Capture information automatically when it is:
+
+- project-relevant
+- explicit enough to preserve safely
+- likely to matter in a future session
+- useful for standups, debugging, or supervisor communication
+
+Examples:
+
+- confirmed story creation, points, scope, or priority
+- confirmed reproduction constraints
+- newly clarified root cause framing
+- approved manager guidance that changes work direction
+- confirmed version, dependency, or rollout facts tied to current work
+- corrections to previously stored project context
+- repeated named people with stable roles or communication relevance
+- repeated named people with multi-channel, multi-year, or high-signal technical/process involvement even when the exact formal role is still unknown
+
+---
+
+## What The Agent Must Do
+
+When new memory-worthy information appears, the agent should:
+
+1. decide whether it is daily, current-state, durable, or decision-level context
+2. update the smallest correct set of files
+3. correct stale or conflicting existing statements
+4. answer the user using the refreshed context
+
+Do not ask the user what to promote unless the ambiguity is real and material.
+
+---
+
+## Tooling Self-Maintenance
+
+User corrections about how the workspace should behave are memory-worthy when they affect future output.
+
+If a correction applies to a command, prompt, skill, agent, or reusable rule, update the linked tool directly instead of only logging the correction.
+
+Examples:
+
+- A standup formatting correction should update `prompts/standup.md` and `.opencode/commands/standup.md`.
+- A Mattermost freshness correction should update the Mattermost command/plugin instructions.
+- A Copilot prompt-structure correction should update `prompts/copilot-prompt.md`, `.opencode/commands/copilot-prompt.md`, or the Copilot skill.
+- A Swift answer-quality correction should update the relevant iOS skill or `vault/03-context/ios/` guidance.
+
+Keep the daily log as evidence of what happened, but make the reusable behavior live in the file that controls that behavior.
+
+---
+
+## File Selection
+
+### `vault/06-daily/YYYY-MM-DD.md`
+
+Default destination for:
+
+- same-day progress
+- same-day findings
+- scoped reproduction notes
+- story and approval movement
+- context that is important now but may evolve later
+
+### `vault/01-current/current-work.md`
+
+Use when the fact changes the active work window, including:
+
+- current priorities
+- currently active story scope
+- current blockers or debugging constraints
+- manager direction that changes the next few days of work
+
+### `vault/02-work-items/*.md` and `vault/01-current/work-items.md`
+
+Use `vault/02-work-items/*.md` as the canonical memory for current Jira-linked work that should remain easy to reference across sessions, especially:
+
+- Jira IDs
+- approved or explicit titles
+- currently relevant status notes
+- current points or scope notes
+
+Use `vault/01-current/work-items.md` as the summary view of what is active now.
+
+These files should help standups and manager updates mention work items precisely.
+
+### `vault/03-context/project.md`
+
+Use for durable project knowledge that should survive beyond the current work window.
+
+### `vault/04-people/manager.md`
+
+Use only when a communication preference or manager expectation becomes stable enough to reuse repeatedly.
+
+### `vault/04-people/index.md` and `vault/04-people/*.md`
+
+Use these files for:
+
+- mapping roles to actual people
+- keeping named stakeholders recognizable across sessions
+- storing stable communication or responsibility context per person
+
+When the role is not explicit, store:
+
+- where the person tends to appear
+- what kinds of topics they influence
+- how they affect approvals, scope, debugging, or communication
+
+### `vault/05-decisions/*.md`
+
+Use for explicit confirmed decisions with ongoing impact.
+
+### `.opencode/commands/`, `prompts/`, `.opencode/agents/`, `.opencode/skills/`, `vault/00-start/`, and `vault/03-context/process/`
+
+Use these when the new information changes how the workspace should operate:
+
+- command invocation behavior
+- reusable output format
+- default agent behavior
+- specialized skill workflow
+- persistent process or memory rules
+
+Do not create a separate note when an existing command, prompt, agent, or skill is the source of truth.
+
+---
+
+## What Not To Store
+
+Do not store:
+
+- tool failures
+- sync attempts
+- generic urgency messages
+- duplicate paraphrases of the same fact
+- weak guesses
+- operational chatter that does not change project understanding
+
+---
+
+## Correction Rule
+
+If new information supersedes old memory:
+
+- update the existing canonical file
+- do not leave stale and corrected versions side by side
+- preserve qualifiers if the fact is only partially confirmed
+
+The agent should behave like a senior engineer maintaining project notes, not like a chat assistant accumulating transcripts.

vault/03-context/process/ai-to-ai-prompting.md

@@ -0,0 +1,78 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# AI-To-AI Prompting
+
+## Goal
+
+Generate prompts that can be sent to another AI assistant on the Fidelity development machine, especially GitHub Copilot.
+
+---
+
+## Operating Assumption
+
+This workspace does not contain the product codebase. The target AI has access to the Fidelity codebase on another machine.
+
+Therefore prompts must:
+
+- include only the relevant project context from this workspace
+- tell the target AI what files/modules to inspect
+- ask for a concrete output
+- specify constraints and non-goals
+- avoid pretending the target AI already has this workspace memory
+
+---
+
+## Prompt Structure
+
+Use this structure by default:
+
+1. Role
+2. Project context
+3. Current task
+4. Relevant ticket/context
+5. Files/modules to inspect
+6. Constraints
+7. Expected output
+8. Validation requirements
+
+---
+
+## Prompt Quality Rules
+
+- Prefer precise task framing over long background dumps.
+- Include Jira ID and title when the work maps to a ticket.
+- Include current constraints such as REST feature flag, GraphQL fallback, auth state, backend-driven behavior, and consumer validation when relevant.
+- Ask the target AI to inspect code before proposing changes.
+- Ask for a plan first when the implementation scope is uncertain.
+- Ask for code changes only when the desired write scope is clear.
+- Include "Do not assume REST is active by default" for REST migration tasks.
+- Include "Separate external issue from regression" for AO/Discourse issues.
+- Include "Validate against Fid4/consumer path when needed" for XFlow integration tasks.
+
+---
+
+## Bad Prompt Pattern
+
+"Fix this issue in XFlow."
+
+Why bad:
+
+- no entry point
+- no auth state
+- no expected behavior
+- no ticket context
+- no validation path
+- no scope boundary
+
+---
+
+## Good Prompt Pattern
+
+"You are working in the Fidelity iOS codebase. Inspect the XFlowSDK and XFlowViewMaker integration path for `PDIAP-14859 - Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation`. First identify where XFlow currently exposes SwiftUI through `UIHostingController`, where XFlowViewMaker consumes it, and what feature flag protects the migration path. Do not change code yet. Return a concise plan with affected files, risks, consumer validation needs in Fid4/FTTransfer, and any questions that block implementation."

vault/03-context/process/communication-rules.md

@@ -0,0 +1,65 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags: [process, communication]
+---
+
+# Communication Rules
+
+## Purpose
+
+These rules keep standups, Jira notes, and Mattermost messages aligned with the actual state of the work.
+
+---
+
+## Rules
+
+- Prefer explicit scope over short vague statements
+- Always mention auth state when it changes reproducibility
+- Separate external report from regression
+- Say whether behavior was confirmed in main when that comparison exists
+- End with the next action when writing status updates
+- Distinguish clearly between the current issue, unrelated preexisting bugs, workarounds, and follow-up work
+- Prefer evidence-backed statements over intuition when communicating status
+- Include branch, build, environment, account, flow, or entry-point details when they materially affect reproduction or ownership
+- When reporting several updates for the same Jira item, group them under one top-level `JIRA-ID - Title` bullet with indented markdown sub-bullets
+- Use real flow identifiers and page names when shorthand could be ambiguous
+- Route ownership explicitly when the issue belongs to a consumer app, service/configuration, or another framework instead of XFlow
+- Do not present a fix as ready if it introduces a new bug or unresolved regression
+- Administrative/project-tracking updates should be prompt when others are visibly waiting on them
+
+---
+
+## English Quality Rules
+
+- Write in natural, professional US English that sounds like a fluent engineer wrote it
+- Prefer direct phrasing over literal or translated-sounding wording
+- Avoid unnecessary softeners or filler such as "actually," "I think" or "for now" unless they add real scope or uncertainty
+- If the message was originally rough or written by a non-native speaker, rewrite it fully instead of preserving awkward phrasing
+- If a sentence can be misunderstood by a manager, stakeholder, or consumer team, rewrite it before sending
+
+---
+
+## Repeated Senior Communication Lessons
+
+- Test in the closest real consumer environment first when consumer-specific behavior is under investigation, but use the sample app to rule ownership in or out quickly
+- Before escalating or concluding root cause, reduce uncertainty with available evidence: screenshots, videos, logs, code comparison, version checks, and parity checks across web/UIKit/SwiftUI/Fid4
+- Keep one issue per update unless a second issue is explicitly called out as separate scope
+- If blocked, communicate what was tried, what was ruled out, and the exact remaining question
+- Use Context, Observation, Action framing when possible so status is easy to forward without rewriting
+
+---
+
+## Avoid
+
+- "same behavior"
+- "looks good"
+- "seems fixed"
+- "working now"
+- "it should be fine"
+- "for some reason"
+- "I think it's fixed" when evidence exists or is needed
+
+Use concrete statements instead.

vault/03-context/process/communication.md

@@ -0,0 +1,49 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# 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.
+- For standups, report the previous workday context, not blindly the prior calendar day.
+- On Mondays, use Friday's work context unless a later prior day has Mattermost activity.
+- If the previous calendar day has no project activity because of weekend, holiday, or OOO, use the latest prior day with Mattermost activity.
+- For standups, when a Jira item has multiple concrete updates, use one top-level `JIRA-ID - Title` bullet and indented markdown sub-bullets instead of repeating the same Jira line.
+- When a flow/page shorthand could be ambiguous, prefer the real flow identifier and page name from `vault/03-context/workstreams/flow-page-references.md`.
+- 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.

vault/03-context/process/context-maintenance.md

@@ -0,0 +1,46 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# 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:
+  - `vault/06-daily/YYYY-MM-DD.md` for daily progress and evolving findings
+  - `vault/01-current/current-work.md` for near-term active work
+  - `vault/02-work-items/*.md` for canonical Jira-linked active work
+  - `vault/01-current/work-items.md` for the compact active-work summary
+  - `vault/03-context/` for durable project knowledge
+  - `vault/04-people/` for named person context
+  - `.opencode/commands/`, `prompts/`, `.opencode/agents/`, `.opencode/skills/`, `vault/00-start/`, or `vault/03-context/process/` for reusable behavior rules that control how the workspace responds
+
+---
+
+## 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.
+- Treat user corrections about command output, prompt structure, memory handling, or agent behavior as inputs to the operational surface, not just as daily notes.
+
+---
+
+## Curation Rule
+
+- If a new stable context file is added, keep `project.md` and `index.md` aligned so future sessions can discover it quickly.
+- If a new rule affects a slash command or reusable prompt, update that command or prompt directly so the behavior changes on the next run.

vault/03-context/process/index.md

@@ -0,0 +1,39 @@
+---
+type: process-index
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# Process Index
+
+## Stable Process Guides
+
+- [communication.md](./communication.md)
+  How to frame technical updates and external communication.
+
+- [ai-to-ai-prompting.md](./ai-to-ai-prompting.md)
+  How to generate prompts for GitHub Copilot or another AI on the Fidelity development machine.
+
+- [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.
+
+- [workspace-model.md](./workspace-model.md)
+  How the companion AI workspace separates runtime, evidence, and canonical memory.
+
+- [agent-memory-rules.md](./agent-memory-rules.md)
+  Default memory-maintenance behavior for agents.
+
+- [memory-promotion-rules.md](./memory-promotion-rules.md)
+  How evidence becomes daily, current, work-item, stable-context, people, or decision memory.
+
+- [communication-rules.md](./communication-rules.md)
+  Reusable communication standards for standups, Jira, and stakeholder updates.
+
+- [pull-requests.md](./pull-requests.md)
+  PR template and framing notes for repositories such as `xflow-for-ios`.

vault/03-context/process/jira-story-rules.md

@@ -0,0 +1,39 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# 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.

vault/03-context/process/memory-promotion-rules.md

@@ -0,0 +1,146 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags: [process, memory, promotion]
+---
+
+# Memory Promotion Rules
+
+## Goal
+
+Keep workspace memory current automatically without asking the user what to promote after every successful sync.
+
+---
+
+## Default Rule
+
+When new Mattermost context is explicit, project-relevant, and high-confidence, promote it automatically.
+
+Do not ask for promotion confirmation by default.
+
+If a fact is ambiguous, skip it or keep it only in the daily log with appropriate qualifiers.
+
+---
+
+## File Selection
+
+### Promote to `vault/06-daily/YYYY-MM-DD.md`
+
+Use the daily log for:
+
+- concrete same-day work updates
+- story creation, sizing, approval, and scope updates
+- manager-approved wording or root-cause framing tied to current work
+- confirmed version checks tied to active work
+- reproduction findings that are useful now but may still evolve
+
+Daily logs are the default destination for most promoted Mattermost facts.
+
+### Promote to `vault/01-current/current-work.md`
+
+Use current state only for facts that materially affect active work over the next few days, such as:
+
+- approved active story scope
+- confirmed current debugging constraints
+- current reproduction conditions that change how the work is approached
+- near-term priorities confirmed by manager communication
+
+Do not copy every daily update into current state.
+
+### Promote to `vault/02-work-items/*.md` and `vault/01-current/work-items.md`
+
+Use `vault/02-work-items/*.md` for:
+
+- explicit Jira IDs
+- approved or explicit story titles
+- current story points
+- current scope notes
+- active status notes that still matter for future updates
+
+If a Jira item is likely to appear again in standups or manager updates, it belongs here.
+
+Use `vault/01-current/work-items.md` as the compact summary of which ticket files are active.
+
+### Promote to `vault/03-context/project.md`
+
+Use project context only for durable project knowledge that should survive beyond the current work window, such as:
+
+- stable architecture constraints
+- recurring debugging truths
+- persistent testing limitations
+- enduring behavior of REST, GraphQL, XFlow, auth, or entry points
+
+Do not promote story-specific daily movement into project context unless it changes durable project understanding.
+
+### Promote to `vault/05-decisions/*.md`
+
+Use decisions only for explicit confirmed decisions with medium or long-term impact.
+
+### Promote to `vault/04-people/index.md` and `vault/04-people/*.md`
+
+Use these files when:
+
+- a person's identity matters repeatedly
+- a role becomes associated with a specific person
+- a stakeholder's communication or approval patterns affect future work
+- a human appears across multiple channels or years with repeated technical, process, or approval signal
+- the archive makes the collaboration pattern clear even if the formal title is still unknown
+
+Prefer:
+
+- `manager.md` for role mapping
+- `index.md` for active roster
+- one file per person for person-specific context
+
+If exact role confidence is low, store the person's repeated project relationship instead of inventing a title.
+
+---
+
+## Do Not Promote
+
+Do not record these as project memory:
+
+- tooling activity
+- sync status
+- missing dependencies
+- empty inbox situations
+- reminders or urgency without project substance
+- unapproved drafts
+- generic chat noise
+
+---
+
+## Confidence Rules
+
+Auto-promote when the signal is high-confidence, for example:
+
+- the manager explicitly approves something
+- a Jira story number, title, points, or scope is explicitly confirmed
+- a version is stated directly and tied to the active project
+- a reproduction condition is clearly stated with scope qualifiers
+
+If confidence is mixed:
+
+- prefer the daily log
+- preserve qualifiers such as "appears", "currently", or "for authenticated users"
+- avoid promoting to stable project context
+
+---
+
+## Example Policy
+
+Given Mattermost updates like:
+
+- PDIAP-15836 created and sized at 8 points
+- the manager approved a story title
+- REST-removal scope was approved
+- XFlowViewMaker 0.5.0 is already in Fid4
+- AO DOB validation issue appears auth-only in TeenIdentityCheck
+
+Automatic behavior should be:
+
+- add all of them to today's log if they are relevant to today's work
+- promote only the currently actionable subset to `vault/01-current/current-work.md`
+- keep story-specific details out of `vault/03-context/project.md` unless they reveal a durable project rule

vault/03-context/process/pull-requests.md

@@ -0,0 +1,43 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - process
+  - fidelity
+---
+# Pull Requests
+
+## xflow-for-ios PR Template
+
+The `xflow-for-ios` repo PR form uses this structure:
+
+- `## What`
+  - What does the PR do?
+  - Is it a bug fix, new feature, refactor, or something else?
+- `## Why`
+  - Why this PR is needed?
+- `## How`
+  - How is it doing what it does?
+  - How to test, how to integrate, any relevant compromises, etc.?
+- `### Changes details`
+  - bullet list such as `Detail one`, `Detail two`
+- `## Missed anything?`
+  - checklist including:
+    - explained the purpose of the PR
+    - self-reviewed the PR
+    - added or updated test cases
+    - informed of breaking changes, testing, and migrations if applicable
+    - updated documentation if applicable
+    - attached screenshots if applicable
+    - resolved SwiftLint warnings introduced by the commit
+
+## Current Small-Fix Example
+
+For the April 15, 2026 iOS validation fallback fix, the code change is a one-line update in `XFlowViewAdapterRepresentable.swift` for `.apxDateSelect`:
+
+- before: only `validationDictionary?["validations"]`
+- after: `validationDictionary?["validations"] ?? validationDictionary?["birthDate"]`
+
+This should be framed as a small compatibility bug fix for AO-style payloads, not as a broader Android-parity refactor.

vault/03-context/process/workspace-model.md

@@ -0,0 +1,57 @@
+---
+type: process
+project: fidelity
+status: active
+updated: 2026-04-16
+tags: [process, workspace, memory]
+---
+
+# Workspace Model
+
+## Purpose
+
+This repository is a support workspace, not the implementation repository.
+
+It now has two layers:
+
+- `core/` contains reusable project-independent operating rules
+- `profiles/<project>/` contains project-specific configuration and assumptions
+
+---
+
+## What belongs here
+
+- daily logs
+- communication context
+- manager update drafts
+- stable project knowledge
+- debugging summaries
+- reusable command, prompt, skill, and agent rules that make the workspace behave consistently
+- project profiles that configure the reusable core for a specific project
+- optional navigation notes and portable Obsidian configuration
+
+---
+
+## What does not belong here
+
+- product source code
+- assumptions about code changes not yet verified
+- statements that imply work was executed from this machine unless explicitly true
+- Obsidian local layout, plugin cache, or runtime state
+
+---
+
+## Operational Surface
+
+When the user corrects a recurring behavior, the workspace should update the file that controls that behavior:
+
+- `core/` for reusable project-independent behavior
+- `profiles/<project>/` for project-specific assumptions
+- `vault/.obsidian/` only for portable vault configuration, not project memory
+- `.opencode/commands/` for slash commands
+- `prompts/` for reusable drafting templates
+- `.opencode/agents/` and `ai/AGENTS.md` for default agent behavior
+- `.opencode/skills/` for specialized workflows
+- `vault/00-start/` and `vault/03-context/process/` for durable process rules
+
+Daily logs can preserve evidence, but they should not be the only place where a reusable behavior rule lives.

vault/03-context/project.md

@@ -0,0 +1,72 @@
+---
+type: project-context
+project: fidelity
+updated: 2026-04-16
+tags:
+  - fidelity
+  - context
+---
+# Project Context - Fidelity
+
+## Overview
+
+This workspace supports daily iOS engineering work for Fidelity.
+
+The product work happens outside this repository, usually from another machine. This repository exists to preserve context, track communication, and help AI generate accurate output for standups, Mattermost messages, Jira notes, and supervisor updates.
+
+---
+
+## Fidelity Ecosystem
+
+- Fid4 is the main consumer iOS app
+- XFlowSDK powers backend-driven UI flows
+- XFlowViewMaker is an adapter layer under evaluation for removal
+- FTFrameworks contains feature modules such as FTAccountOpen and FTTransfer
+- Cogstore is the configuration publishing/version-tracking platform used to inspect which flow-definition versions are live in QA or Production
+
+---
+
+## Stable Context Map
+
+- Core systems live under:
+  - `vault/03-context/systems/`
+- Durable workstreams live under:
+  - `vault/03-context/workstreams/`
+- Stable communication and maintenance rules live under:
+  - `vault/03-context/process/`
+- Named people and role mapping live under:
+  - `vault/04-people/`
+
+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.
+
+---
+
+## 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 communication that changes technical understanding
+- prepare polished updates for the current manager or stakeholder
+- generate standups with better context coverage
+
+This means the context files should hold durable engineering knowledge, while `vault/06-daily/` and `vault/01-current/` hold the moving day-to-day view.
+
+---
+
+## First Files To Read
+
+- `vault/03-context/index.md`
+- `vault/03-context/workstreams/index.md`
+- `vault/03-context/process/communication.md`
+- `vault/04-people/index.md`

vault/03-context/systems/cogstore.md

@@ -0,0 +1,32 @@
+---
+type: system
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# Cogstore
+
+## Role
+
+Cogstore is an important Fidelity platform used to manage and publish many flow configuration definitions, each with its own independent version history.
+
+---
+
+## Confirmed Context
+
+- In the Fidelity flow-config workflow, Cogstore is used to modify and publish individual flow definitions.
+- Cogstore tracks versions per flow definition rather than as one single platform-wide version.
+- Cogstore can be used to compare changes between flow-definition versions, similar to a Git-style diff.
+- Cogstore can be used to check which version of a specific flow definition is published in environments such as QA and Production, including who published it and when.
+- On April 16, 2026, David used Cogstore to confirm that the relevant flow-definition change tied to Rashmi's service-side update was present in QA as version `0.0.142`, while Production was still on `0.0.133`.
+
+---
+
+## Related Context
+
+- Jeff indicated on April 15, 2026 that Slate had been used by newer consumer services during the SwiftUI refactor, but is now believed to be decommissioned.
+- Because service/configuration changes can be environment-specific and versioned per flow, Cogstore should be checked before concluding that a payload/config change is live in Production.
+- Flow IDs are not guaranteed to exist in both Cogstore and Slate. When tracing a specific flow definition, confirm which configuration system actually owns that flow instead of assuming the same ID will appear in both places.

vault/03-context/systems/fid4.md

@@ -0,0 +1,39 @@
+---
+type: system
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# 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.

vault/03-context/systems/ftframeworks.md

@@ -0,0 +1,41 @@
+---
+type: system
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# 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.

vault/03-context/systems/index.md

@@ -0,0 +1,36 @@
+---
+type: system-index
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# 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.
+
+- [cogstore.md](./cogstore.md)
+  Flow-configuration publishing and version-comparison platform used to verify what is live in QA/Production.
+
+---
+
+## 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.
+- Open `cogstore.md` when the question involves published flow-definition versions, config diffs, or whether a service/config change is live in QA vs Production.

vault/03-context/systems/xflowsdk.md

@@ -0,0 +1,48 @@
+---
+type: system
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# 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.

vault/03-context/systems/xflowviewmaker.md

@@ -0,0 +1,38 @@
+---
+type: system
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - system
+  - fidelity
+---
+# 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.

vault/03-context/workstreams/ao-discourse.md

@@ -0,0 +1,47 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.
+- AO-backed flows still carry older service conventions that can differ from what newer XFlow SwiftUI paths were primarily validated against.
+- In at least some AO validation cases, iOS expected `validations` while older AO payloads could still send fallback-style keys such as `birthDate`.
+
+---
+
+## 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.
+- For AO consumers, check whether the payload shape reflects older AO service conventions before concluding the issue is purely client-side.
+- If iOS-only behavior appears around validation decoding, compare what AO sends against older fallback handling already present in XFlow, especially when Android appears more permissive.
+
+---
+
+## 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.
+- Jeff clarified on April 15, 2026 that these fallback validation paths exist largely to accommodate AO flows. AO was the earliest service integration, built around older custom backend tooling and harder-to-change payload conventions, while newer consumer services were primarily built through Slate and aligned more naturally with `validations` during the SwiftUI refactor.

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

@@ -0,0 +1,45 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.

vault/03-context/workstreams/flow-page-references.md

@@ -0,0 +1,34 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# Flow And Page References
+
+## Goal
+
+Keep recurring flow names, page names, and shorthand references aligned so debugging notes and external updates do not drift into ambiguous wording.
+
+---
+
+## Current Mappings
+
+- `HybridYouthAccountOpening`
+  - This is the real flow identifier when David refers to the Youth flow in recent AO validation discussions.
+  - The relevant page in this flow is `TeenIdentityCheck`.
+
+- `HybridBrokerageAccountOpening`
+  - This is the separate authenticated flow discussed alongside the Youth issue.
+  - The relevant page in this flow is `JointIdentityCheck`.
+
+---
+
+## Usage
+
+- When drafting updates, prefer the real flow identifier if there is any risk that shorthand like `Youth flow` or `HybridBrokerage` could be misunderstood.
+- When a shorthand is still useful for readability, keep the real flow ID available somewhere in the same session context.
+- Capture additional stable flow/page mappings here when they come up repeatedly in debugging, standups, Jira comments, or consumer communication.

vault/03-context/workstreams/index.md

@@ -0,0 +1,38 @@
+---
+type: workstream-index
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.
+
+- [flow-page-references.md](./flow-page-references.md)
+  Stable mapping between shorthand flow references and their real flow/page identifiers.
+
+---
+
+## 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.

vault/03-context/workstreams/rest-migration.md

@@ -0,0 +1,41 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.

vault/03-context/workstreams/xflow-debugging.md

@@ -0,0 +1,48 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.
+- When validating service/configuration changes, check the active flow-definition version in Cogstore before assuming a change is live in QA or Production.
+- Do not assume a flow ID will exist in both Cogstore and Slate; verify which config system actually owns the flow you are inspecting.
+
+---
+
+## 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.

vault/03-context/workstreams/xflow-swiftui-migration.md

@@ -0,0 +1,44 @@
+---
+type: workstream
+project: fidelity
+status: active
+updated: 2026-04-16
+tags:
+  - workstream
+  - fidelity
+---
+# 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.