Which Paths Are Reserved and Protected from User-Authored Bundles in Claude-Obsidian

Claude-Obsidian maintains a strict boundary between system-managed infrastructure and user content by reserving specific directories—including .claude-obsidian.json, wiki/, .raw/, .vault-meta/, scripts/, claude_obsidian/, config/, docs/, and .git/—that cannot be modified by user-authored bundles to ensure vault integrity and transaction safety.

Claude-Obsidian implements a hardened vault architecture that separates internal system operations from user-generated content. Understanding which paths are reserved and protected from user-authored bundles is essential for developers extending the platform, as any attempt to write to these locations triggers a permission error and aborts the transaction. The enforcement mechanism is defined in the core Python library and applied uniformly across all vault operations.

The Reserved Path Registry in claude_obsidian/paths.py

The canonical list of protected locations is defined as a constant set in claude_obsidian/paths.py. These paths represent the structural backbone of the vault and are considered immutable by user code.

The RESERVED_PATHS constant includes:

• .claude-obsidian.json — The vault-selection marker that identifies the root of a Claude-Obsidian vault and resolves vault boundaries
• wiki/ — Generated knowledge pages that are auto-populated by the system from source payloads and rebuilt automatically
• .raw/ — Immutable source payloads and legacy delta manifests stored in append-only mode to preserve provenance
• .vault-meta/ — Runtime locks, transaction journals, indexes, queues, and internal configuration files
• scripts/ — Core CLI utilities and mode scripts including wiki-mode.py and retrieve.py that implement agent behavior
• claude_obsidian/ — The core Python library containing transaction logic, path validation, contract enforcement, and ledger management
• config/ — Product contracts, capability declarations, release allow-lists, and marketplace metadata governing allowed extensions
• docs/ — Authoritative documentation and user guides serving as the source of truth for platform usage
• .git/ — Git repository metadata required for version control integrity and reproducibility checks

Any file or directory operation targeting these paths from a user-authored bundle is categorically rejected by the transaction layer.

Transaction-Level Enforcement via _validate_write_path

Protection is not merely declarative; it is actively enforced at runtime in claude_obsidian/transaction.py. The _validate_write_path method inspects every write operation before it is committed to the vault.

# claude_obsidian/transaction.py – Runtime path validation

def _validate_write_path(self, rel_path: str) -> None:
    """Raise an error if a write targets a reserved path."""
    parts = rel_path.split("/")
    for reserved in paths.RESERVED_PATHS:
        if parts[0] == reserved:
            raise PermissionError(
                f"Attempted write to reserved path '{reserved}'. "
                "User-authored bundles cannot modify this location."
            )

When a bundle initiates a write, the transaction object invokes this validator. If the relative path starts with any entry in RESERVED_PATHS, the operation aborts immediately with a PermissionError, preventing corruption of system-critical files.

System Consequences of Reserved Path Violations

Attempting to modify reserved paths breaks the mutation protocol that guarantees vault reproducibility. Writing to .raw/ would corrupt provenance chains and delta calculations, while modifying .vault-meta/ could disable transaction locking or journaling mechanisms. Changes to config/ might open security vulnerabilities by altering capability declarations or release allow-lists.

The claude_obsidian/vault_ops.py module relies on these protections to maintain consistent state across high-level operations. By reserving the claude_obsidian/ directory itself, the platform ensures that core engine files like transaction.py, ledger.py, and paths.py remain immutable during user execution.

Summary

• Reserved paths in Claude-Obsidian include .claude-obsidian.json, wiki/, .raw/, .vault-meta/, scripts/, claude_obsidian/, config/, docs/, and .git/.
• The RESERVED_PATHS constant in claude_obsidian/paths.py defines the protected set that separates system infrastructure from user content.
• Transaction enforcement occurs in claude_obsidian/transaction.py via the _validate_write_path method, which raises PermissionError for any violation.
• User-authored bundles must write exclusively to non-reserved locations, typically within user-specific inbox directories or dedicated vault subdirectories outside the protected set.
• These protections ensure transaction safety, reproducibility, and security boundary integrity across the platform.

Frequently Asked Questions

What happens if a user-authored bundle attempts to write to a reserved path?

The transaction validator immediately raises a PermissionError with a message specifying the reserved path that was targeted. This aborts the current transaction and prevents any changes from being persisted to the vault, ensuring that system files remain untouched and the mutation protocol is upheld.

Is the .git directory also protected from bundle operations?

Yes. The .git/ path is explicitly included in the RESERVED_PATHS set defined in claude_obsidian/paths.py. Modifying Git internals would break version control integrity and compromise the reproducibility guarantees of the vault, so all bundle writes to this location are blocked by the transaction layer.

Why is the wiki/ folder protected if it contains documentation?

The wiki/ directory contains generated knowledge pages that are auto-populated from source payloads managed by the system. While it appears to store documentation, it is system-managed content that is rebuilt from raw sources. User edits belong in the vault inbox or other user-authored spaces, not in the auto-generated wiki/ folder.

Where should user-authored bundles write their files instead?

User-authored bundles should write to locations outside the reserved set, typically within a user-specific inbox directory or a dedicated subdirectory within the vault root that is not listed in RESERVED_PATHS. This ensures compliance with the mutation protocol while allowing full creative freedom for user content and extensions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}