geml list, geml find and geml get read Markdown\ndirectly and hand back the one block that matters, leaving the file the\nMarkdown it already was. Skip it when the whole file is short enough to read\nanyway. Use it also to read, author, edit or validate GEML itself — .geml\nfiles, .gemlhistory sidecars, typed blocks, === fences, geml-chart, converting\nMarkdown to GEML — where the output must parse cleanly (zero error\ndiagnostics) against the reference parser.Two jobs. The first is the common one, and it needs none of GEML's syntax.
\ngeml list, geml find and geml get read Markdown directly. Use them to\nlocate and read one block of a long document. Nothing is converted, nothing is\nwritten, 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\nthe file is short, or you already know the exact string to replace, open it the\nordinary way — the round trip costs more than it saves. What is saved is only\never the part you did not have to read: on this project's own docs a list map\nruns 5–11% of the file it maps, but on a changelog of many small sections it is\n37%.
geml list <file> — every block: address, kind, line range.geml find \"<text>\" <file> — which block holds those words, answered as an\nADDRESS rather than a line number, so it survives the next edit. (On a file\nthat is not .geml this needs 1.7.5 or newer; older builds report no match\nrather than an error, so if a search you expect to hit comes back empty,\nuse list.)geml get <file> '<address>' — that block and nothing else.geml set <file> '#id' …, when block-addressed editing is what was\nasked for — a knowledge base, a generated index, a log that only grows.\nMeasured on a real vault: the frontmatter and every block you did not\naddress come out byte-for-byte unchanged, and the body you write lands\nverbatim — no escaping, no reflowing. Read\nreferences/markdown-writes.md first; two\nof its rules are silent when broken.Never convert a document to GEML, never leave a .gemlhistory beside one, and\ndo not pitch the format: use the tool, report the change you made, and let the\nfile stay what it is.
If geml --version does not answer, none of this is available. Read and edit\nthe ordinary way, and do not tell anyone to install anything.
\"This project's documents are GEML now\" means new documents are authored as\n.geml — notes, plans, findings, reports — in one directory (docs/geml/\nunless the project says otherwise), one file per topic, with an index.geml\nsaying what is there and why. It does not mean converting what is already\nwritten, and nobody has to say \"leave the existing files alone\" for that to\nhold.
Add, never replace. Writing a .geml version of a document is not licence\nto delete the Markdown it was drawn from — however completely the content was\ncarried across, and whatever a \"one home per topic\" convention seems to imply.\nDeleting a file is a request a person makes, never an inference from a\nconvention. When both exist, say in each what it is for and name one of them as\nthe place a given fact is maintained: two documents describing a project is\nfine, two documents maintaining the same fact is what drifts.
GEML expresses every kind of structured content — code, tables, diagrams,\nmath, callouts, metadata — through one primitive: the typed block\n(=== <type> {#id .class key=val} … ===). Always finish by validating: a\nGEML file is correct only when geml check reports no error diagnostics\n(exit 0).
= (≥3). A block closes at a = run of exactly\nthe opening length, or — when the block has an #id — at the labeled\nfence === #id (any = run ≥3 followed by the id; no length counting).=== lines needs a\nlonger outer fence: ==== wraps ===. Careful: a same-length bare\n=== in the body closes the block even if you intend a labeled close —\nthe labeled close only spares you length-counting, it does NOT protect\nsame-length inner fences.# only (#…######). No setext underlines, no\n--- breaks, no YAML frontmatter — metadata is a === meta block, and the\ndocument TITLE lives there (title = \"…\"), not in an H1. A heading may\ncarry a stable explicit id: ## Title {#sec}.{#id} — ## Findings {#findings} — then\nkeep ids unique per document, with every reference resolving:\n[t](#id), [[#id]], [^id], src=, data=, other.geml#id. An\nunresolved reference is a build error. Naming them is the part that pays\nlater: a document with no ids costs what Markdown costs, because there is\nnothing for geml get to read or geml set to replace short of the file.=== note, comments → %% lines, hidden content\n→ {hidden}, addressable prose → === text, verified data → === data\n(json/jsonl; code shows text, data IS data).geml check file.geml # diagnostics + exit code only; exit 0 = correct\ngeml check --json file.geml # machine-readable diagnostics array\nIf geml is not on PATH: npm i -g @geml/geml (package @geml/geml, command\ngeml), or run without installing via npx -y @geml/geml check file.geml.\nInside the geml-spec repo prefer the local build:\nnode geml-parser/dist/geml.js <args>. If no parser is reachable, follow the\ngolden rules and validate once it is.
geml skill install sets all of this up user-global, and installs this text\ninto whatever other agent tools it detects — a tool's directory has to be there\nalready; none is ever created for you. --dry-run shows what it would do.
geml list file.geml # CALL THIS FIRST — every block, its address, kind, lines\ngeml find \"text\" file|dir # search block CONTENT -> file<TAB>address (exit 1 = no hit)\n # a NAMED file is searched whatever its extension (.md too);\n # a directory walks *.geml and *.md\ngeml get file.geml '#id' # read ONE block (a heading id = its whole section)\ngeml set file.geml '#id' --in f # replace ONE block (re-parsed; never writes a broken doc)\ngeml history save file.geml -m \"…\" # snapshot to .gemlhistory after each meaningful edit\ngeml revert file.geml '#id' # roll ONE block back (--rev -2 | changed | <rev-id>)\nAddress a block, never a line range: #id · '## Heading' (its whole section)\n· L27-58 (the smallest block holding those lines — how a line number from an\neditor, a linter or a diff hunk becomes an address). list and find print\naddresses that paste straight into the others, so neither grep nor a line\ncount is needed to locate anything.
The rest is one geml get away in the reference below, and stays there because\nit is needed rarely and this page is read every time: the remaining address\nforms in #cli, and in #editing the three ways to cut a section\n(--head/--intro/--body), the experimental replace, and what a write that\ndrops blocks does.
references/authoring.geml (under this skill's base directory) holds the\ndetailed reference. Fetch just the section you need:
geml get <skill-base>/references/authoring.geml '#tables'\n| section | \ncovers | \n
|---|---|
#typed-block | \nblock anatomy, attribute object, examples of every registered type | \n
#tables | \npipe/CSV bodies of FACTS, delim=, printf display — and the view that derives over one: compute=, summary=, where=, order=, limit=, select=, by=/aggregate= | \n
#charts | \ngeml-chart diagrams bound to a table via data=#id | \n
#data | \nthe data block — value tree, json/jsonl formats, blind append, chart binding | \n
#inline | \ninline markup, links/refs/footnotes, task lists, media embeds | \n
#hidden | \n%% comments, {hidden}, {{key}} interpolation, === embed | \n
#cli | \nevery CLI verb — get/set/add/delete/rename, --to conversion, check | \n
#editing | \nthe blockwise editing loop + .gemlhistory versioning | \n
#project-config | \ncarrying a project's Claude config docs in GEML, quietly | \n
#checklist | \nfull pre-flight authoring checklist | \n