geml-spec/geml

When your agent uses it

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Writing GEML — one-page cheatsheet

GEML is plain text. Every structured thing is one **typed block**:

```
=== <type> {#id .class key=val}
<body>
===
```

The opening fence is **≥ 3** `=`. The **closing fence must be the same length**.
To nest a block inside a block, make the **outer fence longer**:

```
==== note

geml

When your agent uses it

Address a document by its BLOCKS instead of reading it whole. Use for any long Markdown or documentation file — README, spec, guide, design doc, changelog — when the job is to find where something is documented, read one section, or change one section: `geml list`, `geml find` and `geml get` read Markdown directly and hand back the one block that matters, leaving the file the Markdown it already was. Skip it when the whole file is short enough to read anyway. Use it also to read, author, edit or validate GEML itself — .geml files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting Markdown to GEML — where the output must parse cleanly (zero error diagnostics) against the reference parser.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

## A document that is NOT GEML — use this as a read layer

`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
locate and read one block of a long document. Nothing is converted, nothing is
written, and the file stays exactly the Markdown it already was.

**Only when you would otherwise read the whole file to change part of it.** If
the file is short, or you already know the exact string to replace, open it the
ordinary way — the round trip costs more than it saves. What is saved is only
ever the part you did not have to read: on this project's own docs a `list` map

geml

When your agent uses it

Address a document by its BLOCKS instead of reading it whole. Use for any long Markdown or documentation file — README, spec, guide, design doc, changelog — when the job is to find where something is documented, read one section, or change one section: `geml list`, `geml find` and `geml get` read Markdown directly and hand back the one block that matters, leaving the file the Markdown it already was. Skip it when the whole file is short enough to read anyway. Use it also to read, author, edit or validate GEML itself — .geml files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting Markdown to GEML — where the output must parse cleanly (zero error diagnostics) against the reference parser.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

## A document that is NOT GEML — use this as a read layer

`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
locate and read one block of a long document. Nothing is converted, nothing is
written, and the file stays exactly the Markdown it already was.

**Only when you would otherwise read the whole file to change part of it.** If
the file is short, or you already know the exact string to replace, open it the
ordinary way — the round trip costs more than it saves. What is saved is only
ever the part you did not have to read: on this project's own docs a `list` map

geml-code-graph

When your agent uses it

Build, view, update, and navigate a project's call graph as GEML codemap documents. Use when asked to see/update/build a project's code graph or codemap (看下/更新下 code-graph), when asked "who calls X" / "what does X call" / to trace a call chain or impact path, or whenever a .geml/codemap/ directory with index.geml and _index/name-lookup.json exists. Detects the project's languages itself — never asks the user; viewing ends with the browser OPEN on the graph.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Code-graph navigation (codemap profile)

The call graph lives as **text documents, not a database**
([profile](https://github.com/geml-spec/geml/blob/main/spec/profiles/geml-codemap/geml-codemap-profile.md)):
one GEML document per container (module / dir /
file), each with ONE meta (`module`, `src`, `entry`, `resolution-default`),
empty-body `code` blocks per method, and up to three CSV edge tables —
`#calls` (out), `#called-by` (in), `#unresolved` (blind spots). The build's
`verify` has checked that every edge reference resolves.

## The moves

```sh
# 1. resolve a name — where does a symbol live

geml

When your agent uses it

Address a document by its BLOCKS instead of reading it whole. Use for any long Markdown or documentation file — README, spec, guide, design doc, changelog — when the job is to find where something is documented, read one section, or change one section: `geml list`, `geml find` and `geml get` read Markdown directly and hand back the one block that matters, leaving the file the Markdown it already was. Skip it when the whole file is short enough to read anyway. Use it also to read, author, edit or validate GEML itself — .geml files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting Markdown to GEML — where the output must parse cleanly (zero error diagnostics) against the reference parser.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

## A document that is NOT GEML — use this as a read layer

`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
locate and read one block of a long document. Nothing is converted, nothing is
written, and the file stays exactly the Markdown it already was.

**Only when you would otherwise read the whole file to change part of it.** If
the file is short, or you already know the exact string to replace, open it the
ordinary way — the round trip costs more than it saves. What is saved is only
ever the part you did not have to read: on this project's own docs a `list` map

geml-code-graph

When your agent uses it

Build, view, update, and navigate a project's call graph as GEML codemap documents. Use when asked to see/update/build a project's code graph or codemap (看下/更新下 code-graph), when asked "who calls X" / "what does X call" / to trace a call chain or impact path, or whenever a .geml/codemap/ directory with index.geml and _index/name-lookup.json exists. Detects the project's languages itself — never asks the user; viewing ends with the browser OPEN on the graph.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Code-graph navigation (codemap profile)

