obsidian-guide

Scope

One Obsidian vault, reached through the Local REST API plugin while Obsidian runs. Each note tool reads or edits one note per call. No tool moves or renames a note, and none rewrites links in other notes. The multi-note jobs are the workflows below.

Identifiers

• Note path: hits[].filename from obsidian_search_notes, entries[].path from obsidian_list_notes, and the path every note tool returns. Writes and deletes match it exactly, letter case included.
• Heading locator: the full Parent::Child paths in obsidian_get_note's document-map headings, and the sectionTarget a section read or write returns.
• Tag: no leading #. A note's own tags (obsidian_get_note full, the JSONLogic tags field) hold its tags as written, letter case included. Parent tags show up only in tag counts.

Gates

1. Pin active and periodic targets after the first call. Each call resolves them again. active is whichever file has focus in Obsidian at that moment, and a periodic target with no date is the current period. For the rest of the task, address the note by the path the first call returned.
2. A missing periodic note can't be created through a periodic target. Every tool reads the target before acting, so a write to a period with no note also fails periodic_not_found. Ask the user to create it in Obsidian. Or, if they agree, write it by path: read an earlier period's note (pass date) to learn the folder and filename pattern. A note written this way holds only what you send, without the user's periodic-note template. On Local REST API 5.0.2 and later without the periodic-notes extension, every periodic target fails periodic_unsupported, whether or not the note exists; find the note with obsidian_search_notes or obsidian_list_notes and address it by path.
3. Write a heading back with the sectionTarget the read returned, never the bare name you sent. A bare name resolves differently on each side. A read takes the first heading with that text in document order. A write takes the top-level heading with that text when there is one. Reading Notes and then writing Notes can touch two different sections.
4. A heading section is its whole subtree. obsidian_get_note format: "section" returns the heading line, its body, and every sub-section under it. A replace rewrites all of that, so send the sub-sections back or target the child heading instead. An append lands below the last sub-section. A prepend lands right under the heading line. Round-trip a read through obsidian_write_note with section, which drops the leading heading line. obsidian_patch_note replace keeps a leading # heading line, and plugin v5.0 and later refuse that with heading_outside_section.
5. Page a search to the end before editing its hits. Without OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, every page re-runs the search. The cursor is an offset into the new result, so edits that remove matches shift later pages and skip notes. Under a read scope, later pages come from the first page's hits for at most 5 minutes past the last page read. Collect every filename first, then edit.
6. A text hit doesn't promise a replace match. Text mode needs each token somewhere in the filename or body, in any case. obsidian_replace_in_note needs the exact string, case-sensitive by default, and searches the body only by default. Read each note's perReplacement[].count: 0 is a success that wrote nothing. useRegex patterns run without the m flag, so ^ and $ match the ends of the scoped text, not of a line. To anchor a line, use (?<=^|\n) and (?=\n|$).
7. Tags match exactly. {"in": ["work", {"var": "tags"}]} misses notes tagged only Work, or only work/tasks, which obsidian_list_tags still counts under work. To catch nested tags, use {"some": [{"var": "tags"}, {"regexp": ["^work(/|$)", {"var": ""}]}]}. obsidian_manage_tags remove is exact the same way, and its default location: "frontmatter" leaves inline #tags in the body. Pass location: "both" and check the returned tags.
8. A JSONLogic hit is a note whose tree returns something truthy, and that value is the hit's result. A note whose tree returns false, null, 0, "", [], or {} is left out. Return the field you need and one search reads it from every match: {"if": [<test>, {"var": "tags"}, null]} gives each match's tags. An empty value still drops the note.
9. After obsidian_timeout or obsidian_unreachable on a write, assume it may have landed. One write call makes several requests under one shared budget (45 s at the default timeout): a read before the write, the write, and a read after. The error can arrive after the write applied, and the server never re-sends a whole-file append or a section write. Repeating is safe for obsidian_write_note, obsidian_patch_note replace, obsidian_manage_frontmatter, and obsidian_manage_tags. On a retry, file_exists (a create), note_missing (a delete), and content_preexists (a section append or prepend sent without applyIfContentPreexists) each mean the first attempt landed. Don't force a content_preexists through with applyIfContentPreexists. Read the note before repeating a whole-file obsidian_append_to_note, or an obsidian_replace_in_note whose replace still contains its search.
10. Confirm before deleting. obsidian_delete_note deletes on the first call unless its description says it asks. Get the user's go-ahead on the exact path first.