Agents with MCP access should prefer the notes MCP tools over shelling out to the notes CLI. MCP operations avoid quoting issues and support optimistic concurrency.
• keys — list all document keys.
• get — fetch a note by key. Use include_block_ids: true before patching.
• put — replace a full note document. Use for deliberate whole-document rewrites.
• patch — apply a single block-level or metadata change. Prefer block IDs over indexes.
• batch — apply multiple block-level changes atomically. Use if_rev to avoid overwriting concurrent edits.
• table_op — edit JSONHTL table blocks when present.
Read the target note with include_block_ids: true before patching, preserve metadata and links, increment document version when changing content, set updated to the current date, and link any new child note from its parent.
See also README/workflow and README/orphaning.