The call graph lives as **text documents, not a database**
([profile](https://github.com/geml-spec/geml/blob/main/spec/profiles/geml-codemap/geml-codemap-profile.md)):
one GEML document per container (module / dir /
file), each with ONE meta (`module`, `src`, `entry`, `resolution-default`),
empty-body `code` blocks per method, and up to three CSV edge tables —
`#calls` (out), `#called-by` (in), `#unresolved` (blind spots). The build's
`verify` has checked that every edge reference resolves.

## The moves

```sh
# 1. resolve a name — where does a symbol live

geml

When your agent uses it

Address a document by its BLOCKS instead of reading it whole. Use for any long Markdown or documentation file — README, spec, guide, design doc, changelog — when the job is to find where something is documented, read one section, or change one section: `geml list`, `geml find` and `geml get` read Markdown directly and hand back the one block that matters, leaving the file the Markdown it already was. Skip it when the whole file is short enough to read anyway. Use it also to read, author, edit or validate GEML itself — .geml files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting Markdown to GEML — where the output must parse cleanly (zero error diagnostics) against the reference parser.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

## A document that is NOT GEML — use this as a read layer

`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
locate and read one block of a long document. Nothing is converted, nothing is
written, and the file stays exactly the Markdown it already was.

**Only when you would otherwise read the whole file to change part of it.** If
the file is short, or you already know the exact string to replace, open it the
ordinary way — the round trip costs more than it saves. What is saved is only
ever the part you did not have to read: on this project's own docs a `list` map

geml-code-graph

When your agent uses it

Build, view, update, and navigate a project's call graph as GEML codemap documents. Use when asked to see/update/build a project's code graph or codemap (看下/更新下 code-graph), when asked "who calls X" / "what does X call" / to trace a call chain or impact path, or whenever a .geml/codemap/ directory with index.geml and _index/name-lookup.json exists. Detects the project's languages itself — never asks the user; viewing ends with the browser OPEN on the graph.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Code-graph navigation (codemap profile)

The call graph lives as **text documents, not a database**
([profile](https://github.com/geml-spec/geml/blob/main/spec/profiles/geml-codemap/geml-codemap-profile.md)):
one GEML document per container (module / dir /
file), each with ONE meta (`module`, `src`, `entry`, `resolution-default`),
empty-body `code` blocks per method, and up to three CSV edge tables —
`#calls` (out), `#called-by` (in), `#unresolved` (blind spots). The build's
`verify` has checked that every edge reference resolves.

## The moves

```sh
# 1. resolve a name — where does a symbol live

geml

When your agent uses it

Address a document by its BLOCKS instead of reading it whole. Use for any long Markdown or documentation file — README, spec, guide, design doc, changelog — when the job is to find where something is documented, read one section, or change one section: `geml list`, `geml find` and `geml get` read Markdown directly and hand back the one block that matters, leaving the file the Markdown it already was. Skip it when the whole file is short enough to read anyway. Use it also to read, author, edit or validate GEML itself — .geml files, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting Markdown to GEML — where the output must parse cleanly (zero error diagnostics) against the reference parser.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Reading and editing documents blockwise

Two jobs. The first is the common one, and it needs none of GEML's syntax.

## A document that is NOT GEML — use this as a read layer

`geml list`, `geml find` and `geml get` read **Markdown** directly. Use them to
locate and read one block of a long document. Nothing is converted, nothing is
written, and the file stays exactly the Markdown it already was.

**Only when you would otherwise read the whole file to change part of it.** If
the file is short, or you already know the exact string to replace, open it the
ordinary way — the round trip costs more than it saves. What is saved is only
ever the part you did not have to read: on this project's own docs a `list` map

geml-code-graph

When your agent uses it

Build, view, update, and navigate a project's call graph as GEML codemap documents. Use when asked to see/update/build a project's code graph or codemap (看下/更新下 code-graph), when asked "who calls X" / "what does X call" / to trace a call chain or impact path, or whenever a .geml/codemap/ directory with index.geml and _index/name-lookup.json exists. Detects the project's languages itself — never asks the user; viewing ends with the browser OPEN on the graph.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Code-graph navigation (codemap profile)

The call graph lives as **text documents, not a database**
([profile](https://github.com/geml-spec/geml/blob/main/spec/profiles/geml-codemap/geml-codemap-profile.md)):
one GEML document per container (module / dir /
file), each with ONE meta (`module`, `src`, `entry`, `resolution-default`),
empty-body `code` blocks per method, and up to three CSV edge tables —
`#calls` (out), `#called-by` (in), `#unresolved` (blind spots). The build's
`verify` has checked that every edge reference resolves.

## The moves

```sh
# 1. resolve a name — where does a symbol live

geml-vault

When your agent uses it

Work a Markdown knowledge base — an Obsidian vault, a wiki, a docs tree — by BLOCK ADDRESS instead of by whole page. Use when the job is to find which page and which section says something, read that one section, add a line to an index or a log, or rewrite one section of a note: `geml find` answers with `file#address`, `geml get` hands back that block alone, and `geml set` / `geml add` change it in place while every other block, and the YAML frontmatter, stay byte-for-byte identical. Wikilinks, callouts and embeds are written through verbatim, so the file stays the Markdown Obsidian renders. No Obsidian process, no REST API, no plugin required. Triggers on: wiki, vault, knowledge base, second brain, ingest a source, update the index, append to the log, find which note says, edit one section of a note.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# 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.