@geml/dsh-plugin 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geml/dsh-plugin",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Agent-Native document handling for DSH — addressable blocks let an agent read and edit one section instead of the whole file. Ships the geml MCP server and the authoring and code-graph skills.",
   "license": "MIT",
   "homepage": "https://github.com/geml-spec/geml",

package/skills/geml/SKILL.md

@@ -37,14 +37,17 @@ runs 5–11% of the file it maps, but on a changelog of many small sections it i
    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.
+4. Change it. Two ways, and the choice is about **consent**, not capability:
+   - **Ordinary file-editing tool**, using the text from step 3 as the string to
+     replace. The default: a document nobody asked to address by block is edited
+     the way its author edits it.
+   - **`geml set <file> '#id' …`**, when block-addressed editing is what was
+     asked for — a knowledge base, a generated index, a log that only grows.
+     Measured on a real vault: the frontmatter and every block you did not
+     address come out **byte-for-byte unchanged**, and the body you write lands
+     verbatim — no escaping, no reflowing. Read
+     [`references/markdown-writes.md`](references/markdown-writes.md) first; two
+     of its rules are silent when broken.
 
 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
@@ -125,7 +128,7 @@ already; 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
 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
+                                      # a directory walks *.geml and *.md
 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
@@ -156,7 +159,7 @@ 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 |
+| `#tables` | pipe/CSV bodies of FACTS, `delim=`, printf display — and the `view` that derives over one: `compute=`, `summary=`, `where=`, `order=`, `limit=`, `select=`, `by=`/`aggregate=` |
 | `#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 |

package/skills/geml/references/authoring.geml

@@ -83,10 +83,13 @@ Two bodies, one model: the visual (pipe) form, or the data form
 | Basic |      1 |   30 |
 ===
 
-=== table {#fy25 format=csv header=1 compute="FY [%.1f] = Q1 + Q2 + Q3 + Q4" summary="Segment = 'Total'; FY [%.1f] = sum(FY)"}
+=== table {#fy25 format=csv header=1}
 Segment,  Q1, Q2, Q3, Q4
 Cloud,     8, 10, 12, 14
 ===
+
+=== view {#fy25-report src=#fy25 compute="FY [%.1f] = Q1 + Q2 + Q3 + Q4" summary="Segment = 'Total'; FY [%.1f] = sum(FY)"}
+===
 ====
 
 - `delim=";"` — one character replacing the data form's natural delimiter (`,`
@@ -94,6 +97,11 @@ Cloud,     8, 10, 12, 14
   single character is an error, a tab is `format=tsv` (attribute values have no
   escapes), and `delim` without a data `format` is ignored (warning). The data
   form splits and nothing more — it never strips outer `|` like the visual form.
+A `table` holds FACTS and derives nothing. Everything below belongs to a
+`view`, whose `src=` names a table, another view, or a `.csv`/`.tsv` file —
+a `table` carrying these attributes is an `unknown-attribute` warning, and a
+`table` whose `src=` names a BLOCK is an error pointing at `view`.
+
 - `compute="Name = expr; Name2 = expr2"` — per-row formulas over columns (by
   header name, or single letter `A`,`B`,…), operators `+ - * / ( )`.
   Reference an earlier computed column by name. Quote names with spaces:
@@ -102,7 +110,20 @@ Cloud,     8, 10, 12, 14
   foot row. A bare (non-aggregated) column ref in `summary` is an error.
 - A trailing `[printf]` on a name sets numeric display: `FY [%.1f]`,
   `P [%.1f%%]`.
-- Merge cells with `span="r2c1:2x1"`.
+- `where="Status = 'open' and N > 3"` — keep rows. Comparisons take a number
+  or a single-quoted string; `not`/`and`/`or` and parentheses combine them. It
+  MAY name a per-row computed column; naming an aggregate-derived one is
+  circular and refused.
+- `order="N desc, Id"` (`asc` default, stable), `limit=10`, and
+  `select="Id, N"` — columns only, in the order given; an `=` there points at
+  `compute=`.
+- `by="Area"` groups; `aggregate="Open = count(Id)"` names the group's
+  columns. `by=` alone is the distinct set of those keys. To filter GROUPS,
+  consume the view from another one (SQL's `HAVING`).
+- Order of evaluation is SQL's: per-row `compute` → `where` → aggregate
+  `compute` → `by`/`aggregate` → `order` → `limit` → `select` → `summary`.
+  So `sum(FY)` means the same in `compute=` and `summary=` — over the rows
+  shown — and a `summary=` must target a column `select=` kept.
 
 # Charts {#charts}
 
@@ -156,8 +177,12 @@ body the engine rejects is a build ERROR naming the line.
   file no longer has is an error (a drifted reference fails the build), and a
   body kept alongside it is a snapshot that warns when it goes stale. Routes
   resolve document-relative, or relative to `--root` when one is given.
-- `yaml`/`toml` are RESERVED names: no engine in the core — body kept raw
-  plus a warning, never guessed. csv/tsv belong to `table`, not `data`
+- `yaml` IS read, for a declared subset: block mappings and sequences,
+  quoted and block scalars, and YAML 1.2 **core-schema** scalars — so `yes`
+  is the string `"yes"`, not `true`. Anchors, aliases, tags, merge keys, flow
+  collections and a second document are outside it and are parse errors,
+  never guesses. `toml` stays a RESERVED name with no engine — body kept raw
+  plus a warning. csv/tsv belong to `table`, not `data`
   (their delimiter/header dialect parameters only mean something against a
   column model).
 - A chart's `data=#id` accepts a `data` block whose value is a RECORD ARRAY
