# 260614 — Obsidian deep dive (file-over-app vaults, plugin API, ecosystem signal)

Date: 2026-06-14

## What this is

A focused study of **Obsidian** — core/extension architecture and the plugin
ecosystem — read through shard-wiki's lens. Obsidian is the **most INTENT-aligned tool
in the research set**: INTENT names Obsidian vaults as a shard participant, and its
**"file over app"** model (notes are plain Markdown files in a folder you own; the app
is a lens) is the closest cousin to shard-wiki's Markdown-first, sovereignty-preserving
thesis. It is the **file-backed counterpart to the Roam dive** (same tool category,
opposite storage model: Roam = client DB + API; Obsidian = files on disk).

Distinctive material:
- **Architecture** — vault = folder of `.md` + `.obsidian/` config; files canonical;
  **MetadataCache** is a *derived*, async-rebuilt index (links, embeds, tags,
  frontmatter, block IDs, resolved/unresolved links, backlinks)
- **In-file, git-diffable** addressing/structure — `[[wikilinks]]`, `![[embeds]]`
  (transclusion), `^block-id` span refs, YAML frontmatter/properties
- **Plugin API** — `Plugin` `onload/onunload`; `App` modules `vault` (CRUD + file
  events), `metadataCache`, `workspace` (CM6, views), `fileManager.renameFile`;
  `manifest.json`; community plugins, Restricted Mode
- **Ecosystem popularity → UC signal** (§7) — ranked download data mined for use cases,
  per the research brief

## Contents

| Path | Role |
|------|------|
| `findings.md` | File-over-app architecture, in-file addressing, plugin API as adapter host, capability profile, **plugin-popularity → UC mapping**, derived-index lesson, INTENT mapping, UC seeds, sources |

## Status

Initial deep dive complete. Four new use cases promoted to `spec/UseCaseCatalog.md`
(UC-53 attach a local vault with a live concurrent native editor, UC-54 query-defined
dynamic page, UC-55 carry non-Markdown content types, UC-56 outbound publish of a
projection); UC-15/28/34/36/40/51/52 enriched. Logged for `SHARD-WP-0002` (T14):
**dual attachment mode** (file-store *or* in-app plugin host), consume-native-derived-
index capability, non-Markdown content types in the page model, outbound publish,
external-writer tolerance.

**Key takeaways recorded:** (1) Obsidian validates *files-canonical / index-derived* —
shard-wiki's projection model. (2) Fine-grained addressing & structure can be portable
**in-file text** (`^block-id`, frontmatter), not DB state (contrast Roam). (3) The
ecosystem is demand evidence — the #1 plugin is **drawings** (non-Markdown content),
query-as-DB (Dataview/Tasks) is top-tier but an *add-on*, and **Git is top-7** (users
bolt on the portable history shard-wiki provides natively). **Boundary:** a vault is one
file-backed candidate shard, not the federation layer and not a file-sync target
(not-a-sync-daemon).
</content>