@geml/geml 1.8.2 → 1.8.4

package/package.json

@@ -1,67 +1,67 @@
-{
-  "name": "@geml/geml",
-  "version": "1.8.2",
-  "mcpName": "io.github.geml-spec/geml",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "CLI and parser for GEML, a plain-text document format where every block has an id — so an AI patches one block instead of rewriting the file; edits, reference checks and rollbacks are all per block. Ships an MCP server.",
-  "type": "module",
-  "bin": {
-    "geml": "dist/cli.js"
-  },
-  "main": "dist/geml.js",
-  "types": "dist/geml.d.ts",
-  "files": [
-    "dist",
-    "codemap",
-    "skill",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "geml",
-    "general expressive markup language",
-    "mcp",
-    "mcp-server",
-    "markup",
-    "markdown",
-    "parser",
-    "cli",
-    "document",
-    "typed-block",
-    "ai",
-    "agent",
-    "llm",
-    "addressable",
-    "versioning",
-    "docs",
-    "code-graph"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/geml-spec/geml.git",
-    "directory": "geml-parser"
-  },
-  "homepage": "https://github.com/geml-spec/geml#readme",
-  "bugs": {
-    "url": "https://github.com/geml-spec/geml/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "tsc && node test/all.mjs",
-    "parse": "node dist/geml.js",
-    "coverage": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --reporter=text --reporter=text-summary node test/all.mjs",
-    "coverage:check": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --check-coverage --lines 95 --statements 95 --functions 95 --branches 95 node test/all.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.19.21",
-    "c8": "^10.1.3",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@geml/geml",
+  "version": "1.8.4",
+  "mcpName": "io.github.geml-spec/geml",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "CLI and parser for GEML, a plain-text document format where every block has an id — so an AI patches one block instead of rewriting the file; edits, reference checks and rollbacks are all per block. Ships an MCP server.",
+  "type": "module",
+  "bin": {
+    "geml": "dist/cli.js"
+  },
+  "main": "dist/geml.js",
+  "types": "dist/geml.d.ts",
+  "files": [
+    "dist",
+    "codemap",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "geml",
+    "general expressive markup language",
+    "mcp",
+    "mcp-server",
+    "markup",
+    "markdown",
+    "parser",
+    "cli",
+    "document",
+    "typed-block",
+    "ai",
+    "agent",
+    "llm",
+    "addressable",
+    "versioning",
+    "docs",
+    "code-graph"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geml-spec/geml.git",
+    "directory": "geml-parser"
+  },
+  "homepage": "https://github.com/geml-spec/geml#readme",
+  "bugs": {
+    "url": "https://github.com/geml-spec/geml/issues"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node test/all.mjs",
+    "parse": "node dist/geml.js",
+    "coverage": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --reporter=text --reporter=text-summary node test/all.mjs",
+    "coverage:check": "tsc && c8 --all --include=dist/**/*.js --include=codemap/**/*.mjs --check-coverage --lines 95 --statements 95 --functions 95 --branches 95 node test/all.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "c8": "^10.1.3",
+    "typescript": "^5.9.3"
+  }
+}

package/skill/SKILL.md

@@ -1,167 +1,167 @@
----
-name: geml
-description: >-
-  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.
----
-
-# 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
-runs 5–11% of the file it maps, but on a changelog of many small sections it is
-37%.
-
-1. `geml list <file>` — every block: address, kind, line range.
-2. `geml find "<text>" <file>` — which block holds those words, answered as an
-   ADDRESS rather than a line number, so it survives the next edit. (On a file
-   that is not `.geml` this needs 1.7.5 or newer; older builds report no match
-   rather than an error, so if a search you expect to hit comes back empty,
-   use `list`.)
-3. `geml get <file> '<address>'` — that block and nothing else.
-4. Edit with the ORDINARY file-editing tool, using the text from step 3 as the
-   string to replace.
-
-Step 4 is a safety property, not a shortcut taken for speed. `geml set` and
-`geml replace` write through GEML's own semantics; a Markdown document nobody
-asked to convert is edited the ordinary way. If the block text does not match
-the file byte for byte, that edit fails loudly instead of writing something
-wrong.
-
-Never convert a document to GEML, never leave a `.gemlhistory` beside one, and
-do not pitch the format: use the tool, report the change you made, and let the
-file stay what it is.
-
-If `geml --version` does not answer, none of this is available. Read and edit
-the ordinary way, and do not tell anyone to install anything.
-
-## A project moving TO GEML
-
-"This project's documents are GEML now" means new documents are authored as
-`.geml` — notes, plans, findings, reports — in one directory (`docs/geml/`
-unless the project says otherwise), one file per topic, with an `index.geml`
-saying what is there and why. It does not mean converting what is already
-written, and nobody has to say "leave the existing files alone" for that to
-hold.
-
-**Add, never replace.** Writing a `.geml` version of a document is not licence
-to delete the Markdown it was drawn from — however completely the content was
-carried across, and whatever a "one home per topic" convention seems to imply.
-Deleting a file is a request a person makes, never an inference from a
-convention. When both exist, say in each what it is for and name one of them as
-the place a given fact is maintained: two documents describing a project is
-fine, two documents maintaining the same fact is what drifts.
-
-## A GEML document — get the syntax right
-
-GEML expresses **every** kind of structured content — code, tables, diagrams,
-math, callouts, metadata — through **one** primitive: the **typed block**
-(`=== <type> {#id .class key=val}` … `===`). Always finish by **validating**: a
-GEML file is correct only when `geml check` reports **no error diagnostics**
-(exit 0).
-
-## Golden rules (the things that are easy to get wrong)
-
-1. **Fences are runs of `=` (≥3).** A block closes at a `=` run of **exactly
-   the opening length**, or — when the block has an `#id` — at the labeled
-   fence `=== #id` (any `=` run ≥3 followed by the id; no length counting).
-2. **Nest with longer fences.** A body containing `===` lines needs a
-   **longer** outer fence: `====` wraps `===`. Careful: a same-length bare
-   `===` in the body closes the block even if you intend a labeled close —
-   the labeled close only spares you length-counting, it does NOT protect
-   same-length inner fences.
-3. **Headings are ATX `#` only** (`#`…`######`). No setext underlines, no
-   `---` breaks, no YAML frontmatter — metadata is a `=== meta` block, and the
-   document TITLE lives there (`title = "…"`), not in an H1. A heading may
-   carry a stable explicit id: `## Title {#sec}`.
-4. **Give every section a stable `{#id}`** — `## Findings {#findings}` — then
-   keep ids unique per document, with **every reference resolving**:
-   `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`, `other.geml#id`. An
-   unresolved reference is a build **error**. Naming them is the part that pays
-   later: a document with no ids costs what Markdown costs, because there is
-   nothing for `geml get` to read or `geml set` to replace short of the file.
-5. **No raw HTML.** Notes → `=== note`, comments → `%%` lines, hidden content
-   → `{hidden}`, addressable prose → `=== text`, verified data → `=== data`
-   (json/jsonl; `code` shows text, `data` IS data).
-
-## Validate every time
-
-```sh
-geml check file.geml          # diagnostics + exit code only; exit 0 = correct
-geml check --json file.geml   # machine-readable diagnostics array
-```
-
-If `geml` is not on PATH: `npm i -g @geml/geml` (package `@geml/geml`, command
-`geml`), or run without installing via `npx -y @geml/geml check file.geml`.
-Inside the geml-spec repo prefer the local build:
-`node geml-parser/dist/geml.js <args>`. If no parser is reachable, follow the
-golden rules and validate once it is.
-
-`geml skill install` sets all of this up user-global, and installs this text
-into whatever other agent tools it detects — a tool's directory has to be there
-already; none is ever created for you. `--dry-run` shows what it would do.
-
-## Work blockwise (agent editing)
-
-```sh
-geml list    file.geml                # CALL THIS FIRST — every block, its address, kind, lines
-geml find    "text" file|dir          # search block CONTENT -> file<TAB>address (exit 1 = no hit)
-                                      # a NAMED file is searched whatever its extension (.md too);
-                                      # a directory walks *.geml only
-geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
-geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
-geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
-geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
-```
-
-Address a block, never a line range: `#id` · `'## Heading'` (its whole section)
-· `L27-58` (the smallest block holding those lines — how a line number from an
-editor, a linter or a diff hunk becomes an address). `list` and `find` print
-addresses that paste straight into the others, so neither `grep` nor a line
-count is needed to locate anything.
-
-The rest is one `geml get` away in the reference below, and stays there because
-it is needed rarely and this page is read every time: the remaining address
-forms in `#cli`, and in `#editing` the three ways to cut a section
-(`--head`/`--intro`/`--body`), the experimental `replace`, and what a write that
-drops blocks does.
-
-## Full reference — pull ONE section, not the whole file
-
-`references/authoring.geml` (under this skill's base directory) holds the
-detailed reference. Fetch just the section you need:
-
-```sh
-geml get <skill-base>/references/authoring.geml '#tables'
-```
-
-| section | covers |
-|---|---|
-| `#typed-block` | block anatomy, attribute object, examples of every registered type |
-| `#tables` | pipe/CSV bodies, `compute=`, `summary=`, printf display, `span=` merges |
-| `#charts` | `geml-chart` diagrams bound to a table via `data=#id` |
-| `#data` | the `data` block — value tree, `json`/`jsonl` formats, blind append, chart binding |
-| `#inline` | inline markup, links/refs/footnotes, task lists, media embeds |
-| `#hidden` | `%%` comments, `{hidden}`, `{{key}}` interpolation, `=== embed` |
-| `#cli` | every CLI verb — get/set/add/delete/rename, `--to` conversion, check |
-| `#editing` | the blockwise editing loop + `.gemlhistory` versioning |
-| `#project-config` | carrying a project's Claude config docs in GEML, quietly |
-| `#checklist` | full pre-flight authoring checklist |
+---
+name: geml
+description: >-
+  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.
+---
+
+# 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
+runs 5–11% of the file it maps, but on a changelog of many small sections it is
+37%.
+
+1. `geml list <file>` — every block: address, kind, line range.
+2. `geml find "<text>" <file>` — which block holds those words, answered as an
+   ADDRESS rather than a line number, so it survives the next edit. (On a file
+   that is not `.geml` this needs 1.7.5 or newer; older builds report no match
+   rather than an error, so if a search you expect to hit comes back empty,
+   use `list`.)
+3. `geml get <file> '<address>'` — that block and nothing else.
+4. Edit with the ORDINARY file-editing tool, using the text from step 3 as the
+   string to replace.
+
+Step 4 is a safety property, not a shortcut taken for speed. `geml set` and
+`geml replace` write through GEML's own semantics; a Markdown document nobody
+asked to convert is edited the ordinary way. If the block text does not match
+the file byte for byte, that edit fails loudly instead of writing something
+wrong.
+
+Never convert a document to GEML, never leave a `.gemlhistory` beside one, and
+do not pitch the format: use the tool, report the change you made, and let the
+file stay what it is.
+
+If `geml --version` does not answer, none of this is available. Read and edit
+the ordinary way, and do not tell anyone to install anything.
+
+## A project moving TO GEML
+
+"This project's documents are GEML now" means new documents are authored as
+`.geml` — notes, plans, findings, reports — in one directory (`docs/geml/`
+unless the project says otherwise), one file per topic, with an `index.geml`
+saying what is there and why. It does not mean converting what is already
+written, and nobody has to say "leave the existing files alone" for that to
+hold.
+
+**Add, never replace.** Writing a `.geml` version of a document is not licence
+to delete the Markdown it was drawn from — however completely the content was
+carried across, and whatever a "one home per topic" convention seems to imply.
+Deleting a file is a request a person makes, never an inference from a
+convention. When both exist, say in each what it is for and name one of them as
+the place a given fact is maintained: two documents describing a project is
+fine, two documents maintaining the same fact is what drifts.
+
+## A GEML document — get the syntax right
+
+GEML expresses **every** kind of structured content — code, tables, diagrams,
+math, callouts, metadata — through **one** primitive: the **typed block**
+(`=== <type> {#id .class key=val}` … `===`). Always finish by **validating**: a
+GEML file is correct only when `geml check` reports **no error diagnostics**
+(exit 0).
+
+## Golden rules (the things that are easy to get wrong)
+
+1. **Fences are runs of `=` (≥3).** A block closes at a `=` run of **exactly
+   the opening length**, or — when the block has an `#id` — at the labeled
+   fence `=== #id` (any `=` run ≥3 followed by the id; no length counting).
+2. **Nest with longer fences.** A body containing `===` lines needs a
+   **longer** outer fence: `====` wraps `===`. Careful: a same-length bare
+   `===` in the body closes the block even if you intend a labeled close —
+   the labeled close only spares you length-counting, it does NOT protect
+   same-length inner fences.
+3. **Headings are ATX `#` only** (`#`…`######`). No setext underlines, no
+   `---` breaks, no YAML frontmatter — metadata is a `=== meta` block, and the
+   document TITLE lives there (`title = "…"`), not in an H1. A heading may
+   carry a stable explicit id: `## Title {#sec}`.
+4. **Give every section a stable `{#id}`** — `## Findings {#findings}` — then
+   keep ids unique per document, with **every reference resolving**:
+   `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`, `other.geml#id`. An
+   unresolved reference is a build **error**. Naming them is the part that pays
+   later: a document with no ids costs what Markdown costs, because there is
+   nothing for `geml get` to read or `geml set` to replace short of the file.
+5. **No raw HTML.** Notes → `=== note`, comments → `%%` lines, hidden content
+   → `{hidden}`, addressable prose → `=== text`, verified data → `=== data`
+   (json/jsonl; `code` shows text, `data` IS data).
+
+## Validate every time
+
+```sh
+geml check file.geml          # diagnostics + exit code only; exit 0 = correct
+geml check --json file.geml   # machine-readable diagnostics array
+```
+
+If `geml` is not on PATH: `npm i -g @geml/geml` (package `@geml/geml`, command
+`geml`), or run without installing via `npx -y @geml/geml check file.geml`.
+Inside the geml-spec repo prefer the local build:
+`node geml-parser/dist/geml.js <args>`. If no parser is reachable, follow the
+golden rules and validate once it is.
+
+`geml skill install` sets all of this up user-global, and installs this text
+into whatever other agent tools it detects — a tool's directory has to be there
+already; none is ever created for you. `--dry-run` shows what it would do.
+
+## Work blockwise (agent editing)
+
+```sh
+geml list    file.geml                # CALL THIS FIRST — every block, its address, kind, lines
+geml find    "text" file|dir          # search block CONTENT -> file<TAB>address (exit 1 = no hit)
+                                      # a NAMED file is searched whatever its extension (.md too);
+                                      # a directory walks *.geml only
+geml get     file.geml '#id'          # read ONE block (a heading id = its whole section)
+geml set     file.geml '#id' --in f   # replace ONE block (re-parsed; never writes a broken doc)
+geml history save file.geml -m "…"    # snapshot to .gemlhistory after each meaningful edit
+geml revert  file.geml '#id'          # roll ONE block back (--rev -2 | changed | <rev-id>)
+```
+
+Address a block, never a line range: `#id` · `'## Heading'` (its whole section)
+· `L27-58` (the smallest block holding those lines — how a line number from an
+editor, a linter or a diff hunk becomes an address). `list` and `find` print
+addresses that paste straight into the others, so neither `grep` nor a line
+count is needed to locate anything.
+
+The rest is one `geml get` away in the reference below, and stays there because
+it is needed rarely and this page is read every time: the remaining address
+forms in `#cli`, and in `#editing` the three ways to cut a section
+(`--head`/`--intro`/`--body`), the experimental `replace`, and what a write that
+drops blocks does.
+
+## Full reference — pull ONE section, not the whole file
+
+`references/authoring.geml` (under this skill's base directory) holds the
+detailed reference. Fetch just the section you need:
+
+```sh
+geml get <skill-base>/references/authoring.geml '#tables'
+```
+
+| section | covers |
+|---|---|
+| `#typed-block` | block anatomy, attribute object, examples of every registered type |
+| `#tables` | pipe/CSV bodies, `compute=`, `summary=`, printf display, `span=` merges |
+| `#charts` | `geml-chart` diagrams bound to a table via `data=#id` |
+| `#data` | the `data` block — value tree, `json`/`jsonl` formats, blind append, chart binding |
+| `#inline` | inline markup, links/refs/footnotes, task lists, media embeds |
+| `#hidden` | `%%` comments, `{hidden}`, `{{key}}` interpolation, `=== embed` |
+| `#cli` | every CLI verb — get/set/add/delete/rename, `--to` conversion, check |
+| `#editing` | the blockwise editing loop + `.gemlhistory` versioning |
+| `#project-config` | carrying a project's Claude config docs in GEML, quietly |
+| `#checklist` | full pre-flight authoring checklist |