docs: fix shadow-vault "mirrors/syncs" claims in index + first-connect (#429)

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) <noreply@anthropic.com>
This commit is contained in:
Souta 2026-06-30 16:02:32 +09:00
parent 52c1c5d5ba
commit 81dd966dbb
2 changed files with 8 additions and 8 deletions

View file

@ -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/<id>/` 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

View file

@ -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/<profile-id>/`. 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/<profile-id>/` — 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.