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

core/README.md

@@ -57,3 +57,10 @@ Integrations extract evidence. They do not decide what becomes memory.
 
 See `core/integrations/communication-model.md` for the reusable connector contract.
 
+---
+
+## Knowledge Navigation
+
+Optional navigation layers such as Obsidian should read the same Markdown files instead of copying memory into a second store.
+
+See `core/integrations/obsidian-model.md` for the recommended vault model.

core/integrations/obsidian-model.md

@@ -0,0 +1,93 @@
+# Obsidian Integration Model
+
+## Purpose
+
+Use Obsidian as a visual navigation and manual review layer over the same Markdown files that power the AI workspace.
+
+Obsidian should not become a second memory store.
+
+---
+
+## Recommended Vault
+
+Open the repository root as the Obsidian vault:
+
+```text
+<workspace-root>/
+```
+
+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
+
+---
+
+## Source Of Truth
+
+Canonical memory remains in:
+
+- `ai/logs/`
+- `ai/state/`
+- `ai/work-items/`
+- `ai/context/`
+- `knowledge/`
+- `core/`
+- `profiles/`
+
+Obsidian-specific runtime files are not project memory.
+
+---
+
+## What To Version
+
+Version portable Obsidian configuration only when it improves the workspace for every clone:
+
+- `.obsidian/app.json`
+- `.obsidian/core-plugins.json`
+- `.obsidian/graph.json`
+- `.obsidian/appearance.json`
+
+Do not version local runtime state:
+
+- `.obsidian/workspace*.json`
+- `.obsidian/workspace-mobile*.json`
+- `.obsidian/plugins/`
+- `.obsidian/snippets/`
+- `.obsidian/cache/`
+
+Recommended graph and search exclusions:
+
+- `ai/inbox/`
+- `archives/`
+- `scripts/**/generated/`
+- `scripts/**/.venv/`
+- `.opencode/node_modules/`
+- Python caches and compiled files
+
+---
+
+## Linking Policy
+
+Prefer standard Markdown links for shared workspace files because they remain portable across:
+
+- OpenCode
+- VS Code
+- GitHub
+- Obsidian
+- other Markdown tooling
+
+Use Obsidian wiki-links only for Obsidian-only notes when there is a clear navigation benefit.
+
+---
+
+## Agent Rules
+
+The agent may update Obsidian navigation notes when they improve discoverability.
+
+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.

core/profiles/create-project-profile.md

@@ -86,3 +86,16 @@ Before using the workspace for real work:
 - generate one standup from sample context
 - verify that imported evidence and promoted memory stay separate
 
+---
+
+## 6. Optional Obsidian Vault
+
+Open the workspace root as an Obsidian vault when you want a visual/manual navigation layer.
+
+Recommended rules:
+
+- keep the workspace filesystem as the single source of truth
+- do not copy memory into a separate Obsidian-only folder
+- version only portable `.obsidian` configuration
+- ignore local Obsidian workspace state and plugin runtime files
+- create or update a vault map under `knowledge/` for human navigation