From 81dd966dbb3cf4fc082f6c42d0b3ffd2f010edd4 Mon Sep 17 00:00:00 2001 From: Souta Date: Tue, 30 Jun 2026 16:02:32 +0900 Subject: [PATCH] docs: fix shadow-vault "mirrors/syncs" claims in index + first-connect (#429) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two more docs carried the same misconception the compat guide did: - architecture/index.md: "local vault that mirrors remote", "creates a real vault and syncs files", and a "local storage grows / LRU evicts files not opened in N days" cost note (the ReadCache is in-memory and capped, not a growing on-disk mirror). - getting-started/first-connect.md: the connect explanation said it "mirrors the remote vault's files" and "watches both sides and syncs them" — restated as direct-to-remote, virtual notes, remote→local fs.watch only. Found by a full docs/en audit (architecture+api / user-facing / guides+ops+migration). Everything else verified accurate — notably architecture/shadow-vault.md §6.5 already described fs-direct readers as broken and the local mirror as a deferred (never-built) enhancement, which is the source of truth the drifted docs contradicted. Refs #429 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/en/architecture/index.md | 6 +++--- docs/en/getting-started/first-connect.md | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/en/architecture/index.md b/docs/en/architecture/index.md index a1baad5..5c18dc2 100644 --- a/docs/en/architecture/index.md +++ b/docs/en/architecture/index.md @@ -11,7 +11,7 @@ Design specs for the major subsystems — the **why** behind decisions, not just | Doc | What it covers | |---|---| -| [[shadow-vault\|Shadow vault]] | The "local Obsidian vault that mirrors remote" model — shadow lifecycle, file routing, sync events | +| [[shadow-vault\|Shadow vault]] | The shadow-vault model (a local vault whose patched adapter serves the remote virtually) — lifecycle, file routing, change events | | [[perf\|Performance]] | Sync latency budget, perf bench, the per-merge baseline tracking on `perf-baseline` branch | | [[collab\|Collaboration]] | Multi-client editing, conflict handling, the per-client `.obsidian/user//` workspace partition | | [[release-pipeline\|Release & deploy pipeline]] | Two-channel release model, `release.yml` signing flow, sync workflow, branch-aware lint/version-check, plugin-side deploy lifecycle | @@ -28,9 +28,9 @@ The daemon is the only thing that touches the actual vault files. The plugin nev ### "Shadow vault is a real local vault" -Obsidian's plugin API is opinionated about vault paths. Rather than forking Obsidian's vault layer to be remote-aware (a multi-month investment), the shadow vault model just creates a real vault on your local disk and syncs files. Every Obsidian feature works without modification. +Obsidian's plugin API is opinionated about vault paths. Rather than forking Obsidian's vault layer to be remote-aware (a multi-month investment), the shadow vault model creates a real local vault but patches its adapter so every file op goes to the remote — the notes are never copied to local disk (only `.obsidian/` lives there). Every Obsidian feature works without modification. -The cost: storage on your local machine grows with what you have opened. The plugin keeps a hot cache of recently-touched files; LRU eviction frees space for files not opened in N days. +The cost: file ops need the remote reachable and pay per-op SSH/RPC latency. An in-memory cache (capped) speeds re-reads of recently-touched files. ### v1.x stability promises diff --git a/docs/en/getting-started/first-connect.md b/docs/en/getting-started/first-connect.md index 9aa9e21..adc6948 100644 --- a/docs/en/getting-started/first-connect.md +++ b/docs/en/getting-started/first-connect.md @@ -8,13 +8,13 @@ description: "What happens when you click Connect: SSH handshake, daemon auto-de ## The shadow vault model -obsidian-remote-ssh does not edit your remote files directly through Obsidian's vault layer. Instead it: +obsidian-remote-ssh doesn't keep a synced copy of your vault — the remote is the single source of truth. Instead it: -1. Creates a **local shadow vault** under `~/.obsidian-remote/vaults//`. This is a real Obsidian vault on your local disk. -2. Mirrors the remote vault's files into that shadow vault (lazily — large files are fetched on first open). -3. Watches both sides for changes and syncs them through the SSH-tunneled daemon RPC. +1. Creates a **local shadow vault** under `~/.obsidian-remote/vaults//` — a real Obsidian vault dir, but only `.obsidian/` config lives on disk. +2. Patches that vault's file adapter so every read/write goes **directly to the remote** over the SSH-tunneled daemon (or SFTP). Your notes are served virtually — never copied to local disk. +3. The daemon's `fs.watch` pushes remote changes back, so the file explorer and open editors update live (~1 s). -Result: Obsidian thinks it's editing a local vault. All Obsidian features (Dataview, Templater, Excalidraw, …) work because they ARE working against a local vault. The "remote-ness" lives in the sync layer, invisible to most plugins. +Result: Obsidian thinks it's editing a local vault, so all features (Dataview, Templater, Excalidraw, …) work — but every file op actually hits the remote. (Plugins that bypass the vault API and use Node `fs` directly are the exception — see #429.) See [[shadow-vault|Shadow vault architecture]] for the full design.