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.
2026-04-16 16:01:19 -06:00
parent 90043ab6bf
commit b82194bc55
129 changed files with 4777 additions and 251 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -19,11 +19,12 @@ scripts/mattermost/generated/*
 !scripts/mattermost/generated/.gitkeep
 # Obsidian local runtime state
-.obsidian/workspace*.json
+/.obsidian/
-.obsidian/workspace-mobile*.json
+vault/.obsidian/workspace*.json
-.obsidian/hotkeys.json
+vault/.obsidian/workspace-mobile*.json
-.obsidian/community-plugins.json
+vault/.obsidian/hotkeys.json
-.obsidian/plugins/
+vault/.obsidian/community-plugins.json
-.obsidian/snippets/
+vault/.obsidian/plugins/
-.obsidian/cache/
+vault/.obsidian/snippets/
 vault/.obsidian/cache/
 .trash/
--- a/.obsidian/app.json
+++ b/.obsidian/app.json
@@ -1,22 +0,0 @@
 {
  "attachmentFolderPath": "knowledge/assets",
  "newFileLocation": "current",
  "userIgnoreFilters": [
    ".git/",
    ".opencode/node_modules/",
    ".opencode/package-lock.json",
    ".opencode/package.json",
    "ai/inbox/",
    "archives/",
    "**/archives/",
    "scripts/**/.venv/",
    "scripts/**/generated/",
    "**/.venv/",
    "**/generated/",
    "scripts/mattermost/.venv/",
    "scripts/mattermost/generated/",
    "scripts/slack/generated/",
    "**/__pycache__/",
    "**/*.pyc"
  ]
 }
--- a/.opencode/agents/fidelity.md
+++ b/.opencode/agents/fidelity.md
@@ -12,33 +12,35 @@ Behavior rules:
 - Treat `core/` as the reusable project-independent operating model.
 - Treat `profiles/fidelity/profile.md` as the active Fidelity project profile.
- Treat `README.md`, `ai/context/`, `ai/state/`, `knowledge/`, and `ai/logs/` as the persistent memory of the project.
+- Treat `vault/` as the canonical clean knowledge base for humans and AI.
 - Treat `README.md`, `ai/context/`, `ai/state/`, `knowledge/`, and `ai/logs/` as legacy compatibility memory until the vault migration is fully retired.
 - Before answering a prompt that depends on current state, verify the latest relevant files instead of relying only on conversation history.
 - If the prompt asks for the latest Mattermost message, the last message from Jeff/current manager, or what someone just said, force a Mattermost refresh before answering and do not rely on stale inbox context.
 - For any meaningful prompt, decide whether the interaction adds, corrects, or sharpens project memory.
 - When the user provides new durable information, update the right workspace files before or while answering.
- When the user corrects how the workspace should behave, update the linked operational surface too: commands in `.opencode/commands/`, prompt templates in `prompts/`, agent rules in `ai/AGENTS.md` or `.opencode/agents/`, skills in `.opencode/skills/`, and knowledge rules in `knowledge/` when those files control the behavior.
+- When the user corrects how the workspace should behave, update the linked operational surface too: commands in `.opencode/commands/`, prompt templates in `prompts/`, agent rules in `ai/AGENTS.md` or `.opencode/agents/`, skills in `.opencode/skills/`, and vault process rules in `vault/03-context/process/` when those files control the behavior.
 - If existing context is stale, correct it directly instead of leaving conflicting versions.
 - Promote information carefully:
-  - daily facts go to `ai/logs/YYYY-MM-DD.md`
+  - daily facts go to `vault/06-daily/YYYY-MM-DD.md`
-  - current priorities go to `ai/state/current.md`
+  - current priorities go to `vault/01-current/current-work.md`
-  - active Jira-linked work goes to `ai/work-items/*.md`
+  - active Jira-linked work goes to `vault/02-work-items/*.md`
-  - the active-work summary goes to `ai/state/work-items.md`
+  - the active-work summary goes to `vault/01-current/work-items.md`
-  - durable project knowledge overview goes to `ai/context/project.md`
+  - durable project knowledge overview goes to `vault/03-context/project.md`
-  - system-specific durable knowledge goes to `ai/context/systems/`
+  - system-specific durable knowledge goes to `vault/03-context/systems/`
-  - workstream-specific durable knowledge goes to `ai/context/workstreams/`
+  - workstream-specific durable knowledge goes to `vault/03-context/workstreams/`
-  - process-specific durable knowledge goes to `ai/context/process/`
+  - process-specific durable knowledge goes to `vault/03-context/process/`
-  - confirmed team or manager communication preferences go to `ai/context/people/manager.md`
+  - confirmed team or manager communication preferences go to `vault/04-people/manager.md`
-  - role-to-person mapping and recurring stakeholders go to `ai/context/people/`
+  - role-to-person mapping and recurring stakeholders go to `vault/04-people/`
-  - confirmed decisions go to `ai/context/decisions/`
+  - confirmed decisions go to `vault/05-decisions/`
- behavioral rules for how this workspace should respond go to the exact command, prompt, agent, skill, or knowledge file that enforces that behavior
+- behavioral rules for how this workspace should respond go to the exact command, prompt, agent, skill, or vault process file that enforces that behavior
 - Use generic `AIW_*` integration variables for new tooling and keep `FIDELITY_*` only as compatibility aliases.
 - Default to writing new same-day information to today's log unless a more durable destination is clearly better.
 - If a canonical vault note exists, update it first; update legacy `ai/` or `knowledge/` files only when needed for compatibility.
 - Update preexisting memory when a new prompt clarifies or corrects something already stored.
 - Do not wait for a dedicated sync command if the correct memory update is already obvious.
 - Do not leave behavior-only corrections only in daily logs. If a correction should affect future output, update the tool or instruction that produces that output.
 - Do not over-promote uncertain information. Keep uncertain items in the daily log.
 - When drafting communication, preserve technical meaning and improve clarity in natural US English.
- When answering Swift/iOS programming questions, use the project-local iOS skills and `ai/context/ios/`.
+- When answering Swift/iOS programming questions, use the project-local iOS skills and `vault/03-context/ios/`.
- When generating prompts for GitHub Copilot or another AI, use `ai/context/process/ai-to-ai-prompting.md` and the `copilot-prompt-engineering` skill.
+- When generating prompts for GitHub Copilot or another AI, use `vault/03-context/process/ai-to-ai-prompting.md` and the `copilot-prompt-engineering` skill.
 - If the answer depends on current Apple APIs or Xcode/iOS behavior, verify with official Apple or Swift documentation before presenting it as current best practice.
--- a/.opencode/agents/workspace.md
+++ b/.opencode/agents/workspace.md
@@ -12,11 +12,12 @@ Behavior rules:
 - Load `core/` first for project-independent operating rules.
 - Load the active profile from `AIW_PROJECT_PROFILE` when available; otherwise use the configured project files in this workspace.
- Treat `ai/context/`, `ai/state/`, `ai/work-items/`, `ai/logs/`, `knowledge/`, and profile files as persistent memory.
+- Treat `vault/` as the canonical clean knowledge base.
 - Treat `ai/context/`, `ai/state/`, `ai/work-items/`, `ai/logs/`, `knowledge/`, and profile files as compatibility memory unless no vault equivalent exists.
 - Before answering current-state questions, inspect current state, active work items, recent logs, and inbox evidence when available.
 - For any meaningful prompt, decide whether it adds, corrects, or invalidates memory.
 - Update the smallest correct canonical file when memory should change.
- If the user corrects recurring behavior, update the command, prompt, agent, skill, or knowledge file that controls that behavior.
+- If the user corrects recurring behavior, update the command, prompt, agent, skill, vault process note, or other control file that enforces that behavior.
 - Keep imported evidence separate from promoted memory.
 - If an integration or sync command fails, do not update project memory from that failure.
 - Do not promote tooling noise, empty syncs, dependency failures, or generic chat chatter unless the user explicitly asks to track tooling work.
@@ -25,12 +26,11 @@ Behavior rules:
 Memory destinations:
- daily facts -> `ai/logs/YYYY-MM-DD.md`
+- daily facts -> `vault/06-daily/YYYY-MM-DD.md`
- current priorities -> `ai/state/current.md`
+- current priorities -> `vault/01-current/current-work.md`
- active work items -> `ai/work-items/*.md`
+- active work items -> `vault/02-work-items/*.md`
- active-work summary -> `ai/state/work-items.md`
+- active-work summary -> `vault/01-current/work-items.md`
- durable project knowledge -> `ai/context/`
+- durable project knowledge -> `vault/03-context/`
- people and roles -> `ai/context/people/`
+- people and roles -> `vault/04-people/`
- confirmed decisions -> `ai/context/decisions/`
+- confirmed decisions -> `vault/05-decisions/`
- reusable behavior -> `.opencode/commands/`, `prompts/`, `.opencode/agents/`, `.opencode/skills/`, `knowledge/`, or `ai/context/process/`
+- reusable behavior -> `.opencode/commands/`, `prompts/`, `.opencode/agents/`, `.opencode/skills/`, `vault/00-start/`, or `vault/03-context/process/`
--- a/.opencode/commands/ai-prompt.md
+++ b/.opencode/commands/ai-prompt.md
@@ -9,6 +9,10 @@ Read:
@core/README.md
@core/memory/operational-memory.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/process/ai-to-ai-prompting.md
@ai/context/index.md
@ai/context/project.md
@ai/context/process/ai-to-ai-prompting.md
@@ -23,7 +27,7 @@ Read active profile, if present:
 Relevant active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 User request:
--- a/.opencode/commands/archive-import.md
+++ b/.opencode/commands/archive-import.md
@@ -25,6 +25,12 @@ Read:
@core/memory/operational-memory.md
@core/integrations/communication-model.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/process/context-maintenance.md
@vault/04-people/index.md
@vault/04-people/manager.md
@ai/context/index.md
@ai/context/project.md
@ai/context/process/context-maintenance.md
@@ -49,14 +55,14 @@ Instructions:
 - treat the archive as historical evidence
 - promote durable project-relevant context automatically when confidence is high
 - prefer durable role/person associations, recurring architecture patterns, repeated work-item references, approval/scope history, and process lessons
- create or update person files when a human repeatedly affects project flow
+- create or update `vault/04-people/*.md` when a human repeatedly affects project flow
 - avoid promoting outdated daily status unless it changes current understanding
 - update existing memory when the archive clarifies or corrects it
 - keep ambiguous or likely outdated facts as archive-only context
 - write promoted memory to `vault/` first; use legacy `ai/*` only as compatibility fallback
 Return:
 1. What was imported
 2. Which files were updated
 3. Which historical facts were promoted or intentionally left as archive-only context
--- a/.opencode/commands/communication-sync.md
+++ b/.opencode/commands/communication-sync.md
@@ -20,6 +20,10 @@ Read:
@core/memory/operational-memory.md
@core/integrations/communication-model.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/process/context-maintenance.md
@ai/context/index.md
@ai/context/project.md
@ai/context/process/context-maintenance.md
@@ -37,10 +41,11 @@ Instructions:
 - if the sync command failed, stop and do not edit workspace memory
 - treat connector output as evidence, not automatically as project truth
 - promote only explicit, project-relevant, high-confidence facts
- default destination is `ai/logs/$(date +%F).md`
+- default destination is `vault/06-daily/$(date +%F).md`
- update `ai/state/current.md` only for facts that materially change the active work window
+- update `vault/01-current/current-work.md` only for facts that materially change the active work window
- update `ai/work-items/*.md` for explicit work-item IDs, approved titles, points, scope, and status notes
+- update `vault/02-work-items/*.md` for explicit work-item IDs, approved titles, points, scope, and status notes
- keep `ai/state/work-items.md` aligned as the compact summary of active work items
+- keep `vault/01-current/work-items.md` aligned as the compact summary of active work items
 - use `ai/*` paths only as temporary compatibility fallback
 - do not write tooling noise, sync status, or generic chat chatter into project memory
 - if a fact is ambiguous, skip it rather than asking what to do
@@ -49,4 +54,3 @@ Return:
 1. What was synchronized
 2. Which files were updated
 3. Which facts were promoted or intentionally skipped
--- a/.opencode/commands/copilot-prompt.md
+++ b/.opencode/commands/copilot-prompt.md
@@ -10,6 +10,14 @@ Read:
@core/memory/operational-memory.md
@prompts/copilot-prompt.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/process/ai-to-ai-prompting.md
@vault/03-context/ios/index.md
@vault/03-context/ios/project-swift-guidance.md
@vault/03-context/systems/index.md
@vault/03-context/workstreams/index.md
@ai/context/process/ai-to-ai-prompting.md
@ai/context/index.md
@ai/context/project.md
@@ -27,7 +35,7 @@ Active profile, if present:
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 User request:
--- a/.opencode/commands/fidelity-context.md
+++ b/.opencode/commands/fidelity-context.md
@@ -11,6 +11,17 @@ Use these files as the baseline context:
@core/memory/operational-memory.md
@core/integrations/communication-model.md
@profiles/fidelity/profile.md
@vault/00-start/start-here.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/07-maps/current-work.md
@vault/07-maps/fidelity-domain.md
@vault/07-maps/work-items.md
@vault/07-maps/people.md
@vault/03-context/project.md
@vault/03-context/process/communication.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/AGENTS.md
@ai/context/index.md
@ai/context/project.md
@@ -39,17 +50,17 @@ Today's date:
 !`date +%F`
-Today's log, if present:
+Today's canonical daily note, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
-Recent logs available:
+Recent daily notes available:
-!`ls -1 ai/logs 2>/dev/null | sort | tail -n 5`
+!`if [ -d vault/06-daily ]; then ls -1 vault/06-daily 2>/dev/null | sort | tail -n 5; else ls -1 ai/logs 2>/dev/null | sort | tail -n 5; fi`
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 Latest Mattermost context, if available:
--- a/.opencode/commands/index.md
+++ b/.opencode/commands/index.md
@@ -38,7 +38,6 @@ Slash commands available in this workspace.
 ## Related
- [Tooling Map](../../knowledge/maps/tooling.md)
+- [Tooling Map](../../vault/07-maps/tooling.md)
 - [Prompts Index](../../prompts/index.md)
 - [Skills Index](../skills/index.md)
--- a/.opencode/commands/latest-message.md
+++ b/.opencode/commands/latest-message.md
@@ -30,7 +30,7 @@ Instructions:
 - If the user asks for the current manager/stakeholder, filter messages by the profile mapping when visible; for the Fidelity profile, also match `jeff` and `jeff.dewitte`.
 - If multiple messages match, return the newest matching message first.
 - Include timestamp, channel, sender, and concise summary.
- If the message changes project context, update the appropriate workspace memory after answering.
+- If the message changes project context, update the appropriate workspace memory after answering, writing to `vault/` first.
 - If sync fails or no refreshed context is available, say that directly and do not infer from stale context.
 Return:
--- a/.opencode/commands/log-note.md
+++ b/.opencode/commands/log-note.md
@@ -10,6 +10,11 @@ Read:
@core/README.md
@core/memory/operational-memory.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/workstreams/index.md
@vault/03-context/process/context-maintenance.md
@ai/context/index.md
@ai/context/project.md
@ai/context/workstreams/index.md
@@ -22,7 +27,7 @@ Read:
 Today's existing log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Incorporate these new rough notes into today's log:
@@ -31,7 +36,8 @@ $ARGUMENTS
 Instructions:
 - use `workspace-memory-curation` when available
- Update or create `ai/logs/$(date +%F).md`
+- Update or create `vault/06-daily/$(date +%F).md`
 - Use `ai/logs/$(date +%F).md` only as temporary compatibility fallback
 - Preserve concrete technical meaning
 - Capture both technical findings and communication context when relevant
 - Keep the log concise but reusable for later standups and manager updates
--- a/.opencode/commands/manager-update.md
+++ b/.opencode/commands/manager-update.md
@@ -10,6 +10,13 @@ Read:
@prompts/manager-update.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/workstreams/index.md
@vault/03-context/process/communication.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/context/index.md
@ai/context/project.md
@ai/context/workstreams/index.md
@@ -24,7 +31,7 @@ Read:
 Today's log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Latest Mattermost context, if available:
@@ -32,7 +39,7 @@ Latest Mattermost context, if available:
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 User draft or rough notes:
--- a/.opencode/commands/mattermost-sync.md
+++ b/.opencode/commands/mattermost-sync.md
@@ -21,13 +21,14 @@ Then:
 - if the command fails, stop there and do not edit any workspace files
 - use `ai/inbox/mattermost-latest.md` if it exists and is non-empty
 - otherwise use `scripts/mattermost/generated/mattermost_context.jsonl` if it exists and is non-empty
- apply the memory promotion rules from `knowledge/memory-promotion-rules.md`
+- apply the memory promotion rules from `vault/03-context/process/memory-promotion-rules.md`, falling back to `knowledge/memory-promotion-rules.md` only if needed
 - treat Mattermost output as live communication evidence; the agent decides what becomes promoted memory
 - automatically promote explicit, project-relevant, high-confidence facts
- default destination is `ai/logs/$(date +%F).md`
+- default destination is `vault/06-daily/$(date +%F).md`
- update `ai/state/current.md` only for facts that materially change the current work window
+- update `vault/01-current/current-work.md` only for facts that materially change the current work window
- update `ai/work-items/*.md` for explicit Jira IDs, approved titles, points, scope, and status notes
+- update `vault/02-work-items/*.md` for explicit Jira IDs, approved titles, points, scope, and status notes
- keep `ai/state/work-items.md` aligned as the compact summary of active ticket files
+- keep `vault/01-current/work-items.md` aligned as the compact summary of active ticket files
 - use `ai/*` paths only as temporary compatibility fallback
 - do not write tooling noise, sync status, or generic chat chatter into project memory
 - if a fact is ambiguous, skip it rather than asking the user what to do
--- a/.opencode/commands/promote-project-context.md
+++ b/.opencode/commands/promote-project-context.md
@@ -9,6 +9,13 @@ Read:
@core/README.md
@core/memory/operational-memory.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/systems/index.md
@vault/03-context/workstreams/index.md
@vault/03-context/workstreams/flow-page-references.md
@vault/03-context/process/index.md
@ai/context/index.md
@ai/context/project.md
@ai/context/systems/index.md
@@ -24,7 +31,7 @@ Read:
 Today's log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Current Mattermost inbox, if present:
@@ -43,20 +50,21 @@ Instructions:
 - Promote only confirmed project-relevant facts
 - Ignore tooling noise and sync status
 - Update the smallest correct set of files among:
-  - `ai/logs/$(date +%F).md`
+  - `vault/06-daily/$(date +%F).md`
-  - `ai/state/current.md`
+  - `vault/01-current/current-work.md`
-  - `ai/work-items/*.md`
+  - `vault/02-work-items/*.md`
-  - `ai/state/work-items.md`
+  - `vault/01-current/work-items.md`
-  - `ai/context/project.md`
+  - `vault/03-context/project.md`
-  - `ai/context/systems/*.md`
+  - `vault/03-context/systems/*.md`
-  - `ai/context/workstreams/*.md`
+  - `vault/03-context/workstreams/*.md`
-  - `ai/context/process/*.md`
+  - `vault/03-context/process/*.md`
-  - `ai/context/decisions/*.md`
+  - `vault/05-decisions/*.md`
  - `.opencode/commands/*.md` when command behavior needs to change
  - `prompts/*.md` when a reusable output template needs to change
  - `.opencode/agents/*.md` or `ai/AGENTS.md` when default agent behavior needs to change
  - `.opencode/skills/*/SKILL.md` when a specialized workflow needs to change
-  - `knowledge/*.md` when a durable workspace rule needs to change
+  - `vault/00-start/*.md` when durable onboarding or usage guidance needs to change
 - Use legacy `ai/*` and `knowledge/*` only as compatibility fallback during migration
 - Prefer concrete project updates over broad summaries
 - If a fact is still ambiguous, do not promote it
 - If the promoted fact is a reusable behavior correction, do not leave it only in a daily log; update the operational file that controls future behavior
--- a/.opencode/commands/slack-import.md
+++ b/.opencode/commands/slack-import.md
@@ -28,6 +28,14 @@ Read:
@core/README.md
@core/memory/operational-memory.md
@core/integrations/communication-model.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/systems/index.md
@vault/03-context/workstreams/index.md
@vault/03-context/process/index.md
@vault/04-people/index.md
@vault/04-people/manager.md
@ai/context/index.md
@ai/context/project.md
@ai/context/systems/index.md
@@ -60,7 +68,7 @@ Instructions:
  - durable role/person associations
  - recurring architecture or debugging patterns
  - past approvals or decisions that still matter
- create or update person files when the archive shows a human repeatedly contributing across channels, years, or high-signal technical/process discussions
+- create or update `vault/04-people/*.md` when the archive shows a human repeatedly contributing across channels, years, or high-signal technical/process discussions
 - store people conservatively:
  - exact role only when explicitly supported by the archive
  - otherwise store collaboration pattern, communication style, and project relationship
@@ -75,6 +83,7 @@ Instructions:
 - avoid promoting outdated daily status unless it changes current understanding
 - update existing memory when the archive clarifies or corrects it
 - if historical facts are ambiguous or likely outdated, summarize them as archived context instead of promoting them
 - write promoted memory to `vault/` first; use legacy `ai/*` only as compatibility fallback
 Return:
--- a/.opencode/commands/standup.md
+++ b/.opencode/commands/standup.md
@@ -12,6 +12,15 @@ Read:
@prompts/standup.md
@ai/AGENTS.md
@vault/00-start/start-here.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/workstreams/index.md
@vault/03-context/workstreams/flow-page-references.md
@vault/03-context/process/communication.md
@vault/03-context/process/jira-story-rules.md
@vault/04-people/manager.md
@ai/context/index.md
@ai/context/project.md
@ai/context/workstreams/index.md
@@ -31,7 +40,7 @@ Previous workday Mattermost context, if present:
 Today's log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Latest Mattermost context, preferring inbox and falling back to generated JSONL:
@@ -39,7 +48,7 @@ Latest Mattermost context, preferring inbox and falling back to generated JSONL:
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 Before drafting:
@@ -52,7 +61,7 @@ Before drafting:
 - if documentation or root cause updates directly support a story, roll them into that story's update instead of listing them separately
 - exclude items that are not directly tied to a story unless they are true blockers
 - when one Jira item has multiple concrete updates, group them under one top-level `JIRA-ID - Title` bullet with indented markdown sub-bullets instead of repeating the same Jira line
- use `ai/context/workstreams/flow-page-references.md` to preserve real flow/page identifiers when shorthand appears in logs or messages
+- use `vault/03-context/workstreams/flow-page-references.md` to preserve real flow/page identifiers when shorthand appears in logs or messages, falling back to `ai/context/workstreams/flow-page-references.md` only if needed
 Return a standup that is:
--- a/.opencode/commands/story-draft.md
+++ b/.opencode/commands/story-draft.md
@@ -22,6 +22,14 @@ Read:
@core/memory/operational-memory.md
@prompts/story-draft.md
@ai/AGENTS.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/workstreams/index.md
@vault/03-context/process/communication.md
@vault/03-context/process/jira-story-rules.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/context/index.md
@ai/context/project.md
@ai/context/workstreams/index.md
@@ -37,7 +45,7 @@ Read:
 Today's log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Latest Mattermost context, if available:
@@ -45,7 +53,7 @@ Latest Mattermost context, if available:
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 Requirements:
--- a/.opencode/commands/swift-help.md
+++ b/.opencode/commands/swift-help.md
@@ -7,6 +7,13 @@ Answer the user's Swift/iOS programming question using current iOS practices and
 Read:
@ai/AGENTS.md
@vault/03-context/ios/index.md
@vault/03-context/ios/current-practices.md
@vault/03-context/ios/project-swift-guidance.md
@vault/03-context/project.md
@vault/03-context/systems/index.md
@vault/03-context/workstreams/index.md
@vault/01-current/work-items.md
@ai/context/ios/index.md
@ai/context/ios/current-practices.md
@ai/context/ios/project-swift-guidance.md
--- a/.opencode/commands/sync-context.md
+++ b/.opencode/commands/sync-context.md
@@ -8,6 +8,16 @@ Read:
@README.md
@ai/AGENTS.md
@vault/00-start/start-here.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/03-context/project.md
@vault/03-context/systems/index.md
@vault/03-context/workstreams/index.md
@vault/03-context/workstreams/flow-page-references.md
@vault/03-context/process/context-maintenance.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/context/index.md
@ai/context/project.md
@ai/context/systems/index.md
@@ -26,7 +36,7 @@ Read:
 Today's existing log, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 New information to incorporate:
@@ -36,23 +46,23 @@ Instructions:
 - use `workspace-memory-curation` when available
 - Decide whether the new information belongs in:
-  - today's log
+  - today's daily note: `vault/06-daily/$(date +%F).md`
-  - `ai/state/current.md`
+  - current work: `vault/01-current/current-work.md`
-  - `ai/work-items/*.md`
+  - work items: `vault/02-work-items/*.md`
-  - `ai/state/work-items.md`
+  - active work summary: `vault/01-current/work-items.md`
-  - `ai/context/project.md`
+  - project overview: `vault/03-context/project.md`
-  - `ai/context/systems/`
+  - systems: `vault/03-context/systems/`
-  - `ai/context/workstreams/`
+  - workstreams: `vault/03-context/workstreams/`
-  - `ai/context/process/`
+  - process: `vault/03-context/process/`
-  - `ai/context/people/manager.md`
+  - manager mapping: `vault/04-people/manager.md`
-  - `ai/context/people/index.md`
+  - people roster: `vault/04-people/index.md`
-  - `ai/context/people/*.md`
+  - people notes: `vault/04-people/*.md`
-  - `ai/context/decisions/`
+  - decisions: `vault/05-decisions/`
  - `.opencode/commands/*.md`
  - `prompts/*.md`
  - `.opencode/agents/*.md`
  - `.opencode/skills/*/SKILL.md`
-  - `knowledge/*.md`
+- Write to `vault/` first when a canonical note exists; use `ai/*` and `knowledge/*` only as temporary compatibility fallback
 - Update the appropriate files directly
 - If an existing statement became stale, replace or refine it
 - If the new information changes how this workspace should behave, update the linked command, prompt, agent, skill, or knowledge file that enforces that behavior
--- a/.opencode/commands/translate.md
+++ b/.opencode/commands/translate.md
@@ -17,6 +17,10 @@ Read:
@prompts/mattermost-translation.md
@ai/AGENTS.md
@vault/03-context/project.md
@vault/03-context/process/communication.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/context/index.md
@ai/context/project.md
@ai/context/process/communication.md
@@ -26,7 +30,7 @@ Read:
 If relevant, use today's log for context:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
 Return:
--- a/.opencode/commands/workspace-context.md
+++ b/.opencode/commands/workspace-context.md
@@ -14,6 +14,18 @@ Read core:
 Read active workspace memory:
@README.md
@vault/00-start/start-here.md
@vault/00-start/onboarding.md
@vault/01-current/current-work.md
@vault/01-current/work-items.md
@vault/07-maps/current-work.md
@vault/07-maps/fidelity-domain.md
@vault/07-maps/work-items.md
@vault/07-maps/people.md
@vault/03-context/project.md
@vault/03-context/process/communication.md
@vault/04-people/manager.md
@vault/04-people/index.md
@ai/AGENTS.md
@ai/context/index.md
@ai/context/project.md
@@ -37,17 +49,17 @@ Today's date:
 !`date +%F`
-Today's log, if present:
+Today's canonical daily note, if present:
-!`if [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No log exists for today yet."; fi`
+!`if [ -f vault/06-daily/$(date +%F).md ]; then cat vault/06-daily/$(date +%F).md; elif [ -f ai/logs/$(date +%F).md ]; then cat ai/logs/$(date +%F).md; else echo "No daily note exists for today yet."; fi`
-Recent logs available:
+Recent daily notes available:
-!`ls -1 ai/logs 2>/dev/null | sort | tail -n 5`
+!`if [ -d vault/06-daily ]; then ls -1 vault/06-daily 2>/dev/null | sort | tail -n 5; else ls -1 ai/logs 2>/dev/null | sort | tail -n 5; fi`
 Detailed active work item files, if available:
-!`if [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
+!`if [ -d vault/02-work-items ]; then for f in vault/02-work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; elif [ -d ai/work-items ]; then for f in ai/work-items/*.md; do case "$f" in *README.md|*index.md) continue;; esac; echo "\n### $f"; cat "$f"; done; else echo "No work item files available."; fi`
 Latest communication inbox, if available:
@@ -60,4 +72,3 @@ Respond with:
 3. Missing context to capture today
 Keep the response concise, then wait for the next request.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,29 +14,31 @@ OpenCode should treat this project as a persistent context layer used to:
 The detailed operating rules live in:
 - `ai/AGENTS.md`
- `ai/context/index.md`
+- `vault/00-start/start-here.md`
- `ai/context/project.md`
+- `vault/00-start/workspace-architecture.md`
- `ai/context/ios/index.md`
+- `vault/01-current/current-work.md`
- `ai/context/ios/current-practices.md`
+- `vault/01-current/work-items.md`
- `ai/context/ios/project-swift-guidance.md`
+- `vault/03-context/project.md`
- `ai/context/systems/index.md`
+- `vault/03-context/ios/index.md`
- `ai/context/workstreams/index.md`
+- `vault/03-context/ios/current-practices.md`
- `ai/context/process/communication.md`
+- `vault/03-context/ios/project-swift-guidance.md`
- `ai/context/process/ai-to-ai-prompting.md`
+- `vault/03-context/systems/index.md`
- `ai/context/people/manager.md`
+- `vault/03-context/workstreams/index.md`
- `ai/context/people/index.md`
+- `vault/03-context/process/communication.md`
- `ai/work-items/index.md`
+- `vault/03-context/process/ai-to-ai-prompting.md`
- `ai/state/current.md`
+- `vault/03-context/process/workspace-model.md`
- `ai/state/work-items.md`
+- `vault/03-context/process/memory-promotion-rules.md`
- `knowledge/workspace-model.md`
+- `vault/04-people/manager.md`
- `knowledge/communication-rules.md`
+- `vault/04-people/index.md`
 - `vault/02-work-items/index.md`
 These are also loaded through `opencode.json`.
 ## Required Behavior
 - Assume the workspace may contain stale context until checked.
- Before answering questions that depend on current work state, inspect `ai/state/current.md` and the latest relevant log under `ai/logs/`.
+- Treat `vault/` as the canonical clean memory for humans and AI. Legacy `ai/*` and `knowledge/*` paths are temporary compatibility fallback.
 - Before answering questions that depend on current work state, inspect `vault/01-current/current-work.md` and the latest relevant daily note under `vault/06-daily/`.
 - If `ai/inbox/mattermost-latest.md` exists, inspect it for fresher communication context before answering standup, status, or manager-message prompts.
 - If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, synchronize Mattermost first instead of relying on existing inbox context.
 - If automatic refresh is uncertain, use the explicit latest-message flow: run the Mattermost sync command, then answer from the refreshed inbox only.
@@ -44,12 +46,12 @@ These are also loaded through `opencode.json`.
 - If a sync command, extraction script, or inbox refresh fails, do not update logs, state, or context files from that failed attempt.
 - Treat sync failures as operational errors, not project context.
 - `mattermost-sync` should automatically promote high-confidence project facts without asking what to promote.
- Prefer `ai/logs/` as the default destination for new Mattermost-derived facts.
+- Prefer `vault/06-daily/` as the default destination for new Mattermost-derived facts.
- Promote to `ai/state/current.md` only when the fact materially changes active work over the next few days.
+- Promote to `vault/01-current/current-work.md` only when the fact materially changes active work over the next few days.
- Keep explicit Jira IDs and approved titles visible in `ai/work-items/` and summarize active items in `ai/state/work-items.md` when they are useful for future standups or manager updates.
+- Keep explicit Jira IDs and approved titles visible in `vault/02-work-items/` and summarize active items in `vault/01-current/work-items.md` when they are useful for future standups or manager updates.
- Promote to `ai/context/project.md` only when the fact changes durable project understanding.
+- Promote to `vault/03-context/project.md` only when the fact changes durable project understanding.
- When a repeatedly mentioned person becomes relevant to project flow, create or update a file under `ai/context/people/`.
+- When a repeatedly mentioned person becomes relevant to project flow, create or update a file under `vault/04-people/`.
- Keep role-to-person mapping explicit in `ai/context/people/manager.md` and the roster in `ai/context/people/index.md`.
+- Keep role-to-person mapping explicit in `vault/04-people/manager.md` and the roster in `vault/04-people/index.md`.
 - Never promote tooling chatter, sync status, or generic conversation noise.
 - Direct user prompts are also memory sources. Do not limit memory updates to explicit sync commands.
 - If a new prompt corrects prior understanding, update the canonical file directly instead of keeping both versions alive.
@@ -58,9 +60,9 @@ These are also loaded through `opencode.json`.
 - If a previous context file is now stale or inaccurate, update that file directly.
 - Prefer correcting canonical context over appending contradictory notes.
 - Keep changes concise and auditable.
- When the topic is architectural or historical, prefer updating the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/` instead of overloading `ai/context/project.md`.
+- When the topic is architectural or historical, prefer updating the relevant file under `vault/03-context/systems/`, `vault/03-context/workstreams/`, or `vault/03-context/process/` instead of overloading `vault/03-context/project.md`.
- When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `ai/context/ios/` and the local OpenCode iOS skills before answering.
+- When the user asks Swift, SwiftUI, iOS architecture, testing, or debugging questions, use `vault/03-context/ios/` and the local OpenCode iOS skills before answering.
- When the user asks for a prompt for another AI, GitHub Copilot, or the Fidelity development machine, use `ai/context/process/ai-to-ai-prompting.md` and generate a self-contained prompt.
+- When the user asks for a prompt for another AI, GitHub Copilot, or the Fidelity development machine, use `vault/03-context/process/ai-to-ai-prompting.md` and generate a self-contained prompt.
 - If a Swift/iOS recommendation depends on current Apple APIs, Xcode behavior, or framework migration guidance, verify against official Apple or Swift documentation before making strong claims.
 ## Communication
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@ Reusable AI-native companion workspace with Fidelity configured as the first rea
 This repository is not the product codebase. It is an operational context layer used to keep project state current, capture communication evidence, prepare standups, draft clear stakeholder updates, and generate self-contained prompts for another AI that has access to the implementation codebase.
-The reusable logic lives in `core/`. Fidelity-specific context lives in the active profile and existing `ai/context/` memory.
+The reusable logic lives in `core/`. The clean human/AI memory lives in `vault/`. Fidelity-specific setup lives in the active profile under `profiles/fidelity/`.
 ---
@@ -44,6 +44,22 @@ Integrations extract evidence. The agent promotes memory.
 ## Reusable Architecture
 ### /vault
 Canonical Obsidian second brain and AI memory.
 - `00-start/` -> onboarding, glossary, start-here, and vault usage
 - `01-current/` -> current work and active work-item summary
 - `02-work-items/` -> ticket/task notes with metadata properties
 - `03-context/` -> systems, workstreams, process, and iOS context
 - `04-people/` -> people, roles, and collaboration context
 - `05-decisions/` -> durable decisions
 - `06-daily/` -> daily notes
 - `07-maps/` -> graph hubs and semantic maps
 - `08-bases/` -> Obsidian Bases
 - `09-templates/` -> Obsidian templates
 - `attachments/` -> vault assets
 ### /core
 Project-independent workspace logic.
@@ -76,18 +92,15 @@ Fidelity iOS ecosystem:
 ---
-## Structure
+## Runtime Structure
 ### /ai
 Runtime context for AI support.
 - `AGENTS.md` -> behavior rules for AI agents
- `context/` -> stable knowledge organized by systems, workstreams, process, people, and decisions
+- `context/`, `work-items/`, `state/`, and `logs/` -> legacy compatibility memory during the vault migration
- `context/ios/` -> Swift and iOS answer policy for current best practices and Fidelity-specific constraints
+- `inbox/` -> communication evidence and transient inbox files
 - `work-items/` -> one file per active Jira-linked unit of work
 - `state/` -> current focus, active issues, and communication needs
 - `logs/` -> daily work record
 ### /prompts
@@ -115,17 +128,17 @@ Reference material for:
 - XFlow behavior
 - communication rules
 - Fidelity-specific debugging heuristics
- Obsidian vault navigation
+- legacy navigation references during the vault migration
 ### /scripts
 Helpers for future automation around context generation and communication drafting.
-### /.obsidian
+### /vault/.obsidian
 Optional Obsidian vault configuration.
-Open the repository root as the vault. Obsidian should navigate and edit the same Markdown files used by OpenCode; it should not duplicate memory into a separate store.
+Open `vault/` as the Obsidian vault. Do not open the repository root as the vault.
 Portable vault configuration can be versioned, while local layout and plugin runtime files are ignored.
@@ -137,13 +150,13 @@ Portable vault configuration can be versioned, while local layout and plugin run
 Read:
- `ai/context/index.md`
+- `vault/00-start/start-here.md`
- `ai/work-items/index.md`
+- `vault/01-current/current-work.md`
- `ai/state/current.md`
+- `vault/01-current/work-items.md`
- `ai/context/project.md`
+- `vault/03-context/project.md`
- `ai/context/people/manager.md`
+- `vault/04-people/manager.md`
- `ai/context/people/index.md`
+- `vault/04-people/index.md`
- latest file under `ai/logs/`
+- latest file under `vault/06-daily/`
 ### During the day
@@ -156,7 +169,7 @@ Capture:
 Write updates in:
- `ai/logs/YYYY-MM-DD.md`
+- `vault/06-daily/YYYY-MM-DD.md`
 ### Before sending a message
@@ -245,7 +258,7 @@ Recommended setup:
 1. Use the workspace-local script at `scripts/mattermost/sync.sh`, or override it with `AIW_MATTERMOST_SYNC_CMD`.
 2. Let OpenCode run with the project plugins enabled.
 3. The Mattermost inbox plugin will periodically refresh `ai/inbox/mattermost-latest.md`.
-4. Promote durable facts from the inbox into `ai/logs/`, `ai/state/`, and `ai/context/`.
+4. Promote durable facts from the inbox into `vault/06-daily/`, `vault/01-current/`, `vault/02-work-items/`, and `vault/03-context/`.
 Use `/communication-sync` or `/mattermost-sync` when you want to force a refresh manually.
@@ -263,14 +276,15 @@ The older `FIDELITY_*` variables remain supported for compatibility with this pr
 ## Obsidian Vault
-This repository can be opened directly as an Obsidian vault.
+Open `vault/` as the Obsidian vault. The repository root remains the technical workspace for OpenCode, scripts, profiles, runtime inboxes, and generated evidence.
 Recommended entry point:
- `knowledge/obsidian-vault.md`
+- `vault/00-start/start-here.md`
- `knowledge/onboarding.md` for new members
+- `vault/00-start/onboarding.md` for new members
- `knowledge/glossary.md` for terminology
+- `vault/00-start/glossary.md` for terminology
- `knowledge/obsidian-usage.md` for navigation rules
+- `vault/00-start/obsidian-usage.md` for navigation rules
 - `vault/07-maps/` for graph hubs
 Use Obsidian for:
@@ -281,8 +295,24 @@ Use Obsidian for:
 Do not use Obsidian as a second memory database. The source of truth remains the versioned Markdown files in this repository.
 Runtime/evidence stays outside the vault:
 - `.opencode/`
 - `scripts/`
 - `core/`
 - `profiles/`
 - `ai/inbox/`
 - `scripts/*/generated/`
 Ignored Obsidian runtime files include workspace layout, plugin cache, snippets, and local plugin installs.
 Obsidian URI helpers live under `scripts/obsidian/`:
 - `scripts/obsidian/open.sh <vault-relative-path>`
 - `scripts/obsidian/daily.sh`
 - `scripts/obsidian/search.sh <query>`
 - `scripts/obsidian/uri.sh <action> key=value`
 ---
 ## Creating Another Project
@@ -291,7 +321,7 @@ Ignored Obsidian runtime files include workspace layout, plugin cache, snippets,
 2. Fill in `profiles/<project>/profile.md`.
 3. Set `AIW_PROJECT_PROFILE=<project>`.
 4. Configure any communication connector with `AIW_*` variables.
-5. Keep project-specific context under `ai/context/`, not under `core/`.
+5. Create or adapt `vault/` for the project-specific canonical memory.
 6. Use `/workspace-context` to load the core plus active profile.
 See `core/profiles/create-project-profile.md` for the full checklist.
--- a/ai/AGENTS.md
+++ b/ai/AGENTS.md
@@ -8,6 +8,8 @@ This workspace is used to maintain context, organize communication, and draft ac
 The reusable operating model lives in `core/`. Fidelity is the active project profile in `profiles/fidelity/`.
 The canonical clean knowledge base now lives in `vault/`. Legacy `ai/` and `knowledge/` paths remain as compatibility references during migration.
 ---
 ## Primary Responsibilities
@@ -63,29 +65,30 @@ When drafting messages for a manager or stakeholder:
 ## Context Maintenance
 - Treat workspace files as persistent memory, not just reference notes
 - Treat `vault/` as canonical memory when a vault equivalent exists
 - Treat `core/` as project-independent workspace logic and keep Fidelity-specific facts in profile/context files
 - Treat Obsidian as an optional navigation layer over the same Markdown files, not as a separate source of truth
- Do not treat `.obsidian/workspace*.json`, plugin caches, or local Obsidian layout changes as project memory
+- Do not treat `vault/.obsidian/workspace*.json`, plugin caches, or local Obsidian layout changes as project memory
 - Prefer generic `AIW_*` integration variables for new tooling while preserving `FIDELITY_*` fallbacks for compatibility
- Before answering prompts about current work, verify `ai/state/current.md` and the latest relevant log in `ai/logs/`
+- Before answering prompts about current work, verify `vault/01-current/current-work.md` and the latest relevant daily note in `vault/06-daily/`
- Before answering architecture, process, or historical questions, check the relevant file under `ai/context/systems/`, `ai/context/workstreams/`, or `ai/context/process/`
+- Before answering architecture, process, or historical questions, check the relevant file under `vault/03-context/systems/`, `vault/03-context/workstreams/`, or `vault/03-context/process/`
- Before answering Swift, SwiftUI, iOS architecture, testing, or debugging questions, check `ai/context/ios/` and use the project-local iOS skills when available
+- Before answering Swift, SwiftUI, iOS architecture, testing, or debugging questions, check `vault/03-context/ios/` and use the project-local iOS skills when available
- Before generating a prompt for another AI or GitHub Copilot, check `ai/context/process/ai-to-ai-prompting.md` and make the prompt self-contained
+- Before generating a prompt for another AI or GitHub Copilot, check `vault/03-context/process/ai-to-ai-prompting.md` and make the prompt self-contained
 - If `ai/inbox/mattermost-latest.md` exists, check it before answering prompts about current status, standups, or supervisor communication
 - If the user asks for the latest/last/recent Mattermost message, the latest message from Jeff/current manager, or what someone just said, synchronize Mattermost first and then answer from the refreshed inbox
 - If automatic refresh is uncertain, use the explicit latest-message flow: run the Mattermost sync command, then answer from refreshed output only
 - Treat all meaningful user prompts as potential memory updates, not only explicit sync commands
 - Treat meaningful user corrections about workspace behavior as tool-maintenance inputs, not only as notes. If a correction affects a command, prompt, agent, skill, or knowledge rule, update that linked file directly.
- If a Mattermost sync or other context-ingestion step fails, do not update `ai/logs/`, `ai/state/`, or stable context files based on that failure
+- If a Mattermost sync or other context-ingestion step fails, do not update `vault/06-daily/`, `vault/01-current/`, or stable context files based on that failure
 - Do not record missing dependencies, failed sync attempts, or missing inbox files as project facts unless the user explicitly asks to track the operational issue
 - Auto-promote Mattermost content when it is clearly project-relevant, explicit, and high-confidence
 - Auto-promote direct user-provided project facts when they are clearly project-relevant, explicit, and useful for future sessions
- Default promotion target is today's log
+- Default promotion target is `vault/06-daily/YYYY-MM-DD.md`
- Promote to `ai/state/current.md` only when the fact changes the active work window
+- Promote to `vault/01-current/current-work.md` only when the fact changes the active work window
- Maintain `ai/work-items/` as the canonical memory for active Jira-linked work and keep `ai/state/work-items.md` as the quick summary layer
+- Maintain `vault/02-work-items/` as the canonical memory for active Jira-linked work and keep `vault/01-current/work-items.md` as the quick summary layer
- Promote to `ai/context/project.md` only when the fact is durable beyond the current work window
+- Promote to `vault/03-context/project.md` only when the fact is durable beyond the current work window
- Use `ai/context/project.md` as the overview only; put system-specific, workstream-specific, and process-specific durable context in the corresponding subdirectory
+- Use `vault/03-context/project.md` as the overview only; put system-specific, workstream-specific, and process-specific durable context in the corresponding subdirectory
- Maintain `ai/context/people/` when repeated names, roles, or stakeholder relationships become useful for future sessions
+- Maintain `vault/04-people/` when repeated names, roles, or stakeholder relationships become useful for future sessions
 - Update existing memory when the new information is a correction, clarification, or refinement of something already stored
 - Prefer updating stable project context over appending generic operational summaries
 - Do not leave reusable behavior rules only in daily logs. Promote them to the prompt, command, agent, skill, or process file that controls future behavior.
@@ -95,18 +98,18 @@ When drafting messages for a manager or stakeholder:
 - Do not ask the user what should be promoted after a successful sync unless multiple conflicting interpretations are equally plausible
 - When the user shares relevant new information, update today's log if the information belongs to the daily record
 - When the user corrects or changes stable context, update the canonical file directly:
-  - `ai/state/current.md` for current focus or active concerns
+  - `vault/01-current/current-work.md` for current focus or active concerns
-  - `ai/context/project.md` for durable project knowledge
+  - `vault/03-context/project.md` for durable project knowledge
-  - `ai/context/people/manager.md` for communication preferences
+  - `vault/04-people/manager.md` for communication preferences
-  - `ai/context/people/index.md` for active roster mapping
+  - `vault/04-people/index.md` for active roster mapping
-  - `ai/context/people/<person>.md` for person-specific context
+  - `vault/04-people/<person>.md` for person-specific context
-  - `ai/context/decisions/*.md` for confirmed decisions
+  - `vault/05-decisions/*.md` for confirmed decisions
 - If the new fact changes how this workspace should operate, update the linked tool surface as well:
  - `.opencode/commands/*.md` for slash-command behavior
  - `prompts/*.md` for reusable output templates
  - `.opencode/agents/*.md` and `ai/AGENTS.md` for default agent behavior
  - `.opencode/skills/*/SKILL.md` for specialized workflows
-  - `knowledge/*.md` or `ai/context/process/*.md` for durable process rules
+  - `vault/00-start/*.md` or `vault/03-context/process/*.md` for durable process rules
 - Prefer updating stale context over leaving conflicting statements in different files
 - If context is still uncertain, record it in the daily log rather than promoting it to a stable context file
--- a/core/integrations/obsidian-model.md
+++ b/core/integrations/obsidian-model.md
@@ -2,7 +2,7 @@
 ## Purpose
-Use Obsidian as a visual navigation and manual review layer over the same Markdown files that power the AI workspace.
+Use Obsidian as a visual navigation and manual review layer over the same canonical Markdown memory that powers the AI workspace.
 Obsidian should not become a second memory store.
@@ -10,10 +10,10 @@ Obsidian should not become a second memory store.
 ## Recommended Vault
-Open the repository root as the Obsidian vault:
+Open the `vault/` folder as the Obsidian vault:
 ```text
-<workspace-root>/
+<workspace-root>/vault/
 ```
 This keeps one source of truth:
@@ -21,22 +21,34 @@ This keeps one source of truth:
 - OpenCode and agents maintain operational memory
 - Obsidian reads and edits the same Markdown files
 - Git tracks intentional memory and configuration changes
 - runtime evidence and generated artifacts stay outside the vault
 ---
 ## Source Of Truth
-Canonical memory remains in:
+Canonical human/AI memory lives in:
- `ai/logs/`
+- `vault/00-start/`
- `ai/state/`
+- `vault/01-current/`
- `ai/work-items/`
+- `vault/02-work-items/`
- `ai/context/`
+- `vault/03-context/`
- `knowledge/`
+- `vault/04-people/`
 - `vault/05-decisions/`
 - `vault/06-daily/`
 - `vault/07-maps/`
 Technical runtime remains outside the vault:
 - `.opencode/`
 - `scripts/`
 - `core/`
 - `profiles/`
 - `ai/inbox/`
 - `scripts/*/generated/`
 - archives and local virtual environments
-Obsidian-specific runtime files are not project memory.
+Legacy `ai/context`, `ai/state`, `ai/work-items`, `ai/logs`, and `knowledge` paths may exist temporarily as compatibility fallback during migration.
 ---
@@ -44,18 +56,21 @@ Obsidian-specific runtime files are not project memory.
 Version portable Obsidian configuration only when it improves the workspace for every clone:
- `.obsidian/app.json`
+- `vault/.obsidian/app.json`
- `.obsidian/core-plugins.json`
+- `vault/.obsidian/core-plugins.json`
- `.obsidian/graph.json`
+- `vault/.obsidian/graph.json`
- `.obsidian/appearance.json`
+- `vault/.obsidian/appearance.json`
 - `vault/.obsidian/daily-notes.json`
 - `vault/.obsidian/templates.json`
 - `vault/.obsidian/bookmarks.json`
 Do not version local runtime state:
- `.obsidian/workspace*.json`
+- `vault/.obsidian/workspace*.json`
- `.obsidian/workspace-mobile*.json`
+- `vault/.obsidian/workspace-mobile*.json`
- `.obsidian/plugins/`
+- `vault/.obsidian/plugins/`
- `.obsidian/snippets/`
+- `vault/.obsidian/snippets/`
- `.obsidian/cache/`
+- `vault/.obsidian/cache/`
 Recommended graph and search exclusions:
@@ -90,4 +105,32 @@ The agent should not treat Obsidian runtime layout changes as project context.
 If Obsidian metadata or properties are added, use them selectively for high-value notes such as work items, decisions, and index pages. Do not mass-convert existing files just to add metadata.
-Use map notes under `knowledge/maps/` as graph hubs. This keeps the graph navigable without forcing every file into Obsidian-specific wiki-link syntax.
+Use map notes under `vault/07-maps/` as graph hubs. This keeps the graph navigable without forcing every file into Obsidian-specific wiki-link syntax.
 ---
 ## Bases
 Keep Bases simple and property-driven:
 - work items filter on `type: work-item`
 - people filter on `type: person`
 - decisions filter on `type: decision`
 - daily notes filter on `type: daily`
 - systems filter on `type: system`
 - workstreams filter on `type: workstream`
 Do not use Bases for raw inboxes, generated evidence, scripts, or runtime logs.
 ---
 ## CLI Wrappers
 Use `scripts/obsidian/` for non-interactive Obsidian URI helpers:
 - `uri.sh` generates encoded Obsidian URIs.
 - `open.sh <vault-relative-path>` opens a note.
 - `daily.sh` opens the configured daily note.
 - `search.sh <query>` opens Obsidian search.
 The wrappers default to `vault/` and can be overridden with `AIW_OBSIDIAN_VAULT_DIR` and `AIW_OBSIDIAN_VAULT_NAME`.
--- a/core/memory/operational-memory.md
+++ b/core/memory/operational-memory.md
@@ -17,7 +17,7 @@ Use for same-day progress, findings, evolving reproduction notes, and work that
 Default path pattern:
 ```text
