aontu 0.52.1 → 0.54.0

package/grammar/aontu.tmLanguage.json

@@ -0,0 +1,184 @@
+{
+  "information_for_contributors": [
+    "Aontu — published grammar (TextMate), for SYNTAX HIGHLIGHTING.",
+    "",
+    "The third consumer of the published surface, beside grammar/aontu.gbnf",
+    "and grammar/aontu.lark: those two constrain a decoder, this one colours",
+    "a reader. One file serves every TextMate host — the VS Code extension",
+    "(editors/vscode), Shiki on aontu.dev, and GitHub's Linguist if and when",
+    "`.aon` clears its usage bar — so a scope added here reaches all of them.",
+    "",
+    "It is a HIGHLIGHTER, not a parser: it accepts more than the language",
+    "does, and is meant to. A file mid-edit must still colour, so nothing",
+    "here refuses. What it must never do is colour a spelling the engine",
+    "rejects AS THOUGH it were valid, which is why the builtin list below is",
+    "the engine's own set and not a hand-picked sample of it.",
+    "",
+    "THE BUILTIN LIST IS A COPY, AND A COPY DRIFTS. aontu.lark carried",
+    "`same` — never a builtin — and was missing `acyclic`, `inverse` and",
+    "`rel` for two releases, with every test green. So the same guard the",
+    "other two grammars have covers this file: ts/test/grammar.test.ts,",
+    "`the-textmate-grammar-names-exactly-the-engine-builtins`, asserts this",
+    "list against BUILTIN_FUNCS in BOTH directions. Add a builtin to the",
+    "engine without adding it here and that test fails.",
+    "",
+    "No `|>`: ADR-018 removed the pipe from the language, and all three",
+    "published grammars now agree about that."
+  ],
+  "name": "aontu",
+  "displayName": "Aontu",
+  "scopeName": "source.aontu",
+  "aliases": ["aon"],
+  "fileTypes": ["aon", "aontu"],
+  "patterns": [
+    { "include": "#comment" },
+    { "include": "#include-directive" },
+    { "include": "#key" },
+    { "include": "#string" },
+    { "include": "#spread" },
+    { "include": "#builtin" },
+    { "include": "#kind" },
+    { "include": "#constant" },
+    { "include": "#reference" },
+    { "include": "#number" },
+    { "include": "#operator" },
+    { "include": "#punctuation" }
+  ],
+  "repository": {
+    "comment": {
+      "name": "comment.line.number-sign.aontu",
+      "match": "#.*$"
+    },
+
+    "include-directive": {
+      "comment": "@\"path\" pulls in another source. The engine's only import.",
+      "match": "(@)(?=\\s*\")",
+      "captures": {
+        "1": { "name": "keyword.control.import.aontu" }
+      }
+    },
+
+    "key": {
+      "comment": "A map entry's key, bare or quoted, with the optional marker. Listed BEFORE #string so a quoted key does not read as a string, and before #kind so `string: 1` colours `string` as the key it is. Chained keys (`a: b: c: 1`) each match in turn.",
+      "patterns": [
+        {
+          "match": "(\"(?:[^\"\\\\]|\\\\.)*\")\\s*(\\?)?(?=\\s*:)",
+          "captures": {
+            "1": { "name": "entity.name.tag.quoted.aontu" },
+            "2": { "name": "keyword.operator.optional.aontu" }
+          }
+        },
+        {
+          "comment": "No `-`: not a bare-text character (test/spec/op-chars.tsv).",
+          "match": "([A-Za-z_][A-Za-z0-9_]*)\\s*(\\?)?(?=\\s*:)",
+          "captures": {
+            "1": { "name": "entity.name.tag.aontu" },
+            "2": { "name": "keyword.operator.optional.aontu" }
+          }
+        }
+      ]
+    },
+
+    "string": {
+      "name": "string.quoted.double.aontu",
+      "begin": "\"",
+      "beginCaptures": {
+        "0": { "name": "punctuation.definition.string.begin.aontu" }
+      },
+      "end": "\"",
+      "endCaptures": {
+        "0": { "name": "punctuation.definition.string.end.aontu" }
+      },
+      "patterns": [
+        {
+          "name": "constant.character.escape.aontu",
+          "match": "\\\\([\"\\\\/bfnrt]|u[0-9a-fA-F]{4})"
+        },
+        {
+          "name": "invalid.illegal.unknown-escape.aontu",
+          "match": "\\\\."
+        }
+      ]
+    },
+
+    "spread": {
+      "comment": "`&: value` — the map-wide template, distinct from `&` the conjunct.",
+      "match": "(&)(?=\\s*:)",
+      "captures": {
+        "1": { "name": "keyword.control.spread.aontu" }
+      }
+    },
+
+    "builtin": {
+      "comment": "The engine's function registry. `func: name \"(\" ...` in aontu.lark — only these names can be called, so a call to anything else is deliberately left uncoloured rather than dressed up as valid. The prefix family is spelled longest-first (refer|rel|rem|re) to keep the intent legible; the trailing \\b already makes the order immaterial, since a short alternative that swallowed the stem fails the boundary and backtracks.",
+      "match": "\\b(above|acyclic|add|below|close|copy|deprecate|div|each|filter|greatest|hide|inverse|join|key|least|length|list|lower|map|match|max|min|mod|move|mul|must|neq|open|pack|path|pick|pref|refer|rel|rem|re|sub|sum|super|type|unique|upper)\\b(?=\\s*\\()",
+      "captures": {
+        "1": { "name": "support.function.builtin.aontu" }
+      }
+    },
+
+    "kind": {
+      "comment": "Scalar kinds. `number` is the numeric supertype; the rest of the numerics are its leaves.",
+      "name": "support.type.builtin.aontu",
+      "match": "\\b(bigdecimal|biginteger|boolean|float|integer|nil|number|string|top)\\b"
+    },
+
+    "constant": {
+      "patterns": [
+        {
+          "name": "constant.language.aontu",
+          "match": "\\b(true|false|null)\\b"
+        },
+        {
+          "comment": "`_` is a literal of the language as of G8 phase 3, not text.",
+          "name": "constant.language.placeholder.aontu",
+          "match": "(?<![A-Za-z0-9_])_(?![A-Za-z0-9_])"
+        }
+      ]
+    },
+
+    "reference": {
+      "comment": "`$.a.b` resolves from the document root; `.a.b` names a sibling, resolved against the enclosing map. Canon emits the relative form wherever a spread template survives unresolved, so both are real. No conflict with a number: a numeric literal always starts with a digit or `-`, so it matches at an earlier offset and wins there.",
+      "patterns": [
+        {
+          "name": "variable.other.reference.absolute.aontu",
+          "match": "\\$(?:\\.[A-Za-z0-9_]+)*"
+        },
+        {
+          "name": "variable.other.reference.relative.aontu",
+          "match": "(?<![A-Za-z0-9_$.])(?:\\.[A-Za-z0-9_]+)+"
+        }
+      ]
+    },
+
+    "number": {
+      "patterns": [
+        {
+          "comment": "The exact decimal — `0d19.99`. MUST precede the ordinary number: both start at the same `0`, and at equal offsets the first listed pattern wins, so the other order colours the `0` alone and leaves `d19.99` bare.",
+          "name": "constant.numeric.exact.aontu",
+          "match": "-?\\b0d[0-9]+(\\.[0-9]+)?([eE][-+]?[0-9]+)?\\b"
+        },
+        {
+          "name": "constant.numeric.aontu",
+          "match": "-?\\b[0-9]+(\\.[0-9]+)?([eE][-+]?[0-9]+)?\\b"
+        }
+      ]
+    },
+
+    "operator": {
+      "comment": "`&` unify, `|` alternate, `*` prefer, `+` sum.",
+      "name": "keyword.operator.aontu",
+      "match": "[&|*+]"
+    },
+
+    "punctuation": {
+      "patterns": [
+        { "name": "punctuation.definition.map.aontu", "match": "[{}]" },
+        { "name": "punctuation.definition.list.aontu", "match": "[\\[\\]]" },
+        { "name": "punctuation.section.group.aontu", "match": "[()]" },
+        { "name": "punctuation.separator.key-value.aontu", "match": ":" },
+        { "name": "punctuation.separator.comma.aontu", "match": "," }
+      ]
+    }
+  }
+}

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "aontu",
-  "version": "0.52.1",
+  "version": "0.54.0",
   "main": "dist/aontu.js",
   "type": "commonjs",
   "types": "dist/aontu.d.ts",
   "bin": {
     "aontu": "bin/aontu.js",
-    "aontu-lsp": "bin/aontu-lsp.js"
+    "aontu-lsp": "bin/aontu-lsp.js",
+    "aontu-mcp": "bin/aontu-mcp.js"
   },
