geml-vault

A Markdown vault, addressed by block

The pages stay Markdown. Nothing is converted. What changes is how you reach into them: an address (#entities) instead of a line number, and a write that touches one block instead of rewriting a file.

This buys three things grep + Read + Edit cannot give you:

1. An address survives edits. A line number stops being true the moment anything above it changes. #entities does not.
2. A write needs nothing read first. No whole page pulled into context to build an old_string that has to match exactly.
3. It works offline. No Obsidian running, no Local REST API, no API key.

Read: locate, then take one block

geml find '<literal text>' <dir> --head   # → file ⇥ #address ⇥ the matching line
geml get  <file> '#address' --body        # → that block, nothing else
geml list <file>                          # → every address in one page

find walks a directory for *.geml and *.md. It skips hidden directories — a vault that hides sources in .raw/ must name that directory explicitly.

Read a whole page only when list shows it is short enough that taking one block saves nothing. Most notes are; index, log and cache pages are not, and those are where this skill earns its place.

Write: change one block

geml list <file>                          # ALWAYS first — addresses AND the kind column
geml set  <file> '#heading' --body --in - # a HEADING: --body replaces the section body
geml set  <file> '#prose-addr' --in -     # a PROSE block: NO --body, or it appends
geml add  <file> --after '#id' --in -     # insert a new block after one
geml add  <file> --append   --in -        # append to the end (log pages)

--body and the block's kind must agree. On a heading it means "the section below the heading line"; a prose block has no body of its own, so --body writes after the prose instead of over it — silently, exit 0. geml list prints the kind in its second column, which is why it comes first.