# 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.