-  "description": "Unifier.",
-  "homepage": "https://github.com/rjrodger/aontu",
+  "description": "JSON-superset unification language and validation gate for AI-agent ground truth - evaluate, vet, diff, query, and evolution-check structured models.",
+  "homepage": "https://github.com/aontu-lang/aontu",
   "keywords": [
-    "unify"
+    "unify",
+    "unification",
+    "json",
+    "schema",
+    "validation",
+    "vet",
+    "lattice",
+    "config",
+    "cue",
+    "agent",
+    "mcp",
+    "ground-truth"
   ],
   "author": "Richard Rodger (http://richardrodger.com)",
   "repository": {
     "type": "git",
-    "url": "git://github.com/rjrodger/aontu.git"
+    "url": "git+https://github.com/aontu-lang/aontu.git"
   },
   "scripts": {
     "test": "node --enable-source-maps --test \"dist-test/**/*.test.js\"",
@@ -25,6 +37,7 @@
     "test-some": "node --enable-source-maps --test-name-pattern=\"$TEST_PATTERN\" --test \"dist-test/**/*.test.js\"",
     "watch": "tsc --build src test -w",
     "build": "tsc --build src test",
+    "prepack": "node scripts/prepack.js",
     "clean": "rm -rf dist dist-test node_modules yarn.lock package-lock.json",
     "reset": "npm run clean && npm i && npm run build && npm test",
     "version": "node -e \"const fs=require('fs');const v=require('./package.json').version;const f='./src/aontu.ts';const s=fs.readFileSync(f,'utf8');const re=/^const VERSION = '.*?'/m;if(!re.test(s)){console.error('version: no VERSION constant in '+f);process.exit(1)}const n=s.replace(re,'const VERSION = \\''+v+'\\'');if(n!==s){fs.writeFileSync(f,n);console.log('version: src/aontu.ts VERSION -> '+v)}\"",
@@ -46,16 +59,24 @@
     "bin",
     "src",
     "dist",
+    "grammar",
+    "skill",
     "LICENSE"
   ],
   "dependencies": {
     "@tabnas/debug": "0.3.2",
     "@tabnas/directive": "0.5.2",
     "@tabnas/expr": "0.5.5",
+    "@tabnas/ini": "0.5.7",
+    "@tabnas/json": "0.5.7",
+    "@tabnas/json5": "0.5.7",
+    "@tabnas/jsonc": "0.5.6",
     "@tabnas/jsonic": "0.6.2",
     "@tabnas/multisource": "0.5.2",
     "@tabnas/parser": "0.8.7",
-    "@tabnas/path": "0.3.2"
+    "@tabnas/path": "0.3.2",
+    "@tabnas/toml": "0.5.7",
+    "@tabnas/yaml": "0.5.7"
   },
   "devDependencies": {
     "@types/node": "26.2.0",
@@ -66,7 +87,8 @@
     "aliases": {
       "@tabnas/multisource/resolver/file": "@tabnas/multisource/dist/resolver/file.js",
       "@tabnas/multisource/resolver/pkg": "@tabnas/multisource/dist/resolver/pkg.js",
-      "@tabnas/multisource/resolver/mem": "@tabnas/multisource/dist/resolver/mem.js"
+      "@tabnas/multisource/resolver/mem": "@tabnas/multisource/dist/resolver/mem.js",
+      "@tabnas/multisource/processor/jsonic": "@tabnas/multisource/dist/processor/jsonic.js"
     }
   }
 }

