List all configured vaults by name.

Get statistics for a single vault.

List files/directories in the vault, optionally recursively, with optional glob filter.

Find files by name (exact / substring / glob / regex).

Read a file's full content. Returns content + content_hash + totalLines so subsequent surgical edits can use the hash as a precondition.

Read a line range from a file (1-based, inclusive). Returns the slice + rangeHash + contentHash for surgical follow-ups.

Return the heading tree of a markdown file. Each entry includes path, level, line, end_line, section_hash, children_count, and (when applicable) duplicate_of[]. Use this to navigate large notes without reading them.

Find headings by leaf text OR by full Parent::Child::Leaf path. Returns ALL matches; surgical-edit tools require disambiguation when count > 1.

Find a block-reference (^id) in a file. Returns line/structuralType/blockHash so block.replace can be called with the precondition.

Read the frontmatter (or a nested key via dot-notation) from a markdown file.

List tags found in a single file (when 'file' is supplied) or aggregated across the vault.

Return outlinks (from the given file) and/or backlinks (vault-wide search for refs targeting the file's basename).

Read structural metadata for a file: frontmatter, headings, tags, link counts, total lines, content_hash.

Substring search across markdown files. Returns hits with surrounding context and per-line hashes (each hit can be surgically rewritten with str_replace).

(planned) Diff a file against a prior content_hash. Stubbed for v1.0 — requires history cache; returns NOT_FOUND until enabled.

Surgical edit: replace a literal substring in a file. Default occurrence='unique' (errors on >1 match). Tiny payload in/out; preferred over file.replace for any edit smaller than the whole file.

Apply a unified diff to a file. Context lines (' ' prefix) are validated verbatim per hunk — the diff IS the content precondition. expected_content_hash is optional belt-and-suspenders. Use this for multi-hunk surgical edits.

Apply a batch of str_replace edits to a single file in one round-trip. Edits applied in order against the running in-memory text; atomic (rolled back in memory if any edit fails).

Replace the BODY beneath a heading (not the heading line itself). Errors if heading missing or path is ambiguous. Requires expected_section_hash from heading.find/outline.

Rename a heading's text in place. Errors on missing/duplicate. Preserves heading level. Does NOT update backlinks (use bulk.apply for that).

Replace the structural block referenced by ^id (paragraph/list-item/table-row/etc.) preserving the ^id marker. Requires expected_block_hash from block.find.

Rename a block reference (^old → ^new) on the same line, preserving line content.

Set a (possibly nested via dot-notation) key in the file's frontmatter. Creates the frontmatter block if absent. Requires expected_frontmatter_hash unless file has no frontmatter yet.

Delete a (possibly nested) key from the file's frontmatter. No-op if key absent. Requires expected_frontmatter_hash when frontmatter exists.

Replace a contiguous line range (1-based, inclusive). Requires expected_range_hash returned by file.read_range or outline (section_hash).

Insert content before line N (1-based). Use line=totalLines+1 to append. No hash precondition required.

Create a NEW file with the given content. Errors if the file already exists; use file.replace for overwrite.

HEAVY: replace the entire content of a file. Prefer str_replace / apply_patch / heading.replace_body / block.replace / frontmatter.set / lines.replace for surgical edits. Requires expected_content_hash unless create_if_missing is true and the file does not exist.

Append text to a file (creating it if missing). Cheap: no read of existing content required.

Move or rename a file. Defaults to on_conflict='error' — never silently overwrites.

Delete a file. Default trash=true → moved to /.obsidian/trash. Hard delete (trash=false) requires expected_content_hash.

Execute a batch of write operations. With atomic=true (default), all ops are first validated in dry-run mode against in-memory snapshots; the actual writes happen only if every op would succeed. If any post-validation write fails, best-effort restore is attempted.