-ai/logs/YYYY-MM-DD.md
+vault/06-daily/YYYY-MM-DD.md
 ```
 ### `state`
@@ -27,8 +27,8 @@ Use for current priorities, active blockers, near-term constraints, and communic
 Default paths:
 ```text
-ai/state/current.md
+vault/01-current/current-work.md
-ai/state/work-items.md
+vault/01-current/work-items.md
 ```
 ### `work-items`
@@ -38,7 +38,7 @@ Use for canonical memory about active tickets, tasks, stories, investigations, o
 Default path pattern:
 ```text
-ai/work-items/<id-or-slug>.md
+vault/02-work-items/<id-or-slug>.md
 ```
 ### `stable-context`
@@ -48,7 +48,7 @@ Use for durable project knowledge that should survive beyond the current work wi
 Default path pattern:
 ```text
-ai/context/<domain>/*.md
+vault/03-context/<domain>/*.md
 ```
 ### `people`
@@ -58,7 +58,7 @@ Use for repeated collaborators, role mappings, manager/stakeholder context, and
 Default path pattern:
 ```text
-ai/context/people/*.md
+vault/04-people/*.md
 ```
 ### `decisions`
@@ -68,7 +68,7 @@ Use for confirmed decisions with ongoing impact.
 Default path pattern:
 ```text
-ai/context/decisions/*.md
+vault/05-decisions/*.md
 ```
 ### `tooling-behavior`
@@ -82,10 +82,12 @@ Default path patterns:
 .opencode/agents/*.md
 .opencode/skills/*/SKILL.md
 prompts/*.md
-knowledge/*.md
+vault/00-start/*.md
-ai/context/process/*.md
+vault/03-context/process/*.md
 ```
 Legacy `ai/*` and `knowledge/*` paths may remain as compatibility fallback, but new writes should target `vault/` first when a canonical note exists.
 ---
 ## Promotion Rules
@@ -135,4 +137,3 @@ Examples:
 - memory routing correction -> update memory rules and context-maintenance guidance
 The daily log may preserve evidence, but reusable behavior must live in the command, prompt, skill, agent, or knowledge file that enforces it.
--- a/core/profiles/create-project-profile.md
+++ b/core/profiles/create-project-profile.md
@@ -32,17 +32,24 @@ The profile should declare:
 Create or update:
 ```text
-ai/context/project.md
+vault/00-start/start-here.md
-ai/context/index.md
+vault/01-current/current-work.md
-ai/context/process/
+vault/01-current/work-items.md
-ai/context/people/
+vault/02-work-items/
-ai/state/current.md
+vault/03-context/project.md
-ai/state/work-items.md
+vault/03-context/process/
-ai/work-items/index.md
+vault/04-people/
 vault/05-decisions/
 vault/06-daily/
 vault/07-maps/
 vault/08-bases/
 vault/09-templates/
 ```
 Keep project-specific facts out of `core/`.
 Legacy `ai/context`, `ai/state`, `ai/work-items`, and `ai/logs` paths may be kept temporarily for compatibility, but new project profiles should treat `vault/` as canonical memory.
 ---
 ## 3. Configure Integrations
@@ -88,14 +95,15 @@ Before using the workspace for real work:
 ---
-## 6. Optional Obsidian Vault
+## 6. Obsidian Vault
-Open the workspace root as an Obsidian vault when you want a visual/manual navigation layer.
+Open `vault/` as the Obsidian vault.
 Recommended rules:
- keep the workspace filesystem as the single source of truth
+- keep `vault/` as the clean canonical human/AI memory
- do not copy memory into a separate Obsidian-only folder
+- keep runtime evidence, scripts, profiles, and generated files outside `vault/`
- version only portable `.obsidian` configuration
+- version only portable `vault/.obsidian` configuration
 - ignore local Obsidian workspace state and plugin runtime files
- create or update a vault map under `knowledge/` for human navigation
+- create or update map notes under `vault/07-maps/` for human navigation
 - create Bases under `vault/08-bases/` using simple `type` properties
--- a/opencode.json
+++ b/opencode.json
@@ -47,6 +47,34 @@
    "./core/integrations/obsidian-model.md",
    "./core/profiles/create-project-profile.md",
    "./profiles/fidelity/profile.md",
    "./vault/00-start/start-here.md",
    "./vault/00-start/onboarding.md",
    "./vault/00-start/glossary.md",
    "./vault/00-start/workspace-architecture.md",
    "./vault/01-current/current-work.md",
    "./vault/01-current/work-items.md",
    "./vault/07-maps/current-work.md",
    "./vault/07-maps/fidelity-domain.md",
    "./vault/07-maps/work-items.md",
    "./vault/07-maps/people.md",
    "./vault/03-context/project.md",
    "./vault/03-context/process/communication.md",
    "./vault/03-context/process/ai-to-ai-prompting.md",
    "./vault/03-context/process/jira-story-rules.md",
    "./vault/03-context/process/context-maintenance.md",
    "./vault/03-context/process/workspace-model.md",
    "./vault/03-context/process/agent-memory-rules.md",
    "./vault/03-context/process/memory-promotion-rules.md",
    "./vault/03-context/ios/index.md",
    "./vault/03-context/ios/current-practices.md",
    "./vault/03-context/ios/project-swift-guidance.md",
    "./vault/03-context/systems/index.md",
    "./vault/03-context/workstreams/index.md",
    "./vault/03-context/workstreams/flow-page-references.md",
    "./vault/04-people/manager.md",
    "./vault/04-people/index.md",
    "./vault/05-decisions/rest-vs-graphql.md",
    "./vault/05-decisions/discourse-handling.md",
    "./ai/context/index.md",
    "./ai/context/project.md",
    "./ai/context/ios/index.md",
--- a/profiles/example/profile.md
+++ b/profiles/example/profile.md
@@ -28,7 +28,8 @@ Non-sensitive example profile showing how a new project can reuse the workspace
 ## Work System
- Use `ai/work-items/` for active units of work
+- Use `vault/02-work-items/` for active units of work
 - Use `vault/01-current/work-items.md` for the active summary
 - Use any ticket ID format relevant to the project
 - Keep approved titles or explicit task names visible for recurring updates
@@ -36,7 +37,9 @@ Non-sensitive example profile showing how a new project can reuse the workspace
 ## Context
-Project-specific durable context should live under `ai/context/`.
+Project-specific durable context should live under `vault/03-context/`.
 People, decisions, daily notes, maps, and templates should live under the corresponding `vault/` folders.
 Do not place company secrets, raw exports, credentials, or private communication transcripts in the profile.
--- a/profiles/fidelity/profile.md
+++ b/profiles/fidelity/profile.md
@@ -43,16 +43,16 @@ Generic variables should be preferred for new setup:
 ## Work System
 - Work items are Jira-linked when available
- Active ticket memory lives in `ai/work-items/`
+- Active ticket memory lives in `vault/02-work-items/`
- Compact active summary lives in `ai/state/work-items.md`
+- Compact active summary lives in `vault/01-current/work-items.md`
 - Jira IDs and approved titles should remain visible for standups and manager updates
 ---
 ## Stakeholders
- Current manager mapping lives in `ai/context/people/manager.md`
+- Current manager mapping lives in `vault/04-people/manager.md`
- Person-specific collaboration context lives in `ai/context/people/`
+- Person-specific collaboration context lives in `vault/04-people/`
 - Manager-facing messages should be concise, explicit, and natural professional US English
 ---
@@ -61,12 +61,14 @@ Generic variables should be preferred for new setup:
 Core Fidelity context remains in:
- `ai/context/project.md`
+- `vault/03-context/project.md`
- `ai/context/systems/`
+- `vault/03-context/systems/`
- `ai/context/workstreams/`
+- `vault/03-context/workstreams/`
- `ai/context/ios/`
+- `vault/03-context/ios/`
- `ai/context/process/`
+- `vault/03-context/process/`
- `ai/context/decisions/`
+- `vault/05-decisions/`
 Legacy `ai/*` paths remain available only as compatibility fallback during migration.
 Important domain themes:
--- a/scripts/obsidian/daily.sh
+++ b/scripts/obsidian/daily.sh
@@ -0,0 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 VAULT_DIR="${AIW_OBSIDIAN_VAULT_DIR:-$WORKSPACE_ROOT/vault}"
 VAULT_NAME="${AIW_OBSIDIAN_VAULT_NAME:-$(basename "$VAULT_DIR")}"
 URI="$("$SCRIPT_DIR/uri.sh" daily "vault=$VAULT_NAME")"
 open "$URI"
--- a/scripts/obsidian/open.sh
+++ b/scripts/obsidian/open.sh
@@ -0,0 +1,16 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 VAULT_DIR="${AIW_OBSIDIAN_VAULT_DIR:-$WORKSPACE_ROOT/vault}"
 VAULT_NAME="${AIW_OBSIDIAN_VAULT_NAME:-$(basename "$VAULT_DIR")}"
 if [[ $# -lt 1 ]]; then
  echo "usage: open.sh <vault-relative-path>" >&2
  exit 1
 fi
 URI="$("$SCRIPT_DIR/uri.sh" open "vault=$VAULT_NAME" "file=$1")"
 open "$URI"
--- a/scripts/obsidian/search.sh
+++ b/scripts/obsidian/search.sh
@@ -0,0 +1,16 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORKSPACE_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 VAULT_DIR="${AIW_OBSIDIAN_VAULT_DIR:-$WORKSPACE_ROOT/vault}"
 VAULT_NAME="${AIW_OBSIDIAN_VAULT_NAME:-$(basename "$VAULT_DIR")}"
 if [[ $# -lt 1 ]]; then
  echo "usage: search.sh <query>" >&2
  exit 1
 fi
 URI="$("$SCRIPT_DIR/uri.sh" search "vault=$VAULT_NAME" "query=$*")"
 open "$URI"
--- a/scripts/obsidian/uri.sh
+++ b/scripts/obsidian/uri.sh
@@ -0,0 +1,22 @@
 #!/usr/bin/env bash
 set -euo pipefail
 python3 - "$@" <<'PY'
 import sys
 from urllib.parse import urlencode
 if len(sys.argv) < 2:
    raise SystemExit("usage: uri.sh <action> [key=value ...]")
 action = sys.argv[1]
 params = {}
 for item in sys.argv[2:]:
    if "=" not in item:
        raise SystemExit(f"invalid parameter: {item}")
    key, value = item.split("=", 1)
    params[key] = value
 print(f"obsidian://{action}?{urlencode(params)}")
 PY
--- a/vault/.obsidian/app.json
+++ b/vault/.obsidian/app.json
@@ -0,0 +1,10 @@
 {
  "attachmentFolderPath": "attachments",
  "newFileLocation": "current",
  "userIgnoreFilters": [
    "**/.venv/",
    "**/generated/",
    "**/__pycache__/",
    "**/*.pyc"
  ]
 }