package/skill/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: aontu
+description: >-
+  Write, check and query Aontu definitions — a JSON superset where
+  documents UNIFY instead of overwriting. Use when a repository holds
+  `.aon` files, when configuration must satisfy a schema rather than
+  merely parse, or when you need to ask what a configuration says at a
+  path and why it says it.
+---
+
+# Aontu
+
+Aontu is JSON plus a lattice. Two documents do not override each
+other, they **unify**: the result is the most specific value that
+satisfies both, or an error naming the contradiction. That makes a
+definition checkable, queryable and safe to change.
+
+Start here:
+
+- Every JSON document is an Aontu document. Write JSON, then add
+  what JSON cannot say.
+- [`grammar-card.md`](grammar-card.md) — the whole surface on one
+  page.
+- [`examples.md`](examples.md) — the JSON-superset ladder: plain
+  JSON, then kinds, defaults, templates, constraints.
+- [`error-codes.md`](error-codes.md) — what a refusal means and what
+  to do about it.
+
+The verbs, all of which answer as JSON with `--format json`:
+
+```
+aontu vet schema.aon data.aon   # does this data satisfy that truth?
+aontu get $.a.b file.aon        # what does it say at a path?
+aontu why $.a.b file.aon        # why does that value hold?
+aontu set $.a.b=1 --entry file.aon --overlay over.aon
+aontu hash file.aon             # a pin that survives reformatting
+```

