# Obsidian Integration Model

## Purpose

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.

---

## Recommended Vault

Open the `vault/` folder as the Obsidian vault:

```text
<workspace-root>/vault/
```

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 human/AI memory lives in:

- `vault/00-start/`
- `vault/01-current/`
- `vault/02-work-items/`
- `vault/03-context/`
- `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

Communication evidence may exist under `ai/inbox/` or connector `generated/` folders, but promoted memory belongs in `vault/`.

---

## What To Version

Version portable Obsidian configuration only when it improves the workspace for every clone:

- `vault/.obsidian/app.json`
- `vault/.obsidian/core-plugins.json`
- `vault/.obsidian/graph.json`
- `vault/.obsidian/appearance.json`
- `vault/.obsidian/daily-notes.json`
- `vault/.obsidian/templates.json`
- `vault/.obsidian/bookmarks.json`

Do not version local runtime state:

- `vault/.obsidian/workspace*.json`
- `vault/.obsidian/workspace-mobile*.json`
- `vault/.obsidian/plugins/`
- `vault/.obsidian/snippets/`
- `vault/.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 `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`.