aontu 0.65.0 → 0.67.0

package/grammar/aontu.tmLanguage.json

@@ -14,16 +14,14 @@
     "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",
+    "THE BUILTIN LIST IS A COPY, AND A COPY DRIFTS, 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."
+    "No `|>`: the pipe is not in the language, and all three published",
+    "grammars agree about that."
   ],
   "name": "aontu",
   "displayName": "Aontu",
@@ -130,7 +128,7 @@
           "match": "\\b(true|false|null)\\b"
         },
         {
-          "comment": "`_` is a literal of the language as of G8 phase 3, not text.",
+          "comment": "`_` is a literal of the language, not text.",
           "name": "constant.language.placeholder.aontu",
           "match": "(?<![A-Za-z0-9_])_(?![A-Za-z0-9_])"
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aontu",
-  "version": "0.65.0",
+  "version": "0.67.0",
   "main": "dist/aontu.js",
   "type": "commonjs",
   "types": "dist/aontu.d.ts",
@@ -38,7 +38,7 @@
     "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",
+    "clean": "rm -rf dist dist-test .tsbuild 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)}\"",
     "repo-bump": "npm version patch --no-git-tag-version && node -e \"console.log('bumped to v' + require('./package.json').version + ' (package.json only - commit via repo-tag / repo-release)')\"",
@@ -78,7 +78,8 @@
     "@tabnas/parser": "0.9.7",
     "@tabnas/path": "0.3.2",
     "@tabnas/toml": "0.5.7",
-    "@tabnas/yaml": "0.5.7"
+    "@tabnas/yaml": "0.5.7",
+    "jostraca": "0.38.0"
   },
   "devDependencies": {
     "@tabnas/railroad": "0.3.6",

package/skill/tasks.md

@@ -82,16 +82,21 @@ aontu trim --check model.aon     # entries whose removal changes nothing
 ## Generate code from a model, and hold it
 
 ```
-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 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/ 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
 ```
 
 A generator answers a **component tree** -- `file(name, [lines])` and
-its neighbours -- which a generator runtime writes to disk. Hand the
-tree to one and compare with what is committed: the model is the truth,
-the code is the claim, and drift is a finding. `aontu trace` answers
-the other direction: for a line of the output, the model node and the
-rule behind it.
+its neighbours -- which `aontu render` hands to jostraca, the generator
+runtime, to write. A tree that is one file is written to the path
+itself, and a folder of generators is one run. `--check` compares with
+what is committed: the model is the
+truth, the code is the claim, and drift is a finding. `aontu trace`
+answers the other direction: for a line of the output, the model node
+and the rule behind it.
 
 ## Ask what a model says, and why
 

package/src/allow.ts

@@ -3,7 +3,7 @@
 
 import { Aontu } from './aontu'
 import { ConjunctVal } from './val/ConjunctVal'
-import { anchorAt } from './vet'
+import { anchorAt, engineFinding } from './vet'
 import type { VetFinding } from './vet'
 import { evalFailure, nearestKey, pathParts } from './query'
 import { includeOpts } from './utility'
@@ -101,7 +101,7 @@ function readEntries(
     const text: string = true === el.isString ? el.peg : el.gen(ctx)
     if (before < ctx.err.length) {
       const err: any = ctx.err[before]
-      return { entries, finding: finding(err.why, `${by}.${i}`, err.msg) }
+      return { entries, finding: engineFinding(err, ctx, `${by}.${i}`) }
     }
     entries.push({ parts: pathParts(text), text, by: `${by}.${i}` })
   }
@@ -174,7 +174,7 @@ export function allow(
   const root: any = aontu.unify(
     new ConjunctVal({ peg: [model, shape] }, ctx), undefined, ctx)
   if (0 < ctx.err.length || true === root.isNil) {
-    return errorReport(role, evalFailure(ctx))
+    return errorReport(role, evalFailure(ctx, root))
   }
 
   const roles: any = anchorAt(root, at)

package/src/aontu.ts

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

package/src/cli.ts

@@ -5,8 +5,10 @@
 import { evalFailure } from './query'
 // __importStar downlevel helper, whose branches no supported Node takes.
 import {
-  existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync,
+  existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync,
+  writeFileSync,
 } from 'node:fs'
+import type { Dirent } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { createInterface } from 'node:readline'
@@ -97,6 +99,9 @@ const HELP = `Usage: aontu [options] [file]
                       [--profile <file>] <file>
        aontu trace [--at <path>] [--format json] [--marker <token>]
                    [--profile <file>] <file>
+       aontu render [--check] [--at <path>] [--format json]
+                    [--marker <token>] [--profile <file>]
+                    <file|folder> <path>
        aontu hash [options] <file>
        aontu sync [--frozen] [options] [dir]
        aontu add <pkg>[@<version>] [options] [dir]
@@ -161,22 +166,30 @@ query between a document and its own earlier versions.
 
 Options:
   -c, --canon     Print the canonical form instead of generated JSON
-  --format <f>    text (default) or json. The json form wraps the
-                  answer as {aontu, findings, ok, out}, so a failure
-                  here reads like every other verb's
+                  (the bare command's, as --jsonl is; model get has
+                  its own)
+  --format <f>    text (default) or json, on every verb that answers a
+                  report. The json form is one object opening with an
+                  aontu block; the bare command's carries findings, ok
+                  and out
   -h, --help      Show this help and exit (the verbs and their flags);
                   aontu help is the LANGUAGE, and lists its own topics
   --jsonl         REPL: answer every command as one JSON line
   -v, --version   Print the version and exit
-  --trust <t>     Include capability: system (default), none, or
-                  root[:dir] to confine @"..." below a directory.
-                  Every verb takes it too, and a bare root means the
-                  document's own directory
+  --trust <t>     Include capability: system, none, or root[:dir] to
+                  confine @"..." below a directory. A bare root means
+                  the entry root: the document's own directory, or the
+                  project's for the package verbs. Every verb takes it
+                  but help, explain, init and lsp, which read no
+                  document, and mcp, which is the npm build's server
+                  and confines with --root. Unset, a run behaves as
+                  system, and the bare command warns once for an
+                  include that leaves the entry root
   --include-root <dir>  Shorthand for --trust root:<dir>
-  --text-ext <e>  Read these extensions as text too, comma-separated
-                  and without dots (md,sql). .txt needs no flag; a
+  --text-ext <e>  Read these extensions as text too, comma-separated,
+                  with or without dots (md,sql). .txt needs no flag; a
                   named format keeps its meaning, and .js stays
-                  refused. Every verb takes it
+                  refused. The verbs that take --trust take it too
 
 Package verbs (a module is imported; a package is published):
   sync      Make the project correct: resolve by minimum version
@@ -411,6 +424,31 @@ every other line is a line of output.
 
 Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
 
+Render options:
+  --check         Compare what the generator writes with what <path>
+                  holds, write nothing, and exit 1 on drift
+  --at <path>     Where the component tree lives in the document
+                  (default $.out)
+  --format json   Print the files written, or the drift, as JSON
+  --marker <t>    The file is a generator, and this is its marker
+                  (default //-, and #- --- /*- <!--- by extension)
+  --profile <f>   A profile file, whose template.ext names the
+                  extensions it marks and template.marker the marker
+
+The render verb writes the component tree a generator answers. The
+tree is handed to jostraca, the generator runtime, which writes the
+files: a tree that is one file is written to <path> itself, unless
+<path> is a directory, and any other tree is written below <path>.
+With --check nothing is written and <path> is compared with what the
+generator writes, one "kind: file" line per difference.
+A folder as the generator is a set: every regular file directly in
+it, dotfiles aside, in name order, and their trees are written below
+<path> as one run, so a path two of them claim is refused. A file with
+no marker line in it is refused by name.
+
+Render exit codes: 0 written or clean, 1 --check drift, 2 usage or
+I/O, 4 the document does not stand up, or --at names nothing.
+
 Model set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -678,7 +716,7 @@ function takeTrust(argv: string[], io: Io = PROCESS_IO):
     }
     else if ('--include-root' === arg) {
       const dir = argv[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         io.err('aontu: --include-root needs a directory\n')
         return undefined
       }
@@ -2674,20 +2712,42 @@ function pkgNetText(verb: string, report: any): string {
 const MODEL_HELP = 'aontu model get|why|set ... (try --help)'
 
 // One document, interrogated or edited (ADR-039 part 5).
+// Where the subcommand is, past any global flag that precedes it.
+// `takeTrust` strips those anywhere in a tail, so the subcommand has
+// to be found past a flag AND past its value: in `--text-ext get` the
+// `get` is the extension list, not the subcommand.
+const MODEL_SUBS = ['get', 'why', 'set']
+const GLOBAL_VALUED = ['--trust', '--include-root', '--text-ext']
+
+
+function modelSubAt(argv: string[]): number {
+  for (let i = 0; i < argv.length; i++) {
+    if (GLOBAL_VALUED.includes(argv[i])) {
+      i++
+      continue
+    }
+    return MODEL_SUBS.includes(argv[i]) ? i : -1
+  }
+  return -1
+}
+
+
 function runModel(argv: string[]): number {
   const sub = argv[0]
   if ('-h' === sub || '--help' === sub) {
     process.stdout.write(HELP)
     return 0
   }
-  if ('get' === sub) {
-    return runGet(argv.slice(1))
-  }
-  if ('why' === sub) {
-    return runWhy(argv.slice(1))
-  }
-  if ('set' === sub) {
-    return runSet(argv.slice(1))
+  const at = modelSubAt(argv)
+  if (0 <= at) {
+    const tail = argv.slice(0, at).concat(argv.slice(at + 1))
+    if ('get' === argv[at]) {
+      return runGet(tail)
+    }
+    if ('why' === argv[at]) {
+      return runWhy(tail)
+    }
+    return runSet(tail)
   }
   process.stderr.write(`aontu: model needs get, why or set\n${MODEL_HELP}\n`)
   return 2
@@ -2880,6 +2940,297 @@ function runTrace(argv: string[]): number {
 }
 
 
+// ---------------------------------------------------------------------
+// The writer (ADR-040). A generator answers a component tree; this verb
+// hands it to jostraca, which writes the files below a path or holds
+// them to it.
+
+const RENDER_HELP =
+  'aontu render [--check] [--at <path>] [--format json] ' +
+  '[--marker <token>] [--profile <file>] <file|folder> <path> (try --help)'
+
+
+// Loaded at the call, so every other verb starts without it.
+function generatorRuntime(): any {
+  return require('jostraca')
+}
+
+
+function isDirectory(path: string): boolean {
+  return true === statSync(path, { throwIfNoEntry: false })?.isDirectory()
+}
+
+
+// A `File` the write path skips, RENAMED rather than removed: dropping
+// the node would take its children's claims with it and hide drift the
+// write path does make. The skip is the File's own save alone, so what
+// separates the runs is its output path, composed by the runtime rather
+// than here.
+const EXCLUDED_NAME = '.aontu-check-excluded-'
+
+
+// `exclude` as the runtime reads it: `true`, or a string or list member
+// equal to the node's COMPONENT path, the chain of `name` props above
+// it, which a Project's `folder` is not part of. The Go runtime honours
+// the boolean alone, so the ports' `--check` answers differ for the
+// path forms (test/spec/divergent.tsv).
+function excludedFile(exclude: any, at: string[]): boolean {
+  if (true === exclude) {
+    return true
+  }
+  const path = at.join('/')
+  if ('string' === typeof exclude) {
+    return exclude === path
+  }
+  return Array.isArray(exclude) && exclude.includes(path)
+}
+
+
+function renameExcluded(node: any, at: string[], cut: number[]): any {
+  if (Array.isArray(node)) {
+    return node.map((child) => renameExcluded(child, at, cut))
+  }
+  // A hand-written tree carries nodes with no `props` and nodes with
+  // no `children`, and neither needs an arm of its own.
+  const props: any = node.props ?? {}
+  const below = 'string' === typeof props.name ? at.concat(props.name) : at
+  if ('File' === node.cmp && excludedFile(props.exclude, below)) {
+    cut.push(1)
+    return { ...node, props: { ...props, name: EXCLUDED_NAME + cut.length } }
+  }
+  if (!Array.isArray(node.children)) {
+    return node
+  }
+  return { ...node, children: renameExcluded(node.children, below, cut) }
+}
+
+
+// A file the runtime declined to touch, its copy on disk carrying the
+// protect marker, is in none of the lists it answers with: they hold
+// what was DONE to a file, and nothing was. The run's own record names
+// it. `since` drops what earlier runs left.
+function renderSkipped(folder: string, since: number): string[] {
+  const at = join(folder, '.jostraca', 'jostraca.meta.log')
+  let meta: any
+  try {
+    meta = JSON.parse(readFileSync(at, 'utf8'))
+  }
+  catch (err: any) {
+    return []
+  }
+  return Object.entries(meta?.files ?? {})
+    .filter(([_, f]: [string, any]) => 'skip' === f?.action && since <= f?.when)
+    .map(([path]) => path)
+    .sort(cmpCodePoint)
+}
+
+
+async function runRender(argv: string[]): Promise<number> {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const rest: string[] = []
+  const profileFiles: string[] = []
+  let format: SubsumeFormat = 'text'
+  let at: string | undefined = undefined
+  let marker: string | undefined = undefined
+  let check = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--check' === arg) {
+      check = true
+    }
+    else if ('--format' === arg) {
+      const f = argv[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return 2
+      }
+      format = f
+    }
+    else if ('--at' === arg) {
+      at = argv[++i]
+      if (null == at || '' === at) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker || '' === marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if ('--profile' === arg) {
+      const pf = argv[++i]
+      if (null == pf || '' === pf) {
+        process.stderr.write('aontu: --profile needs a file\n')
+        return 2
+      }
+      profileFiles.push(pf)
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(`aontu: unknown render option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      rest.push(arg)
+    }
+  }
+
+  if (2 !== rest.length) {
+    process.stderr.write(`aontu: render needs a file and a path\n${RENDER_HELP}\n`)
+    return 2
+  }
+  const [file, dest] = rest
+
+  const declared = loadProfiles(profileFiles, trust)
+  if ('number' === typeof declared) {
+    return declared
+  }
+
+  // A FOLDER IS A SET OF GENERATORS: every regular file directly in it,
+  // dotfiles aside, in code-point order, written as one tree.
+  let entries: Dirent[] | undefined
+  try {
+    entries = readdirSync(file, { withFileTypes: true })
+  }
+  catch (err: any) {
+    entries = undefined
+  }
+  const set = undefined !== entries
+  const files = undefined === entries ? [file] :
+    entries.filter((e) => e.isFile() && !e.name.startsWith('.'))
+      .map((e) => e.name).sort(cmpCodePoint).map((n) => join(file, n))
+  if (0 === files.length) {
+    process.stderr.write(`aontu: ${file} holds no generator\n`)
+    return 2
+  }
+
+  const trees: any[] = []
+  for (const f of files) {
+    let src: string
+    try {
+      src = readFileSync(f, 'utf8')
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+    if (!/[.](aon|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, ` +
+          'so there is no aontu in it to render\n')
+        return 2
+      }
+      src = desugarTemplate(src, mark)
+    }
+    const report = get(src, at ?? '$.out', {
+      view: 'json', path: f, ...verbOpts(trust, entryRootOf(f)),
+    })
+    if (!report.ok) {
+      process.stderr.write(report.findings.map(renderFinding).join('\n') + '\n')
+      return 4
+    }
+    const tree = JSON.parse(report.out)
+    // A `File` without a name is refused: the runtime ports disagree
+    // about it.
+    if ('File' === tree?.cmp && 'string' !== typeof tree.props?.name) {
+      process.stderr.write(`aontu: ${f}: the file at ${at ?? '$.out'} has no name\n`)
+      return 4
+    }
+    trees.push(tree)
+  }
+
+  // ONE FILE GOES TO THE PATH ITSELF, unless the path is a directory; a
+  // set is written below the path whatever its trees are.
+  let folder = dest
+  const tree: any = set ? trees.flatMap((t) => Array.isArray(t) ? t : [t]) : trees[0]
+  if (!set && 'File' === tree?.cmp && !isDirectory(dest)) {
+    tree.props.name = basename(dest)
+    folder = dirname(dest)
+  }
+
+  const { cmpTree, Jostraca } = generatorRuntime()
+  let root: any
+  try {
+    root = cmpTree(tree, { raw: true })
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: ${file}: ${err.message}\n`)
+    return 4
+  }
+  const runtime = Jostraca()
+
+  try {
+    if (check) {
+      const res = await runtime.check({ folder }, root)
+      let drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      // `--check` answers "would `render` change anything", so a file
+      // the write path leaves alone is not held to the generator's
+      // bytes. The skip is gated on the target BEING there -- `render`
+      // writes an absent one -- so drift at a path with nothing at it
+      // survives, which is the `missing` a deleted file reports.
+      const cut: number[] = []
+      const renamed = renameExcluded(tree, [], cut)
+      if (0 < cut.length) {
+        const kept = new Set<string>((await Jostraca().check(
+          { folder }, cmpTree(renamed, { raw: true }))).checked)
+        const skipped = new Set<string>(
+          res.checked.filter((p: string) => !kept.has(p)))
+        drift = drift.filter((d: any) => !skipped.has(d.path) ||
+          !existsSync(join(folder, d.path)))
+      }
+      if ('json' === format) {
+        process.stdout.write(exactJSON({
+          aontu: { version: version(), verb: 'render' },
+          verdict: 0 === drift.length ? 'ok' : 'drift',
+          checked: res.checked,
+          drift,
+        }, 2) + '\n')
+      }
+      else {
+        for (const d of drift) {
+          process.stdout.write(`${d.kind}: ${d.path}\n`)
+        }
+      }
+      return 0 === drift.length ? 0 : 1
+    }
+
+    const since = Date.now()
+    const res = await runtime.generate({ folder }, root)
+    const skipped = renderSkipped(folder, since)
+    if ('json' === format) {
+      process.stdout.write(exactJSON({
+        aontu: { version: version(), verb: 'render' },
+        verdict: 'ok',
+        files: { ...res.files, skipped },
+      }, 2) + '\n')
+    }
+    else {
+      for (const path of skipped) {
+        process.stdout.write(`skipped: ${path}\n`)
+      }
+    }
+    return 0
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: ${err.message}\n`)
+    return 2
+  }
+}
+
+
 function runReaches(argv: string[]): number {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -3697,7 +4048,7 @@ function runHash(argv: string[]): number {
   if (0 < ctx.err.length || true === v?.isNil) {
     process.stderr.write(
       `aontu: ${files[0]} does not evaluate on its own; nothing to hash\n` +
-      renderFinding(evalFailure(ctx)) + '\n')
+      renderFinding(evalFailure(ctx, v)) + '\n')
     return 4
   }
 
@@ -4880,8 +5231,8 @@ function runInit(argv: string[]): number {
 const KNOWN_VERBS = [
   'add', 'agentsmd', 'allow', 'breaking', 'explain', 'fmt', 'get', 'hash',
   'help', 'init', 'jsonschema', 'lsp', 'mcp', 'model', 'pkg', 'publish',
-  'reaches', 'relations', 'remove', 'subsume', 'sync', 'template', 'trace',
-  'trim', 'vet', 'view', 'why',
+  'reaches', 'relations', 'remove', 'render', 'subsume', 'sync', 'template',
+  'trace', 'trim', 'vet', 'view', 'why',
 ]
 
 
@@ -5029,6 +5380,10 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runTrace(argv.slice(3)))
   }
 
+  if ('render' === argv[2]) {
+    return void runRender(argv.slice(3)).then(finish)
+  }
+
   if ('reaches' === argv[2]) {
     return finish(runReaches(argv.slice(3)))
   }
@@ -5083,7 +5438,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     }
     else if ('--include-root' === arg) {
       const dir = args[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         process.stderr.write('aontu: --include-root needs a directory\n')
         return finish(2)
       }
@@ -5146,6 +5501,7 @@ export {
   runJsonSchema,
   runTemplate,
   runTrace,
+  runRender, renderSkipped,
   runPkg, runModel, runPackageVerb, pkgToolOptions, serveUntilInterrupted,
   runHash, runGet, runHelp, runExplain, runInit, nearestVerb,
   looksLikeVerb,

package/src/helpdoc.ts

@@ -17,7 +17,7 @@ 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 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 a generator runtime writes to disk. Hand the\ntree to one and compare with what is committed: the model is the truth,\nthe code is the claim, and drift is a finding. `aontu trace` answers\nthe other direction: for a line of the output, the model node and the\nrule 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.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"
   },
   {
     "topic": "language",