package/skill/error-codes.md

@@ -0,0 +1,62 @@
+# What a refusal means
+
+Every Aontu error carries a **code**, and every code has a **class**.
+The class says what kind of thing went wrong, which is what decides
+your next move. The full registry — every code, its class, and the
+version it appeared in — is
+[`test/spec/errcodes.tsv`](https://github.com/aontu-lang/aontu/blob/main/test/spec/errcodes.tsv), which the
+test suite holds to the engine in both implementations.
+
+| Class | Meaning | What to do |
+|-------|---------|------------|
+| `parse` | the text is not a document | fix the syntax at the site the frame points at |
+| `conflict` | two values cannot both hold | one of them is wrong: `aontu why <path>` names both and where they were written |
+| `incomplete` | nothing contradicts, but the value is not concrete | supply what is missing, or accept it with `--partial` |
+| `reference` | a path names nothing | check the spelling; `aontu get $ --keys` lists what is there |
+| `compat` | a change breaks an earlier version | that is `aontu subsume` / `aontu breaking` talking: widen the change or version it |
+| `budget` | evaluation hit a deterministic limit | usually a cycle; simplify, or raise the budget deliberately |
+| `internal` | the engine surprised itself | a bug worth reporting |
+
+## The repair loop
+
+```
+aontu vet schema.aon mine.aon --format json
+```
+
+The exit code branches for you: `0` valid, `1` invalid (fix the
+data), `3` incomplete (supply more), `4` the schema itself is
+unusable (fix the truth, not the data). Every finding carries
+`path`, `code`, and the sites on both sides — the data site first,
+because that is the one to edit. A site names **the file whose text
+it excerpts**, so its row and column are safe to edit at even when
+the document loads others.
+
+Read `hint` before guessing. `message` is the one-line headline;
+`hint` is the engine's own explanation of the failure class with the
+offending values filled in, and for several codes it names the fix
+outright — `lossy_integer_literal` tells you to write the literal as
+`0d…`. It is absent for codes that have no hint text.
+
+For a conflict, `aontu why <path> mine.aon` lists every contribution
+to that path with its role and source line, which turns "these
+disagree" into "these two lines disagree".
+
+Then fix it:
+
+```
+aontu set '$.replicas=5' --entry schema.aon --overlay mine.aon --in-place
+```
+
+`--in-place` rewrites the pinned literal **where it was written**, so
+comments and layout survive. Without it, `set` APPENDS — which is the
+right thing when the document left a hole, and cannot work when it
+pinned the wrong value, because unification only narrows.
+
+The edit is verified before a byte is written: a site carries the
+source text it covers, and the text at the span must match it. Where
+that cannot be established — the value comes from a `&:` template or a
+`$ref`, two statements pin the path, the site names the opening token
+of a compound like `min(1)`, or the overlay `@"includes"` another
+document — the assignment is appended as usual and a **warning** says
+which case it hit. A warning never changes the verdict, so asking for
+`--in-place` cannot make a run fail that would have succeeded.

package/skill/examples.md

@@ -0,0 +1,99 @@
+# Aontu by example
+
+The ladder: start with the JSON you already know, add one thing at a
+time. Every rung is a valid document.
+
+## 1. It is JSON
+
+```
+{"service": {"name": "auth", "port": 8080}}
+```
+
+Bare keys and no commas also parse, so this is the same document:
+
+```
+service: {
+  name: "auth"
+  port: 8080
+}
+```
+
+## 2. Say what a value MAY be
+
+```
+service: {
+  name: string
+  port: integer
+}
+```
+
+Nothing generates yet — this is a truth, not a value. `aontu vet
+service.aon deploy.aon` says whether a deployment satisfies it.
+
+## 3. Say what it SHOULD be
+
+```
+service: {
+  name: string
+  port: *8080 | integer      # 8080 unless told otherwise
+  replicas: *1 | integer
+}
+```
+
+Now it generates: `{"service":{"name":…,"port":8080,"replicas":1}}` —
+except `name`, which nothing has supplied. Defaults are picked at
+generation; they do not stop a caller from choosing something else.
+
+`*8080 | integer` means what it reads as: a caller's `9090` overrides
+it, and a caller's `1.5` is refused, because the branch admits only the
+kind it names. Write `*8080 | number` if any numeric value should be
+allowed to win.
+
+## 4. Say it once, for every key
+
+```
+services: {
+  &: { port: integer, replicas: *1 | integer }
+  auth: { port: 8080 }
+  db:   { port: 5432, replicas: 3 }
+}
+```
+
+The `&:` template meets EVERY key. `aontu why $.services.db.replicas`
+reports both contributions — the template's `*1|integer` and the
+literal `3` — with the line each was written on.
+
+## 5. Bound it
+
+```
+services: {
+  &: {
+    port: integer & min(1) & max(65535)
+    name: string & re("^[a-z][a-z0-9-]*$")
+  }
+}
+```
+
+A port of `0` is now an error with a path, not a runtime surprise.
+
+## 6. Layer it
+
+```
+# base.aon
+service: { image: string, replicas: *1 | integer }
+
+# prod.aon
+@"base.aon"
+service: { image: "auth:v2.3", replicas: 5 }
+```
+
+Unification is order-independent: `base & prod` is `prod & base`. To
+change a value without editing the file, append to an overlay:
+
+```
+aontu set '$.service.replicas=7' --entry prod.aon --overlay local.aon
+```
+
+If the value is PINNED rather than open, that command refuses and
+names the pinning site — which is the honest answer, and where
+`aontu why` takes you next.

package/skill/grammar-card.md

@@ -0,0 +1,56 @@
+# Aontu grammar card
+
+Everything the language spells, on one page. The published machine
+grammar is [`grammar/aontu.gbnf`](../grammar/aontu.gbnf) (and
+`aontu.lark`); this is its human twin.
+
+## Values
+
+| Write | Means |
+|-------|-------|
+| `{"a":1}`, `a: 1` | a map; keys may be bare or quoted |
+| `[1,2]` | a list |
+| `"s"`, `1`, `1.5`, `true`, `null` | scalars, as JSON |
+| `0d9007199254740993` | an EXACT number, at any magnitude |
+| `string integer number float boolean null` | kinds: any value of that kind |
+| `top` | anything at all; `nil` is the failure |
+
+## Combining
+
+| Write | Means |
+|-------|-------|
+| `a & b` | both must hold — the meet |
+| `a \| b` | either may hold — the join |
+| `*1 \| integer` | either, with `1` the DEFAULT a generation picks |
+| | the branch keeps its kind: a later `1.5` is refused, not admitted |
+| `x: 1` twice | the two meet; `1 & 2` is an error, `1 & integer` is `1` |
+| `$.a.b` | the value at that path of this document |
+| `1 + 2` | arithmetic on concrete numbers |
+
+## Maps that say more
+
+| Write | Means |
+|-------|-------|
+| `{&: {k: integer}}` | a TEMPLATE every key must satisfy |
+| `close({a:1})` | no key beyond those named |
+| `{a?: 1}` | optional: dropped if unresolved |
+| `hide(x)` | evaluated, then dropped from the output |
+| `type(x)` | a definition, not a value: it generates nothing |
+| `deprecate(x, {msg:"…"})` | still works, and says so |
+| `refer(t) & path($.a.b)` | a checked LINK: the tree address must resolve, and `t` flows into it |
+
+## Constraints
+
+`min(n) max(n) above(n) below(n)` bound a number;
+`length(n)` and `unique()` bound a list or string;
+`re("^…$")` matches a string; `neq(v)` refuses one value;
+`must(cond, "why")` is the escape hatch.
+
+Bounds compose: `integer & min(1) & max(10)` is a range, and two
+ranges meet to their overlap.
+
+## Files
+
+`@"other.aon"` includes another document — it unifies in, it does not
+concatenate. (A constrained decoder is not given this: generated
+documents describe values, they do not load files.)

package/src/agentsmd.ts

@@ -0,0 +1,135 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE AGENTS.md STANZA (G7 phase 6,
+// docs/capability-review/g7-machine-access.md): generated FROM the
+// definition, so the prose entrypoint cannot drift from the formal
+// source it points at.
+//
+// A hand-written "here is where the config lives" paragraph is stale
+// the first time a key is renamed. This one is derived: the root keys
+// come from the document, the pin comes from G6's canon-hash, and the
+// commands are spelled with paths that exist. Re-running the verb
+// after an edit produces the stanza that edit implies.
+
+import { Aontu } from './aontu'
+import type { TrustOptions } from './type'
+import { canonHash } from './hcanon'
+import { get } from './query'
+import { evalFailure } from './query'
+import type { VetFinding } from './vet'
+import { cmpCodePoint } from './keyorder'
+
+
+// The markers an update rewrites between. A stanza outside them is
+// prose someone wrote, and is left alone.
+export const AGENTSMD_BEGIN = '<!-- aontu:begin -->'
+export const AGENTSMD_END = '<!-- aontu:end -->'
+
+
+export type AgentsMdReport = {
+  findings: VetFinding[]
+  ok: boolean
+  stanza: string
+}
+
+export type AgentsMdOptions = {
+  // The name the stanza should call the document. The engine never
+  // reads a file; the CLI passes what the author typed.
+  name?: string
+  path?: string
+  // The include capability this document evaluates under
+  // (G5, docs/trust.md); vet's precedent.
+  trust?: TrustOptions
+}
+
+
+// The stanza for one document.
+export function agentsMd(
+  src: string, opts?: AgentsMdOptions): AgentsMdReport {
+  const options = opts ?? {}
+  const name = options.name ?? 'the definition'
+
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const v: any = aontu.unify(src, parseOpts, ctx)
+  if (0 < ctx.err.length) {
+    return { findings: [evalFailure(ctx)], ok: false, stanza: '' }
+  }
+
+  const keys = true === v.isMap ? Object.keys(v.peg).sort(cmpCodePoint) : []
+  const shape = get(src, '$', { view: 'types', depth: 2, path: options.path })
+
+  // A REAL path, so the example command works as written: the first
+  // root key when there is one, the root itself when there is not.
+  const example = 0 < keys.length ? '$.' + keys[0] : '$'
+
+  const lines = [
+    AGENTSMD_BEGIN,
+    '## Ground truth: `' + name + '`',
+    '',
+    'The values below are DERIVED from `' + name + '`, an Aontu',
+    'definition. Do not restate them here — read them from the source,',
+    'which is the only copy that cannot go stale.',
+    '',
+    '- Pin: `' + canonHash(v) + '`',
+    '  (the canon-hash: it survives reformatting and moves on any',
+    '  change of meaning — `aontu hash ' + name + '` re-derives it)',
+    '- Top-level keys: ' +
+    (0 === keys.length ? '_none_' : keys.map((k) => '`' + k + '`').join(', ')),
+    '- Shape: `' + shape.out + '`',
+    '',
+    'How to work with it:',
+    '',
+    '```',
+    '# what does it say at a path?',
+    'aontu get ' + example + ' ' + name,
+    '',
+    '# why does that value hold?',
+    'aontu why ' + example + ' ' + name,
+    '',
+    '# does my document satisfy it?',
+    'aontu vet ' + name + ' mine.aon',
+    '',
+    '# change it without editing it',
+    'aontu set ' + example + '=<value> --entry ' + name +
+    ' --overlay overlay.aon',
+    '```',
+    '',
+    'Regenerate this section with `aontu agentsmd ' + name + '`.',
+    AGENTSMD_END,
+  ]
+
+  return { findings: [], ok: true, stanza: lines.join('\n') + '\n' }
+}
+
+
+// Splice the stanza into an existing document: replace what stands
+// between the markers, or append when there is nothing to replace. A
+// document is otherwise LEFT ALONE — the rest of an AGENTS.md is
+// someone's prose, and a generator that rewrote it would be a
+// generator nobody dared run twice.
+export function agentsMdSplice(existing: string, stanza: string): string {
+  const from = existing.indexOf(AGENTSMD_BEGIN)
+  const to = existing.indexOf(AGENTSMD_END)
+  if (from < 0 || to < from) {
+    const head = '' === existing || existing.endsWith('\n')
+      ? existing : existing + '\n'
+    return head + ('' === existing ? '' : '\n') + stanza
+  }
+  // Skip the end marker's line terminator, whatever it is, and only if
+  // it is there. The full note is on the Go twin (go/agentsmd.go): `+1`
+  // assumed one byte and got the CR of a CRLF document, leaving the LF
+  // to become a blank line on every regeneration -- and past the end of
+  // a document whose marker is its last content, where Go panicked and
+  // this side quietly did not.
+  let end = to + AGENTSMD_END.length
+  if ('\r' === existing[end]) {
+    end++
+  }
+  if ('\n' === existing[end]) {
+    end++
+  }
+  return existing.slice(0, from) + stanza + existing.slice(end)
+}