@@ -222,7 +247,8 @@ geml list    file.geml                # CALL FIRST: every block, its address, ki
 geml find    "text" file|dir          # search block CONTENT -> file<TAB>address; exit 1 = no hit
                                       # a NAMED file is searched whatever its extension — `list`,
                                       # `get` and `find` all read Markdown, so this addresses a
-                                      # plain README without converting it; a DIRECTORY walks *.geml
+                                      # plain README without converting it; a DIRECTORY walks
+                                      # *.geml and *.md — both formats the parser reads
 geml get     file.geml                # same listing as `list` (the no-selector default)
 geml get     file.geml '#id'          # print ONE block (raw span; --json = model node)
 geml get     file.geml '=== note'     # every block of a type; '@a3f9c1d2' = a block with no #id
@@ -281,8 +307,10 @@ snapshot as you go, rather than re-emitting the whole file:
 
 === code {#editing-loop lang=sh}
 geml get    file.geml '#intro'         # read just this block (a heading id = its whole section)
-geml set    file.geml '#intro' --in -  # replace just this span (stdin or --in FILE);
-                                       #   the splice is re-parsed and REJECTED if it breaks the doc
+geml set    file.geml '#intro' --body --in -  # replace just this span (stdin or --in FILE);
+                                              #   raw text needs --body; a bare --in takes a WHOLE
+                                              #   block, fences and all. Either way the splice is
+                                              #   re-parsed and REJECTED if it breaks the doc
 geml history save   file.geml -m "…"   # snapshot into the .gemlhistory sidecar — do this each step
 geml history get    file.geml          # revisions, newest first; first column IS the --rev selector
 geml revert file.geml '#intro'         # roll ONE block back to the previous revision (= --rev -1)

package/skills/geml/references/markdown-writes.md

@@ -0,0 +1,116 @@
+# Writing to a Markdown file with `geml set`
+
+`geml set` and `geml add` edit one block of a `.md` in place. Nothing is
+converted: the file stays the Markdown it was, and a reader who does not have
+`geml` sees no trace of it.
+
+Everything below was measured against real documents, not read off the help
+text. Two of the rules are **silent** when broken — no error, exit code 0 — and
+they are the reason to read this before the first write rather than after.
+
+## What holds
+
+**A write is surgical.** After `geml set <file> '#id' --body --in -`, the YAML
+frontmatter and every block other than `#id` are byte-for-byte what they were.
+The verb splices; it does not re-serialize the file.
+
+**The body lands verbatim.** Whatever you write goes in as typed — a
+`> [!tip]` callout, a `[[wikilink]]`, a `` ```dataview `` fence, a table. No
+escaping, no reflowing, no normalization of your Markdown to anyone else's
+taste.
+
+**A broken result is refused.** The file is re-parsed before the write lands;
+if the result would not parse, nothing is written.
+
+**Heading addresses are stable.** `## Entities` is `#entities` on every run and
+every platform, and it survives anything happening above it. That is the whole
+reason to address a file this way instead of by line number.
+
+One exception, and it is GitHub's too: **a repeated heading is numbered by
+position.** The second `## Added` is `#added-1`, the third `#added-2` — the same
+anchors GitHub gives them — so a Keep-a-Changelog file is writable section by
+section. But a new `## Added` inserted above one shifts it: `#added-1` becomes
+`#added-2`. Take a repeated heading's address from a fresh `geml list`, never
+from memory.
+
+**The file is read as Markdown, not as GEML.** Where the two disagree, a `.md`
+gets Markdown's reading:
+
+- `[[Note]]`, `[[Note#Heading]]`, `[[Note#Heading|alias]]`, `[[Note#^block]]`
+  and `![[Note#Heading]]` are Obsidian links. The note is found by name
+  anywhere under the resolution root, `.md` implied; one that does not exist
+  yet is a **warning**, never a refusal — a vault plans notes that way.
+  Within the page, `[[#Heading Text]]` may name a heading by its text.
+- `[^label]` is a GFM footnote. With a `[^label]:` line it is a footnote;
+  without one it is plain text — so `[^0-9]` in a sentence about a regex is
+  nothing to worry about.
+- `{{title}}` is text: a template engine's placeholder, not a reference.
+- `~~~` fences and indented code blocks are code, like ``` ones. Nothing inside
+  is a link, a heading or a footnote.
+
+The resolution root is the file's own directory unless you pass `--root`. A
+note in a subfolder that links across its vault needs `--root <vault>`, and
+`geml check` says so when it sees the vault's `.obsidian/` above you. It never
+looks above the root on its own.
+
+## The three that bite
+
+### 1. Never `set` the frontmatter block — it destroys the frontmatter
+
+Frontmatter is not a typed block in Markdown; it is an anonymous prose block,
+and its **closing `---` is part of that block's body**. Replace the body and the
+closer is gone, leaving an opener with nothing to close it — no properties at
+all, for every tool that reads them.
+
+Change frontmatter with an ordinary editor. This is silent: exit code 0.
+
+### 2. `--body` is for a heading. On a prose block it APPENDS
+
+A heading's block is a heading line plus a body. A prose block is body all the
+way down, so it has no separate body to set — `get '#x' --body` on one comes
+back empty, and `set --body` writes into that emptiness, which lands **after**
+the prose already there. Nothing is removed.
+
+| target | `set '#id'` | `set '#id' --body` |
+|---|---|---|
+| a heading block | refused: *content is prose, not a block — use --body* | replaces the section body, keeps the heading line |
+| a prose block | replaces it | **appends to it, silently** |
+
+The rule is the opposite of what one habit would give you, and picking wrong
+fails loudly one way and quietly the other. `geml list` prints the kind in its
+second column — read it before choosing. This is the other silent one.
+
+### 3. `--in <file>` is not "read this text"
+
+`--in F` means *take block `#id` from file F*. Raw text goes in on **stdin**:
+
+```sh
+printf '…' | geml set page.md '#id' --body --in -      # right
+geml set page.md '#id' --body --in fragment.txt        # looks for #id INSIDE fragment.txt
+```
+
+Loud, at least: when F has no such block the refusal names the stdin form.
+
+## Smaller things worth knowing
+
+- `find` is a **literal substring**, not a pattern. `Hot.Cache` does not match
+  "Hot Cache". Case-insensitive unless `--case`.
+- `find --head` shows **one line per block**. A block with thirteen matches
+  reports one; `find` locates, `get` reads.
+- `set --body` replaces a trailing `---` rule too, if the section ends with one.
+- The blank line after a heading is not re-inserted. Cosmetic; renderers do not
+  care, a diff does.
+- A directory walk skips hidden directories. A tree that hides sources in
+  `.raw/` must name that directory: `geml find 'x' notes .raw`.
+- `@…` addresses are content hashes and change when the content does. Fine to
+  read from a fresh `list`; never store one, and never write to one.
+
+Before a first write to a page, `geml check <file>` — exit 0 means every block is
+writable; warnings (a note not yet written) never block one.
+
+## Do not convert the file
+
+`geml <page>.md --to geml` and back is lossy for anything beyond plain
+Markdown — frontmatter lists collapse, `[[…]]` comes back escaped, thematic
+breaks are dropped. The point of addressing a Markdown file is that it **stays
+Markdown**.