--- a/vault/.obsidian/appearance.json
+++ b/vault/.obsidian/appearance.json
--- a/vault/.obsidian/bookmarks.json
+++ b/vault/.obsidian/bookmarks.json
@@ -0,0 +1,39 @@
 {
  "items": [
    {
      "type": "file",
      "path": "00-start/start-here.md",
      "title": "Start Here"
    },
    {
      "type": "file",
      "path": "00-start/onboarding.md",
      "title": "Onboarding"
    },
    {
      "type": "file",
      "path": "01-current/current-work.md",
      "title": "Current Work"
    },
    {
      "type": "folder",
      "path": "02-work-items",
      "title": "Work Items"
    },
    {
      "type": "folder",
      "path": "04-people",
      "title": "People"
    },
    {
      "type": "file",
      "path": "08-bases/work-items.base",
      "title": "Work Items Base"
    },
    {
      "type": "file",
      "path": "08-bases/people.base",
      "title": "People Base"
    }
  ]
 }
--- a/vault/.obsidian/core-plugins.json
+++ b/vault/.obsidian/core-plugins.json
@@ -27,7 +27,7 @@
  "workspaces": false,
  "file-recovery": true,
  "publish": false,
-  "sync": true,
+  "sync": false,
  "bases": true,
  "webviewer": false
-}
+}
--- a/vault/.obsidian/daily-notes.json
+++ b/vault/.obsidian/daily-notes.json
@@ -0,0 +1,5 @@
 {
  "format": "YYYY-MM-DD",
  "folder": "06-daily",
  "template": "09-templates/daily.md"
 }
--- a/vault/.obsidian/graph.json
+++ b/vault/.obsidian/graph.json
@@ -1,6 +1,6 @@
 {
  "collapse-filter": true,
-  "search": "-path:.git -path:.opencode/node_modules -path:ai/inbox -path:archives -path:scripts/mattermost/generated -path:scripts/slack/generated -path:scripts/mattermost/.venv -path:scripts/slack/.venv -path:generated -path:.venv -file:index -file:README -file:AGENTS -file:SKILL",
+  "search": "-path:generated -path:.venv -file:index -file:README -file:AGENTS -file:SKILL",
  "showTags": true,
  "showAttachments": false,
  "hideUnresolved": false,
@@ -22,18 +22,32 @@
      }
    },
    {
-      "query": "path:ai/work-items",
+      "query": "path:02-work-items",
      "color": {
        "a": 1,
        "rgb": 16753920
      }
    },
    {
-      "query": "path:ai/context/people",
+      "query": "path:04-people",
      "color": {
        "a": 1,
        "rgb": 10053324
      }
    },
    {
      "query": "path:05-decisions",
      "color": {
        "a": 1,
        "rgb": 16733525
      }
    },
    {
      "query": "path:03-context/systems OR path:03-context/workstreams",
      "color": {
        "a": 1,
        "rgb": 5793266
      }
    }
  ],
  "collapse-display": true,
@@ -48,4 +62,4 @@
  "linkDistance": 250,
  "scale": 2.0503081104007936,
  "close": true
-}
+}
--- a/vault/.obsidian/templates.json
+++ b/vault/.obsidian/templates.json
@@ -0,0 +1,3 @@
 {
  "folder": "09-templates"
 }
--- a/vault/00-start/glossary.md
+++ b/vault/00-start/glossary.md
@@ -0,0 +1,51 @@
 ---
 type: glossary
 audience: new-member
 tags:
  - onboarding
  - glossary
 ---
 # Glossary
 Common terms used in this workspace.
 ---
 ## Workspace Terms
 - `core`: reusable project-independent AI workspace logic.
 - `profile`: project-specific configuration and assumptions layered on top of the core.
 - `operational memory`: curated file-based memory that helps future AI sessions reason accurately.
 - `daily log`: same-day evidence and evolving findings in `vault/06-daily/`.
 - `state`: near-term active work and priorities in `vault/01-current/`.
 - `work item`: canonical memory for a ticket, story, task, or investigation in `vault/02-work-items/`.
 - `stable context`: durable project knowledge under `vault/03-context/`.
 - `inbox`: raw or lightly processed communication evidence under `ai/inbox/`.
 - `promotion`: moving high-confidence evidence into canonical memory.
 - `tooling behavior`: reusable behavior encoded in commands, prompts, skills, agents, or knowledge rules.
 ---
 ## Fidelity Terms
 - `Fid4`: main Fidelity consumer iOS app and key validation environment.
 - `XFlowSDK`: backend-driven UI engine that renders flows from service-provided configuration.
 - `XFlowViewMaker`: adapter layer historically involved in integration and release propagation.
 - `FTFrameworks`: feature modules such as account opening or transfer flows that can mediate XFlow adoption.
 - `AO`: account opening context; many reports require careful reproduction and scope validation.
 - `Discourse`: external issue/report source; treat reports as external until confirmed.
 - `REST migration`: migration away from GraphQL/Apollo toward REST, with REST behind a feature flag unless confirmed otherwise.
 - `authenticated flow`: behavior reproduced while signed in; often differs from non-authenticated behavior.
 - `entry point`: the path used to reach a flow, which can affect backend-driven behavior.
 - `Cogstore`: flow-configuration publishing and version-comparison platform.
 ---
 ## Communication Terms
 - `external report`: issue reported externally before regression status is confirmed.
 - `regression`: behavior confirmed to be newly broken relative to a known baseline.
 - `scope`: the exact affected flow, platform, auth state, environment, and ownership boundary.
 - `reproducibility`: whether the behavior can be repeated with known steps and context.
 - `manager-ready`: concise, explicit, natural professional English that can be sent without rewriting.
--- a/vault/00-start/obsidian-usage.md
+++ b/vault/00-start/obsidian-usage.md
@@ -0,0 +1,124 @@
 ---
 type: guide
 audience: workspace-user
 tags:
  - onboarding
  - obsidian
 ---
 # Obsidian Usage Guide
 Use Obsidian to navigate and review workspace memory. Do not use it as a separate memory database.
 ---
 ## Recommended Start
 Open the `vault/` folder as the Obsidian vault, not the repository root.
 Open:
 - [Obsidian Vault Map](start-here.md)
 - [New Member Onboarding](onboarding.md)
 - [Knowledge Maps](../07-maps/index.md)
 ---
 ## Best Views
 ### New Member View
 Start with:
 - [New Member Onboarding](onboarding.md)
 - [Glossary](glossary.md)
 - [Current Work Map](../07-maps/current-work.md)
 - [Fidelity Domain Map](../07-maps/fidelity-domain.md)
 ### Daily Work View
 Start with:
 - [Current Work Map](../07-maps/current-work.md)
 - [Work Items Map](../07-maps/work-items.md)
 - [Logs Index](../06-daily/index.md)
 ### System Understanding View
 Start with:
 - [Fidelity Domain Map](../07-maps/fidelity-domain.md)
 - [AI Workspace Core Map](../07-maps/ai-workspace-core.md)
 - [Tooling Map](../07-maps/tooling.md)
 ---
 ## Graph Guidance
 Use the graph to find clusters, not to infer truth.
 High-value graph hubs:
 - `start-here`
 - `onboarding`
 - `current-work`
 - `fidelity-domain`
 - `work-items`
 - `people`
 - `tooling`
 - `ai-workspace-core`
 If a node is isolated, it may still be valid. It may be:
 - a daily log
 - raw evidence
 - a command/prompt file
 - a file that needs to be linked from a map
 ---
 ## Global Graph Defaults
 The global graph is configured for onboarding and project navigation, not full filesystem inspection.
 It intentionally hides generic technical filenames such as:
 - `index`
 - `README`
 - `AGENTS`
 - `SKILL`
 Those files still exist and remain valid workspace files. They are hidden from the graph because Obsidian displays only the basename, which creates many indistinguishable nodes.
 Use the file explorer or search when you need a specific technical file. Use the graph when you want to understand relationships between project concepts.
 ---
 ## When To Show Technical Files
 Temporarily remove these filters from the graph search when debugging workspace internals:
 ```text
 -file:index -file:README -file:AGENTS -file:SKILL
 ```
 For normal onboarding, keep them hidden and navigate through the named maps.
 ---
 ## Editing Rules
 - Edit canonical memory files when the fact is clear.
 - Prefer updating existing notes over adding duplicate summaries.
 - Do not edit generated files as durable memory.
 - Do not treat inbox files as confirmed truth.
 - Use maps to improve navigation, not to store detailed facts.
 ---
 ## Daily Notes, Templates, And Bases
 - Daily notes live under `06-daily/` and use `09-templates/daily.md`.
 - Templates live under `09-templates/`.
 - Bases live under `08-bases/` and use simple `type` properties.
 - Bookmarks should keep `00-start/start-here.md`, `00-start/onboarding.md`, current work, work items, people, and high-value Bases easy to open.
--- a/vault/00-start/onboarding.md
+++ b/vault/00-start/onboarding.md
@@ -0,0 +1,92 @@
 ---
 type: onboarding
 audience: new-member
 tags:
  - onboarding
  - map
 ---
 # New Member Onboarding
 Use this guide when someone new needs to understand this workspace and the Fidelity project context quickly.
 This repository is not the product codebase. It is the AI workspace used to preserve context, navigate project memory, and draft precise communication.
 ---
 ## First 30 Minutes
 Read these in order:
 1. [Obsidian Vault Map](start-here.md)
 2. [Current Work Map](../07-maps/current-work.md)
 3. [Fidelity Domain Map](../07-maps/fidelity-domain.md)
 4. [Work Items Map](../07-maps/work-items.md)
 5. [People Map](../07-maps/people.md)
 Goal:
 - understand where current work lives
 - identify active tickets
 - understand the main systems and people
 - avoid treating raw logs or inbox evidence as confirmed durable truth
 ---
 ## First 60 Minutes
 Read:
 1. [Project Context](../03-context/project.md)
 2. [XFlowSDK](../03-context/systems/xflowsdk.md)
 3. [Fid4](../03-context/systems/fid4.md)
 4. [REST Migration](../03-context/workstreams/rest-migration.md)
 5. [AO And Discourse](../03-context/workstreams/ao-discourse.md)
 6. [Communication Rules](../03-context/process/communication.md)
 Goal:
 - understand why auth state, entry point, and backend configuration matter
 - distinguish external reports from regressions
 - understand why communication precision is part of the engineering workflow
 ---
 ## First 120 Minutes
 Read:
 1. [Memory Promotion Rules](../03-context/process/memory-promotion-rules.md)
 2. [Workspace Architecture](workspace-architecture.md)
 3. [Agent Memory Rules](../03-context/process/agent-memory-rules.md)
 4. [Context Maintenance](../03-context/process/context-maintenance.md)
 5. [Tooling Map](../07-maps/tooling.md)
 Goal:
 - understand how the AI workspace stays current
 - know where to add new facts
 - know when to update logs, state, work items, stable context, people, decisions, or tooling behavior
 ---
 ## Daily Workflow
 1. Start from [Current Work Map](../07-maps/current-work.md).
 2. Check [Current Work](../01-current/current-work.md).
 3. Open the active work item from [Work Items Map](../07-maps/work-items.md).
 4. Review the latest relevant log from [Logs Index](../06-daily/index.md).
 5. Use [Communication Rules](../03-context/process/communication.md) before writing standups, Jira comments, or manager updates.
 ---
 ## Rules Of Thumb
 - `vault/06-daily/` is evidence from a day.
 - `vault/01-current/` is what matters now.
 - `vault/02-work-items/` is canonical ticket memory.
 - `vault/03-context/` is durable project knowledge.
 - `vault/04-people/` is collaborator and role memory.
 - `core/` is reusable workspace logic.
 - `profiles/fidelity/` is Fidelity-specific configuration.
 - `ai/inbox/` and generated files are evidence, not promoted memory.
