@geml/geml 1.7.5 → 1.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geml/geml",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "mcpName": "io.github.geml-spec/geml",
   "publishConfig": {
     "access": "public"

package/skill/SKILL.md

@@ -1,14 +1,76 @@
 ---
 name: geml
 description: >-
-  Read, author, edit, or validate GEML — the General Expressive Markup Language
-  (.geml files) and its .gemlhistory versioning sidecar. Use whenever creating
-  or modifying a .geml/.gemlhistory file, converting Markdown to GEML, or when
-  the user mentions GEML, typed blocks, === fences, or geml-chart. Ensures the
-  output parses cleanly (zero error diagnostics) against the reference parser.
+  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.
 ---
 
-# Writing and reading GEML correctly
+# 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**
@@ -30,9 +92,12 @@ GEML file is correct only when `geml check` reports **no error diagnostics**
    `---` 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. **Every `#id` is unique per document**, and **every reference must
-   resolve** — `[t](#id)`, `[[#id]]`, `[^id]`, `src=`, `data=`,
-   `other.geml#id`. An unresolved reference is a build **error**.
+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).
@@ -63,38 +128,21 @@ geml find    "text" file|dir          # search block CONTENT -> file<TAB>address
                                       # 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 replace file.geml OLD NEW        # EXPERIMENTAL literal swap; --within '#id' to narrow
 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)
-· `'=== type'` · `@<hex>` (no id) · `L27` or `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.
-
-Any section can be cut three ways, on `get` and `set` alike: `--head` (the
-heading line), `--intro` (what it says before its first subheading — empty when
-one follows immediately, the whole body when none does), `--body` (everything
-under it, so it always contains the intro). `--intro` is how you edit a
-section's opening without pulling its subsections into context, and setting an
-empty one writes an opening where the section had none.
-
-When the exact old text is already known and nothing needs reading — a version
-string in six places, a renamed term — `geml replace` is the cheap path, and the
-one to prefer over dropping to `sed`: same two short strings, but the result is
-re-parsed before it lands, the blocks it touched are named back to you, and it
-is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern, and refuses
-a swap that would rename an id (use `geml rename`, which fixes the references
-too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but do not
-build anything on it that cannot change.
-
-A write is refused when it would break the document, never merely because it
-removes something: a replacement that drops blocks is carried out and NAMED on
-stderr — unnamed blocks included — with `geml revert` as the way back. Read,
-edit, write back, and nothing is dropped, because `get` handed those blocks to
-you. Send content that omits them only when removing them is the point.
+· `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
 

package/skill/references/authoring.geml

@@ -293,6 +293,28 @@ geml revert file.geml '#intro' --rev changed  # …the block's last ACTUAL chang
 block) and `history`/`revert` (version and rewind it) let an agent revise a
 document incrementally and undo any single section.
 
+**A section can be cut three ways**, on `get` and `set` alike: `--head` (the
+heading line), `--intro` (what it says before its first subheading — empty when
+one follows immediately, the whole body when none does), `--body` (everything
+under it, so it always contains the intro). `--intro` is how you edit a
+section's opening without pulling its subsections into context, and setting an
+empty one writes an opening where the section had none.
+
+**When the exact old text is already known** and nothing needs reading — a
+version string in six places, a renamed term — `geml replace` is the cheap path,
+and the one to prefer over dropping to `sed`: the same two short strings, but
+the result is re-parsed before it lands, the blocks it touched are named back to
+you, and it is in `.gemlhistory` to revert. It swaps a LITERAL, never a pattern,
+and refuses a swap that would rename an id (use `geml rename`, which fixes the
+references too). **It is EXPERIMENTAL and may be withdrawn** — reach for it, but
+do not build anything on it that cannot change.
+
+**A write is refused when it would BREAK the document**, never merely because it
+removes something: a replacement that drops blocks is carried out and NAMED on
+stderr — unnamed blocks included — with `geml revert` as the way back. Read,
+edit, write back, and nothing is dropped, because `get` handed those blocks to
+you. Send content that omits them only when removing them is the point.
+
 **Where sidecars do NOT belong:** a doc that git already versions — config
 docs especially — usually needs no `.gemlhistory`; do not create one there
 unless the user asks for finer-than-commit history.