aontu 0.72.0 → 0.74.0

package/skill/error-codes.md

@@ -40,7 +40,7 @@ field of a `--format json` report.
 ## The repair loop
 
 ```
-aontu vet schema.aon mine.aon --format json
+aontu vet schema.aontu mine.aontu --format json
 ```
 
 The exit code branches for you: `0` valid, `1` invalid (fix the
@@ -61,14 +61,14 @@ registry code; a **dynamic** code (`func:upper`, `op[+]`) is registered
 through its prefix, and only `explain` falls back to the prefix's text,
 so such a finding carries no `hint`.
 
-For a conflict, `aontu model why <path> mine.aon` lists every contribution
+For a conflict, `aontu model why <path> mine.aontu` 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 model set '$.replicas=5' --entry schema.aon --overlay mine.aon --in-place
+aontu model set '$.replicas=5' --entry schema.aontu --overlay mine.aontu --in-place
 ```
 
 `--in-place` rewrites the pinned literal **where it was written**, so

package/skill/examples.md

@@ -28,7 +28,7 @@ service: {
 ```
 
 Nothing generates yet — this is a truth, not a value. `aontu vet
-service.aon deploy.aon` says whether a deployment satisfies it.
+service.aontu deploy.aontu` says whether a deployment satisfies it.
 
 ## 3. Say what it SHOULD be
 
@@ -79,11 +79,11 @@ A port of `0` is now an error with a path, not a runtime surprise.
 ## 6. Layer it
 
 ```
-# base.aon
+# base.aontu
 service: { image: string, replicas: *1 | integer }
 
-# prod.aon
-@"./base.aon"
+# prod.aontu
+@"./base.aontu"
 service: { image: "auth:v2.3", replicas: 5 }
 ```
 
@@ -91,7 +91,7 @@ Unification is order-independent: `base & prod` is `prod & base`. To
 change a value without editing the file, append to an overlay:
 
 ```
-aontu model set '$.service.replicas=7' --entry prod.aon --overlay local.aon
+aontu model set '$.service.replicas=7' --entry prod.aontu --overlay local.aontu
 ```
 
 If the value is PINNED rather than open, that command refuses and

package/skill/grammar-card.md

@@ -54,6 +54,6 @@ ranges meet to their overlap.
 
 ## Files
 
-`@"./other.aon"` includes another document — it unifies in, it does not
+`@"./other.aontu"` 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/skill/init/check.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 # check.sh --- the four questions to ask of a model. Run it after
-# every edit to model.aon or data.aon.
+# every edit to model.aontu or data.aontu.
 #
 # `aontu help tasks` maps a job to a verb; `aontu explain <code>` says
 # what a refusal means; `aontu help language` is the whole grammar on
@@ -13,16 +13,16 @@ cd "$(dirname "$0")"
 # 1. Does the data satisfy the truth -- and did the check examine
 #    anything? --strict-coverage exits 1 on a check that constrained no
 #    value, which is the failure a passing gate hides.
-$AONTU vet --strict-coverage model.aon data.aon
+$AONTU vet --strict-coverage model.aontu data.aontu
 
 # 2. What does it say at a path?
-$AONTU model get '$.entity.planet.table' data.aon
+$AONTU model get '$.entity.planet.table' data.aontu
 
 # 3. Why does it say that? Every contribution, with the line it is on.
-$AONTU model why '$.entity.planet.table' data.aon
+$AONTU model why '$.entity.planet.table' data.aontu
 
 # 4. A pin for the truth: it survives reformatting and moves on any
 #    change of meaning.
-$AONTU hash model.aon
+$AONTU hash model.aontu
 
-echo "ok --- model.aon and data.aon agree"
+echo "ok --- model.aontu and data.aontu agree"

package/skill/init/{data.aon → data.aontu}

@@ -1,4 +1,4 @@
-# data.aon --- an instance of the truth in model.aon. Edit it and run
+# data.aontu --- an instance of the truth in model.aontu. Edit it and run
 # check.sh: every change is checked against the model, and a change the
 # model refuses is named with the line it is on.
 entity: {

package/skill/init/{model.aon → model.aontu}

@@ -1,4 +1,4 @@
-# model.aon --- the truth. `aontu vet model.aon data.aon` asks whether
+# model.aontu --- the truth. `aontu vet model.aontu data.aontu` asks whether
 # a document satisfies it.
 #
 # `&:` is the construct to learn first: it meets EVERY key of the map

package/skill/tasks.md

@@ -13,8 +13,8 @@ aontu init model/     # or into a named one
 sh check.sh           # the four questions, on what was just written
 ```
 
-`init` writes `model.aon` (an entity map constrained with `&:`),
-`data.aon` (an instance of it that holds) and `check.sh` (the four
+`init` writes `model.aontu` (an entity map constrained with `&:`),
+`data.aontu` (an instance of it that holds) and `check.sh` (the four
 checks to run after every edit). It never overwrites: if any
 of the three already stands there, it refuses and writes none of them.
 
@@ -49,7 +49,7 @@ of every following element renumbered.
 ## Check data against a model
 
 ```
-aontu vet model.aon data.aon
+aontu vet model.aontu data.aontu
 ```
 
 Exit `0` valid, `1` a contradiction, `3` incomplete (nothing
@@ -62,8 +62,8 @@ report, `--closed` to refuse keys the model does not declare,
 nothing answers exactly like one that passed:
 
 ```
-aontu vet --coverage model.aon data.aon         # what did it examine?
-aontu vet --strict-coverage model.aon data.aon  # exit 1 if nothing
+aontu vet --coverage model.aontu data.aontu         # what did it examine?
+aontu vet --strict-coverage model.aontu data.aontu  # exit 1 if nothing
 ```
 
 `--coverage` reports how many data leaves a declaration constrained,
@@ -74,19 +74,19 @@ cause is the `"*"` mistake above: reach for `&:`.
 ## Check the model is coherent with itself
 
 ```
-aontu relations model.aon        # declared entity edges: targets resolve, no cycles
-aontu reaches planet moon model.aon   # does one entity reach another, at any remove?
-aontu trim --check model.aon     # entries whose removal changes nothing
+aontu relations model.aontu        # declared entity edges: targets resolve, no cycles
+aontu reaches planet moon model.aontu   # does one entity reach another, at any remove?
+aontu trim --check model.aontu     # entries whose removal changes nothing
 ```
 
 ## Generate code from a model, and hold it
 
 ```
-aontu render gen.aon build          # write the files below build/
-aontu render --check gen.aon build  # write nothing; exit 1 when build/ has drifted
+aontu render gen.aontu build          # write the files below build/
+aontu render --check gen.aontu build  # write nothing; exit 1 when build/ has drifted
 aontu render gen/ build             # every generator directly in gen/, as one run
-aontu model get out gen.aon         # the component tree: files, and the lines in them
-aontu trace gen.aon                 # what rule wrote each line
+aontu model get out gen.aontu         # the component tree: files, and the lines in them
+aontu trace gen.aontu                 # what rule wrote each line
 ```
 
 A generator answers a **component tree** -- `file(name, [lines])` and
@@ -101,10 +101,10 @@ and the rule behind it.
 ## Ask what a model says, and why
 
 ```
-aontu model get  $.entity.planet.table model.aon
-aontu model why  $.entity.planet.table model.aon
-aontu model get  $.entity --keys       model.aon
-aontu model get  $.entity --types      model.aon
+aontu model get  $.entity.planet.table model.aontu
+aontu model why  $.entity.planet.table model.aontu
+aontu model get  $.entity --keys       model.aontu
+aontu model get  $.entity --types      model.aontu
 ```
 
 `why` names **every** contribution to a value, with the file and line
@@ -114,7 +114,7 @@ what you expected, and the second thing to run when `vet` refuses.
 ## Change a value without editing the file
 
 ```
-aontu model set '$.entity.planet.table=planet_v2' --entry model.aon --overlay local.aon
+aontu model set '$.entity.planet.table=planet_v2' --entry model.aontu --overlay local.aontu
 ```
 
 The change is checked before it is written; a change that contradicts
@@ -123,15 +123,15 @@ a pinned value is refused, and the file is left alone.
 ## Gate a change to the model itself
 
 ```
-aontu subsume old.aon new.aon              # does the general admit every specific?
-aontu breaking --against git#HEAD~1 model.aon
-aontu hash model.aon                       # a pin that survives reformatting
+aontu subsume old.aontu new.aontu              # does the general admit every specific?
+aontu breaking --against git#HEAD~1 model.aontu
+aontu hash model.aontu                       # a pin that survives reformatting
 ```
 
 ## Hand a model to another agent
 
 ```
-aontu agentsmd --write AGENTS.md model.aon
+aontu agentsmd --write AGENTS.md model.aontu
 ```
 
 Splices a derived stanza — the pin, the root keys, the shape, and the

package/src/agentsmd.ts

@@ -86,11 +86,11 @@ export function agentsMd(
     'aontu model why ' + example + ' ' + name,
     '',
     '# does my document satisfy it?',
-    'aontu vet ' + name + ' mine.aon',
+    'aontu vet ' + name + ' mine.aontu',
     '',
     '# change it without editing it',
     'aontu model set ' + example + '=<value> --entry ' + name +
-    ' --overlay overlay.aon',
+    ' --overlay overlay.aontu',
     '',
     '# the language itself, offline: the whole grammar on one page',
     'aontu help language',

package/src/aontu.ts

@@ -36,7 +36,7 @@ import { format, unifiedDiff } from './format'
 export type { LintFinding, FormatReport, FormatOptions } from './format'
 
 
-const VERSION = '0.72.0'
+const VERSION = '0.74.0'
 
 
 function genQuiet(val: any, aontu: Aontu): any {

package/src/cli.ts

@@ -193,7 +193,7 @@ Options:
 
 Package verbs (a module is imported; a package is published):
   sync      Make the project correct: resolve by minimum version
-            selection, fetch what is missing, write aontu_meta/pkg-lock.aon,
+            selection, fetch what is missing, write aontu_meta/pkg-lock.aontu,
             vendor, verify. --frozen refuses to change the lockfile
   add       Take on a dependency the project does not have, then sync;
             refuses one it has and names get
@@ -214,15 +214,15 @@ Package options:
                   signs the manifest, for the key provider
   --token <file>  publish: the forge's OIDC token, read from a file
   --base <url>    the repository to read from (repeatable; overrides
-                  pkg.aon repo.base)
-  --write <url>   publish: the write path (overrides pkg.aon repo.write)
+                  pkg.aontu repo.base)
+  --write <url>   publish: the write path (overrides pkg.aontu repo.write)
   --against <dir> manifest: a prior version's tree, to gate on
   --upstream <u>  serve: fetch on miss from this repository (repeatable)
   --listen <a>    serve: the address to listen on (default 127.0.0.1:8017)
 
 pkg subcommands (the rest of the package operations):
   tidy      Resolve the closure by minimum version selection and
-            rewrite aontu_meta/pkg-lock.aon in canonical form
+            rewrite aontu_meta/pkg-lock.aontu in canonical form
   verify    Check every locked package still is and still means what
             the lockfile pins, bytes before meaning, and change nothing
             (the CI gate; tidy rewrites)
@@ -402,7 +402,7 @@ View exit codes: 0 rendered, 1 --check mismatch or lossy under
 --strict, 2 usage or --max-rows exceeded, 4 the document does not stand
 up on its own, or a relation, root or path that names nothing.
 
-A template entry file whose extension is not .aon is a GENERATOR: a
+A template entry file whose extension is not .aontu is a GENERATOR: a
 document in the target's own syntax, whose marker lines carry aontu and
 whose other lines are output. It is desugared before it is evaluated,
 and a language the table does not know names its marker with --marker,
@@ -541,7 +541,7 @@ Fmt options:
 The fmt verb prints one document in the agreed form; with no file it
 reads standard input. Several files need one of the options above.
 
-A file whose extension is not .aon is a GENERATOR, as it is for
+A file whose extension is not .aontu is a GENERATOR, as it is for
 template: the aontu its marker lines carry is formatted, the marker
 stands at the left margin with the aontu indented after it, and every
 line of output is held on a line of its own. A file with no marker line
@@ -1695,7 +1695,7 @@ function parseBreakingArgs(
 
 type OldVersion = { src: string, path: string, temp?: string }
 
-const INCLUDABLE = /\.(aon|aontu|jsonic|json)$/
+const INCLUDABLE = /\.(aontu|jsonic|json)$/
 
 function oldVersion(spec: string, file: string): OldVersion | undefined {
   if (!spec.startsWith('git#')) {
@@ -2230,18 +2230,28 @@ function parsePkgArgs(argv: string[], verb: string, io: Io): PkgArgs | undefined
 }
 
 
-// A verb that finds the older layout names the current one, once, and
-// reads nothing from it.
+// A verb that finds an older layout names the current one, once, and
+// reads nothing from it. `pkg.aon` is the sharper case: a project
+// carrying it declares nothing to any verb, so `verify` answers over an
+// empty package and `sync` writes a lock with every pin dropped.
 function nameOldLayout(dir: string, io: Io): void {
-  const old = ['aon_vendor', 'mod-lock.aon', 'mod.aon',
-    join(META_DIR, 'mod-lock.aon')].filter((f) => existsSync(join(dir, f)))
-  if (0 < old.length) {
+  const here = (f: string): boolean => existsSync(join(dir, f))
+  const mod = ['aon_vendor', 'mod-lock.aon', 'mod.aon',
+    join(META_DIR, 'mod-lock.aon')].filter(here)
+  const aon = ['pkg.aon', join(META_DIR, 'pkg-lock.aon')].filter(here)
+  if (0 < mod.length) {
     io.err(
-      'aontu: ' + old.join(', ') + ' belong to an older layout: the package ' +
+      'aontu: ' + mod.join(', ') + ' belong to an older layout: the package ' +
       'file is ' + PKG_FILE + ', the lockfile ' + join(META_DIR, LOCK_FILE) +
       ' and the vendor tree ' + join(META_DIR, 'vendor') + '; rename ' +
       PKG_FILE + '\'s `mod` block to `pkg`, then run aontu sync\n')
   }
+  if (0 < aon.length) {
+    io.err(
+      'aontu: ' + aon.join(', ') + ' carry the withdrawn .aon extension, so ' +
+      'nothing here declares a package: rename them to ' + PKG_FILE + ' and ' +
+      join(META_DIR, LOCK_FILE) + ', then run aontu sync\n')
+  }
 }
 
 
@@ -2913,7 +2923,7 @@ function runTrace(argv: string[]): number {
 
   // A GENERATOR IS AN ENTRY, not a preprocessing step: the file whose
   // provenance is asked for is the one the author edits.
-  if (!rest[0].endsWith('.aon')) {
+  if (!rest[0].endsWith('.aontu')) {
     src = desugarTemplate(src, marker ??
       markerFromProfiles(declared, rest[0]) ?? markerFor(rest[0]))
   }
@@ -3126,7 +3136,7 @@ async function runRender(argv: string[]): Promise<number> {
       process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
       return 2
     }
-    if (!/[.](aon|aontu)$/.test(f)) {
+    if (!/[.]aontu$/.test(f)) {
       const mark = marker ?? markerFromProfiles(declared, f) ?? markerFor(f)
       if (!templateOutputs(src, mark).some((out) => !out)) {
         process.stderr.write(`aontu: ${f} carries no ${mark} marker line, ` +
@@ -4802,7 +4812,7 @@ function runFmt(argv: string[]): number | Promise<number> {
       marker ?? markerFromProfiles(declared, file))
     if (false === mark) {
       process.stderr.write(
-        `aontu: ${file} is not aontu source (.aon, .aontu) and carries no ` +
+        `aontu: ${file} is not aontu source (.aontu) and carries no ` +
         `${markerFor(file)} marker line, so there is no aontu in it to ` +
         'format; --marker names the marker for a language the table ' +
         'does not know, and --profile reads one that declares it\n')
@@ -4818,7 +4828,7 @@ function fmtMarker(
   if (undefined !== marker) {
     return marker
   }
-  if (/[.](aon|aontu)$/.test(file)) {
+  if (/[.]aontu$/.test(file)) {
     return undefined
   }
   const mark = markerFor(file)
@@ -5259,7 +5269,7 @@ const KNOWN_VERBS = [
 
 // looksLikeVerb reports whether an unreadable argument was meant as a
 // verb rather than as a path. A bare word has no separator and no
-// extension; `./help`, `help.aon`, `/tmp/help` and `sub/dir` are paths
+// extension; `./help`, `help.aontu`, `/tmp/help` and `sub/dir` are paths
 // and keep the file diagnosis. Mirrors go/cmd/aontu/main.go.
 function looksLikeVerb(arg: string): boolean {
   return '' !== arg &&

package/src/err.ts

@@ -163,7 +163,7 @@ function resolveFile(url: string | undefined) {
   // The PLATFORM'S separator, not '/': a hardcoded slash never matched
   // a Windows cwd, so every Windows report named the absolute path
   // where the POSIX report (and the Go CLI, which prints the entry as
-  // typed) named `clash.aon` -- caught by the docs transcript for
+  // typed) named `clash.aontu` -- caught by the docs transcript for
   // reading a conflict error, which pins the relative spelling.
   let out = url?.replace(cwd + sep, '') ?? '<no-file>'
   out = out === cwd || '' === out ? '<no-file>' : out

package/src/format.ts

@@ -11,6 +11,9 @@ import { ALIAS_RE, EXPORT_DECL_NAME, isExportHoldKey } from './aliasname'
 
 const BUDGET = 80
 
+// The gap behind a comment that ends a line of code.
+const TRAIL_GAP = '  '
+
 const MAX_DEPTH = 1000
 
 export type FormatOptions = {
@@ -50,7 +53,7 @@ export type FormatReport =
 type Tok = { name: string, src: string, val: any, sI: number }
 
 const stubResolver: Resolver = ((spec: any) => ({
-  ...spec, kind: 'aon', full: '__fmt__.aon', src: '', found: true, search: [],
+  ...spec, kind: 'aontu', full: '__fmt__.aontu', src: '', found: true, search: [],
 })) as any
 
 let ENGINE: Aontu | undefined
@@ -688,6 +691,11 @@ class Writer {
     this.line += s
   }
 
+  // One gap behind the code; alone on its line it keeps its indent.
+  trail(s: string): void {
+    this.line = this.fresh() ? this.line + s : rtrim(this.line) + TRAIL_GAP + s
+  }
+
   // Nothing on the line yet but its indentation.
   fresh(): boolean {
     return '' === this.line.trim()
@@ -772,7 +780,7 @@ function emitBody(
       const e = chain(node)
       emitValue(w, e, indent)
       if (undefined !== e.trail) {
-        w.text(' ' + e.trail)
+        w.trail(e.trail)
       }
     }
     if (root && from < w.mark()) {
@@ -797,7 +805,7 @@ function emitValue(w: Writer, node: Node, indent: number): void {
       const v = chain(node.value!)
       emitValue(w, v, indent)
       if (undefined !== v.trail) {
-        w.text(' ' + v.trail)
+        w.trail(v.trail)
       }
       return
     }
@@ -855,7 +863,7 @@ function emitCall(w: Writer, node: Node, indent: number): void {
         w.text(it.text!)
       }
       else {
-        w.text(' ' + it.text)
+        w.trail(it.text!)
       }
       noted = true
       continue
@@ -917,7 +925,7 @@ function emitBlock(
   }
   w.text(open)
   if (undefined !== node.open) {
-    w.text(' ' + node.open)
+    w.trail(node.open)
   }
   emitBody(w, node.body!, indent + 2, stmt)
   w.open(indent, false)
@@ -926,7 +934,6 @@ function emitBlock(
 
 function emitExpr(w: Writer, items: Node[], indent: number): void {
   const cont = w.fresh() ? indent : indent + 2
-  let operand = false
   let cur = indent
   for (const it of items) {
     if ('op' === it.t) {
@@ -940,26 +947,19 @@ function emitExpr(w: Writer, items: Node[], indent: number): void {
       else {
         w.text(TIGHT_OP === it.text ? it.text! : ' ' + it.text + ' ')
       }
-      operand = false
       continue
     }
     if ('prefix' === it.t) {
       w.text(it.text!)
-      operand = false
       continue
     }
     if ('note' === it.t) {
-      if (operand) {
-        w.text(' ')
-      }
-      w.text(it.text!)
+      w.trail(it.text!)
       cur = cont
       w.open(cur, false)
-      operand = false
       continue
     }
     emitValue(w, it, cur)
-    operand = true
   }
 }
 
@@ -1104,7 +1104,7 @@ function repeatLines(entries: Node[], prefix: string, indent: number): Line[] |
       out.push({ t: 'comment', text: e.text })
       continue
     }
-    const trail = undefined === e.trail ? '' : ' ' + e.trail
+    const trail = undefined === e.trail ? '' : TRAIL_GAP + e.trail
     if ('spread' === e.t) {
       // The repeated spread entry is a one-entry map holding only a
       // spread, so by D1's exception it keeps its braces.
@@ -1205,7 +1205,7 @@ function emitStatement(w: Writer, p: Node, indent: number, stmt: Stmt, prefix: s
     }
   }
   if (undefined !== p.trail) {
-    w.text(' ' + p.trail)
+    w.trail(p.trail)
   }
   if (rewritten && !stmt.covered) {
     const before = emitAt(p.orig ?? [p], indent)

package/src/helpdoc.ts

@@ -17,25 +17,25 @@ const HELPDOC: HelpTopic[] = [
     "topic": "tasks",
     "summary": "what do you want to do? — the verb for a job",
     "source": "docs/skill/tasks.md",
-    "text": "# What do you want to do?\n\nThe verb for a job, found by the word you arrived with. aontu's own\nvocabulary is on the right; yours is probably on the left.\n\n## Start from a document that works\n\nNothing written yet? Do not invent the first document, edit one:\n\n```\naontu init            # into the working directory\naontu init model/     # or into a named one\nsh check.sh           # the four questions, on what was just written\n```\n\n`init` writes `model.aon` (an entity map constrained with `&:`),\n`data.aon` (an instance of it that holds) and `check.sh` (the four\nchecks to run after every edit). It never overwrites: if any\nof the three already stands there, it refuses and writes none of them.\n\n## Describe a domain\n\nAn **ontology**, a **schema**, a **data model**, a **contract** — in\naontu these are all one thing: a document. Write the entities as a\n**map keyed by name**, and say what every entry must satisfy with the\n`&:` template:\n\n```\nentity: {\n  &: {\n    table:  string\n    fields: { &: { type: string, required: *false | boolean } }\n  }\n  planet: { table: \"planets\", fields: { name: { type: \"string\" } } }\n  moon:   { table: \"moons\",   fields: { name: { type: \"string\" } } }\n}\n```\n\n`&:` is the construct to reach for first, and the one most easily\nmissed. It meets **every** key of the map it sits in. A quoted `\"*\"`\nis not a wildcard — it is a key named `*`, and a schema written that\nway constrains nothing while still reporting `valid`.\n\nPrefer a named map to a list unless the order is a fact (a migration\nsequence, a rule table tried in order). A key is an address, a name\nother parts can refer to, and a diff that shows one insertion instead\nof every following element renumbered.\n\n## Check data against a model\n\n```\naontu vet model.aon data.aon\n```\n\nExit `0` valid, `1` a contradiction, `3` incomplete (nothing\ncontradicts, but the model is not yet satisfied), `4` the model does\nnot stand up on its own. `--format json` for the machine-readable\nreport, `--closed` to refuse keys the model does not declare,\n`--max-errors <n>` to cap the list.\n\n**Make the check prove it checked something.** A check that examined\nnothing answers exactly like one that passed:\n\n```\naontu vet --coverage model.aon data.aon         # what did it examine?\naontu vet --strict-coverage model.aon data.aon  # exit 1 if nothing\n```\n\n`--coverage` reports how many data leaves a declaration constrained,\nthe data paths none did, and the declarations no data met.\n`--strict-coverage` exits 1 when the answer is nothing. The usual\ncause is the `\"*\"` mistake above: reach for `&:`.\n\n## Check the model is coherent with itself\n\n```\naontu relations model.aon        # declared entity edges: targets resolve, no cycles\naontu reaches planet moon model.aon   # does one entity reach another, at any remove?\naontu trim --check model.aon     # entries whose removal changes nothing\n```\n\n## Generate code from a model, and hold it\n\n```\naontu render gen.aon build          # write the files below build/\naontu render --check gen.aon build  # write nothing; exit 1 when build/ has drifted\naontu render gen/ build             # every generator directly in gen/, as one run\naontu model get out gen.aon         # the component tree: files, and the lines in them\naontu trace gen.aon                 # what rule wrote each line\n```\n\nA generator answers a **component tree** -- `file(name, [lines])` and\nits neighbours -- which `aontu render` hands to jostraca, the generator\nruntime, to write. A tree that is one file is written to the path\nitself, and a folder of generators is one run. `--check` compares with\nwhat is committed: the model is the\ntruth, the code is the claim, and drift is a finding. `aontu trace`\nanswers the other direction: for a line of the output, the model node\nand the rule behind it.\n\n## Ask what a model says, and why\n\n```\naontu model get  $.entity.planet.table model.aon\naontu model why  $.entity.planet.table model.aon\naontu model get  $.entity --keys       model.aon\naontu model get  $.entity --types      model.aon\n```\n\n`why` names **every** contribution to a value, with the file and line\neach was written on. It is the first thing to run when a value is not\nwhat you expected, and the second thing to run when `vet` refuses.\n\n## Change a value without editing the file\n\n```\naontu model set '$.entity.planet.table=planet_v2' --entry model.aon --overlay local.aon\n```\n\nThe change is checked before it is written; a change that contradicts\na pinned value is refused, and the file is left alone.\n\n## Gate a change to the model itself\n\n```\naontu subsume old.aon new.aon              # does the general admit every specific?\naontu breaking --against git#HEAD~1 model.aon\naontu hash model.aon                       # a pin that survives reformatting\n```\n\n## Hand a model to another agent\n\n```\naontu agentsmd --write AGENTS.md model.aon\n```\n\nSplices a derived stanza — the pin, the root keys, the shape, and the\ncommands spelled with paths that exist — between two markers, and\nleaves the rest of the file alone. Re-run it in the commit that\nchanges the model.\n\n## When something refuses\n\nRead the code in the brackets, then look it up:\n\n```\naontu explain no_scalar_unify\n```\n\nEvery finding carries a `code`, a `class`, a `path` and the **two\nsites** that disagree — the value and the constraint it failed, each\nwith its file and line. The class says what kind of answer it is:\n`conflict` (two things cannot both hold), `incomplete` (nothing is\nwrong yet, something is missing), `parse`, `reference`, `budget`.\n\nFull index: [`error-codes.md`](error-codes.md). The language on one\npage: [`grammar-card.md`](grammar-card.md). The worked ladder from\nplain JSON upward: [`examples.md`](examples.md).\n"
+    "text": "# What do you want to do?\n\nThe verb for a job, found by the word you arrived with. aontu's own\nvocabulary is on the right; yours is probably on the left.\n\n## Start from a document that works\n\nNothing written yet? Do not invent the first document, edit one:\n\n```\naontu init            # into the working directory\naontu init model/     # or into a named one\nsh check.sh           # the four questions, on what was just written\n```\n\n`init` writes `model.aontu` (an entity map constrained with `&:`),\n`data.aontu` (an instance of it that holds) and `check.sh` (the four\nchecks to run after every edit). It never overwrites: if any\nof the three already stands there, it refuses and writes none of them.\n\n## Describe a domain\n\nAn **ontology**, a **schema**, a **data model**, a **contract** — in\naontu these are all one thing: a document. Write the entities as a\n**map keyed by name**, and say what every entry must satisfy with the\n`&:` template:\n\n```\nentity: {\n  &: {\n    table:  string\n    fields: { &: { type: string, required: *false | boolean } }\n  }\n  planet: { table: \"planets\", fields: { name: { type: \"string\" } } }\n  moon:   { table: \"moons\",   fields: { name: { type: \"string\" } } }\n}\n```\n\n`&:` is the construct to reach for first, and the one most easily\nmissed. It meets **every** key of the map it sits in. A quoted `\"*\"`\nis not a wildcard — it is a key named `*`, and a schema written that\nway constrains nothing while still reporting `valid`.\n\nPrefer a named map to a list unless the order is a fact (a migration\nsequence, a rule table tried in order). A key is an address, a name\nother parts can refer to, and a diff that shows one insertion instead\nof every following element renumbered.\n\n## Check data against a model\n\n```\naontu vet model.aontu data.aontu\n```\n\nExit `0` valid, `1` a contradiction, `3` incomplete (nothing\ncontradicts, but the model is not yet satisfied), `4` the model does\nnot stand up on its own. `--format json` for the machine-readable\nreport, `--closed` to refuse keys the model does not declare,\n`--max-errors <n>` to cap the list.\n\n**Make the check prove it checked something.** A check that examined\nnothing answers exactly like one that passed:\n\n```\naontu vet --coverage model.aontu data.aontu         # what did it examine?\naontu vet --strict-coverage model.aontu data.aontu  # exit 1 if nothing\n```\n\n`--coverage` reports how many data leaves a declaration constrained,\nthe data paths none did, and the declarations no data met.\n`--strict-coverage` exits 1 when the answer is nothing. The usual\ncause is the `\"*\"` mistake above: reach for `&:`.\n\n## Check the model is coherent with itself\n\n```\naontu relations model.aontu        # declared entity edges: targets resolve, no cycles\naontu reaches planet moon model.aontu   # does one entity reach another, at any remove?\naontu trim --check model.aontu     # entries whose removal changes nothing\n```\n\n## Generate code from a model, and hold it\n\n```\naontu render gen.aontu build          # write the files below build/\naontu render --check gen.aontu build  # write nothing; exit 1 when build/ has drifted\naontu render gen/ build             # every generator directly in gen/, as one run\naontu model get out gen.aontu         # the component tree: files, and the lines in them\naontu trace gen.aontu                 # what rule wrote each line\n```\n\nA generator answers a **component tree** -- `file(name, [lines])` and\nits neighbours -- which `aontu render` hands to jostraca, the generator\nruntime, to write. A tree that is one file is written to the path\nitself, and a folder of generators is one run. `--check` compares with\nwhat is committed: the model is the\ntruth, the code is the claim, and drift is a finding. `aontu trace`\nanswers the other direction: for a line of the output, the model node\nand the rule behind it.\n\n## Ask what a model says, and why\n\n```\naontu model get  $.entity.planet.table model.aontu\naontu model why  $.entity.planet.table model.aontu\naontu model get  $.entity --keys       model.aontu\naontu model get  $.entity --types      model.aontu\n```\n\n`why` names **every** contribution to a value, with the file and line\neach was written on. It is the first thing to run when a value is not\nwhat you expected, and the second thing to run when `vet` refuses.\n\n## Change a value without editing the file\n\n```\naontu model set '$.entity.planet.table=planet_v2' --entry model.aontu --overlay local.aontu\n```\n\nThe change is checked before it is written; a change that contradicts\na pinned value is refused, and the file is left alone.\n\n## Gate a change to the model itself\n\n```\naontu subsume old.aontu new.aontu              # does the general admit every specific?\naontu breaking --against git#HEAD~1 model.aontu\naontu hash model.aontu                       # a pin that survives reformatting\n```\n\n## Hand a model to another agent\n\n```\naontu agentsmd --write AGENTS.md model.aontu\n```\n\nSplices a derived stanza — the pin, the root keys, the shape, and the\ncommands spelled with paths that exist — between two markers, and\nleaves the rest of the file alone. Re-run it in the commit that\nchanges the model.\n\n## When something refuses\n\nRead the code in the brackets, then look it up:\n\n```\naontu explain no_scalar_unify\n```\n\nEvery finding carries a `code`, a `class`, a `path` and the **two\nsites** that disagree — the value and the constraint it failed, each\nwith its file and line. The class says what kind of answer it is:\n`conflict` (two things cannot both hold), `incomplete` (nothing is\nwrong yet, something is missing), `parse`, `reference`, `budget`.\n\nFull index: [`error-codes.md`](error-codes.md). The language on one\npage: [`grammar-card.md`](grammar-card.md). The worked ladder from\nplain JSON upward: [`examples.md`](examples.md).\n"
   },
   {
     "topic": "language",
     "summary": "the grammar card — everything the language spells, on one page",
     "source": "docs/skill/grammar-card.md",
-    "text": "# aontu grammar card\n\nEverything the language spells, on one page. The published machine\ngrammars are [`grammar/aontu.abnf`](../../grammar/aontu.abnf) — the\nnotation a person reads, with railroad diagrams — and\n[`aontu.gbnf`](../../grammar/aontu.gbnf), `aontu.lark` and\n`aontu.tmLanguage.json` for constrained decoding, parsing and\nhighlighting; this is their human twin.\n\n## Values\n\n| Write | Means |\n|-------|-------|\n| `{\"a\":1}`, `a: 1` | a map; keys may be bare or quoted |\n| `[1,2]` | a list |\n| `\"s\"`, `1`, `1.5`, `true`, `null` | scalars, as JSON |\n| `0d9007199254740993` | an EXACT number, at any magnitude |\n| `string integer number float boolean null` | kinds: any value of that kind |\n| `top` | anything at all; `nil` is the failure |\n\n## Combining\n\n| Write | Means |\n|-------|-------|\n| `a & b` | both must hold — the meet |\n| `a \\| b` | either may hold — the join |\n| `*1 \\| integer` | either, with `1` the DEFAULT a generation picks |\n| | the branch keeps its kind: a later `1.5` is refused, not admitted |\n| `x: 1` twice | the two meet; `1 & 2` is an error, `1 & integer` is `1` |\n| `$.a.b` | the value at that path of this document |\n| `1 + 2` | arithmetic on concrete numbers |\n\n## Maps that say more\n\n| Write | Means |\n|-------|-------|\n| `{&: {k: integer}}` | a TEMPLATE every key must satisfy |\n| `close({a:1})` | no key beyond those named |\n| `{a?: 1}` | optional: dropped if unresolved |\n| `hide(x)` | evaluated, then dropped from the output |\n| `type(x)` | a definition, not a value: it generates nothing |\n| `deprecate(x, {msg:\"…\"})` | still works, and says so |\n| `refer(t) & path($.a.b)` | a checked LINK: the tree address must resolve, and `t` flows into it |\n\n## Constraints\n\n`min(n) max(n) above(n) below(n)` bound a number;\n`length(n)` and `unique()` bound a list or string;\n`re(\"^…$\")` matches a string; `neq(v)` refuses one value;\n`must(cond, \"why\")` is the escape hatch.\n\nBounds compose: `integer & min(1) & max(10)` is a range, and two\nranges meet to their overlap.\n\n## Files\n\n`@\"./other.aon\"` includes another document — it unifies in, it does not\nconcatenate. (A constrained decoder is not given this: generated\ndocuments describe values, they do not load files.)\n"
+    "text": "# aontu grammar card\n\nEverything the language spells, on one page. The published machine\ngrammars are [`grammar/aontu.abnf`](../../grammar/aontu.abnf) — the\nnotation a person reads, with railroad diagrams — and\n[`aontu.gbnf`](../../grammar/aontu.gbnf), `aontu.lark` and\n`aontu.tmLanguage.json` for constrained decoding, parsing and\nhighlighting; this is their human twin.\n\n## Values\n\n| Write | Means |\n|-------|-------|\n| `{\"a\":1}`, `a: 1` | a map; keys may be bare or quoted |\n| `[1,2]` | a list |\n| `\"s\"`, `1`, `1.5`, `true`, `null` | scalars, as JSON |\n| `0d9007199254740993` | an EXACT number, at any magnitude |\n| `string integer number float boolean null` | kinds: any value of that kind |\n| `top` | anything at all; `nil` is the failure |\n\n## Combining\n\n| Write | Means |\n|-------|-------|\n| `a & b` | both must hold — the meet |\n| `a \\| b` | either may hold — the join |\n| `*1 \\| integer` | either, with `1` the DEFAULT a generation picks |\n| | the branch keeps its kind: a later `1.5` is refused, not admitted |\n| `x: 1` twice | the two meet; `1 & 2` is an error, `1 & integer` is `1` |\n| `$.a.b` | the value at that path of this document |\n| `1 + 2` | arithmetic on concrete numbers |\n\n## Maps that say more\n\n| Write | Means |\n|-------|-------|\n| `{&: {k: integer}}` | a TEMPLATE every key must satisfy |\n| `close({a:1})` | no key beyond those named |\n| `{a?: 1}` | optional: dropped if unresolved |\n| `hide(x)` | evaluated, then dropped from the output |\n| `type(x)` | a definition, not a value: it generates nothing |\n| `deprecate(x, {msg:\"…\"})` | still works, and says so |\n| `refer(t) & path($.a.b)` | a checked LINK: the tree address must resolve, and `t` flows into it |\n\n## Constraints\n\n`min(n) max(n) above(n) below(n)` bound a number;\n`length(n)` and `unique()` bound a list or string;\n`re(\"^…$\")` matches a string; `neq(v)` refuses one value;\n`must(cond, \"why\")` is the escape hatch.\n\nBounds compose: `integer & min(1) & max(10)` is a range, and two\nranges meet to their overlap.\n\n## Files\n\n`@\"./other.aontu\"` includes another document — it unifies in, it does not\nconcatenate. (A constrained decoder is not given this: generated\ndocuments describe values, they do not load files.)\n"
   },
   {
     "topic": "examples",
     "summary": "the ladder — plain JSON, then one addition at a time",
     "source": "docs/skill/examples.md",
-    "text": "# aontu by example\n\nThe ladder: start with the JSON you already know, add one thing at a\ntime. Every rung is a valid document.\n\n## 1. It is JSON\n\n```\n{\"service\": {\"name\": \"auth\", \"port\": 8080}}\n```\n\nBare keys and no commas also parse, so this is the same document:\n\n```\nservice: {\n  name: \"auth\"\n  port: 8080\n}\n```\n\n## 2. Say what a value MAY be\n\n```\nservice: {\n  name: string\n  port: integer\n}\n```\n\nNothing generates yet — this is a truth, not a value. `aontu vet\nservice.aon deploy.aon` says whether a deployment satisfies it.\n\n## 3. Say what it SHOULD be\n\n```\nservice: {\n  name: string\n  port: *8080 | integer      # 8080 unless told otherwise\n  replicas: *1 | integer\n}\n```\n\nNow it generates: `{\"service\":{\"name\":…,\"port\":8080,\"replicas\":1}}` —\nexcept `name`, which nothing has supplied. Defaults are picked at\ngeneration; they do not stop a caller from choosing something else.\n\n`*8080 | integer` means what it reads as: a caller's `9090` overrides\nit, and a caller's `1.5` is refused, because the branch admits only the\nkind it names. Write `*8080 | number` if any numeric value should be\nallowed to win.\n\n## 4. Say it once, for every key\n\n```\nservices: {\n  &: { port: integer, replicas: *1 | integer }\n  auth: { port: 8080 }\n  db:   { port: 5432, replicas: 3 }\n}\n```\n\nThe `&:` template meets EVERY key. `aontu model why $.services.db.replicas`\nreports both contributions — the template's `*1|integer` and the\nliteral `3` — with the line each was written on.\n\n## 5. Bound it\n\n```\nservices: {\n  &: {\n    port: integer & min(1) & max(65535)\n    name: string & re(\"^[a-z][a-z0-9-]*$\")\n  }\n}\n```\n\nA port of `0` is now an error with a path, not a runtime surprise.\n\n## 6. Layer it\n\n```\n# base.aon\nservice: { image: string, replicas: *1 | integer }\n\n# prod.aon\n@\"./base.aon\"\nservice: { image: \"auth:v2.3\", replicas: 5 }\n```\n\nUnification is order-independent: `base & prod` is `prod & base`. To\nchange a value without editing the file, append to an overlay:\n\n```\naontu model set '$.service.replicas=7' --entry prod.aon --overlay local.aon\n```\n\nIf the value is PINNED rather than open, that command refuses and\nnames the pinning site — which is the honest answer, and where\n`aontu model why` takes you next.\n"
+    "text": "# aontu by example\n\nThe ladder: start with the JSON you already know, add one thing at a\ntime. Every rung is a valid document.\n\n## 1. It is JSON\n\n```\n{\"service\": {\"name\": \"auth\", \"port\": 8080}}\n```\n\nBare keys and no commas also parse, so this is the same document:\n\n```\nservice: {\n  name: \"auth\"\n  port: 8080\n}\n```\n\n## 2. Say what a value MAY be\n\n```\nservice: {\n  name: string\n  port: integer\n}\n```\n\nNothing generates yet — this is a truth, not a value. `aontu vet\nservice.aontu deploy.aontu` says whether a deployment satisfies it.\n\n## 3. Say what it SHOULD be\n\n```\nservice: {\n  name: string\n  port: *8080 | integer      # 8080 unless told otherwise\n  replicas: *1 | integer\n}\n```\n\nNow it generates: `{\"service\":{\"name\":…,\"port\":8080,\"replicas\":1}}` —\nexcept `name`, which nothing has supplied. Defaults are picked at\ngeneration; they do not stop a caller from choosing something else.\n\n`*8080 | integer` means what it reads as: a caller's `9090` overrides\nit, and a caller's `1.5` is refused, because the branch admits only the\nkind it names. Write `*8080 | number` if any numeric value should be\nallowed to win.\n\n## 4. Say it once, for every key\n\n```\nservices: {\n  &: { port: integer, replicas: *1 | integer }\n  auth: { port: 8080 }\n  db:   { port: 5432, replicas: 3 }\n}\n```\n\nThe `&:` template meets EVERY key. `aontu model why $.services.db.replicas`\nreports both contributions — the template's `*1|integer` and the\nliteral `3` — with the line each was written on.\n\n## 5. Bound it\n\n```\nservices: {\n  &: {\n    port: integer & min(1) & max(65535)\n    name: string & re(\"^[a-z][a-z0-9-]*$\")\n  }\n}\n```\n\nA port of `0` is now an error with a path, not a runtime surprise.\n\n## 6. Layer it\n\n```\n# base.aontu\nservice: { image: string, replicas: *1 | integer }\n\n# prod.aontu\n@\"./base.aontu\"\nservice: { image: \"auth:v2.3\", replicas: 5 }\n```\n\nUnification is order-independent: `base & prod` is `prod & base`. To\nchange a value without editing the file, append to an overlay:\n\n```\naontu model set '$.service.replicas=7' --entry prod.aontu --overlay local.aontu\n```\n\nIf the value is PINNED rather than open, that command refuses and\nnames the pinning site — which is the honest answer, and where\n`aontu model why` takes you next.\n"
   },
   {
     "topic": "codes",
     "summary": "what a refusal means, and what to do about it",
     "source": "docs/skill/error-codes.md",
-    "text": "# What a refusal means\n\nEvery aontu error carries a **code**, and every code has a **class**.\nThe class says what kind of thing went wrong, which is what decides\nyour next move. The full registry — every code, its class, and the\nversion it appeared in — is\n[`test/spec/errcodes.tsv`](../../test/spec/errcodes.tsv), which the\ntest suite holds to the engine in both implementations.\n\n| Class | Meaning | What to do |\n|-------|---------|------------|\n| `parse` | the text is not a document | fix the syntax at the site the frame points at |\n| `conflict` | two values cannot both hold | one of them is wrong: `aontu model why <path>` names both and where they were written |\n| `incomplete` | nothing contradicts, but the value is not concrete | supply what is missing, or accept it with `--partial` |\n| `reference` | a path names nothing | check the spelling; `aontu model get $ --keys` lists what is there |\n| `compat` | a change breaks an earlier version | that is `aontu subsume` / `aontu breaking` talking: widen the change or version it |\n| `budget` | evaluation hit a deterministic limit | usually a cycle; simplify, or raise the budget deliberately |\n| `internal` | the engine surprised itself | a bug worth reporting |\n\n## Looking a code up\n\n```\naontu explain constraint    # what one code means, and its class\naontu explain --list        # every registered code, with its class\n```\n\nA report prints two bracketed spans, and only one of them is a code:\n\n```\n$.note.n1.id: constraint [conflict]\n  [aontu/constraint]: Cannot unify values at path $.note.n1.id\n```\n\n`[conflict]` is the **class**. `[aontu/constraint]` is the **code**,\ncarrying the `aontu/` prefix. `explain` takes either spelling —\n`constraint` or `aontu/constraint` — and answers under the registered\none. The headline carries the bare code as well, and so does the `code`\nfield of a `--format json` report.\n\n## The repair loop\n\n```\naontu vet schema.aon mine.aon --format json\n```\n\nThe exit code branches for you: `0` valid, `1` invalid (fix the\ndata), `3` incomplete (supply more), `4` the schema itself is\nunusable (fix the truth, not the data). Every finding carries\n`path`, `code`, and the sites on both sides — the data site first,\nbecause that is the one to edit. A site names **the file whose text\nit excerpts**, so its row and column are safe to edit at even when\nthe document loads others.\n\nRead `hint` before guessing. `message` is the one-line headline;\n`hint` is the engine's own explanation of the failure class with the\noffending values filled in, and for several codes it names the fix\noutright — `lossy_integer_literal` tells you to write the literal as\n`0d…`. Every code in the registry has hint text, which is what\n`aontu explain` prints. A finding carries it inline for an exact\nregistry code; a **dynamic** code (`func:upper`, `op[+]`) is registered\nthrough its prefix, and only `explain` falls back to the prefix's text,\nso such a finding carries no `hint`.\n\nFor a conflict, `aontu model why <path> mine.aon` lists every contribution\nto that path with its role and source line, which turns \"these\ndisagree\" into \"these two lines disagree\".\n\nThen fix it:\n\n```\naontu model set '$.replicas=5' --entry schema.aon --overlay mine.aon --in-place\n```\n\n`--in-place` rewrites the pinned literal **where it was written**, so\ncomments and layout survive. Without it, `set` APPENDS — which is the\nright thing when the document left a hole, and cannot work when it\npinned the wrong value, because unification only narrows.\n\nThe edit is verified before a byte is written: a site carries the\nsource text it covers, and the text at the span must match it. Where\nthat cannot be established — the value comes from a `&:` template or a\n`$ref`, two statements pin the path, the site names the opening token\nof a compound like `min(1)`, or the overlay `@\"includes\"` another\ndocument — the assignment is appended as usual and a **warning** says\nwhich case it hit. A warning never changes the verdict, so asking for\n`--in-place` cannot make a run fail that would have succeeded.\n"
+    "text": "# What a refusal means\n\nEvery aontu error carries a **code**, and every code has a **class**.\nThe class says what kind of thing went wrong, which is what decides\nyour next move. The full registry — every code, its class, and the\nversion it appeared in — is\n[`test/spec/errcodes.tsv`](../../test/spec/errcodes.tsv), which the\ntest suite holds to the engine in both implementations.\n\n| Class | Meaning | What to do |\n|-------|---------|------------|\n| `parse` | the text is not a document | fix the syntax at the site the frame points at |\n| `conflict` | two values cannot both hold | one of them is wrong: `aontu model why <path>` names both and where they were written |\n| `incomplete` | nothing contradicts, but the value is not concrete | supply what is missing, or accept it with `--partial` |\n| `reference` | a path names nothing | check the spelling; `aontu model get $ --keys` lists what is there |\n| `compat` | a change breaks an earlier version | that is `aontu subsume` / `aontu breaking` talking: widen the change or version it |\n| `budget` | evaluation hit a deterministic limit | usually a cycle; simplify, or raise the budget deliberately |\n| `internal` | the engine surprised itself | a bug worth reporting |\n\n## Looking a code up\n\n```\naontu explain constraint    # what one code means, and its class\naontu explain --list        # every registered code, with its class\n```\n\nA report prints two bracketed spans, and only one of them is a code:\n\n```\n$.note.n1.id: constraint [conflict]\n  [aontu/constraint]: Cannot unify values at path $.note.n1.id\n```\n\n`[conflict]` is the **class**. `[aontu/constraint]` is the **code**,\ncarrying the `aontu/` prefix. `explain` takes either spelling —\n`constraint` or `aontu/constraint` — and answers under the registered\none. The headline carries the bare code as well, and so does the `code`\nfield of a `--format json` report.\n\n## The repair loop\n\n```\naontu vet schema.aontu mine.aontu --format json\n```\n\nThe exit code branches for you: `0` valid, `1` invalid (fix the\ndata), `3` incomplete (supply more), `4` the schema itself is\nunusable (fix the truth, not the data). Every finding carries\n`path`, `code`, and the sites on both sides — the data site first,\nbecause that is the one to edit. A site names **the file whose text\nit excerpts**, so its row and column are safe to edit at even when\nthe document loads others.\n\nRead `hint` before guessing. `message` is the one-line headline;\n`hint` is the engine's own explanation of the failure class with the\noffending values filled in, and for several codes it names the fix\noutright — `lossy_integer_literal` tells you to write the literal as\n`0d…`. Every code in the registry has hint text, which is what\n`aontu explain` prints. A finding carries it inline for an exact\nregistry code; a **dynamic** code (`func:upper`, `op[+]`) is registered\nthrough its prefix, and only `explain` falls back to the prefix's text,\nso such a finding carries no `hint`.\n\nFor a conflict, `aontu model why <path> mine.aontu` lists every contribution\nto that path with its role and source line, which turns \"these\ndisagree\" into \"these two lines disagree\".\n\nThen fix it:\n\n```\naontu model set '$.replicas=5' --entry schema.aontu --overlay mine.aontu --in-place\n```\n\n`--in-place` rewrites the pinned literal **where it was written**, so\ncomments and layout survive. Without it, `set` APPENDS — which is the\nright thing when the document left a hole, and cannot work when it\npinned the wrong value, because unification only narrows.\n\nThe edit is verified before a byte is written: a site carries the\nsource text it covers, and the text at the span must match it. Where\nthat cannot be established — the value comes from a `&:` template or a\n`$ref`, two statements pin the path, the site names the opening token\nof a compound like `min(1)`, or the overlay `@\"includes\"` another\ndocument — the assignment is appended as usual and a **warning** says\nwhich case it hit. A warning never changes the verdict, so asking for\n`--in-place` cannot make a run fail that would have succeeded.\n"
   },
   {
     "topic": "grammar",
@@ -54,22 +54,22 @@ type InitFile = {
 
 const INITDOC: InitFile[] = [
   {
-    "file": "docs/skill/init/model.aon",
-    "name": "model.aon",
+    "file": "docs/skill/init/model.aontu",
+    "name": "model.aontu",
     "mode": 420,
-    "text": "# model.aon --- the truth. `aontu vet model.aon data.aon` asks whether\n# a document satisfies it.\n#\n# `&:` is the construct to learn first: it meets EVERY key of the map\n# it sits in, so one statement constrains every entity. A quoted \"*\" is\n# not a wildcard -- it is a key named `*`, it meets nothing, and a\n# schema written that way reports `valid` over data that violates it.\n# `aontu vet --strict-coverage` refuses to pass such a check.\nentity: {\n  &: {\n    table: string & re(\"^[a-z][a-z0-9_]*$\")\n    fields: {\n      &: {\n        type: \"string\" | \"integer\" | \"boolean\"\n        required: *false | boolean\n      }\n    }\n  }\n}\n"
+    "text": "# model.aontu --- the truth. `aontu vet model.aontu data.aontu` asks whether\n# a document satisfies it.\n#\n# `&:` is the construct to learn first: it meets EVERY key of the map\n# it sits in, so one statement constrains every entity. A quoted \"*\" is\n# not a wildcard -- it is a key named `*`, it meets nothing, and a\n# schema written that way reports `valid` over data that violates it.\n# `aontu vet --strict-coverage` refuses to pass such a check.\nentity: {\n  &: {\n    table: string & re(\"^[a-z][a-z0-9_]*$\")\n    fields: {\n      &: {\n        type: \"string\" | \"integer\" | \"boolean\"\n        required: *false | boolean\n      }\n    }\n  }\n}\n"
   },
   {
-    "file": "docs/skill/init/data.aon",
-    "name": "data.aon",
+    "file": "docs/skill/init/data.aontu",
+    "name": "data.aontu",
     "mode": 420,
-    "text": "# data.aon --- an instance of the truth in model.aon. Edit it and run\n# check.sh: every change is checked against the model, and a change the\n# model refuses is named with the line it is on.\nentity: {\n  planet: {\n    table: \"planets\"\n    fields: {\n      name: { type: \"string\", required: true }\n      diameter: { type: \"integer\" }\n    }\n  }\n}\n"
+    "text": "# data.aontu --- an instance of the truth in model.aontu. Edit it and run\n# check.sh: every change is checked against the model, and a change the\n# model refuses is named with the line it is on.\nentity: {\n  planet: {\n    table: \"planets\"\n    fields: {\n      name: { type: \"string\", required: true }\n      diameter: { type: \"integer\" }\n    }\n  }\n}\n"
   },
   {
     "file": "docs/skill/init/check.sh",
     "name": "check.sh",
     "mode": 493,
-    "text": "#!/usr/bin/env sh\n# check.sh --- the four questions to ask of a model. Run it after\n# every edit to model.aon or data.aon.\n#\n# `aontu help tasks` maps a job to a verb; `aontu explain <code>` says\n# what a refusal means; `aontu help language` is the whole grammar on\n# one page. None of them needs a network.\nset -eu\n\nAONTU=\"${AONTU:-aontu}\"\ncd \"$(dirname \"$0\")\"\n\n# 1. Does the data satisfy the truth -- and did the check examine\n#    anything? --strict-coverage exits 1 on a check that constrained no\n#    value, which is the failure a passing gate hides.\n$AONTU vet --strict-coverage model.aon data.aon\n\n# 2. What does it say at a path?\n$AONTU model get '$.entity.planet.table' data.aon\n\n# 3. Why does it say that? Every contribution, with the line it is on.\n$AONTU model why '$.entity.planet.table' data.aon\n\n# 4. A pin for the truth: it survives reformatting and moves on any\n#    change of meaning.\n$AONTU hash model.aon\n\necho \"ok --- model.aon and data.aon agree\"\n"
+    "text": "#!/usr/bin/env sh\n# check.sh --- the four questions to ask of a model. Run it after\n# every edit to model.aontu or data.aontu.\n#\n# `aontu help tasks` maps a job to a verb; `aontu explain <code>` says\n# what a refusal means; `aontu help language` is the whole grammar on\n# one page. None of them needs a network.\nset -eu\n\nAONTU=\"${AONTU:-aontu}\"\ncd \"$(dirname \"$0\")\"\n\n# 1. Does the data satisfy the truth -- and did the check examine\n#    anything? --strict-coverage exits 1 on a check that constrained no\n#    value, which is the failure a passing gate hides.\n$AONTU vet --strict-coverage model.aontu data.aontu\n\n# 2. What does it say at a path?\n$AONTU model get '$.entity.planet.table' data.aontu\n\n# 3. Why does it say that? Every contribution, with the line it is on.\n$AONTU model why '$.entity.planet.table' data.aontu\n\n# 4. A pin for the truth: it survives reformatting and moves on any\n#    change of meaning.\n$AONTU hash model.aontu\n\necho \"ok --- model.aontu and data.aontu agree\"\n"
   }
 ]