--- a/vault/00-start/start-here.md
+++ b/vault/00-start/start-here.md
@@ -0,0 +1,115 @@
 ---
 type: map
 audience: workspace-user
 tags:
  - map
  - obsidian
 ---
 # Start Here
 Use this note as the human navigation entry point when opening `vault/` as an Obsidian vault.
 ---
 ## Start Here
 - Repository README: `README.md`
 - [New Member Onboarding](onboarding.md)
 - [Glossary](glossary.md)
 - [Obsidian Usage Guide](obsidian-usage.md)
 - [Workspace Architecture](workspace-architecture.md)
 - [Knowledge Maps](../07-maps/index.md)
 ---
 ## Maps
 - [AI Workspace Core](../07-maps/ai-workspace-core.md)
 - [Current Work](../07-maps/current-work.md)
 - [Fidelity Domain](../07-maps/fidelity-domain.md)
 - [Work Items](../07-maps/work-items.md)
 - [People](../07-maps/people.md)
 - [Tooling](../07-maps/tooling.md)
 ---
 ## New Members
 If you are new to this project, read:
 1. [New Member Onboarding](onboarding.md)
 2. [Glossary](glossary.md)
 3. [Current Work Map](../07-maps/current-work.md)
 4. [Fidelity Domain Map](../07-maps/fidelity-domain.md)
 5. [People Map](../07-maps/people.md)
 6. [Workspace Architecture](workspace-architecture.md)
 ---
 ## Current Work
 - [Current State](../01-current/current-work.md)
 - [Active Work Items](../01-current/work-items.md)
 - [Work Item Index](../02-work-items/index.md)
 - [Logs Index](../06-daily/index.md)
 ---
 ## Stable Context
 - [Context Index](../03-context/index.md)
 - [Project Context](../03-context/project.md)
 - [Systems Index](../03-context/systems/index.md)
 - [Workstreams Index](../03-context/workstreams/index.md)
 - [People Index](../04-people/index.md)
 - [Manager Mapping](../04-people/manager.md)
 ---
 ## Process And Rules
 - [Workspace Model](../03-context/process/workspace-model.md)
 - [Agent Memory Rules](../03-context/process/agent-memory-rules.md)
 - [Memory Promotion Rules](../03-context/process/memory-promotion-rules.md)
 - [Communication Rules](../03-context/process/communication-rules.md)
 - [Context Maintenance](../03-context/process/context-maintenance.md)
 - [Workspace Architecture](workspace-architecture.md)
 ---
 ## Daily Logs
 Daily notes live in:
 ```text
 vault/06-daily/
 ```
 Use the latest dated note for recent evidence, but promote durable facts into `01-current/`, `02-work-items/`, or `03-context/` when they should survive beyond the day.
 - [Logs Index](../06-daily/index.md)
 ---
 ## Inbox And Generated Evidence
 Inbox and generated files are evidence, not durable memory by default.
 - `ai/inbox/`
 - `scripts/mattermost/generated/`
 - `scripts/slack/generated/`
 Promote only high-confidence, project-relevant facts into canonical memory.
 ---
 ## Canonical Vault Areas
 - [Current Work](../01-current/current-work.md)
 - [Work Items](../02-work-items/index.md)
 - [Fidelity Domain Map](../07-maps/fidelity-domain.md)
 - [People Map](../07-maps/people.md)
 - [Daily Notes](../06-daily/index.md)
 - [Bases](../08-bases/work-items.base)
 - [Templates](../09-templates/daily.md)
--- a/vault/00-start/workspace-architecture.md
+++ b/vault/00-start/workspace-architecture.md
@@ -0,0 +1,57 @@
 ---
 type: guide
 project: fidelity
 status: active
 updated: 2026-04-16
 tags: [onboarding, obsidian, workspace]
 related:
  - start-here.md
  - ../07-maps/ai-workspace-core.md
 ---
 # Workspace Architecture
 This repository has two layers:
 - `vault/` is the clean Obsidian second brain and canonical AI memory.
 - Everything outside `vault/` is technical runtime, reusable core, profile configuration, scripts, commands, prompts, or raw evidence.
 ---
 ## Canonical Memory
 Use these folders as the source of truth for humans and AI agents:
 - `00-start/` for onboarding and usage guidance
 - `01-current/` for current work state
 - `02-work-items/` for ticket/task memory
 - `03-context/` for systems, workstreams, process, and iOS context
 - `04-people/` for people and role memory
 - `05-decisions/` for confirmed decisions
 - `06-daily/` for daily notes
 - `07-maps/` for graph hubs
 - `08-bases/` for table-style review
 - `09-templates/` for note templates
 ---
 ## Runtime Outside The Vault
 These folders are intentionally outside Obsidian memory:
 - `.opencode/` stores agents and slash commands.
 - `core/` stores reusable workspace logic.
 - `profiles/` stores project-specific profile declarations.
 - `scripts/` stores connectors, importers, and wrappers.
 - `ai/inbox/` stores live evidence from communication sync.
 - `scripts/*/generated/` stores extracted evidence.
 Runtime and generated files can be used as evidence, but durable project facts should be promoted into `vault/`.
 ---
 ## Migration Rule
 Legacy `ai/context`, `ai/state`, `ai/work-items`, `ai/logs`, and `knowledge` files may still exist for compatibility.
 When a `vault/` equivalent exists, update `vault/` first.
--- a/vault/01-current/current-work.md
+++ b/vault/01-current/current-work.md
@@ -0,0 +1,87 @@
 ---
 type: current
 project: fidelity
 status: active
 updated: 2026-04-16
 tags:
  - current-work
  - fidelity
 ---
 # Current Work
 ## Focus
 - Keep Fidelity context current from daily work performed on another machine
 - Track REST migration findings
 - Debug Discourse and AO issues
 - Prepare better updates for the current manager or stakeholder through Mattermost
 - Follow up on active tickets through `vault/02-work-items/`, especially `PDIAP-14859`, `PDIAP-15765`, `PDIAP-15836`, and `PDIAP-15838`
 - Wrap up `PDIAP-14859` by publishing the approved rollout document, linking the spike-result documents and follow-up story, then closing the spike
 - After the immediate `PDIAP-14859` closeout and `PDIAP-15765` resume work, return to `PDIAP-15838`; `PDIAP-15836` comes later
 - Resume `PDIAP-15765` for the authenticated iOS-only `HybridYouthAccountOpening` / `TeenIdentityCheck` handling gap so iOS aligns with Android behavior
 - Keep the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario out of `PDIAP-15765` scope unless later evidence proves it belongs there
 - Include feature-flag planning for the broader UIKit-removal spike, including dismissal sequencing changes that affect consumers
 - Thoroughly verify current `ApexBridgingAddressComponent` / rule-loading usage before describing it as inactive or dead code
 - Reconcile the old UIKit address-rule path with the current SwiftUI handling path through the adapter/view-model layer before reporting final ownership or replacement guidance
 - The ApexKitV3 risk write-up for Quy has been published and sent; use that research as the current high-level framing for dependency-removal risk
 - Investigate the current XFlow dependency surface on `ApexKitV3`, including the `23` build errors on removal and the remaining `13` errors when swapping to `ApexKitSwiftUI`
 - The process-oriented rollout document for the UIKit-removal spike is approved and ready to publish for spike closure
 - The rollout document should frame the work as a more deliberate migration phase toward the SwiftUI-only path, not as a correction to a prior failed attempt
 - The rollout document uses a global feature-flag rollout model with broad XQ1 validation before production enablement
 - The rollout document should use the new flag name `xflow-swiftui-container-enabled` and note that the flag will be added later during implementation
 - Re-check the authenticated AO validation issue with scenario-specific evidence: the `HybridYouthAccountOpening` / `TeenIdentityCheck` path currently points to an iOS-only decoding gap, while a separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` case reproduces on both platforms
 - The immediate Youth issue was fixed on the service side for the Youth-flow `TeenIdentityCheck` path after the payload moved from `birthDate` to `validations`; local Fid4 validation also confirmed it. The XFlowSDK-side fallback PR should still ship in the next release
 - Jeff later decided the iOS fallback PR should be treated as the primary fix path for the Youth issue rather than relying on a separate service rollout; the QA-side service change has since been rolled back and Fid4 validation still passed with the PR in place
 - When describing the XFlowSDK fallback PR, frame it as a compatibility improvement for similar future `birthDate` payloads, not as a fix for the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue
 - The Youth / `TeenIdentityCheck` issue was iOS-only; do not describe it as reproducing on both platforms
 - The service-side payload update and the XFlowSDK fallback PR address the same Youth / `TeenIdentityCheck` issue; do not split them into separate Youth issues when summarizing scope
 - `PDIAP-15765` should stay out of Done until the PR is merged; Santosh approved it, but code-owner approval is still required before merge
 - Before closing out the AO thread, send one more working-group Teams reply that summarizes the original iOS issue, links the Jira comment, Discourse comment, and PR, and separates the remaining `HybridBrokerageAccountOpening` / `JointIdentityCheck` service-side issue
 - The `HybridBrokerageAccountOpening` / `JointIdentityCheck` rule-content issue appears unchanged between QA and Production in Cogstore and should be treated as the remaining service-side follow-up
 ---
 ## Active Concerns
 - Authenticated vs non-authenticated behavior
 - Reproducibility across entry points
 - Backend-driven inconsistencies in XFlow
 - Distinguishing external issues from true regressions
 - Preserving accurate context when summarizing work from another machine
 - Validating dismissal sequencing changes across SwiftUI flows
 - Keeping REST deprecation scope explicit while GraphQL fallback still exists
 - Defining a consumer rollout plan for UIKit-removal sequencing changes, including validation, communication, and feature-flag retirement
 - Closing `PDIAP-14859` cleanly with the right links, blocker relationship, and feature-flag wording
 - Avoiding assumptions when comparing iOS and Android validation behavior; scenario-specific parity needs to be confirmed before reporting scope
 - Avoiding assumptions about legacy Apex/ApexKit paths; breakpoint evidence and helper usage both need to be reconciled before reporting ownership or replacement guidance
 - When ownership is still uncertain under production pressure, prefer rollback-plus-investigation framing over confident blame assignment to consumers
 - Swift 6 migration risk is now time-sensitive because external dependency removal could break XFlow before the planned `26Q3` work
 - The write-up for Quy should remain the reference framing for moderate effort, medium risk, and required consumer validation while deeper implementation details are still being researched
 ---
 ## Communication Priorities
 - Standups should reflect the latest technical state, not generic progress
 - Standups should prefer updates directly tied to active work items over one-off memory refreshes or side questions
 - Standups should include story titles whenever a reported update maps to a Jira item
 - Standups should use bullet points for each item, but avoid dash-separated title formatting inside the sentence body
 - When one Jira item has multiple concrete updates, prefer one top-level Jira bullet with indented sub-bullets rather than repeating the same Jira line multiple times
 - When pairing a Jira ID with a title in standups, prefer a simple hyphen after the ID or omit punctuation instead of using commas
 - Standups should omit side questions or manager-only context refreshes unless they materially changed story work
 - If a root cause document or other documentation update directly supports a story, it should be reported under that story instead of as a separate standalone item
 - Standups should omit items not tied to a story unless they are real blockers
 - If a new request is important work but not directly tied to a Jira item, include it as a standalone bullet instead of forcing it under a story
 - Manager updates should be short, precise, and natural in English
 - Mattermost messages should make scope and next action explicit
 - When root cause is not fully isolated, do not position framework conclusions as authoritative consumer-side fault
 - Standups should be written as David's external progress report and should not mention Jeff by name
 - Standups should never mention Mattermost because it is internal-only communication
 ---
 ## Notes
 - REST remains behind a feature flag
 - Validate against main before calling something a regression
 - This workspace is the context source for communication, not the source of product code changes
--- a/vault/01-current/work-items.md
+++ b/vault/01-current/work-items.md
@@ -0,0 +1,35 @@
 ---
 type: current-work-items
 project: fidelity
 status: active
 updated: 2026-04-16
 tags:
  - current-work
  - work-item
  - fidelity
 ---
 # Active Work Items
 Use this file as the quick summary for active Jira-linked work.
 Detailed ticket memory now lives under `vault/02-work-items/`.
 Update the per-ticket files first when scope, status, sequencing, or communication framing changes materially.
 ## Current
 - `PDIAP-14859` - Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation
  Detail: `vault/02-work-items/pdiap-14859.md`
  Current note: the impact write-up is published, and the rollout document is approved for publication; update it to use the new flag name `xflow-swiftui-container-enabled` with a note that it will be added later during implementation, then publish and close out the spike with `Spike Results:` links.
 - `PDIAP-15838` - Remove Apollo for iOS
  Detail: `vault/02-work-items/pdiap-15838.md`
  Current note: approved at `8` points and next to work on; keep it separate from the UIKit-removal spike.
 - `PDIAP-15836` - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment
  Detail: `vault/02-work-items/pdiap-15836.md`
  Current note: approved at `8` points, rooted in the AccountLink dismissal sequencing investigation, and sequenced after `PDIAP-15838`.
 - `PDIAP-15765` - AO DOB field error not showing investigation
  Detail: `vault/02-work-items/pdiap-15765.md`
  Current note: a small XFlowSDK PR is open for the iOS `birthDate` fallback, the immediate `HybridYouthAccountOpening` / `TeenIdentityCheck` issue appears fixed on the service side, and the separate cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` case remains out of scope for this fix.
--- a/vault/02-work-items/README.md
+++ b/vault/02-work-items/README.md
@@ -0,0 +1,25 @@
 # Work Items
 ## Goal
 Keep active Jira-linked work in one canonical place so standups, manager updates, and memory syncs can reference each ticket precisely.
 ---
 ## Structure
 - `index.md`
  Active index and quick status view.
 - `<jira-id>.md`
  Canonical file for a specific ticket.
 ---
 ## Update Rules
 - Use one file per active or recently relevant Jira item.
 - Keep titles exact when approved or explicitly confirmed.
 - If the title is not confirmed, store the Jira ID and current framing without inventing a final title.
 - Update the ticket file when scope, sequencing, points, status, rollout implications, or reproducibility meaningfully change.
 - Keep `vault/01-current/work-items.md` as a short bridge summary, not the primary source of detailed ticket context.
--- a/vault/02-work-items/index.md
+++ b/vault/02-work-items/index.md
@@ -0,0 +1,39 @@
 ---
 type: work-item-index
 project: fidelity
 updated: 2026-04-16
 tags:
  - work-item
  - map
 ---
 # Work Item Index
 ## Goal
 Provide a quick view of active and recently relevant Jira-linked work while keeping the full detail in one file per ticket.
 ---
 ## Active
 - [pdiap-14859.md](./pdiap-14859.md)
  `PDIAP-14859` `Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation` spike wrap-up work around dual UIKit/SwiftUI support, dynamic `UIHostingController` removal, consumer rollout planning, and linking the final result documents.
 - [pdiap-15838.md](./pdiap-15838.md)
  `PDIAP-15838` next story to work on; approved scope removes Apollo and GraphQL-specific iOS transport code while leaving REST.
 - [pdiap-15836.md](./pdiap-15836.md)
  `PDIAP-15836` approved follow-up story for dismissal delegate lifecycle sequencing in pure SwiftUI; comes after `PDIAP-15838`.
 ## Active / Reopened
 - [pdiap-15765.md](./pdiap-15765.md)
  `PDIAP-15765` authenticated-only DOB issue in `HybridYouthAccountOpening` / `TeenIdentityCheck`; reopened around the iOS-only handling gap while the separate cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario stays out of scope.
 ---
 ## Usage
 - Read this file first for active ticket context.
 - Open the specific ticket file when you need exact scope, sequencing, or communication wording.
 - Update the per-ticket file first when ticket context changes materially.
