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

> Discover which paths are protected from user-authored bundles in Claude-Obsidian. Learn about reserved directories like .claude-obsidian.json, wiki, and config to maintain vault integrity.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Claude-Obsidian maintains a strict boundary between system-managed infrastructure and user content by reserving specific directories—including [`.claude-obsidian.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/paths.py)

The canonical list of protected locations is defined as a constant set in [`claude_obsidian/paths.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/wiki-mode.py) and [`retrieve.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py). The `_validate_write_path` method inspects every write operation before it is committed to the vault.

```python

# 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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/transaction.py), [`ledger.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/ledger.py), and [`paths.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/paths.py) remain immutable during user execution.

## Summary

- **Reserved paths** in Claude-Obsidian include [`.claude-obsidian.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.claude-obsidian.json), `wiki/`, `.raw/`, `.vault-meta/`, `scripts/`, `claude_obsidian/`, `config/`, `docs/`, and `.git/`.
- The **RESERVED_PATHS** constant in [`claude_obsidian/paths.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/paths.py) defines the protected set that separates system infrastructure from user content.
- **Transaction enforcement** occurs in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/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.