feat: Add Obsidian vault configuration and documentation for navigation and memory management

2026-04-16 12:12:31 -06:00
parent 53eb9dbc36
commit 1ab9472055
27 changed files with 1016 additions and 0 deletions
--- a/knowledge/glossary.md
+++ b/knowledge/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 `ai/logs/`.
+- `state`: near-term active work and priorities in `ai/state/`.
+- `work item`: canonical memory for a ticket, story, task, or investigation in `ai/work-items/`.
+- `stable context`: durable project knowledge under `ai/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/knowledge/maps/ai-workspace-core.md
+++ b/knowledge/maps/ai-workspace-core.md
@@ -0,0 +1,38 @@
+---
+type: map
+domain: workspace-core
+tags:
+  - map
+  - core
+---
+
+# AI Workspace Core Map
+
+Reusable workspace logic and project-independent operating rules.
+
+---
+
+## Core Model
+
+- [Core Overview](../../core/README.md)
+- [Operational Memory](../../core/memory/operational-memory.md)
+- [Communication Integration Model](../../core/integrations/communication-model.md)
+- [Obsidian Integration Model](../../core/integrations/obsidian-model.md)
+- [Create Project Profile](../../core/profiles/create-project-profile.md)
+
+---
+
+## Workspace Rules
+
+- [Workspace Model](../workspace-model.md)
+- [Agent Memory Rules](../agent-memory-rules.md)
+- [Memory Promotion Rules](../memory-promotion-rules.md)
+- [Communication Rules](../communication-rules.md)
+- [Context Maintenance](../../ai/context/process/context-maintenance.md)
+
+---
+
+## Profiles
+
+- [Fidelity Profile](../../profiles/fidelity/profile.md)
+- [Example Profile](../../profiles/example/profile.md)
--- a/knowledge/maps/current-work.md
+++ b/knowledge/maps/current-work.md
@@ -0,0 +1,39 @@
+---
+type: map
+domain: current-work
+tags:
+  - map
+  - current-work
+---
+
+# Current Work Map
+
+Current operational state for daily work, standups, and manager updates.
+
+---
+
+## Current State
+
+- [New Member Onboarding](../onboarding.md)
+- [Current Work](../../ai/state/current.md)
+- [Work Item State](../../ai/state/work-items.md)
+- [Work Item Index](../../ai/work-items/index.md)
+- [Logs Index](../../ai/logs/index.md)
+
+---
+
+## Active Work Items
+
+- [PDIAP-14859](../../ai/work-items/pdiap-14859.md)
+- [PDIAP-15765](../../ai/work-items/pdiap-15765.md)
+- [PDIAP-15836](../../ai/work-items/pdiap-15836.md)
+- [PDIAP-15838](../../ai/work-items/pdiap-15838.md)
+
+---
+
+## Communication Context
+
+- [Communication Rules](../communication-rules.md)
+- [Manager Update Prompt](../../prompts/manager-update.md)
+- [Standup Prompt](../../prompts/standup.md)
+- [Manager Mapping](../../ai/context/people/manager.md)
--- a/knowledge/maps/fidelity-domain.md
+++ b/knowledge/maps/fidelity-domain.md
@@ -0,0 +1,50 @@
+---
+type: map
+domain: fidelity
+tags:
+  - map
+  - fidelity
+---
+
+# Fidelity Domain Map
+
+Stable Fidelity-specific systems, workstreams, and domain rules.
+
+---
+
+## Project Context
+
+- [Glossary](../glossary.md)
+- [Project Context](../../ai/context/project.md)
+- [Context Index](../../ai/context/index.md)
+- [Fidelity Profile](../../profiles/fidelity/profile.md)
+
+---
+
+## Systems
+
+- [Systems Index](../../ai/context/systems/index.md)
+- [Fid4](../../ai/context/systems/fid4.md)
+- [XFlowSDK](../../ai/context/systems/xflowsdk.md)
+- [XFlowViewMaker](../../ai/context/systems/xflowviewmaker.md)
+- [FTFrameworks](../../ai/context/systems/ftframeworks.md)
+- [Cogstore](../../ai/context/systems/cogstore.md)
+
+---
+
+## Workstreams
+
+- [Workstreams Index](../../ai/context/workstreams/index.md)
+- [REST Migration](../../ai/context/workstreams/rest-migration.md)
+- [AO And Discourse](../../ai/context/workstreams/ao-discourse.md)
+- [XFlow Debugging](../../ai/context/workstreams/xflow-debugging.md)
+- [XFlow SwiftUI Migration](../../ai/context/workstreams/xflow-swiftui-migration.md)
+- [Consumer Integration](../../ai/context/workstreams/consumer-integration.md)
+- [Flow And Page References](../../ai/context/workstreams/flow-page-references.md)
+
+---
+
+## Decisions
+
+- [REST vs GraphQL](../../ai/context/decisions/rest-vs-graphql.md)
+- [Discourse Handling](../../ai/context/decisions/discourse-handling.md)
--- a/knowledge/maps/index.md
+++ b/knowledge/maps/index.md
@@ -0,0 +1,35 @@
+---
+type: map-index
+audience: workspace-user
+tags:
+  - map
+---
+
+# Knowledge Maps
+
+Human navigation hubs for the Obsidian graph.
+
+Use these maps to navigate the workspace by meaning instead of by raw folder structure.
+
+---
+
+## Primary Maps
+
+- [AI Workspace Core](ai-workspace-core.md)
+- [Current Work](current-work.md)
+- [Fidelity Domain](fidelity-domain.md)
+- [Work Items](work-items.md)
+- [People](people.md)
+- [Tooling](tooling.md)
+- [Logs](../../ai/logs/index.md)
+
+---
+
+## Entry Points
+
+- [Obsidian Vault Map](../obsidian-vault.md)
+- [New Member Onboarding](../onboarding.md)
+- [Glossary](../glossary.md)
+- [Obsidian Usage Guide](../obsidian-usage.md)
+- [README](../../README.md)
+- [Fidelity Profile](../../profiles/fidelity/profile.md)
--- a/knowledge/maps/people.md
+++ b/knowledge/maps/people.md
@@ -0,0 +1,43 @@
+---
+type: map
+domain: people
+tags:
+  - map
+  - people
+---
+
+# People Map
+
+Stakeholder, manager, and collaborator context.
+
+---
+
+## Indexes
+
+- [People Index](../../ai/context/people/index.md)
+- [Manager Mapping](../../ai/context/people/manager.md)
+
+---
+
+## People
+
+- [Jeff DeWitte](../../ai/context/people/jeff-dewitte.md)
+- [Norman Arauz](../../ai/context/people/norman-arauz.md)
+- [David Delagneau](../../ai/context/people/david-delagneau.md)
+- [Aylwing Olivas](../../ai/context/people/aylwing-olivas.md)
+- [Bruce Meeks](../../ai/context/people/bruce-meeks.md)
+- [Derian Cordoba](../../ai/context/people/derian-cordoba.md)
+- [Erik Reynolds](../../ai/context/people/erik-reynolds.md)
+- [Gurram Santosh](../../ai/context/people/gurram-santosh.md)
+- [Jason Mandozzi](../../ai/context/people/jason-mandozzi.md)
+- [Quy Mai](../../ai/context/people/quy-mai.md)
+- [Raj Sundararaj](../../ai/context/people/raj-sundararaj.md)
+- [Tim Longfield](../../ai/context/people/tim-longfield.md)
+
+---
+
+## Communication
+
+- [Communication Rules](../communication-rules.md)
+- [Manager Update Workflow](../../workflows/manager-update.md)
+- [Professional Communication Skill](../../.opencode/skills/professional-communication/SKILL.md)
--- a/knowledge/maps/tooling.md
+++ b/knowledge/maps/tooling.md
@@ -0,0 +1,52 @@
+---
+type: map
+domain: tooling
+tags:
+  - map
+  - tooling
+---
+
+# Tooling Map
+
+Commands, prompts, skills, workflows, and automation surfaces that make the workspace operate consistently.
+
+---
+
+## OpenCode Agents
+
+- [Fidelity Agent](../../.opencode/agents/fidelity.md)
+- [Workspace Agent](../../.opencode/agents/workspace.md)
+
+---
+
+## Commands
+
+- [Commands Index](../../.opencode/commands/index.md)
+- [Workspace Context](../../.opencode/commands/workspace-context.md)
+- [Communication Sync](../../.opencode/commands/communication-sync.md)
+- [Archive Import](../../.opencode/commands/archive-import.md)
+- [AI Prompt](../../.opencode/commands/ai-prompt.md)
+- [Standup](../../.opencode/commands/standup.md)
+- [Manager Update](../../.opencode/commands/manager-update.md)
+- [Sync Context](../../.opencode/commands/sync-context.md)
+
+---
+
+## Skills
+
+- [Skills Index](../../.opencode/skills/index.md)
+- [Workspace Memory Curation](../../.opencode/skills/workspace-memory-curation/SKILL.md)
+- [Professional Communication](../../.opencode/skills/professional-communication/SKILL.md)
+- [Status Reporting](../../.opencode/skills/status-reporting/SKILL.md)
+- [AI Prompt Engineering](../../.opencode/skills/ai-prompt-engineering/SKILL.md)
+
+---
+
+## Prompts And Workflows
+
+- [Prompts Index](../../prompts/index.md)
+- [Standup Prompt](../../prompts/standup.md)
+- [Manager Update Prompt](../../prompts/manager-update.md)
+- [Story Draft Prompt](../../prompts/story-draft.md)
+- [OpenCode Entry Workflow](../../workflows/opencode-entry.md)
+- [Daily Context Sync](../../workflows/daily-context-sync.md)
--- a/knowledge/maps/work-items.md
+++ b/knowledge/maps/work-items.md
@@ -0,0 +1,36 @@
+---
+type: map
+domain: work-items
+tags:
+  - map
+  - work-items
+---
+
+# Work Items Map
+
+Canonical memory for active and recently relevant work units.
+
+---
+
+## Indexes
+
+- [Work Item Index](../../ai/work-items/index.md)
+- [Work Item State](../../ai/state/work-items.md)
+- [Current Work](../../ai/state/current.md)
+
+---
+
+## Active Items
+
+- [PDIAP-14859](../../ai/work-items/pdiap-14859.md)
+- [PDIAP-15765](../../ai/work-items/pdiap-15765.md)
+- [PDIAP-15836](../../ai/work-items/pdiap-15836.md)
+- [PDIAP-15838](../../ai/work-items/pdiap-15838.md)
+
+---
+
+## Related Process
+
+- [Jira Story Rules](../../ai/context/process/jira-story-rules.md)
+- [Story Draft Prompt](../../prompts/story-draft.md)
+- [Status Reporting Skill](../../.opencode/skills/status-reporting/SKILL.md)
--- a/knowledge/obsidian-usage.md
+++ b/knowledge/obsidian-usage.md
@@ -0,0 +1,84 @@
+---
+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:
+
+- [Obsidian Vault Map](obsidian-vault.md)
+- [New Member Onboarding](onboarding.md)
+- [Knowledge Maps](maps/index.md)
+
+---
+
+## Best Views
+
+### New Member View
+
+Start with:
+
+- [New Member Onboarding](onboarding.md)
+- [Glossary](glossary.md)
+- [Current Work Map](maps/current-work.md)
+- [Fidelity Domain Map](maps/fidelity-domain.md)
+
+### Daily Work View
+
+Start with:
+
+- [Current Work Map](maps/current-work.md)
+- [Work Items Map](maps/work-items.md)
+- [Logs Index](../ai/logs/index.md)
+
+### System Understanding View
+
+Start with:
+
+- [Fidelity Domain Map](maps/fidelity-domain.md)
+- [AI Workspace Core Map](maps/ai-workspace-core.md)
+- [Tooling Map](maps/tooling.md)
+
+---
+
+## Graph Guidance
+
+Use the graph to find clusters, not to infer truth.
+
+High-value graph hubs:
+
+- `obsidian-vault`
+- `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
+
+---
+
+## 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.
--- a/knowledge/obsidian-vault.md
+++ b/knowledge/obsidian-vault.md
@@ -0,0 +1,104 @@
+---
+type: map
+audience: workspace-user
+tags:
+  - map
+  - obsidian
+---
+
+# Obsidian Vault Map
+
+Use this note as the human navigation entry point when opening this repository as an Obsidian vault.
+
+---
+
+## Start Here
+
+- [README](../README.md)
+- [New Member Onboarding](onboarding.md)
+- [Glossary](glossary.md)
+- [Obsidian Usage Guide](obsidian-usage.md)
+- [Knowledge Maps](maps/index.md)
+- [Core Overview](../core/README.md)
+- [Operational Memory](../core/memory/operational-memory.md)
+- [Obsidian Integration Model](../core/integrations/obsidian-model.md)
+- [Fidelity Profile](../profiles/fidelity/profile.md)
+
+---
+
+## Maps
+
+- [AI Workspace Core](maps/ai-workspace-core.md)
+- [Current Work](maps/current-work.md)
+- [Fidelity Domain](maps/fidelity-domain.md)
+- [Work Items](maps/work-items.md)
+- [People](maps/people.md)
+- [Tooling](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](maps/current-work.md)
+4. [Fidelity Domain Map](maps/fidelity-domain.md)
+5. [People Map](maps/people.md)
+
+---
+
+## Current Work
+
+- [Current State](../ai/state/current.md)
+- [Active Work Items](../ai/state/work-items.md)
+- [Work Item Index](../ai/work-items/index.md)
+- [Logs Index](../ai/logs/index.md)
+
+---
+
+## Stable Context
+
+- [Context Index](../ai/context/index.md)
+- [Project Context](../ai/context/project.md)
+- [Systems Index](../ai/context/systems/index.md)
+- [Workstreams Index](../ai/context/workstreams/index.md)
+- [People Index](../ai/context/people/index.md)
+- [Manager Mapping](../ai/context/people/manager.md)
+
+---
+
+## Process And Rules
+
+- [Workspace Model](workspace-model.md)
+- [Agent Memory Rules](agent-memory-rules.md)
+- [Memory Promotion Rules](memory-promotion-rules.md)
+- [Communication Rules](communication-rules.md)
+- [Context Maintenance](../ai/context/process/context-maintenance.md)
+
+---
+
+## Daily Logs
+
+Daily logs live in:
+
+```text
+ai/logs/
+```
+
+Use the latest dated log for recent evidence, but promote durable facts into `ai/state/`, `ai/work-items/`, or `ai/context/` when they should survive beyond the day.
+
+- [Logs Index](../ai/logs/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.
--- a/knowledge/onboarding.md
+++ b/knowledge/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](obsidian-vault.md)
+2. [Current Work Map](maps/current-work.md)
+3. [Fidelity Domain Map](maps/fidelity-domain.md)
+4. [Work Items Map](maps/work-items.md)
+5. [People Map](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](../ai/context/project.md)
+2. [XFlowSDK](../ai/context/systems/xflowsdk.md)
+3. [Fid4](../ai/context/systems/fid4.md)
+4. [REST Migration](../ai/context/workstreams/rest-migration.md)
+5. [AO And Discourse](../ai/context/workstreams/ao-discourse.md)
+6. [Communication Rules](communication-rules.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. [Operational Memory](../core/memory/operational-memory.md)
+2. [Workspace Model](workspace-model.md)
+3. [Agent Memory Rules](agent-memory-rules.md)
+4. [Context Maintenance](../ai/context/process/context-maintenance.md)
+5. [Tooling Map](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](maps/current-work.md).
+2. Check [Current Work](../ai/state/current.md).
+3. Open the active work item from [Work Items Map](maps/work-items.md).
+4. Review the latest relevant log from [Logs Index](../ai/logs/index.md).
+5. Use [Communication Rules](communication-rules.md) before writing standups, Jira comments, or manager updates.
+
+---
+
+## Rules Of Thumb
+
+- `ai/logs/` is evidence from a day.
+- `ai/state/` is what matters now.
+- `ai/work-items/` is canonical ticket memory.
+- `ai/context/` is durable project knowledge.
+- `ai/context/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/knowledge/workspace-model.md
+++ b/knowledge/workspace-model.md
@@ -20,6 +20,7 @@ It now has two layers:
 - 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

 ---

@@ -28,6 +29,7 @@ It now has two layers:
 - 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

 ---

@@ -37,6 +39,7 @@ When the user corrects a recurring behavior, the workspace should update the fil

 - `core/` for reusable project-independent behavior
 - `profiles/<project>/` for project-specific assumptions
+- `.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