--- a/vault/02-work-items/pdiap-14859.md
+++ b/vault/02-work-items/pdiap-14859.md
@@ -0,0 +1,61 @@
 ---
 type: work-item
 project: fidelity
 status: active
 ticket: PDIAP-14859
 title: "Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation"
 updated: 2026-04-16
 tags:
  - work-item
  - fidelity
 ---
 # PDIAP-14859 - Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation
 ## Status
 - Active
 - Rollout draft prepared and sent to Jeff for review on April 13, 2026
 - Rollout document approved for publication; publish and close out the spike next
 ---
 ## Current Framing
 - Approved title: `Spike - Research strategy to remove final UIKit wrapping from XFlowSDK and XFlowViewMaker without disrupting consumer implementation`.
 - This work is currently framed in the workspace as a dual UIKit/SwiftUI plan that removes `UIHostingController` dynamically while preserving both flows appropriately.
 - The remaining deliverable is process-oriented, not just technical implementation.
 ---
 ## Current Scope
 - Define a consumer-facing rollout plan for the broader UIKit-removal work.
 - Preserve both UIKit and SwiftUI paths appropriately while introducing the new path safely.
 - Cover risky entry points such as `FTTransfer`, while keeping the latest spike finding explicit that consumer-side changes there may no longer be strictly required after the SwiftUI dismissal behavior is applied correctly.
 - Include validation expectations in `XQ1`.
 - Use a global feature-flag rollout model rather than entry-point-based enablement.
 - Include consumer communication expectations.
 - Include a 30-day production period with no reported bugs before final removal.
 - Include a follow-up release to remove the feature flag and old code after rollout confidence is achieved.
 ---
 ## Notes
 - The feature-flag and rollout planning guidance applies to the broader UIKit-removal spike, not only to dismissal-sequencing work.
 - Jeff suggested sending the process-oriented rollout document to Quy for feedback when ready.
 - The draft shared with Jeff already reflects the global feature flag, broad `XQ1` validation, and consumer-facing rollout flow guidance.
 - Additional review feedback from April 13: rename the proposed flag to `xflow-swiftui-enabled`, make consumer contact and `XQ1` validation explicit in the first phase, remove overly technical rollout wording, and avoid implying there are no consumer-side changes without qualification.
 - On April 14, Jeff asked whether the FTTransfer part of the rollout document also needed updating; David confirmed the document had already been revised to clarify that root-cause section.
 - April 15 clarification: do not reuse the existing SwiftUI LaunchDarkly flag for this rollout.
 - The new flag name for this work should be `xflow-swiftui-container-enabled`.
 - The document should note that the flag is `to be added in the future as part of implementation`.
 - Late April 14 guidance: the document was approved late in the day; the next step is to publish it, then close out the spike by commenting `Spike Results:` with the relevant document links and the new follow-up story link.
 - The new follow-up story should also be marked as a blocker for the reopened UIKit-removal story.
 ---
 ## Related Work
 - Related consumer rollout thinking should stay aligned with `PDIAP-15836`.
 - `PDIAP-15838` should not be framed as part of this UIKit-removal spike.
--- a/vault/02-work-items/pdiap-15765.md
+++ b/vault/02-work-items/pdiap-15765.md
@@ -0,0 +1,72 @@
 ---
 type: work-item
 project: fidelity
 status: active
 ticket: PDIAP-15765
 title: "AO DOB field error not showing investigation"
 updated: 2026-04-16
 tags:
  - work-item
  - fidelity
 ---
 # PDIAP-15765 - AO DOB field error not showing investigation
 ## Status
 - Active again
 - Move back to In Progress on the next workday
 - Small XFlowSDK compatibility PR opened for the iOS-side fix
 - PR has Santosh approval, but still needs code-owner approval before merge and story completion
 ---
 ## Context
 - This ticket is tied to an AO DOB validation issue.
 - The issue was confirmed for authenticated users in the `HybridYouthAccountOpening` flow on the `TeenIdentityCheck` page.
 ---
 ## Confirmed Findings
 - The issue reproduces only for authenticated users based on the currently stored evidence.
 - The Youth / `TeenIdentityCheck` scenario is the iOS-only issue; do not describe it as reproducing on Android.
 - Root cause was documented.
 - The original external report was incomplete.
 - For the config discussion, `CheckIdentity` was already correct. The `TeenIdentityCheck` issue had two config gaps inside `validation-rules`: the root key should be `validations`, and the age gate also needs `eighteenOrAbove` there when that rule is required.
 - Follow-up validation on April 13 showed two distinct authenticated scenarios rather than one uniform cross-platform issue.
 - A `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario reproduces on both iOS and Android.
 - A `HybridYouthAccountOpening` / `TeenIdentityCheck` scenario works on Android but fails on iOS.
 - Current evidence suggests Android is more flexible in how it decodes rule variations, while iOS is stricter about the expected `validation-rules` structure.
 - Later validation on April 15 showed the original `HybridYouthAccountOpening` / `TeenIdentityCheck` issue no longer reproduces once the payload uses `validations` instead of `birthDate`.
 - A minimal XFlowSDK fix was still prepared on April 15 so the iOS `.apxDateSelect` path also falls back to `birthDate` for a future release.
 - Jeff confirmed on April 15 that this minimal iOS fallback is the right fix direction for the Youth / `TeenIdentityCheck` case and approved opening the PR under the same story.
 - On April 16, Jeff decided the iOS PR should be the primary fix path for the Youth / `TeenIdentityCheck` issue rather than relying on a separate service rollout.
 ---
 ## Current Guidance
 - Treat the iOS-only `HybridYouthAccountOpening` / `TeenIdentityCheck` discrepancy as the main client-side issue currently aligned with the story.
 - Keep the cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario separate until it is clear whether it is a service/config issue, a distinct bug, or an unreported rule-processing difference.
 - Keep the authenticated-user qualifier whenever this ticket is mentioned.
 - Do not describe it as a generic validation issue without the `TeenIdentityCheck` and auth context.
 - The originally reported Youth issue was fixed for the Youth-flow `TeenIdentityCheck` path by the service-side payload update from `birthDate` to `validations`; local Fid4 validation also confirmed it. The XFlowSDK fallback PR should still be released so iOS handles the older `birthDate` format more safely.
 - That service-side Youth fix was later rolled back in QA so the iOS PR can remain the single fix path; local Fid4 validation with the PR still confirmed the `birthDate` validation works correctly.
 - Jeff provided historical context that these fallback paths exist largely to accommodate older AO payload conventions; when the issue is AO-specific, iOS-only, and caused by a service-vs-SDK key mismatch, this kind of iOS fallback is the usual fix.
 - The `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue is different from the original Youth report: the rule content itself does not include `ageRange` or `eighteenOrAbove`, so that path still points to a service-side update rather than the same iOS parsing gap.
 - David compared `HybridBrokerageAccountOpening` / `JointIdentityCheck` in Cogstore and found the relevant rule content is the same in QA and Production despite different flow-definition versions, so that separate issue should also exist in Production.
 - The small iOS PR should be described as a compatibility safeguard for future older-format payloads and should not be framed as applying to the `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue.
 - The service-side `birthDate` -> `validations` change and the small iOS PR both relate to the same Youth / `TeenIdentityCheck` issue; they should not be described as separate Youth issues.
 ---
 ## Next Step
 - Get the small XFlowSDK compatibility PR reviewed and released.
 - Send one more AO working-group Teams summary that points to the Jira comment, Discourse comment, and PR while keeping the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue clearly out of the original Youth-fix scope.
 - Keep the final AO working-group message very explicit about there being two flow scenarios: the Youth iOS-only issue now handled by the service change plus iOS fallback, and the separate cross-platform `HybridBrokerageAccountOpening` / `JointIdentityCheck` service-side issue.
 - Update that AO working-group message so it now reflects the final framing: the original Youth issue is fixed on the iOS side, and the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` issue is the remaining service-side follow-up.
 - Close the story with comments explaining that the immediate Youth issue was resolved on the service side and that the XFlowSDK fallback fix will be available in the next release.
 - Keep the separate `HybridBrokerageAccountOpening` / `JointIdentityCheck` scenario out of the client-fix scope unless later evidence proves it is part of the same issue.
 - Consider a separate follow-up ticket for the cross-platform service-side issue if that path still stands after consumer confirmation.
--- a/vault/02-work-items/pdiap-15836.md
+++ b/vault/02-work-items/pdiap-15836.md
@@ -0,0 +1,49 @@
 ---
 type: work-item
 project: fidelity
 status: active
 ticket: PDIAP-15836
 title: "Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment"
 updated: 2026-04-16
 tags:
  - work-item
  - fidelity
 ---
 # PDIAP-15836 - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI environment
 ## Status
 - Approved
 - Sequenced after `PDIAP-15838`
 - Sized at `8` points
 ---
 ## Context
 - This story came out of the `AccountLink` root cause investigation.
 - It is tied to the dismissal sequencing problem found after UIKit removal in SwiftUI-only paths.
 - The root cause document was updated and the revised wording was approved.
 ---
 ## Approved Scope
 - Modernize dismissal delegate lifecycle sequencing for pure SwiftUI flows.
 - Cover the missing lifecycle contract where delegate callbacks can happen before the view is fully removed.
 - Validate the change across affected SwiftUI flows rather than only in one narrow reproduction.
 ---
 ## Sequencing And Dependencies
 - This story should come after `PDIAP-15838`.
 - It is aligned with epic `26Q2 - Updating XFlowSDK to Decouple and Fix ApexKit Dependencies (Split Part 2)`.
 - If possible, it should use the same consumer-impact feature flag strategy as the broader UIKit-removal rollout.
 ---
 ## Communication Notes
 - Keep the scope framed as lifecycle sequencing in a pure SwiftUI environment, not only as a symptom like multiple modal presentation.
 - If mentioned externally, keep it separate from `PDIAP-15838`.
--- a/vault/02-work-items/pdiap-15838.md
+++ b/vault/02-work-items/pdiap-15838.md
@@ -0,0 +1,48 @@
 ---
 type: work-item
 project: fidelity
 status: active
 ticket: PDIAP-15838
 title: "Remove Apollo for iOS"
 updated: 2026-04-16
 tags:
  - work-item
  - fidelity
 ---
 # PDIAP-15838 - Remove Apollo for iOS
 ## Status
 - Approved
 - Next story to work on
 - Sized at `8` points
 ---
 ## Context
 - This ticket covers the REST migration cleanup on iOS.
 - The approved title is `Remove Apollo for iOS`.
 ---
 ## Approved Scope
 - Remove Apollo from iOS.
 - Remove GraphQL-specific networking code.
 - Remove related tests and mocks.
 - Remove transport feature flags so REST remains.
 ---
 ## Current Guidance
 - Do not frame this ticket as directly tied to the UIKit-removal spike.
 - Do not imply it is dependent on or part of dismissal-sequencing work.
 - Keep the migration framing explicit: REST remains behind a feature flag until otherwise confirmed, and GraphQL fallback context still matters when describing the overall migration.
 ---
 ## Sequencing
 - This is the next story to work on before `PDIAP-15836`.
