The Boundary That Keeps the Vault Yours
For claude-obsidian, the first system question is not where a note looks best; it is which part of the system is allowed to own and change it. This chapter examines the boundary between the product package, the host that loads it, the user’s vault, and the runtime state that supports operations. That distinction lets readers choose a vault safely, understand what should survive an upgrade or uninstall, and avoid treating a plugin checkout as personal knowledge.
The product is not the vault
A product repository and a knowledge vault can both contain Markdown, JSON, and folders, but they play opposite roles. The claude-obsidian checkout is product source: it contains Agent Skills, the portable Python core, scripts, hooks, templates, documentation, tests, and release assets. Its files describe and implement behavior. A user vault is data: it contains the user’s notes, source material, provenance records, and Obsidian settings. The product may operate on the vault, but it should not absorb the vault into its own installation directory.
This is not merely a matter of keeping a repository tidy. Ownership determines what an operation is permitted to do. Product code changes through development and release processes. Vault knowledge changes through reviewed knowledge operations. A plugin cache is an installed copy of product code, not a hidden database in which the user’s notes belong. The project therefore rejects the product root as an implicit vault, even when a user happens to run a command from that directory.
There are two more roles worth separating. Derived runtime state supports operations but is not canonical knowledge. Locks, transaction journals, capture queues, retrieval chunks, and indexes may be created under the vault’s runtime area so they can be regenerated or recovered, but they should not be mistaken for source evidence or reader-facing notes. The public artifact is separate again: it is built from a clean tracked snapshot and excludes contributor-vault state. A development checkout can therefore contain material useful to maintainers that should never ship as someone else’s knowledge.
The distinction can be summarized by asking who has the final say over a piece of state. The product owns the rules and implementation. The host supplies an environment in which skills may be discovered and optional tools may be available. The user owns the vault’s knowledge and decides when a canonical change is applied. Runtime machinery records how an operation is proceeding, but it does not acquire authority to redefine the knowledge itself.
That ownership question also determines lifecycle. A product upgrade can replace a skill or improve the portable core without relocating notes. A retrieval index can be discarded and rebuilt without changing the pages it indexes. A transaction journal can help restore an interrupted operation without becoming part of the reader’s explanation. A release build can select reviewed product files without packaging a maintainer’s live vault. If these states were mixed, the boundaries between “new software,” “new knowledge,” and “temporary recovery data” would disappear, and every upgrade would become a data migration by accident.
The diagram is useful because it shows interfaces rather than a directory tour. Skills cross from the product package into a host. The host can invoke operations against a selected vault. Sources, pages, and ledgers remain in that vault. Runtime journals and indexes support the vault without becoming its evidence. The release artifact is produced from product state, not by packaging a live user workspace.
Selection is an ownership decision
Once the roles are distinct, vault selection becomes a substantive safety step. A command must know which user-owned state it is about to inspect or mutate. claude-obsidian resolves that target in a defined order: an explicit vault argument takes precedence, then the CLAUDE_OBSIDIAN_VAULT environment setting, then the nearest workspace configuration, and finally an unambiguous initialized vault at or above the current directory. If there is no clear answer, the operation stops rather than guessing.
The order matters because convenience signals can conflict. A current working directory may be inside a product checkout. An environment variable may point to one vault while a nearby workspace configuration names another. A parent directory may contain more than one initialized vault. Guessing in any of those cases could turn a read or write intended for one body of knowledge into an operation on another. Failing closed preserves the user’s ability to correct the selection before any state changes.
Selection is also about time, not only location. Before a setup or mutation is applied, the selected destination and its expected state are inspected. The resulting plan is tied to the reviewed operation, so an apply cannot quietly mean something different because a path was replaced or a target changed between preview and execution. This is the same logic that later protects a note update: the system should know what it inspected, which vault it inspected, and whether that state is still the state being changed.
The same principle applies during setup. Initialization of a new vault and adoption of an existing Obsidian directory are preview-first operations. A preview identifies the destination and the paths that would be created or changed. Applying it requires the reviewed plan hash, so the operation being applied is tied to what was inspected. Setup does not silently add an upstream Git remote or install community plugins. Adoption preserves existing notes and Obsidian JSON rather than treating an existing workspace as an empty product surface.
Host installation follows the same division. The project can expose its skills through a Claude Code plugin or through per-skill links for compatible hosts such as Codex, OpenCode, Gemini, Cursor, Windsurf, and ZCode. Those links make the product discoverable; they do not relocate the vault into the host’s skill directory. A user can upgrade or remove the integration while leaving the Markdown knowledge, raw evidence, ledgers, and Obsidian settings in place. The portability is therefore grounded in the vault’s ordinary files and explicit selection, not in a promise that every host shares the same runtime behavior.
An example makes the boundary concrete. Suppose a user clones claude-obsidian to inspect its documentation and then starts a command from the checkout. The repository contains a README, skills, scripts, and tests, but that fact does not make it a user vault. A safe command should require a separately initialized or explicitly selected vault. If the user instead has two vaults above the current directory, the right outcome is a request for a clearer target, not a best-effort write into the first path returned by a filesystem walk.
A vault has layers with different lifecycles
A selected vault is not a single undifferentiated folder. It has layers that answer different questions about durability and authority. The visible inbox is where a user places source material for intake. The raw area preserves immutable source bytes and legacy capture metadata. The wiki area contains generated, user-owned pages and navigation. The runtime area holds locks, journals, queues, and derived indexes that make operations recoverable or retrieval faster.
The inbox is intentionally visible and user-controlled. Capture does not delete it after copying a source. That choice protects the original staging context and makes capture a reversible act from the user’s perspective: the system may create a durable copy, but it does not decide that the visible source has served its purpose. If a source was placed there by mistake, the user—not an automatic cleanup routine—decides what to remove.
Raw source storage has a stricter invariant. New payloads are content-addressed by SHA-256 and created without replacing an existing payload. If the same content is encountered again, the system can recognize the identity rather than silently overwriting an earlier capture. If the remote or local material changes, the right response is a new immutable capture or an honest ledger update. This keeps the evidence layer from becoming a mutable scratchpad whose current bytes no longer explain an old claim.
The wiki layer is where the source becomes useful to a reader. It can contain source summaries, concepts, entities, questions, indexes, logs, and overviews, with methodology-specific routes available for future pages. These pages are not automatically equivalent to the raw source. A page may organize or synthesize evidence; its claims still need provenance. The operation log records completed logical changes, while the bounded hot context helps orient a later session without becoming a transcript.
The ledgers occupy a special position inside the wiki layer. A source ledger describes what a source is and how it was retrieved or reviewed. A claim ledger describes what a page asserts and what evidence supports or contradicts it. Keeping those roles separate prevents a page’s prose from becoming the only record of where an assertion came from. It also creates a place to express freshness, review status, and uncertainty without rewriting the source to make it sound more certain.
Imagine a user placing a document in the inbox. The durable capture answers, “Which bytes were preserved?” A source record answers, “Where did those bytes come from, and are they still active?” A generated page answers, “How can a reader navigate and reuse the relevant ideas?” A claim record answers, “What exactly is being asserted, and what supports or contradicts it?” A runtime index may answer, “Which page should appear first for this query?” Each answer is useful, but none should silently substitute for another. The layers make it possible to repair a missing index without inventing a source, or to revise a claim without rewriting the original bytes.
Runtime state has a different lifecycle again. A retrieval index can be rebuilt from wiki pages. A journal can be used to recover an interrupted operation. A lock can be released after the process ends, subject to conservative recovery rules. None of those artifacts should be treated as a new concept or as proof that a claim is correct. The distinction is important when inspecting a vault: a missing derived cache may reduce convenience, while a missing raw source or provenance record can change what the knowledge itself means.
Portability depends on refusing ambiguity
The product/vault boundary also explains why installation and uninstall are deliberately independent from knowledge maintenance. If a user removes a plugin or host link, the vault remains. If the product is upgraded, the user’s Markdown and source material do not need to move into a new cache. If an older vault needs additional workspace or provenance state, migration is additive and previewed rather than being an excuse to rewrite legacy notes. The system can evolve its tooling without claiming ownership of the content it operates on.
That portability has a limit. The core runs with the current user’s filesystem permissions; it is not a sandbox. A host, agent, plugin, hook, or external command that already has those permissions remains inside the same trust boundary. Separating product and vault reduces accidental target confusion and constrains supported operations, but it does not protect a user from every authorized process. Filesystem permissions and the user’s choice of tools remain part of the security model.
Platform behavior makes the same trade-off visible. On Linux, macOS, and WSL, the full mutation path can use the filesystem primitives required to confine a vault during a write. Native Windows supports inspection, dry-run previews, and retrieval, but writes are refused rather than silently performed with weaker guarantees. The refusal is not a claim that Windows cannot store Markdown. It is a decision to preserve the project’s mutation guarantees instead of changing the contract based on a weaker platform primitive.
The practical rule is simple: select the vault as deliberately as you would select the source. Keep product code, user knowledge, and derived runtime in their proper roles. Treat setup as a reviewed boundary crossing, not as an implicit side effect of installing a plugin. Once that boundary is secure, the next question is how evidence crosses into the vault: what capture actually preserves, what ingest adds, and how the system records the difference between a source, a page, and a claim.