research: Obsidian deep dive (file-over-app vaults, plugin API, ecosystem-popularity signal); UC-53/54/55/56

The most INTENT-aligned tool yet and the file-backed counterpart to Roam:
file-over-app vaults (plain .md folders, files canonical, MetadataCache a
derived index), in-file git-diffable addressing/structure (^block-id,
wikilink embeds, YAML frontmatter), and a plugin API (Plugin onload/onunload
over App.vault/metadataCache/workspace) that doubles as an adapter host —
so a vault is dual-attachable (file-store direct or in-app plugin). Mined
the plugin download rankings as demand evidence per the research brief:
#1 is drawings (Excalidraw, non-Markdown content), query-as-DB
(Dataview/Tasks) is top-tier but an add-on, Git is top-7 (bolt-on history),
Remotely Save shows sync-to-anywhere demand. Added UC-53 (attach local
vault w/ live concurrent native editor), UC-54 (query-defined dynamic
page), UC-55 (non-Markdown content types), UC-56 (outbound publish of a
projection); enriched UC-15/28/34/36/40/51/52. Boundary: a vault is one
file-backed candidate shard, not the federation layer and not a file-sync
target.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

spec/UseCaseCatalog.md

@@ -6,8 +6,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
 `research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`,
 `research/260608-wikiengines-overview/`, `research/260613-xwiki-deep-dive/`,
 `research/260613-twiki-deep-dive/`, `research/260613-foswiki-deep-dive/`,
-`research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`, and
-`research/260614-roam-deep-dive/`.
+`research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`,
+`research/260614-roam-deep-dive/`, and `research/260614-obsidian-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.
 
 ## Conventions
@@ -137,7 +137,9 @@ detection.
 read-only, or retired shard into an active information space.  
 **Source:** federation  
 **Notes:** Caulfield bounded conversation / reverse bit-rot. Optional space
-lifecycle policy. Complements UC-02 attach and UC-26 fork at scale.  
+lifecycle policy. Complements UC-02 attach and UC-26 fork at scale. Obsidian's
+**Importer** (1.4M) plugin (Evernote/Notion/Bear/Apple Notes → Markdown) shows demand
+for importing from foreign tools (`research/260614-obsidian-deep-dive/findings.md` §7).  
 **Priority:** Later
 
 ### UC-29 — Remix with portable attribution
@@ -225,7 +227,10 @@ topic text file*, so structure is diffable rather than locked in a DB
 (`research/260613-twiki-deep-dive/findings.md` §2.3). Roam is the modern exemplar:
 `key:: value` attributes over a datom graph, queryable via Datalog
 (`research/260614-roam-deep-dive/findings.md` §3, §4) — structure to preserve via
-sidecar metadata, and a candidate for query delegation (UC-52).  
+sidecar metadata, and a candidate for query delegation (UC-52). Obsidian shows the
+**git-diffable in-file** variant: YAML frontmatter/properties live in the Markdown text
+and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md`
+§3) — structure as portable text, not DB state.  
 **Priority:** Later
 
 ### UC-35 — Attach a shard with coarse write granularity
@@ -257,7 +262,10 @@ is the journal authoritative or a mirror reconciled back to the engine
 internal RCS table (`xwikircs`) is a concrete instance
 (`research/260613-xwiki-deep-dive/findings.md` §2.4). This UC is *supplementation*
 (the engine's past is DB-locked); where history is already in an open file format
-(TWiki RCS `.txt,v`) it can instead be **imported** — see UC-41.  
+(TWiki RCS `.txt,v`) it can instead be **imported** — see UC-41. Demand evidence:
+**Obsidian Git is a top-7 plugin (2.7M)** — users manually bolt portable git history
+onto a vault that has none natively (`research/260614-obsidian-deep-dive/findings.md`
+§5, §7), exactly the gap the coordination journal fills as core.  
 **Priority:** Later
 
 ### UC-37 — Attach a static engine export as a read-only backup shard
@@ -328,7 +336,10 @@ the choice (`research/260613-twiki-deep-dive/findings.md` §5–§6, §8 Q1). Di
 from UC-37 (no live origin) and broader than UC-02's generic attach. Foswiki's
 **PlainFile** store (timestamped whole-version copies, no RCS) is a cleaner
 direct-attach target than RCS diffs (`research/260613-foswiki-deep-dive/findings.md`
-§2.2).  
+§2.2). An **Obsidian vault** is the cleanest case of all — a plain Markdown folder,
+Markdown-first and git-friendly — and uniquely **dual-attachable**: file-store direct
+*or* via an in-app plugin adapter for write-through + live file events (UC-53,
+`research/260614-obsidian-deep-dive/findings.md` §4, §10).  
 **Priority:** Later
 
 ### UC-41 — Import an engine's native file history into the coordination journal
