# Supported Operation Types in Claude-Obsidian Transactions: Complete Reference

> Discover the 13 supported operation types in Claude-Obsidian transactions for strict vault mutation control. Explore save, ingest, lint-fix, and migration operations.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: api-reference
- Published: 2026-08-29

---

**Claude-Obsidian defines 13 distinct operation types in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) that enforce strict authority boundaries over vault mutations, ranging from `save` and `ingest` to `lint-fix` and `migration`.**

The claude-obsidian repository by AgriciDaniel implements a transactional vault system where every mutation is modeled as a typed operation. Understanding these **supported operation types in claude-obsidian transactions** is essential for extending the system or debugging permission errors. Each type is enumerated in the `OPERATION_TYPES` constant and determines whether a transaction can modify raw payloads, wiki content, or configuration metadata.

## Understanding the Transaction Architecture

In [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), the transaction system wraps every vault change in a bundle that carries an operation type. This design enforces **authority boundaries**—specifically, which parts of the vault a given transaction may touch. The core constant `OPERATION_TYPES` (lines 44-58) defines the valid enumeration, while `safe_operation_id()` validates operation strings before bundle construction.

## The 13 Operation Types Defined in claude-obsidian

The following table documents all supported operation types as implemented in the source code:

### Core and Administrative Operations

- **base**: Core low-level operation used internally for generic changes.
- **setup**: Initial vault setup or re-initialization (bootstrap files).
- **migration**: Structural or format migrations across vault versions.
- **configuration**: Adjusts [`.claude-obsidian.json`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/.claude-obsidian.json) and other config files.
- **generic**: Catch-all wiki-only operation that cannot modify managed metadata.

### Content Creation and Ingestion

- **save**: Primary wiki-write action for creating or updating pages.
- **ingest**: Imports raw source payloads (e.g., `.raw/` files) into the vault.
- **capture**: Handles incoming notes such as inbox entries.
- **autoresearch**: Automatic research extensions pulling external data into vault.

### Transformation and UI Operations

- **markdown**: Pure markdown transformations that avoid touching raw payloads.
- **lint-fix**: Applies automatic linting corrections to wiki pages.
- **fold**: Collapses or folds wiki structures like page sections.
- **canvas**: Manipulates canvas-type artifacts for graphical UI elements.

## Authority Boundaries: Wiki vs. Raw Payload Access

The transaction system enforces strict separation between **wiki content** and **raw payloads**. According to [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py), only two operation types may touch both domains:

- **ingest**: Imports external raw files into the vault structure.
- **autoresearch**: Pulls external data that may include raw sources.

The following are restricted to **wiki-only** modifications:
- **save**, **lint-fix**, **markdown**, **generic**

Attempting to use a wiki-only operation to modify raw payloads results in validation rejection during the bundle planning phase.

## Validating and Using Operation Types in Code

When building transaction bundles programmatically, always validate against `OPERATION_TYPES` before construction.

### Validating Operation Strings

Use the built-in enumeration to reject unsupported types:

```python
from claude_obsidian.transaction import OPERATION_TYPES, safe_operation_id

def validate_op(op: str) -> str:
    """Verify operation is supported and return normalized ID."""
    if op not in OPERATION_TYPES:
        raise ValueError(f"Unsupported operation type: {op}")
    return safe_operation_id(op)  # Validates ID format

```

### Constructing Transaction Bundles

Create bundles with the correct schema and operation field:

```python
from pathlib import Path

def make_save_bundle(vault: Path, rel_path: str, content: bytes) -> dict:
    """Create a 'save' transaction bundle for wiki updates."""
    return {
        "schema": "claude-obsidian.transaction.v1",
        "operation": "save",
        "writes": [
            {
                "path": rel_path,
                "data": content.decode(),
                "mode": 0o644,
            }
        ],
    }

# Usage example

bundle = make_save_bundle(
    Path("/my/vault"), 
    "wiki/example.md", 
    b"# Example Content"

)

# Bundle passed to plan_approval_sha256 for approval

```

## Integration with Vault Operations

The high-level API in [`claude_obsidian/vault_ops.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/vault_ops.py) wraps these primitives, automatically setting the correct operation type based on the method called. For example, `ingest_raw_files()` sets operation to `ingest`, while `save_page()` uses `save`. The CLI entry point in [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py) exposes these through command-line arguments that map directly to the supported operation types.

## Summary

- Claude-obsidian defines **13 operation types** in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) under the `OPERATION_TYPES` constant.
- Types range from **base** and **generic** to specialized operations like **autoresearch** and **lint-fix**.
- **Authority boundaries** restrict which operations can modify raw payloads versus wiki-only content.
- Use `safe_operation_id()` and membership checks against `OPERATION_TYPES` to validate operations before bundle construction.
- The transaction system uses these types to construct journal entries and reject unauthorized writes.

## Frequently Asked Questions

### What happens if I use an unsupported operation type in a transaction?

The validation logic in [`claude_obsidian/transaction.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/transaction.py) raises a `ValueError` during bundle construction if the operation string is not found in `OPERATION_TYPES`. This prevents malformed transactions from reaching the approval or commit stages.

### Can I create custom operation types for my claude-obsidian extensions?

No, the `OPERATION_TYPES` set is enforced as a closed enumeration in the source code. Extensions should map their functionality to existing types like `generic` for wiki modifications or `ingest` for importing external data. The authority boundary system depends on this fixed enumeration for security validation.

### Which operation types can modify raw files in the .raw/ directory?

Only **ingest** and **autoresearch** operations possess the authority to touch both wiki content and raw payload files. Operations like **save**, **markdown**, and **lint-fix** are restricted to wiki-only modifications and will be rejected if they attempt to write to raw paths.

### How does the CLI map commands to operation types?

The [`scripts/claude-obsidian.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/claude-obsidian.py) entry point maps subcommands directly to operation types. For instance, the `save` command creates bundles with operation `"save"`, while `ingest` uses `"ingest"`. This mapping ensures that authority boundaries are respected even when invoking operations from the shell.