--- a/vault/03-context/index.md
+++ b/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.
--- a/vault/03-context/ios/current-practices.md
+++ b/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/`
--- a/vault/03-context/ios/index.md
+++ b/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.
--- a/vault/03-context/ios/project-swift-guidance.md
+++ b/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.
--- a/vault/03-context/process/agent-memory-rules.md
+++ b/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.
--- a/vault/03-context/process/ai-to-ai-prompting.md
+++ b/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."
--- a/vault/03-context/process/communication-rules.md
+++ b/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.
--- a/vault/03-context/process/communication.md
+++ b/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.
--- a/vault/03-context/process/context-maintenance.md
+++ b/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.
--- a/vault/03-context/process/index.md
+++ b/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`.
--- a/vault/03-context/process/jira-story-rules.md
+++ b/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.
--- a/vault/03-context/process/memory-promotion-rules.md
+++ b/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
--- a/vault/03-context/process/pull-requests.md
+++ b/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.
--- a/vault/03-context/process/workspace-model.md
+++ b/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.
--- a/vault/03-context/project.md
+++ b/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`
--- a/vault/03-context/systems/cogstore.md
+++ b/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.
--- a/vault/03-context/systems/fid4.md
+++ b/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.
--- a/vault/03-context/systems/ftframeworks.md
+++ b/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.
--- a/vault/03-context/systems/index.md
+++ b/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.
--- a/vault/03-context/systems/xflowsdk.md
+++ b/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.
--- a/vault/03-context/systems/xflowviewmaker.md
+++ b/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.
--- a/vault/03-context/workstreams/ao-discourse.md
+++ b/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.
--- a/vault/03-context/workstreams/consumer-integration.md
+++ b/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.
--- a/vault/03-context/workstreams/flow-page-references.md
+++ b/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.
--- a/vault/03-context/workstreams/index.md
+++ b/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.
--- a/vault/03-context/workstreams/rest-migration.md
+++ b/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.
--- a/vault/03-context/workstreams/xflow-debugging.md
+++ b/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.
--- a/vault/03-context/workstreams/xflow-swiftui-migration.md
+++ b/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.
--- a/vault/04-people/README.md
+++ b/vault/04-people/README.md
@@ -0,0 +1,27 @@
 ---
 type: people-index
 project: fidelity
 updated: 2026-04-16
 tags:
  - people
  - map
 ---
 # People Context
 Store reusable human context here.
 Use this directory for:
 - who is who
 - current role ownership
 - communication preferences
 - recurring stakeholders
 - stable relationship between people and project work
 Guidelines:
 - use one file per named person when that person matters repeatedly
 - keep `manager.md` as the role mapping for the current active manager
 - keep `index.md` as the quick roster for the active project
 - do not put secrets here
 - do not invent roles; use qualifiers when uncertain
--- a/vault/04-people/aylwing-olivas.md
+++ b/vault/04-people/aylwing-olivas.md
@@ -0,0 +1,34 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Aylwing Olivas
 ## Role
 Repeated Fidelity collaborator visible across multiple historical Slack channels.
 ---
 ## Known Context
 - Appears in technical discussions about XFlow, SwiftUI limitations, navigation architecture, and dependency risk
 - Surfaces cross-team constraints such as security or token access issues affecting pipeline work
 - Frequently adds architectural framing rather than only status updates
 - Often reframes implementation problems at the architecture/system-design level rather than the ticket level
 - Repeatedly advised on state machines, navigation architecture, off-screen rendering, and long-term maintainability tradeoffs
 - Common escalation point when the team needs a technical sounding board or higher-level design critique
 ---
 ## Guidance
 - Treat Aylwing as a useful source for higher-level technical framing and dependency risk context
 - Treat Aylwing as a strong reviewer for architecture direction, refactor scope, and risk framing
 - If future context clarifies the formal team or title, update this file directly
--- a/vault/04-people/bruce-meeks.md
+++ b/vault/04-people/bruce-meeks.md
@@ -0,0 +1,31 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Bruce Meeks
 ## Role
 Repeated Fidelity collaborator in XFlow-related work.
 ---
 ## Known Context
 - Reviewed and approved XFlow work repeatedly in historical threads
 - Sometimes covered XFlow iOS issues while others were unavailable
 - Later context suggests Bruce primarily worked on Android while still remaining a useful cross-platform contact
 - Relevant in release coordination, PR review, and parity discussions between iOS and Android
 ---
 ## Guidance
 - Treat Bruce as a useful source for cross-platform context and historical PR/review state
 - If future context clarifies the formal role/team, update this file directly
--- a/vault/04-people/david-delagneau.md
+++ b/vault/04-people/david-delagneau.md
@@ -0,0 +1,33 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # David Delagneau
 ## Role
 Repeated Fidelity collaborator in historical Slack threads.
 ---
 ## Known Context
 - Appears heavily in pipeline, Jenkins, SonarQube, test-reporting, and release-process work
 - Later historical activity also includes Sparta SDK proof-of-concept implementation and framework setup work
 - Often provides implementation updates, process notes, and operational debugging context to Jeff
 - Frequently handled CI/CD, Jenkins, reporting, and repo/setup tasks while Norman focused on SDK and consumer debugging
 - Later archive activity shows him taking lead on SpartaSDK setup, JSON decoding, and repo/bootstrap work
 ---
 ## Guidance
 - Treat David as a relevant source for CI/CD, release-process, and framework-setup context
 - Treat David as especially relevant for Jenkins, SonarQube, Pod/repo setup, and Sparta SDK bootstrapping context
 - If future context clarifies the formal role or team, update this file directly
--- a/vault/04-people/derian-cordoba.md
+++ b/vault/04-people/derian-cordoba.md
@@ -0,0 +1,33 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Derian Cordoba
 ## Role
 Historical Fidelity collaborator in project support discussions.
 ---
 ## Known Context
 - Appears in historical pipeline, Jenkins, and documentation conversations
 - Helped document pipeline work and supported notification/credential troubleshooting
 - Collaboration signal is real but current formal role remains unclear from the archive
 - Often paired with David on CI/CD and notification-related work
 - Showed up when the team needed operational documentation, release-process notes, or pipeline triage support
 ---
 ## Guidance
 - Treat Derian as a relevant collaborator for historical pipeline/debugging context
 - Treat Derian as most relevant for historical CI/CD coordination and documentation support
 - If future context clarifies the formal role or team, update this file directly
--- a/vault/04-people/erik-reynolds.md
+++ b/vault/04-people/erik-reynolds.md
@@ -0,0 +1,34 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Erik Reynolds
 ## Role
 Historical Fidelity collaborator in XFlow-related discussions.
 ---
 ## Known Context
 - Appears in discussions about XFlow manager behavior, consumer-vs-framework boundaries, and migration constraints
 - Raises implementation and sizing concerns in architecture-heavy conversations
 - Often comments on where responsibility lies between XFlow and consuming teams
 - Deep archive signal suggests strong familiarity with XFlow and Apex internals, especially ownership boundaries and migration tradeoffs
 - Often challenged weak assumptions about architecture, sizing, and framework responsibilities
 - Useful source when deciding whether a problem belongs in XFlow, Apex, or the consumer app
 ---
 ## Guidance
 - Treat Erik as a relevant source when historical context touches XFlow ownership boundaries or migration difficulty
 - Treat Erik as a high-signal source for framework architecture and responsibility boundaries
 - If future context clarifies the formal role or team, update this file directly
--- a/vault/04-people/gurram-santosh.md
+++ b/vault/04-people/gurram-santosh.md
@@ -0,0 +1,35 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Gurram Santosh
 ## Role
 Project-related contact involved in issue discussions.
 The exact formal role is not yet confirmed in workspace memory.
 ---
 ## Known Context
 - Repeatedly appears in AO-related testing, screenshot validation, and issue verification conversations
 - Often serves as a consumer-side validator or reporter when the team needs confirmation that a fix worked in their environment
 - Relevant when tracking whether an issue still reproduces, whether a release build contains a fix, or whether additional consumer validation is needed
 ---
 ## Guidance
 If future communication makes Santosh's role explicit, update this file with:
 - team or function
 - relationship to Fidelity work
 - whether the person is a reporter, tester, partner, or stakeholder
--- a/vault/04-people/index.md
+++ b/vault/04-people/index.md
@@ -0,0 +1,61 @@
 ---
 type: people-index
 project: fidelity
 updated: 2026-04-16
 tags:
  - people
  - map
 ---
 # People Index
 ## Active Roles
 - Manager: [jeff-dewitte.md](./jeff-dewitte.md)
 ## Known People
 - [jeff-dewitte.md](./jeff-dewitte.md)
  Current direct manager for the active Fidelity project; repeated communication gatekeeper and scope shaper in historical XFlow work.
 - [norman-arauz.md](./norman-arauz.md)
  Frequent XFlow collaborator in historical Slack threads; primary implementer/investigator across SwiftUI, AO/Fid4 bugs, and release work.
 - [david-delagneau.md](./david-delagneau.md)
  Repeated historical collaborator on pipeline, CI/CD, and Sparta/SwiftUI proof-of-concept work, especially around Jenkins, reporting, and framework setup.
 - [bruce-meeks.md](./bruce-meeks.md)
  Repeated XFlow collaborator who often reviewed PRs, covered iOS work during absences, and later shifted primarily toward Android.
 - [jason-mandozzi.md](./jason-mandozzi.md)
  Repeated collaborator tied to XFlowViewMaker, FTPlanning/Fid4 integration, release support, and major architectural transitions.
 - [aylwing-olivas.md](./aylwing-olivas.md)
  Repeated historical collaborator who surfaces architectural concerns, SwiftUI constraints, and cross-team dependency risks.
 - [erik-reynolds.md](./erik-reynolds.md)
  Historical collaborator focused on XFlow manager behavior, integration boundaries, migration effort sizing, and framework responsibility boundaries.
 - [gurram-santosh.md](./gurram-santosh.md)
  AO-related contact who often validates fixes or confirms whether issues still reproduce in consumer environments.
 - [raj-sundararaj.md](./raj-sundararaj.md)
  Repeated collaborator involved in AO issue triage, release coordination, and backlog/story management around XFlow work.
 - [quy-mai.md](./quy-mai.md)
  Scrum/contact point who repeatedly managed backlog state, points, and closure expectations for Fidelity work.
 - [tim-longfield.md](./tim-longfield.md)
  FTPlanning-side contact relevant when issues crossed from XFlow into consumer-framework ownership.
 - [derian-cordoba.md](./derian-cordoba.md)
  Historical collaborator in pipeline and documentation work, especially around CI/CD support and operational notes.
 ## Usage
 When a person appears repeatedly in project communication, create or update their file here so the agent can reuse:
 - name
 - role
 - relationship to the project
 - communication expectations
 - important context about how they influence work
--- a/vault/04-people/jason-mandozzi.md
+++ b/vault/04-people/jason-mandozzi.md
@@ -0,0 +1,31 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Jason Mandozzi
 ## Role
 Repeated Fidelity collaborator in XFlow and consumer-integration work.
 ---
 ## Known Context
 - Closely associated with XFlowViewMaker, Fid4/FTPlanning integration, and release/version work
 - Frequently authored or owned implementation branches later reviewed by others
 - Showed up repeatedly in architecture, eventing, navigation, and consumer-facing integration discussions
 - Often served as an important source of context on historical implementation choices inside XFlow and related consumer flows
 ---
 ## Guidance
 - Treat Jason as a high-signal source for XFlowViewMaker and consumer integration history
 - If future context clarifies the formal role/team, update this file directly
--- a/vault/04-people/jeff-dewitte.md
+++ b/vault/04-people/jeff-dewitte.md
@@ -0,0 +1,74 @@
 ---
 type: person
 project: fidelity
 role: manager
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Jeff DeWitte
 ## Role
 Current direct manager for the active Fidelity project.
 ---
 ## Historical Collaboration Pattern
 - Repeatedly acted as reporting manager, reviewer, and communication gatekeeper across multi-year XFlow work
 - Frequently rewrote PR descriptions, Jira updates, and cross-team messages before they were sent
 - Regularly redirected work based on release risk, consumer pressure, or manager/stakeholder expectations
 - Often pushed for explicit distinction between framework bugs, consumer bugs, service issues, and scope creep
 ---
 ## Communication Requirements
 - Native US English
 - Prefers clear, concise updates
 - Needs accurate scope, not vague reassurance
 - Frequently asks for precise reproducibility, auth context, and regression scope
 ---
 ## What Good Updates Include
 1. Context
 2. Observation
 3. Action
 Good updates usually clarify:
 - what issue or task is being discussed
 - whether the behavior is reproducible
 - whether auth state matters
 - whether this looks like an external issue or a regression
 - what the next step is
 ---
 ## Influence On Work
 - Story titles, points, and scope discussions with Jeff are often worth remembering
 - Jeff approvals can change what belongs in current state or work-item memory
 - Jeff feedback is often a signal to tighten wording before communicating externally
 - Jeff often asks for evidence, reproduction detail, and exact next action before approving external communication
 - If a draft is still ambiguous, Jeff may prefer to rewrite it directly so the external version is unambiguous and does not generate avoidable follow-up
 ---
 ## Repeated Coaching / Expectations
 - Test in the closest real consumer environment first when the issue is consumer-specific; use sample app mainly to rule ownership in or out
 - Do not open or socialize a PR as "ready" until the issue is fully resolved and no obvious follow-up bug has been introduced
 - Separate current-ticket scope from unrelated preexisting bugs; do not blur them in standups or status updates
 - Be explicit about environment, branch/build/version, account, flow entry point, and repro steps before concluding where a bug belongs
 - When blocked, keep reducing uncertainty with other available evidence sources instead of waiting passively
 - Fast admin/process actions matter: update Jira/status/comments promptly when others are visibly waiting on them
 - Prefer evidence-heavy communication: screenshots, videos, exact error text, branch/version, and direct comparisons to main/web/UIKit/Fid4 when relevant
 - Use polished native-sounding English for external-facing comments; avoid sending rough wording when a cleaner version is easy to produce
 - When a consumer issue may actually belong to another team/framework, document the finding clearly and route ownership instead of carrying it indefinitely in XFlow
 - For cross-team status messages, make the sequence of events extremely explicit so the reader can tell what was the original issue, what changed, what XFlow changed, and what remains a separate service-side issue
--- a/vault/04-people/manager.md
+++ b/vault/04-people/manager.md
@@ -0,0 +1,40 @@
 ---
 type: person
 project: fidelity
 role: manager
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Manager
 ## Current Holder
 - Name: Jeff DeWitte
 - Profile: [jeff-dewitte.md](./jeff-dewitte.md)
 ---
 ## Role
 Direct supervisor or primary reporting manager for the active project.
 ---
 ## Usage
 This file maps the current project role to the actual person.
 If the active manager changes in a future project, update this file to point to the new person while preserving their person-specific profile separately.
 ---
 ## Default Communication Requirements
 - Clear written English
 - Concise updates
 - Explicit scope
 - No vague reassurance
 - Useful next action when relevant
--- a/vault/04-people/norman-arauz.md
+++ b/vault/04-people/norman-arauz.md
@@ -0,0 +1,32 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Norman Arauz
 ## Role
 Frequent Fidelity/XFlow engineer collaborator in historical Slack threads.
 ---
 ## Known Context
 - Repeated day-to-day implementer/investigator across XFlow SwiftUI, AO/Fid4 bugs, version bumps, analytics, and pipeline debugging
 - Often coordinated with Jeff on scope, descriptions, approvals, and manager-ready wording
 - Frequently investigated consumer-reported issues directly in Fid4 and sample-app parity checks
 - Often produced detailed technical findings first, then asked Jeff to polish or approve external wording
 - Exact formal role may need confirmation if used outside workspace memory
 ---
 ## Guidance
 - Treat Norman as a strong source for historical implementation detail, reproduction findings, and release-process context
 - If later communication clarifies the formal team/title, update this file directly
--- a/vault/04-people/quy-mai.md
+++ b/vault/04-people/quy-mai.md
@@ -0,0 +1,31 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Quy Mai
 ## Role
 Confirmed Scrum Master / contact point repeatedly involved in backlog and process management.
 ---
 ## Known Context
 - Repeatedly asked for clearer Jira/state management, points, and backlog hygiene
 - Often confirmed whether work should remain in backlog, be canceled, or be reframed as separate stories
 - Relevant for sprint structure, story cleanup, and expectation-setting around what counts as production or release-priority work
 ---
 ## Guidance
 - Treat Quy as an important source for process expectations, backlog cleanup, and story framing
 - When drafting notes or prompts, refer to Quy as Scrum Master rather than a generic stakeholder
 - If future context clarifies the formal title/team, update this file directly
--- a/vault/04-people/raj-sundararaj.md
+++ b/vault/04-people/raj-sundararaj.md
@@ -0,0 +1,30 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Raj Sundararaj
 ## Role
 Repeated Fidelity collaborator involved in project coordination and active issue triage.
 ---
 ## Known Context
 - Repeatedly surfaced or assigned XFlow/AO issues and asked for current status
 - Involved in release coordination, validation follow-up, and backlog movement
 - Relevant when the team needed to align issue ownership, repro state, or urgency with consumer-side expectations
 ---
 ## Guidance
 - Treat Raj as a useful contact for issue routing, AO coordination, and release follow-up
 - If future context clarifies the formal role/team, update this file directly
--- a/vault/04-people/tim-longfield.md
+++ b/vault/04-people/tim-longfield.md
@@ -0,0 +1,30 @@
 ---
 type: person
 project: fidelity
 role: collaborator
 status: active
 updated: 2026-04-16
 tags:
  - person
  - fidelity
 ---
 # Tim Longfield
 ## Role
 FTPlanning-side collaborator relevant to cross-framework issue ownership.
 ---
 ## Known Context
 - Appeared when issues first thought to be XFlow bugs were traced into FTPlanning
 - Relevant contact for whether a transfer/add-money bug belonged to FTPlanning instead of XFlow
 - Useful when a consumer-side framework fix was needed before XFlow could close validation work
 ---
 ## Guidance
 - Treat Tim as a relevant contact for FTPlanning-owned fixes and cross-team validation
 - If future context clarifies the formal role/team, update this file directly
--- a/vault/05-decisions/discourse-handling.md
+++ b/vault/05-decisions/discourse-handling.md
@@ -0,0 +1,48 @@
 ---
 type: decision
 project: fidelity
 status: accepted
 title: "Discourse Issues Handling"
 updated: 2026-04-16
 tags:
  - decision
  - fidelity
 ---
 # Discourse Issues Handling
 ## Context
 External reports from AO testing or Discourse may:
 - already exist in main
 - be partially reproducible
 - depend on authentication
 - reflect backend behavior rather than a new regression
 ---
 ## Decision
 Treat incoming reports as external issues until scope is confirmed.
 ---
 ## Validation Rules
 Always confirm:
 - reproducibility
 - environment
 - auth state
 - entry point
 - whether the issue exists in main
 ---
 ## Communication Rule
 Do not say a report is a regression until comparison has been validated.
 Preferred framing:
 "Investigating external report. Scope, auth state, and reproducibility still being confirmed."
--- a/vault/05-decisions/rest-vs-graphql.md
+++ b/vault/05-decisions/rest-vs-graphql.md
@@ -0,0 +1,40 @@
 ---
 type: decision
 project: fidelity
 status: accepted
 title: "REST vs GraphQL"
 updated: 2026-04-16
 tags:
  - decision
  - fidelity
 ---
 # REST vs GraphQL
 ## Decision
 Deprecate GraphQL and migrate to REST progressively.
 ---
 ## Constraints
 - REST is behind a feature flag
 - GraphQL remains fallback
 - Behavior parity matters during migration
 ---
 ## Communication Rule
 When reporting findings:
 - state whether REST was confirmed enabled
 - avoid implying REST is the default path
 - call out when behavior may still come from GraphQL fallback
 ---
 ## Follow-up
 - Remove Apollo when migration is safe
 - Retire GraphQL-specific tests only after parity is confirmed
--- a/Show More
+++ b/Show More