@@ -487,7 +498,10 @@ opaque per-block UID, public and referenceable (`research/260614-roam-deep-dive/
 §2, §7). Enables UC-44/45 at sub-page granularity; falls back to content-fingerprint
 (UC-46) or path+range where no native ID exists. Open: use native ID directly or wrap in
 a shard-scoped address to avoid cross-shard collision and survive projection (findings
-§11 Q1).  
+§11 Q1). Obsidian shows the **text-embedded** variant: `^block-id` and heading anchors
+live in the Markdown text — git-diffable and portable (survives a file copy) but opt-in
+(`research/260614-obsidian-deep-dive/findings.md` §2), vs Roam's mandatory DB-minted
+UID.  
 **Priority:** Later
 
 ### UC-52 — Delegate derived views to a shard's native query engine
@@ -500,7 +514,68 @@ recent changes, typed queries) by delegating to it instead of scanning the proje
 (`research/260614-roam-deep-dive/findings.md` §4). Makes "native query" an adapter
 capability the orchestrator can key off (vs. computing views itself over the
 projection). Operationalizes the ZigZag "dimensions + rasters" insight
-(`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34.  
+(`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34. Obsidian
+nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "native query"
+is adapter/plugin-provided and must not be assumed
+(`research/260614-obsidian-deep-dive/findings.md` §7).  
+**Priority:** Later
+
+### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor
+
+**Actor:** Maintainer  
+**Goal:** Attach an Obsidian-style local Markdown vault as a file-backed shard while its
+own app continues to edit the files concurrently — watching for external changes,
+re-projecting, and treating the app's config dir as opaque.  
+**Source:** obsidian, intent  
+**Notes:** Obsidian "file over app": vault = folder of `.md` + `.obsidian/` config;
+files are canonical (`research/260614-obsidian-deep-dive/findings.md` §1). Cleanest
+file-store attach (UC-40) — and uniquely **dual-mode**: zero-config direct attach
+(read/projection/overlay) *or* an in-app adapter (Obsidian plugin) for write-through +
+live `vault` events (UC-38, findings §4). Needs **external-writer tolerance**
+(file-watch, re-project, conflict-with-live-app) distinct from multi-user write
+conflicts. Exclude `.obsidian/` as shard-local config, not page content.  
+**Priority:** Later
+
+### UC-54 — Define a page as a live query over the union
+
+**Actor:** Author  
+**Goal:** Author a page whose body is materialized from a saved query over the union
+(e.g. "all open tasks", "all pages tagged X"), refreshed as the union changes.  
+**Source:** obsidian, roam, intent  
+**Notes:** The Obsidian **Dataview** (4.4M downloads) / **Tasks** (3.6M) pattern, and
+Roam `{{query}}` — query-defined dynamic pages
+(`research/260614-obsidian-deep-dive/findings.md` §7). Distinct from UC-44 (reference/
+span manifest) and UC-52 (delegating *computation* of an existing view): here the *page
+itself* is a query. Open: core page type vs. adapter vs. reference-UI/plugin (findings
+§11 Q2). May delegate execution to a shard's native query engine (UC-52).  
+**Priority:** Later
+
+### UC-55 — Carry non-Markdown content types as typed or opaque assets
+
+**Actor:** Maintainer or author  
+**Goal:** Attach and present a shard's non-Markdown content — drawings (Excalidraw),
+spatial canvases (JSON Canvas), images, attachments — as typed or opaque assets with
+provenance, without flattening them into Markdown or dropping them.  
+**Source:** obsidian, intent  
+**Notes:** The **#1 Obsidian plugin is Excalidraw (6.4M)** — users keep non-Markdown
+content in "Markdown" vaults (`research/260614-obsidian-deep-dive/findings.md` §7).
+Extends UC-34's no-lossy-flatten rule from structured-text to binary/spatial content.
+Pushes the **wiki page model**: page vs. typed asset vs. opaque blob — a page-model
+decision, not just adapter config (findings §10). JSON Canvas is an open format worth
+first-class support.  
+**Priority:** Later
+
+### UC-56 — Publish a curated projection to an external read-only target
+
+**Actor:** Maintainer  
+**Goal:** Publish a selected projection of the union (or a shard) to an external
+read-only target — a static site or hosted page set — preserving provenance.  
+**Source:** obsidian, intent  
+**Notes:** The Obsidian Publish / **Quartz** / Digital Garden pattern — outbound
+publish (`research/260614-obsidian-deep-dive/findings.md` §7, §10). Formalizes the
+`publish` capability from INTENT's adapter-capability list; **complements UC-37**
+(inbound static-export *attach*) as its outbound mirror. Open: core vs. publish-adapter
+family; interaction with overlays and projection freshness (findings §11 Q4).  
 **Priority:** Later
 
 ---
@@ -586,7 +661,9 @@ shard-wiki adds Git history as structural safety net beyond social norms.
 an agreed layout or subtree.  
 **Source:** yawex  
 **Notes:** yawex blueprint pages. Distinct from UC-08 (blank capture) and UC-10
-(refactoring existing discussion).  
+(refactoring existing discussion). Obsidian's popular **Templater** (4.6M) / **QuickAdd**
+(1.9M) plugins show templated creation is a top real-world need
+(`research/260614-obsidian-deep-dive/findings.md` §7).  
 **Priority:** Later
 
 ### UC-16 — Append or comment without full edit
@@ -741,6 +818,10 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-50 | | | | § | ✓ |
 | UC-51 | | | | § | ✓ |
 | UC-52 | | | | § | ✓ |
+| UC-53 | | | | ¶ | ✓ |
+| UC-54 | | | | ¶ | ✓ |
+| UC-55 | | | | ¶ | ✓ |
+| UC-56 | | | | ¶ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -916,6 +997,50 @@ Markdown-first page model, not adopted as a substrate and never the federation l
 native-query capabilities, block↔page mapping, and Roam as a second
 engine-hosts-adapter exemplar alongside XWiki.
 
+### obsidian mapping
+
+(¶ UC-53–UC-56 are placed in the **wikiengines** matrix column as the nearest existing
+source — Obsidian is a shipped tool — but their true lineage is the **Obsidian deep
+dive**, `research/260614-obsidian-deep-dive/findings.md`.)
+
+| Obsidian mechanism (findings §) | Catalog UC |
+|---------------------------------|------------|
+| File-over-app vault; cleanest file-backed Markdown shard, dual-attachable (§1, §4) | UC-53 (new); enriches UC-40, UC-02, UC-38 |
+| Dataview/Tasks: a page materialized from a query (§7) | UC-54 (new) |
+| Excalidraw/Canvas/attachments: non-Markdown content (§7) | UC-55 (new) |
+| Obsidian Publish/Quartz: outbound publish (§7) | UC-56 (new) |
+| In-file `^block-id` / heading anchors = git-diffable opt-in span IDs (§2) | UC-51 (enriched) |
+| YAML frontmatter/properties = git-diffable in-file structured data (§3) | UC-34 (enriched) |
+| Git plugin (top-7) = bolt-on portable history (§5, §7) | UC-36 (enriched) |
+| Query is a plugin (Dataview), not core (§7) | UC-52 (enriched) |
+| Importer plugin = import from foreign tools (§7) | UC-28 (enriched) |
+| Templater/QuickAdd = templated creation (§7) | UC-15 (enriched) |
+| MetadataCache: files-canonical / index-derived (§1, §6) | reinforces UC-05/17–20 derived-view model |
+
+#### Plugin-popularity → use-case signal
+
+Per the research brief (let ecosystem popularity inform the catalog). All-time download
+ranks read as **demand evidence** — full table in
+`research/260614-obsidian-deep-dive/findings.md` §7. Headlines:
+
+- **#1 is drawings** (Excalidraw 6.4M) → non-Markdown content is a *primary* real-world
+  use, not an edge case → **UC-55**.
+- **Query-as-DB** (Dataview 4.4M, Tasks 3.6M) is top-tier but an *add-on* → query is an
+  adapter/plugin capability (**UC-52**) and motivates query-defined pages (**UC-54**).
+- **Git is top-7** (2.7M) → users manually bolt on portable history → direct demand for
+  the coordination journal (**UC-36**).
+- **Sync-to-anywhere** (Remotely Save 2.0M: S3/Dropbox/OneDrive/GDrive/WebDAV) →
+  demand to connect a vault to the heterogeneous backends INTENT targets — while
+  reaffirming the **not-a-file-sync-daemon** boundary (attach as shards, don't mirror).
+
+Note: an Obsidian vault is **one file-backed candidate shard** — the cleanest,
+INTENT-named, and the file-store counterpart to the DB-backed Roam shard — mapped into
+the Markdown-first page model; **not** the federation layer and **not** a file-sync
+target (`research/260614-obsidian-deep-dive/findings.md` §8.2). Architecture logged for
+`SHARD-WP-0002` (T14): dual attachment mode, consume-native-derived-index capability,
+non-Markdown content types in the page model, outbound publish, external-writer
+tolerance.
+
 ---
 
 ## Open questions
@@ -936,4 +1061,8 @@ engine-hosts-adapter exemplar alongside XWiki.
    model — clones, a parallel graph index, or both? (ZigZag dive §10.)
 9. Is **in-engine adapter hosting** (e.g. a Roam Depot extension for write-through) an
    accepted deployment mode generally, or do we restrict API-only backends to
-   read/projection/overlay-target? (Roam dive §11 Q2; ties UC-38, UC-50.)
+   read/projection/overlay-target? (Roam dive §11 Q2; ties UC-38, UC-50.)
+10. How does shard-wiki represent **non-Markdown content** (UC-55) — typed asset with a
+    Markdown stub, opaque blob with provenance, or a pluggable content-type registry?
+11. Is a **query-defined page** (UC-54) a core page type, an adapter feature, or a
+    reference-UI/plugin concern? (Shared with catalog Q7.)